Skip to main content
POST
/
checkout
/
session
curl --request POST \
  --url https://uat-api.clinkbill.com/api/checkout/session \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-Timestamp: <api-key>' \
  --data '
{
  "customerId": "customer_id",
  "originalAmount": 4.99,
  "originalCurrency": "USD",
  "priceId": "price_id",
  "productId": "prd_id",
  "uiMode": "hostedPage"
}
'
{
  "code": 123,
  "msg": "<string>",
  "data": {
    "sessionId": "sess_abc123xyz",
    "tokenValue": "<string>",
    "customerId": "cus_12345",
    "originalAmount": 99.99,
    "originalCurrency": "USD",
    "returnUrl": "<string>",
    "url": "https://uat-checkout.clinkbill.com/pay/sess_abc123xyz",
    "merchantReferenceId": "order_ref_123",
    "expireTime": "2023-11-07T05:31:56Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-KEY
string
header
required

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

​
X-Timestamp
string
header
required

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

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

​
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 only supports CASHAPP.

This parameter takes effect only when:

  • paymentMethodType is set to CASHAPP
  • CASHAPP 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:

  • CASHAPP is not available in checkout
  • paymentMethodType is not CASHAPP

Allowed values:

  • CASHAPP
Available options:
CASHAPP
​
priceDataList
object[]

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

​
allowPromotionCodes
boolean

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

​
promotionCode
string

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

Response

Checkout session created successfully

​
code
integer<int32>
​
msg
string
​
data
object

Details of the created checkout session