Business Flow Guide - Payment-guide

Core Integration Flow

Complete payment card service integration is divided into four stages, from user authentication to consumption reconciliation. The following details each stage and corresponding interfaces:

Stage 1: User Registration & KYC Authentication

Scenario: Complete cardholder authentication. Cardholders must be authenticated before they can apply for cards.

Flow Steps

Frontend Integration of SumSub KYC Component — User completes identity verification
Backend Initiates Cardholder Authentication — Call interface to create cardholder and initiate authentication
Query Authentication Status — Get cardholder list or details to confirm authentication passes

Interface	Method	Path	Description
Get Token	GET	`/open-api/v1/merchant/token`	Get Access-Token, required for all subsequent requests
Cardholder Authentication Application	POST	`/open-api/v1/cardholder/apply`	Create cardholder and initiate authentication through this interface; after authentication failure, can update authentication info and re-initiate
Get Cardholder List	POST	`/open-api/v1/cardholder/list`	Get current cardholder list
Get Cardholder Details	GET	`/open-api/v1/cardholder/{cardholder_no}/info`	Get cardholder’s card list; can verify authentication status

Typical Flow

Frontend KYC Authentication
    ↓
[POST /cardholder/apply] Initiate cardholder application
    ↓
Authentication in progress... (Platform verifies with Sumsub)
    ↓
[POST /cardholder/list] Query cardholder status
    ↓
Authentication successful ✓ (Status: Approved)

Authentication Status

Status	Description
Pending	Awaiting authentication
In_progress	Authentication in progress
Approved	Authentication successful ✓ (Can apply for cards)
Rejected	Authentication failed (Can re-apply)

Stage 2: Select Package, Apply for Card, Card Management

Scenario: After cardholder authentication passes, user selects card type (virtual/physical) and applies for card, along with card management.

Flow Steps

Get Card Package or BIN List — Get available card products based on integration mode
Apply for Card — User selects card type (virtual/physical) and submits application
Query Card Status — Get card list or card details to confirm card application success
Activate Card (Physical Cards) — After user receives physical card, must activate to use
Manage Card Status — Freeze, unfreeze, or delete cards

Interface	Method	Path	Mode	Description
Get Card Package List	POST	`/open-api/v1/card/package/list`	Credit	Login merchant backend to create card packages; charge based on corresponding package when applying
Supported Card BIN List	POST	`/open-api/v1/card/support/bins`	Auth	Get supported card BINs for authorization mode; card pricing needs to be maintained by the merchant
Apply for Card	POST	`/open-api/v1/card/apply`	Common	Apply for card (pass `package_no` for credit, `card_bin_no` for auth)
Get Card List	POST	`/open-api/v1/card/list`	Common	Get current card list
Get Card Details	GET	`/open-api/v1/card/{card_no}/detail`	Common	Get card details (including rates, fees, etc.)
Get Card Privacy Info	GET	`/open-api/v1/card/{card_no}/private/info`	Common	Get card’s CVV, expiry, card number (requires contacting business to enable PCI permission)
Activate Physical Card	POST	`/open-api/v1/card/active`	Common	Physical card needs activation after receipt (requires encrypted CVV)
Update Card Status	POST	`/open-api/v1/card/status/update`	Common	Update card usage status (Frozen / Activated / Delete)
Set PIN	POST	`/open-api/v1/card/pin/set`	Common	Set physical card PIN (requires encrypted PIN)
Card Status Change Notification	—	Webhook	Common	Notification when card status changes after applying; also notified for risk control changes

Typical Flow

Credit Mode:

[POST /card/package/list] Get package list
    ↓
User selects package
    ↓
[POST /card/apply] Apply for card (pass package_no)
    ↓
[POST /card/list] Query card status
    ↓
Virtual card: Immediately available ✓
    or
Physical card: Mailing → User receives card → [POST /card/active] Activate
    ↓
[POST /card/pin/set] Set PIN (optional)

Authorization Mode:

[POST /card/support/bins] Get supported BINs
    ↓
User selects card BIN
    ↓
[POST /card/apply] Apply for card (pass card_bin_no)
    ↓
[POST /card/list] Query card status
    ↓
Virtual card: Immediately available ✓
    or
Physical card: Mailing → User receives card → [POST /card/active] Activate

Card Status

Status	Description	Available Operations
Pending	In progress (manufacturing, etc.)	—
ToActivate	Awaiting activation (physical card received)	Activate, update status
Activated	Activated/Normal	Consume, freeze, delete, set PIN
Frozen	Frozen	Unfreeze, delete
Delete	Deleted/Cancelled	—
Fail	Failed	Re-apply

Stage 3: Account & Fund Management (Credit Mode)

Scenario: Check cardholder account balance and execute fund transfers. Credit mode only.

Flow Steps

Recharge Reserve — Merchant manually recharges reserve in backend (no interface currently)
Query Account Balance — Get cardholder account info to confirm available assets
Execute Fund Transfer — Perform fund transfer when cardholder funds change (top-up or withdrawal)
Query Transfer Flow — Check transfer history for reconciliation

