The Receive-Payment object

QuickBooks Desktop API

Core Resources

Auth Sessions
End Users

Utilities

GET
Health check

Transactions

All Transactions
Bill Check Payments
Bill Credit Card Payments
Bills
Checks
Credit Card Charges
Credit Card Credits
Credit Memos
Estimates
Inventory Adjustments
Invoices
Journal Entries
Purchase Orders
Receive-Payments
Sales Orders
Sales Receipts
Time Tracking Activities
Transfers
Vendor Credits

General

Accounts
Classes
Customers / Jobs
Date-Driven Terms
Employees
Inventory Sites
Payroll Wage Items
Sales Representatives
Sales-Tax Codes
Standard Terms
Vendors

Items

Discount Items
Inventory Assembly Items
Inventory Items
Non-Inventory Items
Sales-Tax Items
Service Items
Subtotal Items

string

required

The unique identifier assigned by QuickBooks to this receive-payment. This ID is unique across all transaction types.

Example:

"123ABC-1234567890"

objectType

string

required

The type of object. This value is always "qbd_receive_payment".

Allowed value: "qbd_receive_payment"

Example:

"qbd_receive_payment"

createdAt

string

required

The date and time when this receive-payment was created, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm). The time zone is the same as the user's time zone in QuickBooks.

Example:

"2021-10-01T17:34:56.000Z"

updatedAt

string

required

The date and time when this receive-payment was last updated, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm). The time zone is the same as the user's time zone in QuickBooks.

Example:

"2021-10-01T20:45:30.000Z"

revisionNumber

string

required

The current QuickBooks-assigned revision number of this receive-payment object, which changes each time the object is modified. When updating this object, you must provide the most recent revisionNumber to ensure you're working with the latest data; otherwise, the update will return an error.

Example:

"1721172183"

customer

object

required

The customer or customer-job to which the payment for this receive-payment is credited.

Example:

{
  "id": "80000001-1234567890",
  "fullName": "Acme Corporation"
}

receivablesAccount

object | null

required

The Accounts-Receivable (A/R) account to which this receive-payment is assigned, used to track the amount owed. If not specified, QuickBooks Desktop will use its default A/R account.

IMPORTANT: If this receive-payment is linked to other transactions, this A/R account must match the receivablesAccount used in all linked transactions. For example, when refunding a credit card payment, the A/R account must match the one used in the original credit transactions being refunded.

Example:

{
  "id": "80000001-1234567890",
  "fullName": "Accounts-Receivable"
}

transactionDate

string

required

The date of this receive-payment, in ISO 8601 format (YYYY-MM-DD).

Example:

"2021-10-01T00:00:00.000Z"

refNumber

string | null

required

The case-sensitive user-defined reference number for this receive-payment, which can be used to identify the transaction in QuickBooks. This value is not required to be unique and can be arbitrarily changed by the QuickBooks user.

Example:

"PAYMENT-1234"

totalAmount

string

required

The total monetary amount of this receive-payment, represented as a decimal string.

Example:

"1000.00"

currency

object | null

required

The receive-payment's currency. For built-in currencies, the name and code are standard international values. For user-defined currencies, all values are editable.

Example:

{
  "id": "80000001-1234567890",
  "fullName": "USD"
}

exchangeRate

number | null

required

The market exchange rate between this receive-payment's currency and the home currency in QuickBooks at the time of this transaction. Represented as a decimal value (e.g., 1.2345 for 1 EUR = 1.2345 USD if USD is the home currency).

Example:

1.2345

totalAmountInHomeCurrency

string | null

required

The total monetary amount of this receive-payment converted to the home currency of the QuickBooks company file. Represented as a decimal string.

Example:

"1234.56"

paymentMethod

object | null

required

The receive-payment's payment method (e.g., cash, check, credit card).

Example:

{
  "id": "80000001-1234567890",
  "fullName": "Credit Card"
}

memo

string | null

required

A memo or note for this receive-payment that will be displayed at the beginning of reports containing details about this receive-payment.

Example:

