Checkout Session

Overview

A Checkout Session is dynamically generated through the POST Session API. The API provides a time-limited link to a Clink-hosted checkout page with pre-filled customer information. We recommend creating a new Session for each customer payment intention. Each checkout session can accommodate multiple payment attempts until a successful transaction is completed. Successful transactions can represent either one-time purchases or subscriptions.

Session Data

Status

Open: The checkout session is created but no successful payment has been received
Complete: The checkout session has concluded with a successful payment
Expired: The checkout session has expired and no further payment attempts are allowed

Product & Price

If you have configured products and prices in the dashboard, you can simply reference them using their IDs. For subscription-based recurring payments, pre-created products are mandatory. For one-time purchase products, you can define product details (name, unit price, quantity, etc.) in the priceDataList. The checkout session will display these product details accordingly.

Amount Units

originalAmount and priceDataList[].unitAmount are expressed in the major currency unit, not the minor unit. Send 19.99 for USD 19.99. Sending 1999 is interpreted as USD 1999. Currencies with no decimal places — JPY, KRW, IDR — accept integers only.

Subscription Scheduled Phases

For subscription checkout sessions, send scheduledPhases as a top-level request field when you want the subscription created after checkout to change plans at future renewal boundaries. The initial subscription is still created from productId and priceId. Each scheduled phase references a subscription priceSnapshotId, sets the target quantity, and uses effectiveCycle to say which renewal cycle activates the phase. sequence and effectiveCycle both start at 1 and must be strictly increasing. You can include up to 10 phases. Use the priceSnapshotId returned by the Product or Price APIs. Phase snapshots must be subscription prices with valid recurring details and must support the checkout payment currency. metadata is optional and is limited to 20 keys, 40 characters per key, and 500 characters per value.

Customer

Checkout sessions include pre-filled customer information. Provide at least one of customerId, customerEmail, referenceCustomerId, or a complete historicalPaymentInstrumentImport object. If none is provided, the request fails with CUSTOMER_NOT_FOUND. referenceCustomerId is the merchant-side customer ID. It can be used to locate, validate, create, or bind a Clink customer. When customerId is provided, it is the primary identifier. Clink first looks up the customer by customerId. If customerEmail is also provided, it must match that customer. If referenceCustomerId is also provided, it must match that customer; when the customer does not already have a referenceCustomerId and the reference ID is not used by another customer, Clink automatically binds it to the customer. When customerId is not provided, Clink resolves the customer by customerEmail and/or referenceCustomerId:

Only customerEmail: Clink finds an existing customer by email, or creates a new customer if none exists.
Only referenceCustomerId: Clink finds an existing customer by the merchant-side customer ID, or creates a new customer if none exists.
Both customerEmail and referenceCustomerId: both identifiers must resolve to the same customer. If the email resolves to customer A and the reference ID resolves to customer B, and A is not B, the request fails with CUSTOMER_IDENTIFIER_NOT_MATCHED. If only one identifier matches an existing customer, the request also fails with CUSTOMER_IDENTIFIER_NOT_MATCHED. If neither identifier matches an existing customer, Clink creates a new customer with both identifiers.

When customerId, customerEmail, and referenceCustomerId are all omitted, Clink can use a complete historicalPaymentInstrumentImport object to resolve or create the customer. The checkout session stores the resolved customerId. customerEmail, referenceCustomerId, and historicalPaymentInstrumentImport are used to locate, validate, create, or bind the customer.

Historical Payment Instrument Import

To resolve or create a customer and import payment instruments previously saved at a merchant-owned hosted Stripe channel, provide historicalPaymentInstrumentImport when creating the checkout session. Other channel types are not currently supported. Both channelAlias and channelCustomerReference are required when historicalPaymentInstrumentImport is provided:

channelAlias: the alias of the merchant-owned hosted Stripe channel.
channelCustomerReference: the Stripe customer ID assigned by that channel.
paymentMethodTypes: optional payment method types to import. Supported values are CARD and CASHAPP.

If paymentMethodTypes is omitted or empty, Clink uses the server-side payment method set allowed for the merchant and channel. CASHAPP takes effect only when it is enabled for both the merchant and the channel. Otherwise, Clink filters it out without failing the request.

