Checkout sessions
A checkout session is a hosted page where one buyer pays one transaction. Times on checkout sessions are epoch milliseconds.
Read Checkout sessions for the model and the lifecycle. For a walkthrough, read Accept a payment with hosted checkout.
The checkout session object#
A hosted checkout page for one transaction. Times are epoch milliseconds.
Attributes
- idstring
- objectTypestring
- accountIdstring
- modestring
One of:
payment - statusstring
The state of the session.
openaccepts changes.payment_pendingwaits for the payment result.completeandcancelledare final.expiredpassed its expiry time.One of:
open,payment_pending,complete,expired,cancelled - paymentStatusstring
One of:
unpaid,pending,paid,failed,cancelled A summary of the transaction for display. The transaction holds the authoritative amounts.
Child attributes of
transaction- idstring
- revisioninteger
The transaction revision that this summary shows.
- statestring
The transaction state when this summary was made.
One of:
draft,ready,processing,completed,past_due,canceled - currencystring
Pattern
^[A-Z]{3}$. - subtotalobject
An amount in minor units with its currency.
Child attributes of
subtotal- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- discountobject
An amount in minor units with its currency.
Child attributes of
discount- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- netobject
An amount in minor units with its currency.
Child attributes of
net- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- taxobject
An amount in minor units with its currency.
Child attributes of
tax- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- totalobject
An amount in minor units with its currency.
Child attributes of
total- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- amountCollectedobject
An amount in minor units with its currency.
Child attributes of
amountCollected- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- amountRemainingobject
An amount in minor units with its currency.
Child attributes of
amountRemaining- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- linesarray of objects
Child attributes of
lines- idstring
- namestring
Absent when the product has no description.
- quantityinteger
- taxBehaviorstring
One of:
inclusive,exclusive - unitAmountobject
An amount in minor units with its currency.
Child attributes of
unitAmount- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- subtotalobject
An amount in minor units with its currency.
Child attributes of
subtotal- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- discountobject
An amount in minor units with its currency.
Child attributes of
discount- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- netobject
An amount in minor units with its currency.
Child attributes of
net- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- taxobject
An amount in minor units with its currency.
Child attributes of
tax- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- totalobject
An amount in minor units with its currency.
Child attributes of
total- amountMinorinteger
The amount in the smallest unit of the currency, for example cents.
- currencystring
An ISO 4217 alphabetic currency code.
Pattern
^[A-Z]{3}$.
- urlstring (URL)
The hosted checkout page. Only the create response includes the access token in this URL.
- expiresAtinteger
- createdAtinteger
- customerTypestring
businessonce the buyer gives business details.One of:
consumer,business The branding of the hosted page, frozen when the session was created.
- metadataobject
Your own key-value pairs. At most 50 entries. A key has at most 64 characters, a value at most 512.
The response can include fields that this page does not list. Ignore fields that you do not know.
Create a checkout session#
POST/
Creates an open checkout session and returns the url of its hosted page. Send the buyer to that URL.
Give exactly one of these:
transactionId: adraftorreadytransaction that you created.transactionDraft: catalog prices and quantities. Merxian creates the transaction.
The url in this response carries the access token of the hosted page. Later reads return the URL without the token. Keep the URL from this response.
Requires the checkout:write scope.
Headers
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.
Request body
- modestring
One of:
paymentDefault
payment. - transactionIdstring
A
draftorreadytransaction of your account. - transactionDraftobject
Catalog prices from which Merxian creates a new draft transaction.
Child attributes of
transactionDraft Where to send the buyer after payment. Must be
https, except for a localhost URL in local development.At most 2048 characters.
Where to send the buyer after a cancelled or failed payment.
At most 2048 characters.
- customerEmailstring (email)
Prefills the buyer email.
- customerNamestring
At most 256 characters.
- customerCountrystring
A 2-letter ISO country code. Enables tax calculation at creation.
Pattern
^[A-Za-z]{2}$. - clientReferenceIdstring
Your own reference, returned with the session and its events.
At most 200 characters.
- allowPromotionCodesboolean
Lets the buyer enter a promotion code on the hosted page.
Default
false. - collectBillingAddressboolean
Shows the billing address form. The page also shows it when the transaction has platform-issued invoices, because such an invoice needs the billing address.
Default
false. - collectShippingAddressboolean
Default
false. - localestring
The hosted checkout page is in English only.
- metadataobject
Your own key-value pairs. At most 50 entries. A key has at most 64 characters, a value at most 512.
- expiresAtinteger
When the session expires, in epoch milliseconds. Must be 30 minutes to 7 days from now. Defaults to 24 hours from now.
Returns
201The checkout session object.
Errors
| Status | Meaning |
|---|---|
| 400 | The request is not valid. See the error body for the field at fault. |
| 401 | The API key is missing, malformed, revoked, or unknown. |
| 403 | The API key does not hold the scope that this operation requires. |
| 404 | The resource does not exist, or it belongs to another account. |
| 409 | The request conflicts with the current state of the resource, or the idempotency key was used with a different request. |
| 500 | An unexpected error occurred. Retry with the same idempotency key. |
| 502 | Merxian could not complete the request. Retry with the same idempotency key. |
| 503 | Merxian could not verify the API key. Retry later. |
The error reference lists the codes in each error body.
Webhook events
This call can cause these events, later and in any order:
Retrieve a checkout session#
GET/
Returns one checkout session with a summary of its transaction. A session after its expiry time reads as expired.
Requires the checkout:read scope.
Path parameters
The checkout session id.
Returns
200The checkout session object.
Errors
| Status | Meaning |
|---|---|
| 401 | The API key is missing, malformed, revoked, or unknown. |
| 403 | The API key does not hold the scope that this operation requires. |
| 404 | The resource does not exist, or it belongs to another account. |
| 500 | An unexpected error occurred. Retry with the same idempotency key. |
| 502 | Merxian could not complete the request. Retry with the same idempotency key. |
| 503 | Merxian could not verify the API key. Retry later. |
The error reference lists the codes in each error body.
List checkout sessions#
GET/
Returns one page of your checkout sessions, newest first.
Requires the checkout:read scope.
Query parameters
- limitinteger
How many sessions to return. A value outside 1-100 fails with
400.1 to 100. Default
20. - cursorstring
An opaque cursor taken from a previous response's
pagination.nextCursor. - statusstring
Keep only sessions in this status.
One of:
open,payment_pending,complete,expired,cancelled
Returns
200A page of checkout session objects, in data, with pagination.
Errors
| Status | Meaning |
|---|---|
| 400 | The request is not valid. See the error body for the field at fault. |
| 401 | The API key is missing, malformed, revoked, or unknown. |
| 403 | The API key does not hold the scope that this operation requires. |
| 500 | An unexpected error occurred. Retry with the same idempotency key. |
| 502 | Merxian could not complete the request. Retry with the same idempotency key. |
| 503 | Merxian could not verify the API key. Retry later. |
The error reference lists the codes in each error body.
Expire a checkout session#
POST/
Closes an open or payment_pending session and cancels a payment that the session started. After this, the buyer cannot pay on the hosted page.
An expired session returns the same session again. A complete or cancelled session returns 409.
Requires the checkout:write scope.
Path parameters
The checkout session id.
Headers
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.
Returns
200The checkout session object.
Errors
| Status | Meaning |
|---|---|
| 400 | The request is not valid. See the error body for the field at fault. |
| 401 | The API key is missing, malformed, revoked, or unknown. |
| 403 | The API key does not hold the scope that this operation requires. |
| 404 | The resource does not exist, or it belongs to another account. |
| 409 | The request conflicts with the current state of the resource, or the idempotency key was used with a different request. |
| 500 | An unexpected error occurred. Retry with the same idempotency key. |
| 502 | Merxian could not complete the request. Retry with the same idempotency key. |
| 503 | Merxian could not verify the API key. Retry later. |
The error reference lists the codes in each error body.
Webhook events
This call can cause these events, later and in any order: