> ## 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 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 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, 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. 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, or referenceCustomerId 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, 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 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, or referenceCustomerId is required. If all three are empty, the request fails with CUSTOMER_NOT_FOUND 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 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 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) ````