{
  "historicalPaymentInstrumentImport": {
    "channelAlias": "mcht_xxx-stripe-m1",
    "channelCustomerReference": "cus_xxx",
    "paymentMethodTypes": [
      "CARD"
    ]
  }
}

URLs

Use uiMode to control how the checkout session is rendered:

hostedPage: hosted checkout page
elements: embedded checkout

For hosted checkout, we strongly recommend providing successUrl and cancelUrl for post-checkout navigation. When uiMode is elements, returnUrl is required.

Payment Method Sort Order

Use paymentMethodSortOrder to control the display order of payment methods when customers open the Checkout Session.

{
  "paymentMethodSortOrder": [
    "WECHAT",
    "APPLEPAY",
    "CASHAPP",
    "PAYPAL",
    "GOOGLEPAY",
    "ALIPAY",
    "LINK",
    "CARD"
  ]
}

Available payment methods included in the array are displayed in exactly the specified order. Available payment methods not included in the array are appended afterward in the system default order.

Unsupported, unrecognized, or currently unavailable payment method codes are ignored.
Duplicate codes are deduplicated using the position of the first occurrence.
If the field is omitted or an empty array is provided, Checkout uses the system default payment method order.
This field controls display order only. It does not enable unavailable payment methods or replace paymentMethodTypeBlackList.

Direct QR Launch

directPaymentQrCodePaymentMethodType 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 will not be automatically completed

Ignored when:

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

Allowed values:

CASHAPP
QRIS

Promotion Code Display

Set allowPromotionCodes to true to enable promotion code support in checkout. By default, checkout shows the promotion code input. To apply a promotion code without showing the input box, set showPromotionCode to false and provide promotionCode. In this mode, promotionCode is required and Clink validates it when the session is created.

Local Price Only

localPriceOnly applies only to one-time payments. Set it to true when you want checkout to prioritize price options that match the customer’s local currencies resolved from the checkout access IP. By default, this setting is false. When localPriceOnly is enabled for a one-time payment, checkout shows local price options first. If no local price option can be shown, Clink falls back to the original pricing currency when it is available. This setting does not apply to subscription checkout sessions.

Merchant Reference

The merchant reference serves as your internal identifier for tracking purposes. This reference will be recorded on orders created through the checkout session.

Idempotency: Clink does not maintain idempotency based on merchant reference IDs.
These IDs are solely for reconciling Sessions with your internal systems. Multiple checkout sessions created with the same merchant reference ID will be treated as distinct sessions.

Return and Redirect URLs

For hosted checkout sessions created with uiMode: hostedPage, Clink redirects customers to successUrl after a successful payment and to cancelUrl when they leave the flow. During the hosted success redirect, Clink appends the session ID as a URL parameter, allowing you to retrieve session data via the Session#Get API. Hosted success URL examples:

https://your_success_url.com?sessionId=sess_randoms
https://your_success_url.com?custom=xxxxxxxx&sessionId=sess_randoms

For embedded checkout sessions created with uiMode: elements, returnUrl is required. You can include {ELEMENTS_SESSION_ID} in the URL, and Clink will replace it with the created session ID before returning control to your site. Example returnUrl:

https://YOUR_DOMAIN/complete.html?session_id=

Customer Experience

Clink provides a streamlined solution with a standardized checkout experience. While customization options are limited, the interface maintains a clean, professional design. Merchant information and the cancel URL are accessible from the top left. Product and price information is displayed based on either dashboard configurations or API inputs. Available payment methods and currencies adapt automatically based on:

Purchase type (one-time or subscription)
Customer’s geographical location

For one-time payments, create the checkout session with localPriceOnly: true to prioritize the customer’s local currencies. If no local price option can be shown, Clink falls back to the original pricing currency when it is available.

Quick Start Examples

Reference these code snippets to get started:

Sample Code

Always test your code thoroughly before deploying to production!

