Create Checkout

post

https://api-sandbox.paymentlabs.io/checkouts

Creates a checkout: a request for one payment of a fixed amount from one buyer.

Use it from your server for every one-time payment. Send the buyer to links.checkout (hosted page), embed
links.embeddable in an iframe, or pass the checkout id to the Payin SDK. You can also charge a saved instrument or a
payment terminal yourself with /reference/charge-checkout.

Permission: Merchant Write.

Rules

alias, amount, currency, buyer.email, termsOfServiceUrl and privacyPolicyUrl are required. Unknown fields are rejected.
The buyer is identified by buyer.email within your account. The first checkout for a new email creates the buyer;
later checkouts reuse it, so buyerId is stable per email.
expiresAt accepts a date or a date-time. The checkout is payable until 23:59:59 of that day in userTimezone
(UTC by default). It defaults to one year from now and must not be in the past.
An amount of 0 saves the buyer's card or bank account without charging it. The buyer must sign in, so
authenticationOptions defaults to AUTHENTICATED_ONLY and any other value is rejected.

The checkout starts in PENDING. Nothing is charged and no webhook is sent until a charge is attempted.

Errors

400 CURRENCY_NOT_ALLOWED: this currency is not enabled for your account. Use another currency or ask Payment Labs to enable it.
400 MAXIMUM_AMOUNT_EXCEEDED: the amount is above your limit for this currency (maxAmount). Lower it or split the payment.
400 VALIDATION_ERROR: a field is invalid. details.expiresAt with INVALID_FIELD_DATE means the expiry date is in the past.
On details.statementAlias: INVALID_CHARACTERS (a character other than letters, digits, spaces, ., , or -),
INVALID_FIELD_LENGTH_TOO_LONG (the descriptor would be over 22 characters with your prefix) or NOT_ALLOWED_FIELD
(soft descriptors are not enabled for your account, or not available for this checkout). On details.threeDSecureMethod:
INVALID_FIELD_ENUM_TYPE (not a known method) or VALUE_NOT_IN_ALLOWED_LIST (the method is not enabled for your account).
404 NOT_FOUND: your merchant account could not be loaded. Contact Payment Labs.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

The fields accepted by Create Checkout. Any other field is rejected.

alias

string

required

Short name of what the buyer pays for, shown on the checkout page and in your lists. Letters A–Z, digits, spaces and
common punctuation; accented letters are rejected.

referenceId

string

Your own identifier for this payment, such as an order number, to match the checkout with your records. Same characters as alias.

description

string

Longer description of what the buyer pays for, shown on the checkout page.

statementAlias

string

Text the buyer sees on their card statement after your merchant prefix, as PREFIX*STATEMENT ALIAS. Accepted only when
soft descriptors are enabled for your account. Letters, digits, spaces and ., , or - only. The whole descriptor,
prefix and * included, can be at most 22 characters. Card issuers may still shorten or uppercase it.

termsOfServiceUrl

string

required

URL of your terms of service, linked on the checkout page.

privacyPolicyUrl

string

required

URL of your privacy policy, linked on the checkout page.

buyer

object

required

The person who pays.

redirectLinks

object

Where the hosted checkout page sends the buyer after the payment succeeds, fails or the checkout expires.

expiresAt

string

Last day the checkout can be paid, as a date (2026-12-31) or date-time. The checkout stays payable until 23:59:59 of
that day in userTimezone. Defaults to one year from today. Cannot be in the past.

userTimezone

string

IANA time zone used to read expiresAt, for example America/New_York. Defaults to UTC.

currency

string

required

ISO 4217 currency code of amount, for example USD. Must be a currency your account accepts; see Get Merchant.

amount

number

required

Amount to charge, in decimal notation in currency (10.52). 0 creates a checkout that saves the buyer's card or bank
account without charging it.

authenticationOptions

string

enum

How the buyer identifies themselves on the checkout page: ALL (guest or signed in, the default), GUEST_ONLY or
AUTHENTICATED_ONLY. A zero-amount checkout requires AUTHENTICATED_ONLY and uses it when you omit the field.

Allowed:

threeDSecureMethod

string

enum

How strictly 3D Secure is enforced for card payments on this checkout: REQUIRE_3DS (the charge fails if 3D Secure
cannot be completed), PREFER_3DS (the charge fails if 3D Secure is attempted and fails, but goes ahead when the card
does not support it) or SKIP_3DS (3D Secure is not attempted). Omit it to use your account's default. Only a method
enabled for your account is accepted; any other value is rejected rather than replaced.

Allowed:

Responses

200The checkout was created in PENDING.

404The resource does not exist in your account.

422The request body is not valid JSON, or is not a JSON object. Send Content-Type: application/json with a JSON object body.