Payments

Record, read, update and delete payments against invoices, and manage the notes and files on them.

A payment records money received against one or more invoices, by processor, credit note or gift certificate. This area has 15 endpoints: create, read, update and delete payments, list them by invoice or order, and manage their notes and files. Every SDK supports all of them.

Creating a payment can charge a card. If a payment_applied entry names a processor that holds a saved card token, the card is charged.

At a glance

Endpoint	Method	Path	What it does
List payments	GET	/payments	Returns one page of payments.
Create a payment	POST	/payments	Records a payment against one or more invoices and returns it.
List notes across all payments	GET	/payments/notes	Returns one page of notes from every payment.
Delete a payment	DELETE	/payments/{payment_id}	Deletes a payment.
Update a payment	PATCH	/payments/{payment_id}	Changes a payment’s note and returns the payment.
Retrieve a payment	GET	/payments/{payment_id}	Returns one payment by its id.
List an invoice’s payments	GET	/invoices/{invoice_id}/payments	Returns one page of the payments made against an invoice.
List an order’s payments	GET	/orders/{order_id}/payments	Returns one page of the payments made against an order’s invoices.
List a payment’s notes	GET	/payments/{payment_id}/notes	Returns one page of the notes on a payment.
Create a payment note	POST	/payments/{payment_id}/notes	Adds a note, and optionally a file, to a payment and returns the note.
Retrieve a payment note	GET	/payments/{payment_id}/notes/{payment_note_id}	Returns one note on a payment.
Delete a payment note	DELETE	/payments/{payment_id}/notes/{payment_note_id}	Deletes a note, and its files, from a payment.
Retrieve a payment note file	GET	/payments/{payment_id}/notes/{payment_note_id}/files/{payment_file_id}	Returns the details of one file attached to a payment note, not the file’s contents.
Retrieve a payment through an invoice	GET	/invoices/{invoice_id}/payments/{payment_id}	Returns one payment by its id, reached through an invoice.
List a payment note’s files	GET	/payments/{payment_id}/notes/{payment_note_id}/files	Returns the files attached to a note on a payment.

Before you call

Register your API credentials once when your app starts, as shown in Authentication. Every SDK sample on these pages then gets its client in one line. With cURL, send the access token in an Authorization header: Authorization: Bearer $ACCESS_TOKEN.

Things to know

• Write bodies go under a payment key. Creating a payment accepts only id, date, origin, payment_note, note, invoices, payment_applied, credit_applied, gift_certificates and custom_attributes; any other key returns 400.
• A payment’s invoices name each invoice by its inv_ uuid. Creating a payment takes the invoice’s id, such as INV-0001, but reads return the inv_ uuid in that field.
• Listings page by cursor. Records are under data. Pass pagination.next_cursor back as cursor while pagination.has_more is true.
• Deleting a note takes its uuid, not its id. Reads take the note’s id; the delete takes the hex part of that id as a dashed uuid.
• Reading a payment through an invoice does not check that the payment belongs to it. Any payment is returned under any invoice that exists.
• Note text goes in a form field. Creating a note sends a multipart form with the text as note and any attachment as file.