curl --location --request POST 'https://api.clinkbill.com/api/checkout/session' \
--header 'X-Timestamp: ${currentMillisecondsTimestamp}' \
--header 'X-API-Key: ${sk_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerEmail": "customer@example.com",
    "originalAmount": ${amount},
    "originalCurrency": "USD",
    "uiMode": "hostedPage",
    "priceDataList":[
        {
            "name":"A one-time purchase",
            "quantity": 1,
            "unitAmount":${unitAmount},
            "currency":"USD"
        }
    ]
}'

curl --location --request POST 'https://api.clinkbill.com/api/checkout/session' \
--header 'X-Timestamp: ${currentMillisecondsTimestamp}' \
--header 'X-API-Key: ${sk_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerEmail": "customer@example.com",
    "originalAmount": ${amount},
    "originalCurrency": "USD",
    "uiMode": "hostedPage",
    "priceId": "${price_id}",
    "productId": "${prd_id}"
}'

curl --location --request POST 'https://api.clinkbill.com/api/checkout/session' \
--header 'X-Timestamp: ${currentMillisecondsTimestamp}' \
--header 'X-API-Key: ${sk_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerId": "cus_xxxxx",
    "originalAmount": 19.99,
    "originalCurrency": "USD",
    "uiMode": "hostedPage",
    "priceId": "price_xxxxx",
    "productId": "prd_xxxxx",
    "allowPromotionCodes": true,
    "showPromotionCode": false,
    "promotionCode": "SAVE10"
}'

curl --location --request POST 'https://api.clinkbill.com/api/checkout/session' \
--header 'X-Timestamp: ${currentMillisecondsTimestamp}' \
--header 'X-API-Key: ${sk_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerId": "cus_xxxxx",
    "originalAmount": ${amount},
    "originalCurrency": "USD",
    "uiMode": "hostedPage",
    "priceId": "${initial_price_id}",
    "productId": "${prd_id}",
    "successUrl": "https://YOUR_DOMAIN/success",
    "cancelUrl": "https://YOUR_DOMAIN/cancel",
    "scheduledPhases": [
        {
            "sequence": 1,
            "effectiveCycle": 2,
            "priceSnapshotId": "${growth_price_snapshot_id}",
            "quantity": 1,
            "metadata": {
                "source": "checkout_schedule"
            }
        },
        {
            "sequence": 2,
            "effectiveCycle": 4,
            "priceSnapshotId": "${scale_price_snapshot_id}",
            "quantity": 2
        }
    ]
}'

curl --location --request POST 'https://api.clinkbill.com/api/checkout/session' \
--header 'X-Timestamp: ${currentMillisecondsTimestamp}' \
--header 'X-API-Key: ${sk_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerEmail": "customer@example.com",
    "originalAmount": ${amount},
    "originalCurrency": "USD",
    "uiMode": "elements",
    "returnUrl": "https://YOUR_DOMAIN/complete.html?session_id={ELEMENTS_SESSION_ID}",
    "priceDataList":[
        {
            "name":"Embedded checkout purchase",
            "quantity": 1,
            "unitAmount":${unitAmount},
            "currency":"USD"
        }
    ]
}'

Get Started

Integration

Configure & Launch

Guides

Finance

Overview

Session Data

Status

Product & Price

Amount Units

Subscription Scheduled Phases

Customer

Historical Payment Instrument Import

URLs

Payment Method Sort Order

Direct QR Launch

Promotion Code Display

Local Price Only

Merchant Reference

Return and Redirect URLs

Customer Experience

Quick Start Examples

​Overview

​Session Data

​Status

​Product & Price

​Amount Units

​Subscription Scheduled Phases

​Customer

​Historical Payment Instrument Import

​URLs

​Payment Method Sort Order

​Direct QR Launch

​Promotion Code Display

​Local Price Only

​Merchant Reference

​Return and Redirect URLs

​Customer Experience

​Quick Start Examples

Overview

Session Data

Status

Product & Price

Amount Units

Subscription Scheduled Phases

Customer

Historical Payment Instrument Import

URLs

Payment Method Sort Order

Direct QR Launch

Promotion Code Display

Local Price Only

Merchant Reference

Return and Redirect URLs

Customer Experience

Quick Start Examples