Payments resource

What it is

Customer payments received (QuickBooks ReceivePayment transaction).

Payments live in the connected QuickBooks Desktop company file. Every call names the file with the X-End-User-Id header, and every field name below is the JSON key you send and receive. Behaviour on this page is validated against the QuickBooks Web Connector simulator and not yet against a real QuickBooks Desktop install. The acceptance run on a Windows rig is a launch step.

Endpoints

GET https://wirebook.buffersoltech.com/v1/qbd/payments lists payments. Filters: customer, refNumber, modifiedSince, includeLines, plus limit (1 to 100, default 25) and cursor. The response has data, hasMore, nextCursor and cursorExpiresAt.

GET https://wirebook.buffersoltech.com/v1/qbd/payments/{id} returns one record by its txnId.

POST https://wirebook.buffersoltech.com/v1/qbd/payments creates a record and returns 201 with the created object. Send an Idempotency-Key header on every write.

Update is not available yet for payments: POST https://wirebook.buffersoltech.com/v1/qbd/payments/{id} returns 405 with the error code not_supported.

Create fields

Fields for POST https://wirebook.buffersoltech.com/v1/qbd/payments. Unknown fields are rejected with 400 invalid_request and the JSON path of the first problem. Lengths are the QuickBooks limits.

field                         type               required  max length
customerRef                   object             yes
customerRef.listId            string             no        36
customerRef.fullName          string             no        209
aRAccountRef                  object             no
aRAccountRef.listId           string             no        36
aRAccountRef.fullName         string             no        209
txnDate                       date (YYYY-MM-DD)  no
refNumber                     string             no        20
totalAmount                   number             yes
paymentMethodRef              object             no
paymentMethodRef.listId       string             no        36
paymentMethodRef.fullName     string             no        209
memo                          string             no        4095
depositToAccountRef           object             no
depositToAccountRef.listId    string             no        36
depositToAccountRef.fullName  string             no        209
appliedTo[]                   array              no
appliedTo[].txnId             string             yes
appliedTo[].paymentAmount     number             no

Update fields

There are none yet. Payments cannot be updated through the API, and POST https://wirebook.buffersoltech.com/v1/qbd/payments/{id} returns 405 not_supported.

Example with curl

Create a record with the required fields. Replace the key and the end user id with your own.

curl -X POST https://wirebook.buffersoltech.com/v1/qbd/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "X-End-User-Id: acme-42" \
  -H "Idempotency-Key: payments-create-1" \
  -H "Content-Type: application/json" \
  -d '{"customerRef":{"listId":"80000001-1"},"totalAmount":100}'

Example with TypeScript

Typed with the models generated from the same field specs. create returns the record, or a Queued marker if QuickBooks has not answered yet.

import { Wirebook } from "@wirebook/sdk";

const qb = new Wirebook({ apiKey: process.env.WIREBOOK_API_KEY! }).forUser("acme-42");

const created = await qb.qbd.payments.create({
  "customerRef": {
    "listId": "80000001-1"
  },
  "totalAmount": 100
});

for await (const row of qb.qbd.payments.iterate({ limit: 100 })) {
  console.log(row);
}

Example with Python

The Python SDK takes the same JSON keys, as typed dictionaries.

import os
from wirebook import Wirebook

qb = Wirebook(os.environ["WIREBOOK_API_KEY"]).for_user("acme-42")

created = qb.qbd.payments.create({
    "customerRef": {
        "listId": "80000001-1",
    },
    "totalAmount": 100,
})

for row in qb.qbd.payments.iterate(limit=100):
    print(row)

Waiting for QuickBooks

A request waits for QuickBooks to answer for 55 seconds. If QuickBooks has not answered by then, the API returns 202 with a request id and a Location header, and you poll GET /v1/requests/{id}. Send Prefer: respond-async to get the 202 straight away without waiting. The company file must be open and polling, see Troubleshooting.

If a write times out after it was sent, its state becomes outcome_unknown. Query by RefNumber before you retry, and do not retry blindly.