"Payment received at store location - cash"

depositToAccount

object | null

required

The account where the funds for this receive-payment will be or have been deposited.

Example:

{
  "id": "80000001-1234567890",
  "fullName": "Undeposited Funds"
}

creditCardTransaction

object | null

required

The credit card transaction data for this receive-payment's payment when using QuickBooks Merchant Services (QBMS).

creditCardTransaction.request

object | null

required

The transaction request data originally supplied for this credit card transaction when using QuickBooks Merchant Services (QBMS).

creditCardTransaction.response

object | null

required

The transaction response data for this credit card transaction when using QuickBooks Merchant Services (QBMS).

creditCardTransaction.response.statusCode

number

required

The status code returned in the original QBMS transaction response for this credit card transaction.

Example:

0

creditCardTransaction.response.statusMessage

string

required

The status message returned in the original QBMS transaction response for this credit card transaction.

Example:

"Success"

creditCardTransaction.response.creditCardTransactionId

string

required

The ID returned from the credit card processor for this credit card transaction.

Example:

"1234567890"

creditCardTransaction.response.merchantAccountNumber

string

required

The QBMS account number of the merchant who is running this transaction using the customer's credit card.

Example:

"1234567890"

creditCardTransaction.response.authorizationCode

string | null

required

The authorization code returned from the credit card processor to indicate that this charge will be paid by the card issuer.

Example:

"1234567890"

creditCardTransaction.response.avsStreetStatus

enum<string> | null

required

Indicates whether the street address supplied in the transaction request matches the customer's address on file at the card issuer.

Available options:

fail,

not_available,

pass

Example:

"pass"

creditCardTransaction.response.avsZipStatus

enum<string> | null

required

Indicates whether the customer postal ZIP code supplied in the transaction request matches the customer's postal code recognized at the card issuer.

Available options:

fail,

not_available,

pass

Example:

"pass"

creditCardTransaction.response.cardSecurityCodeMatch

enum<string> | null

required

Indicates whether the card security code supplied in the transaction request matches the card security code recognized for that credit card number at the card issuer.

Available options:

fail,

not_available,

pass

Example:

"pass"

creditCardTransaction.response.reconBatchId

string | null

required

An internal ID returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.

Example:

"1234567890"

creditCardTransaction.response.paymentGroupingCode

number | null

required

An internal code returned by QuickBooks Merchant Services (QBMS) from the transaction request, needed for the QuickBooks reconciliation feature.

Example:

2

creditCardTransaction.response.paymentStatus

enum<string>

required

Indicates whether this credit card transaction is known to have been successfully processed by the card issuer.

Available options:

completed,

unknown

Example:

"completed"

creditCardTransaction.response.transactionAuthorizedAt

string

required

The date and time when the credit card processor authorized this credit card transaction.

Example:

"2024-01-01T12:34:56.000Z"

creditCardTransaction.response.transactionAuthorizationStamp

number | null

required

An internal value for this credit card transaction, needed for the QuickBooks reconciliation feature.

Example:

2

creditCardTransaction.response.clientTransactionId

string | null

required

A value returned from QBMS transactions for future use by the QuickBooks Reconciliation feature.

Example:

"1234567890"

unusedPayment

string | null

required

The amount of this receive-payment that remains unapplied to any transactions. This occurs in two cases: (1) When the sum of paymentAmount amounts in applyToTransactions is less than totalAmount, leaving a portion of the payment unused, or (2) When a payment is received that equals the exact amount of an invoice, but credits or discounts are also applied, resulting in excess payment.

Example:

"100.00"

unusedCredits

string | null

required

The amount of credit that remains unused after applying credits to this receive-payment. This occurs when the applyCredit.appliedAmount specified for a credit memo (applyCredit.creditMemoId) in the applyToTransactions array is less than the total available credit amount for that credit memo.

Example:

"100.00"

externalId

string | null

required

A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.

Example:

"12345678-abcd-1234-abcd-1234567890ab"

appliedToTransactions

object[]

required

