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

Example:

"end_usr_1234567abcdefg"

Path Parameters

​
id
string
required

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

Example:

"123ABC-1234567890"

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.

Example:

"1721172183"

​
customerId
string

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

Example:

"80000001-1234567890"

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

Example:

"80000001-1234567890"

​
transactionDate
string

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

Example:

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

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

Example:

"PAYMENT-1234"

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

Example:

"1000.00"

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

Example:

1.2345

​
paymentMethodId
string

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

Example:

"80000001-1234567890"

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

Example:

"Payment received at store location - cash"

​
depositToAccountId
string

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

Example:

"80000001-1234567890"

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

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

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

​
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-paymentRetrieve a receive-payment