Card Payment

Overview

This guide provides comprehensive instructions for integrating Card Payment functionality into your merchant system. Our platform supports two integration modes to meet different business needs:

Cashier Mode (pay_access_type=1): Redirect users to our hosted cashier page

OpenAPI Mode (pay_access_type=2): Direct API integration with your own payment form

Integration Mode 1: Cashier Mode

Overview

In Cashier Mode, merchants redirect customers to our hosted payment page where users can securely enter their card details. This mode minimizes PCI compliance requirements and provides a quick integration path.

Payment Flow Screenshots

Step 1: Cashier Payment Page

Users are redirected to the hosted cashier page where they enter their card details:

Step 2: 3D Secure Authentication

After clicking "Pay now", users complete 3DS verification:

Step 3: Payment Success

Upon successful payment, users see the confirmation page:

Sequence Diagram

Complete API Documentation

Create Order API: Create Payin

Signature Generation: Authentication

Create Order Endpoint

POST /api/global/v1/pay/create-order

Request Parameters

Required Parameters:

Parameter	Type	Required	Description
`target_amount`	String	Yes	Payment amount
`target_currency`	String	Yes	Currency code (e.g., CNY, USD)
`transaction_type`	String	Yes	Must be `PAY_IN`
`notify_url`	String	Yes	Callback URL for payment notifications
`request_id`	String	Yes	Unique merchant order ID
`fail_url`	String	Yes	Redirect URL on payment failure
`success_url`	String	Yes	Redirect URL on payment success
`product_name`	String	Yes	Product/service name
`description`	String	Yes	Order description
`way_type`	String	Yes	Must be `CARD_PAYMENT`
`api_version`	String	Yes	Must be `V2`
`pay_access_type`	Integer	Yes	Must be `1` for Cashier Mode

Request Example

Response Example

{
    "msg": "SUCCESS",
    "code": 0,
    "data": {
        "order_data": {
            "payOrderId": "P2011337513994018818",
            "payOrderDetailIdEncode": "0c11add2dd42e4853755e2ea325c2e100b4aec92f6cc8f83efff27d6c5362f8f",
            "mchOrderNo": "M17662773795657082",
            "payOrderDetailId": "PD2011337514476363778",
            "payOrderDetailState": 1,
            "payData": "https://authentication-devices.sandbox.checkout.com/sessions-interceptor/sid_qxhjzqibm23yxopurfcsx2bhdi",
            "payDataType": "payurl",
            "orderState": 1
        },
        "pay_order_id": "P2011337513994018818"
    }
}

Response Handling

Check payDataType: If the value is payurl, redirect the user to the URL in payData

Redirect User: The payData URL points to the hosted cashier page

User Interaction: User completes payment and 3DS verification on the cashier page

Result: User is redirected to success_url or fail_url based on payment result

Callback: Wait for payment callback notification for final confirmation

Integration Mode 2: OpenAPI Mode

Overview

In OpenAPI Mode, merchants have full control over the payment UI. This mode supports two payment methods:

Direct Card Payment: Collect and submit card details via API

Token Payment: Use saved card tokens for recurring payments

2.1 Direct Card Payment

Sequence Diagram

Required Parameters

In addition to the common parameters (same as Cashier Mode, but with pay_access_type=2), you must include:

Parameter	Type	Required	Description
`target_amount`	String	Yes	Payment amount
`target_currency`	String	Yes	Currency code (e.g., CNY, USD)
`transaction_type`	String	Yes	Must be `PAY_IN`
`notify_url`	String	Yes	Callback URL for payment notifications
`request_id`	String	Yes	Unique merchant order ID
`fail_url`	String	Yes	Redirect URL on payment failure
`success_url`	String	Yes	Redirect URL on payment success
`product_name`	String	Yes	Product/service name
`description`	String	Yes	Order description
`way_type`	String	Yes	Must be `CARD_PAYMENT`
`api_version`	String	Yes	Must be `V2`
`pay_access_type`	Integer	Yes	Must be `2` for OpenAPI Mode
`channel_extra`	Object	Yes	Card payment specific data
`channel_extra.extra_type`	String	Yes	Must be `card` for direct card payment
`channel_extra.card_data`	Object	Yes	Card information object
`channel_extra.card_data.number`	String	Yes	Card number
`channel_extra.card_data.expiry_month`	Integer	Yes	Expiry month (1-12)
`channel_extra.card_data.expiry_year`	Integer	Yes	Expiry year (e.g., 2027)
`channel_extra.card_data.cvv`	String	Yes	Card CVV/CVC code
`channel_extra.card_data.store_for_future_use`	Boolean	Optional	Set to `true` to generate a token

Request Example

Response Example

With 3DS Required:

{
    "code": 0,
    "data": {
        "order_data": {
            "mchOrderNo": "M20260115121901",
            "orderState": 1,
            "payData": "https://authentication-devices.sandbox.checkout.com/sessions-interceptor/sid_iixxg7abmqkypepvfsrwua7uja",
            "payDataType": "payurl",
            "payOrderDetailId": "PD2011293075558170625",
            "payOrderDetailIdEncode": "3ff04ea391ed7163c6943e39e774dbf159ddde496e5ffcde0996ab4805a6eaaf",
            "payOrderDetailState": 1,
            "payOrderId": "P2011293075021299713"
        },
        "pay_order_id": "P2011293075021299713"
    },
    "msg": "SUCCESS"
}

Without 3DS (Direct Processing):

