Create Checkout Session - Clink Documentation

Authorizations

X-API-KEY

string

header

required

Your secret API key obtained from the Clink dashboard (Developers section)

Headers

X-Timestamp

string

required

Current timestamp in milliseconds since Unix epoch (required for request signing)

Example:

"1783513683000"

Body

application/json

Parameters required to initialize a new checkout session. Provide at least one of customerId, customerEmail, or referenceCustomerId. If all three are empty, the request fails with CUSTOMER_NOT_FOUND. When customerId is provided, it is the primary identifier and customerEmail/referenceCustomerId must match the same customer. Without customerId, Clink resolves the customer by customerEmail and/or referenceCustomerId; when both are provided, they must resolve to the same customer or the request fails with CUSTOMER_IDENTIFIER_NOT_MATCHED.

originalAmount

number

required

Total transaction amount in the specified currency (must be greater than 0)

Required range: x > 0

originalCurrency

string

required

Three-letter ISO currency code for the transaction (e.g., USD, EUR, GBP)

customerId

string

Existing customer's unique identifier. At least one of customerId, customerEmail, or referenceCustomerId is required. When provided, customerId is the primary identifier and customerEmail/referenceCustomerId must match the same customer

Minimum string length: 1

customerEmail

string

Customer's email address. At least one of customerId, customerEmail, or referenceCustomerId is required. When customerId is not provided, Clink uses customerEmail and/or referenceCustomerId to resolve the customer. A new customer may be created when no existing customer matches

Minimum string length: 1

referenceCustomerId

string

Merchant-side customer ID used to locate, validate, create, or bind a customer. At least one of customerId, customerEmail, or referenceCustomerId is required. If all three are empty, the request fails with CUSTOMER_NOT_FOUND

Minimum string length: 1

merchantReferenceId

string

Your internal reference ID for tracking (non-unique identifier, does not guarantee idempotency)

priceId

string

Unique identifier of the predefined price configuration from your dashboard

productId

string

Unique identifier of the product configured in your dashboard

scheduledPhases

object[]

Optional top-level list of scheduled subscription plan changes for subscription checkout sessions. The initial subscription uses productId and priceId; each scheduled phase references an existing subscription price snapshot and takes effect at a future billing period boundary. One-time price snapshots are rejected. sequence and effectiveCycle must be strictly increasing.

Maximum array length: 10

Show child attributes

uiMode

enum<string>

Checkout UI mode. Use hostedPage for hosted redirect checkout and elements for embedded checkout. When set to elements, returnUrl is required.

Available options:

elements,

hostedPage

returnUrl

string

Return URL for embedded checkout. Required when uiMode is elements. Clink replaces {ELEMENTS_SESSION_ID} in the URL with the created session ID before returning control to your site. Example: https://merchant.example.com/complete.html?session_id={ELEMENTS_SESSION_ID}

successUrl

string

URL where customers will be redirected after successful payment completion

cancelUrl

string

URL where customers will be redirected if they cancel the checkout process

paymentMethodType

enum<string>

The default selected payment method for created checkout session. Recommended if you know customer preference in advance

Available options:

CARD,

CASHAPP,

WECHAT,

KAKAO,

PIX,

ALIPAY,

UPI,

PAYPAL,

GOOGLEPAY,

APPLEPAY,

QRIS,

GCASH

paymentMethodTypeBlackList

enum<string>[]

List of payment method types to be excluded from the checkout session. Recommended if you know customer preference in advance. Supported values: CARD, CASHAPP, WECHAT, KAKAO, PIX, ALIPAY, UPI, PAYPAL, GOOGLEPAY, APPLEPAY, QRIS, GCASH

Available options:

CARD,

CASHAPP,

WECHAT,

KAKAO,

PIX,

ALIPAY,

UPI,

PAYPAL,

GOOGLEPAY,

APPLEPAY,

QRIS,

GCASH

directPaymentQrCodePaymentMethodType

enum<string>

Controls whether the QR code payment flow is launched directly when opening checkout.

Currently supports CASHAPP and QRIS.

This parameter takes effect only when:

paymentMethodType is set to the same value as directPaymentQrCodePaymentMethodType
The selected payment method is available in the checkout session

Behavior:

When effective, checkout directly initiates the QR code payment flow
In no-password scenarios, payment is not automatically completed

Ignored when:

The selected payment method is not available in checkout
paymentMethodType does not match directPaymentQrCodePaymentMethodType

Allowed values:

CASHAPP
QRIS

Available options:

CASHAPP,

QRIS

priceDataList

object[]

List of product pricing details for one-time purchases. Use this when creating transactions without pre-configured products

Show child attributes

allowPromotionCodes

boolean

Set to true to enable customers to enter promotion codes during checkout

showPromotionCode

boolean

default:true

Controls whether the promotion code input is shown in checkout. Defaults to true. Set to false with allowPromotionCodes=true and promotionCode to apply a hidden promotion code without showing the input box.

promotionCode

string

Pre-filled promotion code for the checkout session. Only effective when allowPromotionCodes is set to true. Required when showPromotionCode is false

metadata

object

Merchant metadata. Values must be strings. Maximum 20 keys. Key length must be 40 characters or fewer and string value length must be 500 characters or fewer.

Show child attributes

Response

Checkout session created successfully

code

integer<int32>

msg

string

data

object

Details of the created checkout session

Show child attributes