> ## 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. # Create Checkout Session > Create a new checkout session for payment processing ## OpenAPI ````yaml /api-reference/openapi.json post /checkout/session openapi: 3.1.0 info: title: Clink API description: >- Official API documentation for Clink's payment processing platform. This API enables merchants to create and manage payment sessions, handle subscriptions, and process transactions. version: 1.0.0 servers: - url: https://uat-api.clinkbill.com/api/ security: - ApiKeyAuth: [] paths: /checkout/session: post: summary: Create Checkout Session description: Create a new checkout session for payment processing operationId: add parameters: - $ref: '#/components/parameters/TimestampHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/SessionCreateReq' examples: hostedCheckout: summary: Hosted checkout value: customerId: customer_id originalAmount: 4.99 originalCurrency: USD priceId: price_id productId: prd_id uiMode: hostedPage metadata: customerTier: vip source: merchant_portal embeddedElements: summary: Embedded checkout (elements) value: customerId: customer_id originalAmount: 4.99 originalCurrency: USD priceId: price_id productId: prd_id uiMode: elements returnUrl: >- https://merchant.example.com/complete.html?session_id={ELEMENTS_SESSION_ID} metadata: customerTier: vip source: merchant_portal hiddenPromotionCode: summary: Checkout with a hidden promotion code value: customerId: cus_xxxxx originalAmount: 19.99 originalCurrency: USD priceId: price_xxxxx productId: prd_xxxxx uiMode: hostedPage allowPromotionCodes: true showPromotionCode: false promotionCode: SAVE10 historicalPaymentInstrumentImport: summary: Checkout with historical payment instrument import value: customerId: cus_xxxxx originalAmount: 19.99 originalCurrency: USD priceId: price_xxxxx productId: prd_xxxxx uiMode: hostedPage historicalPaymentInstrumentImport: channelAlias: mcht_xxx-stripe-m1 channelCustomerReference: cus_xxx paymentMethodTypes: - CARD subscriptionScheduledPhases: summary: Subscription checkout with scheduled phases value: customerId: cus_xxxxx originalAmount: 1000 originalCurrency: USD priceId: price_initial productId: prd_basic uiMode: hostedPage successUrl: https://merchant.example.com/success cancelUrl: https://merchant.example.com/cancel metadata: customerTier: vip source: merchant_portal scheduledPhases: - sequence: 1 effectiveCycle: 2 priceSnapshotId: pricesns_growth_monthly quantity: 1 metadata: source: checkout_schedule - sequence: 2 effectiveCycle: 4 priceSnapshotId: pricesns_scale_monthly quantity: 2 required: true responses: '200': description: Checkout session created successfully content: '*/*': schema: $ref: '#/components/schemas/RSessionApiCreateVo' application/json: schema: $ref: '#/components/schemas/SessionCreateRes' '401': description: Unauthorized content: '*/*': schema: type: string components: parameters: TimestampHeader: name: X-Timestamp in: header required: true description: >- Current timestamp in milliseconds since Unix epoch (required for request signing) schema: type: string example: '1783513683000' schemas: SessionCreateReq: description: >- Parameters required to initialize a new checkout session. Provide at least one of customerId, customerEmail, referenceCustomerId, or a complete historicalPaymentInstrumentImport object. If none is provided, the request fails with CUSTOMER_NOT_FOUND. A complete historicalPaymentInstrumentImport object can be used by itself to resolve or create the customer. 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. required: - originalAmount - originalCurrency type: object allOf: - if: properties: uiMode: const: elements required: - uiMode then: required: - returnUrl properties: customerId: type: string minLength: 1 description: >- Existing customer's unique identifier. At least one of customerId, customerEmail, referenceCustomerId, or a complete historicalPaymentInstrumentImport object is required. When provided, customerId is the primary identifier and customerEmail/referenceCustomerId must match the same customer customerEmail: type: string minLength: 1 description: >- Customer's email address. At least one of customerId, customerEmail, referenceCustomerId, or a complete historicalPaymentInstrumentImport object 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 referenceCustomerId: type: string minLength: 1 description: >- Merchant-side customer ID used to locate, validate, create, or bind a customer. At least one of customerId, customerEmail, referenceCustomerId, or a complete historicalPaymentInstrumentImport object is required. If none is provided, the request fails with CUSTOMER_NOT_FOUND historicalPaymentInstrumentImport: $ref: '#/components/schemas/HistoricalPaymentInstrumentImport' description: >- Optional customer information associated with a merchant's existing payment channel. Currently, only Stripe is supported. It is used to resolve or create the corresponding customer record and migrate historical payment instruments from supported payment providers. This object may be used as the only customer identifier. When provided, both channelAlias and channelCustomerReference are required. originalAmount: minimum: 0 exclusiveMinimum: true type: number description: >- Total transaction amount in the specified currency (must be greater than 0) originalCurrency: type: string description: >- Three-letter ISO currency code for the transaction (e.g., USD, EUR, GBP) merchantReferenceId: type: string description: >- Your internal reference ID for tracking (non-unique identifier, does not guarantee idempotency) priceId: type: string description: >- Unique identifier of the predefined price configuration from your dashboard productId: type: string description: Unique identifier of the product configured in your dashboard scheduledPhases: type: array description: >- 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. maxItems: 10 items: $ref: '#/components/schemas/ScheduledPhase' uiMode: type: string enum: - elements - hostedPage description: >- Checkout UI mode. Use `hostedPage` for hosted redirect checkout and `elements` for embedded checkout. When set to `elements`, `returnUrl` is required. returnUrl: type: string description: >- 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: type: string description: >- URL where customers will be redirected after successful payment completion cancelUrl: type: string description: >- URL where customers will be redirected if they cancel the checkout process paymentMethodType: type: string enum: - CARD - CASHAPP - WECHAT - KAKAO - PIX - ALIPAY - UPI - PAYPAL - GOOGLEPAY - APPLEPAY - QRIS - GCASH description: >- The default selected payment method for created checkout session. Recommended if you know customer preference in advance paymentMethodTypeBlackList: type: array items: type: string enum: - CARD - CASHAPP - WECHAT - KAKAO - PIX - ALIPAY - UPI - PAYPAL - GOOGLEPAY - APPLEPAY - QRIS - GCASH description: >- 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 directPaymentQrCodePaymentMethodType: type: string enum: - CASHAPP - QRIS description: >- 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` priceDataList: type: array description: >- List of product pricing details for one-time purchases. Use this when creating transactions without pre-configured products items: $ref: '#/components/schemas/PriceData' refType: PriceData allowPromotionCodes: type: boolean description: >- Set to true to enable customers to enter promotion codes during checkout showPromotionCode: type: boolean description: >- 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. default: true localPriceOnly: type: boolean description: >- One-time payments only. Controls whether checkout prioritizes price options that match the customer's local currencies resolved from the checkout access IP. Defaults to false. When true, checkout shows local price options for one-time payments; 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. default: false promotionCode: type: string description: >- Pre-filled promotion code for the checkout session. Only effective when allowPromotionCodes is set to true. Required when showPromotionCode is false metadata: type: object description: >- 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. maxProperties: 20 propertyNames: maxLength: 40 additionalProperties: type: string maxLength: 500 RSessionApiCreateVo: type: object properties: code: type: integer format: int32 msg: type: string data: $ref: '#/components/schemas/SessionApiCreateVo' SessionCreateRes: type: object description: Response object returned when creating a new checkout session properties: code: type: integer description: >- HTTP status code indicating the request result (200 for success, 4xx for client errors, 5xx for server errors) format: int32 example: 200 msg: type: string description: >- Human-readable message describing the result ('success' for successful operations, error details for failures) example: success data: $ref: '#/components/schemas/SessionApiCreateVo' description: Checkout session details when successfully created HistoricalPaymentInstrumentImport: description: >- Identifies an existing customer at a merchant-owned hosted Stripe channel so Clink can resolve or create the Clink customer and import that customer's historical payment instruments. required: - channelAlias - channelCustomerReference type: object properties: channelAlias: type: string minLength: 1 description: >- Alias of the merchant-owned hosted Stripe channel, for example mcht_xxx-stripe-m1 channelCustomerReference: type: string minLength: 1 description: >- Stripe customer identifier assigned by the channel, for example cus_xxx paymentMethodTypes: type: array description: >- Optional payment method types to import from the Stripe customer. If omitted or empty, Clink uses the server-side payment method set allowed for the merchant and channel. Supported values are CARD and CASHAPP. CASHAPP takes effect only when enabled for both the merchant and the channel; otherwise it is filtered out without failing the request. uniqueItems: true items: type: string enum: - CARD - CASHAPP ScheduledPhase: required: - sequence - effectiveCycle - priceSnapshotId - quantity type: object description: >- A scheduled subscription plan change that takes effect at a future billing period boundary. properties: sequence: minimum: 1 type: integer description: >- Position of this phase in the schedule. Values must be strictly increasing. format: int32 effectiveCycle: minimum: 1 type: integer description: >- The renewal boundary when this phase takes effect, counted from subscription creation. Values must be strictly increasing. format: int32 priceSnapshotId: type: string description: >- Target subscription price snapshot ID. The snapshot must exist, have priceType=SUBSCRIBE with valid recurring details, and support the subscription payment currency. quantity: minimum: 1 type: integer description: Target quantity for the scheduled phase. format: int32 metadata: type: object description: >- Optional metadata for this scheduled phase. Maximum 20 keys. Key length must be 40 characters or fewer and string value length must be 500 characters or fewer. maxProperties: 20 propertyNames: maxLength: 40 additionalProperties: type: string maxLength: 500 PriceData: required: - name - unitAmount type: object properties: name: type: string description: Display name of the product shown to customers during checkout quantity: minimum: 1 type: integer description: Number of units to be purchased (minimum 1) format: int32 unitAmount: minimum: 0 exclusiveMinimum: true type: number description: Price per unit in the specified currency (must be greater than 0) currency: type: string description: Three-letter ISO currency code for the price (e.g., USD, EUR, GBP) imageUrl: type: string description: URL of the product image to display during checkout SessionApiCreateVo: type: object description: Details of the created checkout session properties: sessionId: type: string description: Unique identifier for the created checkout session example: sess_abc123xyz tokenValue: type: string description: >- Secure, time-limited token for authenticating checkout session access customerId: type: string description: >- Unique identifier of the customer associated with this checkout session example: cus_12345 originalAmount: type: number description: Initial transaction amount specified in the creation request example: 99.99 originalCurrency: type: string description: >- Three-letter ISO currency code specified in the creation request (e.g., USD, EUR, GBP) example: USD uiMode: type: string enum: - elements - hostedPage description: Checkout UI mode used for this session returnUrl: type: string description: Return URL configured for embedded checkout sessions url: type: string description: >- Complete URL to the hosted checkout page where customers can complete their payment example: https://uat-checkout.clinkbill.com/pay/sess_abc123xyz merchantReferenceId: type: string description: Your provided reference identifier for tracking this transaction example: order_ref_123 expireTime: type: string description: ISO 8601 formatted timestamp when this checkout session will expire format: date-time securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: >- Your secret API key obtained from the Clink dashboard (Developers section) ````