Update a receive-payment - Conductor Docs

QuickBooks Desktop API

General

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

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

Items

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

POST

quickbooks-desktop

receive-payments

{id}

import Conductor from 'conductor-node';

const client = new Conductor({
  apiKey: process.env['CONDUCTOR_SECRET_KEY'], // This is the default and can be omitted
});

async function main() {
  const receivePayment = await client.qbd.receivePayments.update('123ABC-1234567890', {
    revisionNumber: '1721172183',
    conductorEndUserId: 'end_usr_1234567abcdefg',
  });

  console.log(receivePayment.id);
}

main();

{
  "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"
    }
  ]
}

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

customerId

string

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

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.

transactionDate

string

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

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.

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

paymentMethodId

string

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

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.

depositToAccountId

string

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

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

string

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

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

string

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

creditCardTransaction.response.transactionAuthorizationStamp

number

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

creditCardTransaction.response.clientTransactionId

string

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

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

Response

200 - application/json

Returns the updated receive-payment.

string

required

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

objectType

string

required

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

Allowed value: "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.

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.

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.

customer

object

required

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

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.

transactionDate

string

required

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

refNumber

string | null

required

totalAmount

string

required

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

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.

exchangeRate

number | null

required

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.

paymentMethod

object | null

required

The receive-payment's payment method (e.g., cash, check, 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.

depositToAccount

object | null

required

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

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.

creditCardTransaction.response.statusMessage

string

required

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

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

string

required

The date and time when the credit card processor authorized 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.clientTransactionId

string | null

required

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

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.

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.

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.

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.

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

appliedToTransactions.transactionDate

string

required

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

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

string | null

required

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

appliedToTransactions.amount

string | null

required

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

appliedToTransactions.discountAmount

string | null

required

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

appliedToTransactions.discountAccount

object | null

required

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

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.

customFields

object[]

required

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

Create a receive-payment Retrieve a receive-payment

import Conductor from 'conductor-node';

const client = new Conductor({
  apiKey: process.env['CONDUCTOR_SECRET_KEY'], // This is the default and can be omitted
});

async function main() {
  const receivePayment = await client.qbd.receivePayments.update('123ABC-1234567890', {
    revisionNumber: '1721172183',
    conductorEndUserId: 'end_usr_1234567abcdefg',
  });

  console.log(receivePayment.id);
}

main();

{
  "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"
    }
  ]
}