Update a receive-payment

Authorizations

Authorization

string

header

required

Your Conductor secret key using Bearer auth (e.g., "Authorization: Bearer {{YOUR_SECRET_KEY}}").

Headers

Conductor-End-User-Id

string

required

The ID of the EndUser to receive this request (e.g., "Conductor-End-User-Id: {{END_USER_ID}}").

Path Parameters

string

required

The QuickBooks-assigned unique identifier of the receive-payment to update.

Body

application/json

revisionNumber

string

required

The current revision number of the receive-payment object you are updating, which you can get by fetching the object first. Provide the most recent revisionNumber to ensure you're working with the latest data; otherwise, the update will return an error.

applyToTransactions

object[]

The invoices to be paid by this receive-payment. This will create a link between this receive-payment and the specified invoices.

IMPORTANT: In each applyToTransactions object, you must specify either paymentAmount, applyCredits, discountAmount, or any combination of these; if none of these are specified, you will receive an error for an empty transaction.

IMPORTANT: The target invoice must have isPaid=false, otherwise, QuickBooks will report this object as "cannot be found".

creditCardTransaction

object

The credit card transaction data for this receive-payment's payment when using QuickBooks Merchant Services (QBMS). If specifying this field, you must also specify the paymentMethod field.

creditCardTransaction.request

object

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

creditCardTransaction.response

object

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

creditCardTransaction.response.authorizationCode

string

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

creditCardTransaction.response.avsStreetStatus

enum<string>

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

creditCardTransaction.response.avsZipStatus

enum<string>

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

creditCardTransaction.response.cardSecurityCodeMatch

enum<string>

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

creditCardTransaction.response.clientTransactionId

string

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

creditCardTransaction.response.creditCardTransactionId

string

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

creditCardTransaction.response.merchantAccountNumber

string

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

creditCardTransaction.response.paymentGroupingCode

number

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

creditCardTransaction.response.paymentStatus

enum<string>

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

Available options:

completed,

unknown

creditCardTransaction.response.reconBatchId

string

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

creditCardTransaction.response.statusCode

number

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

creditCardTransaction.response.statusMessage

string

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

creditCardTransaction.response.transactionAuthorizationStamp

number

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

creditCardTransaction.response.transactionAuthorizedAt

string

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

customerId

string

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

depositToAccountId

string

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

exchangeRate

number

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).

memo

string

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

paymentMethodId

string

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

receivablesAccountId

string

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.

refNumber

string

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.

totalAmount

string

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

NOTE: The sum of the paymentAmount amounts in the applyToTransactions array cannot exceed the totalAmount, or you will receive an error.

transactionDate

string

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

Response

200 - application/json

appliedToTransactions

object[]

required

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

appliedToTransactions.amount

string | null

required

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

appliedToTransactions.balanceRemaining

string | null

required

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

appliedToTransactions.discountAccount

object | null

required

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

appliedToTransactions.discountAmount

string | null

required

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

appliedToTransactions.discountClass

object | null

required

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

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.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.

appliedToTransactions.transactionDate

string

required

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

appliedToTransactions.transactionId

string

required

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

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

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.

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.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.

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

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

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

creditCardTransaction.response.clientTransactionId

string | null

required

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

creditCardTransaction.response.creditCardTransactionId

string

required

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

creditCardTransaction.response.merchantAccountNumber

string

required

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

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.

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

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.

creditCardTransaction.response.statusCode

number

required

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

creditCardTransaction.response.statusMessage

string

required

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

creditCardTransaction.response.transactionAuthorizationStamp

number | null

required

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

creditCardTransaction.response.transactionAuthorizedAt

string

required

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

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.

customer

object

required

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

customFields

object[]

required

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

depositToAccount

object | null

required

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

exchangeRate

number | null

required

externalId

string | null

required

A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system.

string

required

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

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.

objectType

string

required

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

Allowed value: "qbd_receive_payment"

paymentMethod

object | null

required

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

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.

refNumber

string | null

required

revisionNumber

string

required

The current 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.

totalAmount

string

required

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

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.

transactionDate

string

required

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

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.

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.

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.

QuickBooks Desktop API

Core Resources

Transactions

Items

Authorizations

Headers

Path Parameters

Body

Response