The invoice(s) paid by this receive-payment.

appliedToTransactions.transactionId

string

required

The ID of the receivable transaction to which this payment is applied.

Example:

"123ABC-1234567890"

appliedToTransactions.transactionType

enum<string>

required

The type of transaction for this receivable transaction.

Available options:

ar_refund_credit_card,

bill,

bill_payment_check,

bill_payment_credit_card,

build_assembly,

charge,

check,

credit_card_charge,

credit_card_credit,

credit_memo,

deposit,

estimate,

inventory_adjustment,

invoice,

item_receipt,

journal_entry,

liability_adjustment,

paycheck,

payroll_liability_check,

purchase_order,

receive_payment,

sales_order,

sales_receipt,

sales_tax_payment_check,

transfer,

vendor_credit,

ytd_adjustment

Example:

"invoice"

appliedToTransactions.transactionDate

string

required

The date of this receivable transaction, in ISO 8601 format (YYYY-MM-DD).

Example:

"2021-10-01T00:00:00.000Z"

appliedToTransactions.refNumber

string | null

required

The case-sensitive user-defined reference number for this receivable transaction, which can be used to identify the transaction in QuickBooks. This value is not required to be unique and can be arbitrarily changed by the QuickBooks user.

Example:

"PAYMENT-1234"

appliedToTransactions.balanceRemaining

string | null

required

The outstanding balance of this receivable transaction after applying any credits or payments. Represented as a decimal string.

Example:

"100.00"

appliedToTransactions.amount

string | null

required

The monetary amount of this receivable transaction, represented as a decimal string.

Example:

"1000.00"

appliedToTransactions.discountAmount

string | null

required

The monetary amount by which to reduce the receivable transaction's receivable amount, represented as a decimal string.

Example:

"50.00"

appliedToTransactions.discountAccount

object | null

required

The financial account used to track this receivable transaction's discount.

Example:

{
  "id": "80000001-1234567890",
  "fullName": "Discount Account"
}

appliedToTransactions.discountClass

object | null

required

The class used to track this receivable transaction's discount.

Example:

{
  "id": "80000001-1234567890",
  "fullName": "Discounts"
}

appliedToTransactions.linkedTransactions

object[]

required

The receivable transaction's linked transactions, such as payments applied, credits used, or associated purchase orders.

IMPORTANT: You must specify the parameter includeLinkedTransactions when fetching a list of receivable transactions to receive this field because it is not returned by default.

appliedToTransactions.linkedTransactions.id

string

required

The unique identifier assigned by QuickBooks to this linked transaction. This ID is unique across all transaction types.

Example:

"123ABC-1234567890"

appliedToTransactions.linkedTransactions.objectType

string

required

The type of object. This value is always "qbd_linked_transaction".

Allowed value: "qbd_linked_transaction"

Example:

"qbd_linked_transaction"

appliedToTransactions.linkedTransactions.transactionType

enum<string>

required

The type of transaction for this linked transaction.

Available options:

ar_refund_credit_card,

bill,

bill_payment_check,

bill_payment_credit_card,

build_assembly,

charge,

check,

credit_card_charge,

credit_card_credit,

credit_memo,

deposit,

estimate,

inventory_adjustment,

invoice,

item_receipt,

journal_entry,

liability_adjustment,

paycheck,

payroll_liability_check,

purchase_order,

receive_payment,

sales_order,

sales_receipt,

sales_tax_payment_check,

transfer,

vendor_credit,

ytd_adjustment

Example:

"invoice"

appliedToTransactions.linkedTransactions.transactionDate

string

required

The date of this linked transaction, in ISO 8601 format (YYYY-MM-DD).

Example:

"2021-10-01T00:00:00.000Z"

appliedToTransactions.linkedTransactions.refNumber

string | null

required

The case-sensitive user-defined reference number for this linked transaction, which can be used to identify the transaction in QuickBooks. This value is not required to be unique and can be arbitrarily changed by the QuickBooks user.

Example:

"LINK-1234"

appliedToTransactions.linkedTransactions.linkType

