Menu

Payment Collections API Routes

A payment collection is one or more payments of an order. They're also used for outstanding payments due to order exchanges or claims.

Every purchase or request for payment starts with a payment collection.

A payment collection holds the payment sessions used to authorize the payment amount, and the payments to be captured / refunded.

These API routes allow admin users to manage payment collections.

POST /admin/payment-collections#

Create Payment Collection

Create a payment collection.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

order_idstring
The ID of the associated order.
amountnumber
The amount to be paid.

Request examples

Responses

200 OK

payment_collectionobject
The payment collection's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/payment-collections/{id}#

Delete a Payment Collection

Delete a payment collection.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The payment collection's ID.

Request examples

Responses

200 OK

idstring
The payment collection's ID.
objectstring
The name of the object that was deleted.

Default: "payment-collection"

deletedboolean
Whether the object was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/payment-collections/{id}/mark-as-paid#

Mark a Payment Collection as Paid

Mark a payment collection as paid. This creates and authorizes a payment session, then capture its payment, using the manual payment provider.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The payment collection's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

order_idstring
The ID of the order associated with the payment collection.
provider_idstringOptional
The ID of the payment provider to use for marking the payment collection as paid. If not provided, the system provider will be used.

Request examples

Responses

200 OK

payment_collectionobject
The payment collection's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • payment.captured: Emitted when a payment is captured.

POST /admin/payment-collections/{id}/payment-sessions#

Initialize Payment Session in Payment Collection

Initialize a Payment Session in a payment collection. This is useful for orders placed outside the checkout flow, such as draft orders, or when a payment session needs to be re-initialized for an existing payment collection.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The ID of the payment collection.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. If a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. Without prefix it will replace the entire default fields.

Request body (application/json)

provider_idstring
The ID of the payment provider to initialize the session with.
Example: pp_stripe_stripe
dataobjectOptional
Any data necessary for the payment provider to process the payment.

Request examples

Responses

200 OK

payment_collectionobject
The payment collection's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page