{
    "code": 0,
    "data": {
        "order_data": {
            "mchOrderNo": "M20260115121901",
            "orderState": 1,
            "payOrderDetailId": "PD2011293075558170625",
            "payOrderDetailIdEncode": "3ff04ea391ed7163c6943e39e774dbf159ddde496e5ffcde0996ab4805a6eaaf",
            "payOrderDetailState": 1,
            "payOrderId": "P2011293075021299713"
        },
        "pay_order_id": "P2011293075021299713"
    },
    "msg": "SUCCESS"
}

Response Handling

Check payDataType:

If payDataType is payurl: Redirect user to the payData URL for 3DS authentication

If payDataType is empty: Payment is processing, wait for callback notification

Wait for Callback: Always wait for the payment callback to confirm the final payment status

2.2 Token Payment

Overview

After a successful card payment with store_for_future_use: true, you'll receive a card_token in the callback notification. This token can be used for future payments without requiring the user to re-enter card details.

Token Acquisition

The card_token is provided in the channel_biz_data field of the payment callback:

{
  "channel_biz_data": {
    "card_token": "src_3oqxta2juhbevjaw72pgorkd5e",
    "issuer": "CKO, WHERE THE WORLD CHECKS OUT",
    "issuer_country": "GB"
  }
}

Sequence Diagram

Complete API Documentation

Create Order API: Create Payin

Signature Generation: Authentication

Create Order Endpoint

POST /api/global/v1/pay/create-order

Required Parameters

Similar to Direct Card Payment, but replace card_data with token_data:

Parameter	Type	Required	Description
`target_amount`	String	Yes	Payment amount
`target_currency`	String	Yes	Currency code (e.g., CNY, USD)
`transaction_type`	String	Yes	Must be `PAY_IN`
`notify_url`	String	Yes	Callback URL for payment notifications
`request_id`	String	Yes	Unique merchant order ID
`fail_url`	String	Yes	Redirect URL on payment failure
`success_url`	String	Yes	Redirect URL on payment success
`product_name`	String	Yes	Product/service name
`description`	String	Yes	Order description
`way_type`	String	Yes	Must be `CARD_PAYMENT`
`api_version`	String	Yes	Must be `V2`
`pay_access_type`	Integer	Yes	Must be `token` for OpenAPI Mode
`channel_extra.extra_type`	String	Yes	Must be `token` for token payment
`channel_extra.token_data`	Object	Yes	Token information object
`channel_extra.token_data.token`	String	Yes	The card token from previous payment

Request Example

Response Handling

Token payments follow the same response handling as Direct Card Payments:

Check payDataType for 3DS requirement

Wait for callback notification for final status

Webhook (Payment Callback Notification)

Overview

After payment processing (success or failure), our system sends a callback notification to the notify_url you provided in the order request.

Callback Format

{
  "api_version": "V2",
  "description": "Lesspay Order",
  "fail_url": "https://www.doopayment.com",
  "order_status": "SUCCEED",
  "order_status_int": 2,
  "pay_order_id": "P2011789219984105474",
  "product_name": "Lesspay Order",
  "request_id": "M20260115121901",
  "success_url": "https://www.doopayment.com",
  "target_amount": "100.00",
  "target_currency": "CNY",
  "channel_biz_data": {
    "card_token": "src_3oqxta2juhbevjaw72pgorkd5e",
    "issuer": "CKO, WHERE THE WORLD CHECKS OUT",
    "issuer_country": "GB"
  }
}

Callback Parameters

Parameter	Type	Description
`order_status`	String	Payment status: `SUCCEED`, `FAILED`, etc.
`order_status_int`	Integer	Status code: `2` = Success
`pay_order_id`	String	Platform order ID
`request_id`	String	Your original merchant order ID
`target_amount`	String	Payment amount
`target_currency`	String	Payment currency
`channel_biz_data`	Object	Channel-specific data (includes card_token if requested)

Callback Verification

See Payin webhook

Order Status

See Parameter Specifications

Overview#

Integration Mode 1: Cashier Mode#

Overview#

Payment Flow Screenshots#

Step 1: Cashier Payment Page#

Step 2: 3D Secure Authentication#

Step 3: Payment Success#

Sequence Diagram#

Complete API Documentation#

Create Order Endpoint#

Request Parameters#

Request Example#

Response Example#

Response Handling#

Integration Mode 2: OpenAPI Mode#

Overview#

2.1 Direct Card Payment#

Sequence Diagram#

Required Parameters#

Request Example#

Response Example#

Response Handling#

2.2 Token Payment#

Overview#

Token Acquisition#

Sequence Diagram#

Complete API Documentation#

Create Order Endpoint#

Required Parameters#

Request Example#

Response Handling#

Webhook (Payment Callback Notification)#

Overview#

Callback Format#

Callback Parameters#

Callback Verification#

Order Status#

Overview

Integration Mode 1: Cashier Mode

Overview

Payment Flow Screenshots

Step 1: Cashier Payment Page

Step 2: 3D Secure Authentication

Step 3: Payment Success

Sequence Diagram

Complete API Documentation

Create Order Endpoint

Request Parameters

Request Example

Response Example

Response Handling

Integration Mode 2: OpenAPI Mode

Overview

2.1 Direct Card Payment

Sequence Diagram

Required Parameters

Request Example

Response Example

Response Handling

2.2 Token Payment

Overview

Token Acquisition

Sequence Diagram

Complete API Documentation

Create Order Endpoint

Required Parameters

Request Example

Response Handling

Webhook (Payment Callback Notification)

Overview

Callback Format

Callback Parameters

Callback Verification

Order Status