enum<string> | null

required

Indicates the nature of the link between the transactions: amount denotes an amount-based link (e.g., an invoice linked to a payment), and quantity denotes a quantity-based link (e.g., an invoice created from a sales order based on the quantity of items received).

Available options:

amount,

quantity

Example:

"amount"

appliedToTransactions.linkedTransactions.amount

string | null

required

The monetary amount of this linked transaction, represented as a decimal string.

Example:

"1000.00"

customFields

object[]

required

The custom fields for the receive-payment object, added as user-defined data extensions, not included in the standard QuickBooks object.

Delete a purchase order Create a receive-payment

{
  "id": "123ABC-1234567890",
  "objectType": "qbd_receive_payment",
  "createdAt": "2021-10-01T17:34:56.000Z",
  "updatedAt": "2021-10-01T20:45:30.000Z",
  "revisionNumber": "1721172183",
  "customer": {
    "id": "80000001-1234567890",
    "fullName": "Acme Corporation"
  },
  "receivablesAccount": {
    "id": "80000001-1234567890",
    "fullName": "Accounts-Receivable"
  },
  "transactionDate": "2021-10-01T00:00:00.000Z",
  "refNumber": "PAYMENT-1234",
  "totalAmount": "1000.00",
  "currency": {
    "id": "80000001-1234567890",
    "fullName": "USD"
  },
  "exchangeRate": 1.2345,
  "totalAmountInHomeCurrency": "1234.56",
  "paymentMethod": {
    "id": "80000001-1234567890",
    "fullName": "Credit Card"
  },
  "memo": "Payment received at store location - cash",
  "depositToAccount": {
    "id": "80000001-1234567890",
    "fullName": "Undeposited Funds"
  },
  "creditCardTransaction": {
    "request": {
      "number": "xxxxxxxxxxxx1234",
      "expirationMonth": 12,
      "expirationYear": 2024,
      "name": "John Doe",
      "address": "1234 Main St, Anytown, USA, 12345",
      "postalCode": "12345",
      "commercialCardCode": "corporate",
      "transactionMode": "card_not_present",
      "transactionType": "charge"
    },
    "response": {
      "statusCode": 0,
      "statusMessage": "Success",
      "creditCardTransactionId": "1234567890",
      "merchantAccountNumber": "1234567890",
      "authorizationCode": "1234567890",
      "avsStreetStatus": "pass",
      "avsZipStatus": "pass",
      "cardSecurityCodeMatch": "pass",
      "reconBatchId": "1234567890",
      "paymentGroupingCode": 2,
      "paymentStatus": "completed",
      "transactionAuthorizedAt": "2024-01-01T12:34:56.000Z",
      "transactionAuthorizationStamp": 2,
      "clientTransactionId": "1234567890"
    }
  },
  "unusedPayment": "100.00",
  "unusedCredits": "100.00",
  "externalId": "12345678-abcd-1234-abcd-1234567890ab",
  "appliedToTransactions": [
    {
      "transactionId": "123ABC-1234567890",
      "transactionType": "invoice",
      "transactionDate": "2021-10-01T00:00:00.000Z",
      "refNumber": "PAYMENT-1234",
      "balanceRemaining": "100.00",
      "amount": "1000.00",
      "discountAmount": "50.00",
      "discountAccount": {
        "id": "80000001-1234567890",
        "fullName": "Discount Account"
      },
      "discountClass": {
        "id": "80000001-1234567890",
        "fullName": "Discounts"
      },
      "linkedTransactions": [
        {
          "id": "123ABC-1234567890",
          "objectType": "qbd_linked_transaction",
          "transactionType": "invoice",
          "transactionDate": "2021-10-01T00:00:00.000Z",
          "refNumber": "LINK-1234",
          "linkType": "amount",
          "amount": "1000.00"
        }
      ]
    }
  ],
  "customFields": [
    {
      "ownerId": "0",
      "name": "Customer Rating",
      "type": "string_1024_type",
      "value": "Premium"
    }
  ]
}