Interface	Method	Path	Description
Reserve Recharge	—	—	Currently no interface available, must manually recharge in merchant backend
Cardholder Fund Transfer	POST	`/open-api/v1/account/transfer`	Perform fund transfer when cardholder funds change (top-up or withdrawal); keep both sides in sync; fixed currency TUSDT
Get Cardholder Account Info List	GET	`/open-api/v1/account/{cardholder_no}/info`	Available assets in cardholder’s credit mode account
Get Account Transfer Flow List	POST	`/open-api/v1/account/transfer/list`	Cardholder fund transfer history

Typical Flow

User top-up request
    ↓
[POST /account/transfer] Execute transfer (type: In)
    ↓
Transfer successful ✓ (returns transfer reference)
    ↓
[GET /account/{cardholder_no}/info] Query balance to confirm
    ↓
[POST /account/transfer/list] Query transfer flow for reconciliation

Transfer Types

Type	Direction	Description
In	Company → Cardholder	User top-up (merchant account can go negative)
Out	Cardholder → Company	User withdrawal (requires sufficient balance, otherwise fails)

Stage 4: Consumption & Billing

Scenario: After user uses card for consumption, view transaction records and details for merchant reconciliation.

Flow Steps

User Consumption — Cardholder uses card for transaction
Receive Consumption Notification — Platform sends consumption order notification via Webhook
Query Consumption Details — Get detailed info by consumption reference
Query Consumption List — Query consumption records by time range for reconciliation

Interface	Method	Path	Description
Consumption Order Notification	—	Webhook	Notification sent when cardholder consumes; also sent when order settles; includes fee details and merchant info
Get Card Consumption List	POST	`/open-api/v1/card/consume/list`	Query historical consumption records by card; supports filtering by time range, card number, etc.
Get Card Consumption Details	GET	`/open-api/v1/card/consume/{consume_no}/info`	Query consumption details including rates, fees, merchant info

Typical Flow

User uses card for consumption
    ↓
[Webhook Consumption Notification] Platform sends consumption order notification
    ↓
Merchant handles notification (returns code: 0)
    ↓
[GET /consume/{consume_no}/info] Query consumption details
    ↓
[POST /consume/list] Periodically query consumption list for reconciliation
    ↓
Generate billing and reconciliation statement

Consumption Types

Type	Description
Consumption	Transaction
Atm	ATM Withdrawal
Manage_fee	Management Fee
Refund	Refund
Reversal	Chargeback/Reversal
Open_card	Card Issuance Fee

Authorization Mode Special Flow

Authorization mode requires real-time authorization confirmation

User consumption request
    ↓
[Webhook Auth Notification] Platform sends authorization notification
    ↓
Merchant must confirm within 800 ms
    ↓
Return response { "code": 0 }
    ↓
Authorization approved → Transaction continues ✓
    or
Authorization denied → Transaction fails ✗
    ↓
[Webhook Consumption Notification] Final result notification

Important: Authorization mode has very high performance requirements. Ensure your system can complete authorization response within 800 ms.

Complete Integration Timeline

Stage	Operation	Estimated Time
Preparation	Request credentials, configure whitelist, configure callbacks	1-2 days
Authentication	Integrate SumSub, complete KYC	3-5 days
Card Application	Card interface integration, test virtual + physical cards	5-7 days
Account	Complete account and transfer interface integration (credit mode)	3-5 days
Consumption	Receive and process Webhook notifications, consumption queries	3-5 days
Testing	Full chain testing, pre-launch review	2-3 days
Total		15-25 days

FAQ

Q1: Must users complete KYC before applying for cards?
A: Yes, cardholders must complete KYC authentication with status Approved before applying for cards. Q2: How long after card application can it be used?
A: Virtual cards are immediately available after application; physical cards require activation after user receives them. Q3: How do I distinguish between credit and authorization modes?
A: Based on the integration_mode confirmed with business before integration:

CREDIT_EXTENSION = Credit mode
AUTHORIZATION = Authorization mode

Q4: Why must authorization mode confirm within 800 milliseconds?
A: Authorization mode settles funds in real-time. Merchants must confirm within 800 milliseconds whether to allow the transaction. Timeout defaults to transaction rejection. Q5: How are consumption fees calculated?
A: Fee details are in the card package configuration at application time, including consumption rate, fees, exchange rate, etc. See the “Constants” section for details.

​Core Integration Flow

​Stage 1: User Registration & KYC Authentication

​Flow Steps

​Related Interfaces

​Typical Flow

​Authentication Status

​Stage 2: Select Package, Apply for Card, Card Management

​Flow Steps

​Related Interfaces

​Typical Flow

​Card Status

​Stage 3: Account & Fund Management (Credit Mode)

​Flow Steps

​Related Interfaces

​Typical Flow

​Transfer Types

​Stage 4: Consumption & Billing

​Flow Steps

​Related Interfaces

​Typical Flow

​Consumption Types

​Authorization Mode Special Flow

​Complete Integration Timeline

​FAQ

Core Integration Flow

Stage 1: User Registration & KYC Authentication

Flow Steps

Related Interfaces

Typical Flow

Authentication Status

Stage 2: Select Package, Apply for Card, Card Management

Flow Steps

Related Interfaces

Typical Flow

Card Status

Stage 3: Account & Fund Management (Credit Mode)

Flow Steps

Related Interfaces

Typical Flow

Transfer Types

Stage 4: Consumption & Billing

Flow Steps

Related Interfaces

Typical Flow

Consumption Types

Authorization Mode Special Flow

Complete Integration Timeline

FAQ