Overview

This API is used to create a card and assign it to a specified account or card product. Once created, the card can be used for online or offline payments, and its usage can be controlled through transaction restriction rules (such as limits, regions, and merchant categories) to ensure fund security and regulatory compliance.

Before You Start

Before creating a card, the merchant must first confirm the account management mode to be used for the card: Independent Account Management Mode or Shared Account Management Mode. After confirming the account management mode, complete the required parameter preparation and basic configuration, including request header settings, cardholder creation, card product and account information retrieval, and card transaction limit configuration.

Confirm the Creation Mode

NOTE

Please select the card fund management mode that best suits your needs. It is recommended that the merchant complete the relevant configurations in the order shown in the flowchart and verify that the selected account management mode and related parameters are correct before calling the Create Card.

Standalone Account Management Mode

Merchants can create multiple independent accounts (account_id). When creating a card, a specific account must be assigned to the card. Cards under the same account share the account's available balance, while funds between different accounts are completely segregated. Under the Independent Account Management Mode, each card is assigned to a sub-account with an independent fund pool. The parent-child account structure must be enabled first. The API call sequence is: Query the sub-account account_id (create the sub-account first if it does not exist) → Retrieve the card product (program_value, product_name) → Call the Create Card.

There are three scenarios based on the combination of parameters provided:

Parameter Combination	System Processing Logic	Result
Both program_value and the sub-account account_id are provided	Validates whether program_value matches account_id: If they match, the card is created under the specified sub-account account_id. If they do not match, card creation fails.	Match: Success Mismatch: Failed
Only the sub-account account_id is provided	Creates the card directly under the specified sub-account account_id	Success
Only program_value is provided (there is no need to query account_id in advance)	Creates the sub-account account_id first, and then creates the card	Success

Flowchart

Shared Account Management Mode

Each merchant has a default account (account_id) in the system. When issuing a card, all cards are automatically linked to this default account. The cards share the same account-level balance and collectively consume the account's total available limit.

Flowchart

Set Request Headers

Retrieve the created Access Token.

Resquest

cURL -X POST /card-api/v1/cards/create
-H 'Content-Type: application/json'
-H 'Authorization: {token}'

Create a Cardholder

• If a default cardholder already exists for the account, card_holder_id is optional.
• If no default cardholder exists for the account, you must first create a cardholder and provide the cardholder ID (card_holder_id).

Response

{
    "data": {
        "card_holder_id": 1955930998425718784
    }
}

Card Product Name

product_name identifies the Card Product Name, which represents the card product, card range, or issuance program to which the card belongs. It is used to distinguish different card types or card issuance plans. You can obtain product_name by Query Card Product Name.

Response

{
  "data": {
     "program_value": 2,
     "total_count": 1,
     "products": [
        {
            "product_name": "***26452HKMastercard"
        }
     ]
  }
}

Retrieve Account Unique ID

A system-generated unique account identifier used to distinguish the fund pools of different merchant accounts or sub-accounts. When creating a card, you can use account_id to specify whether the card belongs to a parent account or a sub-account.

Response

{
  "data": {
     "account_id": "1016X10007530070724",
     "parent_account_id": "1016X10007422220312",
     "creation_time": 1782367203137,
     "modified_time": 1782367203137
  }
}

Retrieve Account Card Type

Retrieve the account card type list to obtain the program_value.

Response

{
  "program_value": 2,
  "program_cn_name": "USD",
  "program_en_name": "Oceanpayment Merchant USD_HOME"
}

Configure Card Transaction Limits

• Define transaction limits for your card. Each rule consists of a trade_risk_name (limit key) and a corresponding trade_risk_value.
• Multiple limits: If multiple transaction rules are required, configure them using the risk_list array.

Resquest

{
    "risk_list": [{
         "trade_risk_name": "purchase_count_1d",
         "trade_risk_value": "100"
       },
       {
         "trade_risk_name": "purchase_1d",
         "trade_risk_value": "10"
       },
       {
         "trade_risk_name": "allowed_countries",
         "trade_risk_value": "US,CN"
       }
    ]
}

Create a Card

Resquest

cURL -X POST /card-api/v1/card-api/v1/cards/create
-H 'Content-Type: application/json'
-H 'Authorization: {token}'
-d '{
	"card_name": "78415632",
	"card_holder_id": "1814356660259814571",
	"card_desc": 100,
	"card_validity_time": "203010",
    "product_name": "***26452HKMastercard",
	"account_id": "1016X10007530070724",
	"program_value": 2,
	"risk_list": [{
			"trade_risk_name": "purchase_count_1d",
			"trade_risk_value": "100"
		},
		{
			"trade_risk_name": "purchase_1d",
			"trade_risk_value": "10"
		},
		{
			"trade_risk_name": "allowed_countries",
			"trade_risk_value": "US,CN"
		}
	]

   }'

Parameter	Type	Length	Required	Description	Example
card_name	string	0-50	Optional	Card name	Personal Card
card_holder_id	string	0-20	Conditional	Cardholder ID	1814356660259814571
card_desc	string	0-200	Optional	Card description	Personal spending card
card_validity_time	string	0-10	Optional	Card expiration date Format: yyyyMM	203010
product_name	string	1-10	Required	Card product name Card products are distinguished by BIN ranges, issuing country, and card scheme (network).	***26452HKMastercard
account_id	string	0-20	Conditional	Unique merchant account ID At least one of account_id or program_value must be provided. account_id takes precedence over program_value. In Shared Account Management Mode, pass the parent account ID; in Standalone Account Management Mode, pass the sub-account ID.	1016X10007530070724
program_value	int	0-10	Conditional	Account card type At least one of program_value or account_id must be provided. Retrieve the configured card transaction limits using the Query Card Details. Update your card transaction limits via the Update Card Transaction Limits	2
+risk_list	object	-	Required	Transaction risk list	{ "risk_list": [{      "trade_risk_name":"purchase_1d",  "trade_risk_value":"100" }] }

Card Created Successfully

After the card is created, use the card_id to associate and retrieve the card number information.

Response

{
    "code": "200",
    "msg": "Success",
    "trace_id": "6b9884b1583847c4a72b2b28525b2535",
    "data": {
        "product_name": "***26452HKMastercard",
        "card_id": 1954802358738284544,
        "card_number": "527375 **** 4392",
        "card_name": "",
        "card_status": "Activate",
        "create_time": "2025-08-11T15:09:35+08:00",
        "card_remark": null,
        "card_validity_time": "2027-08-01T00:00:00+08:00",
        "card_desc": "",
        "risk_list": [
            {
                "trade_risk_name": "purchase_1d",
                "trade_risk_value": "100"
            },
            {
                "trade_risk_name": "blocked_countries",
                "trade_risk_value": "US"
            }
        ],
        "program_value": 2,
        "program_cn_name": "OTA",
        "program_en_name": "USD Multi Card_OTA",
        "card_holder_id": 1950830536975781888,
        "create_status": 1,
        "create_resp_msg": null,
        "account_id": "1016X10034796020144"
    }
}

1. Use the Query Card Number and CVV to retrieve your card number and CVV information.
2. Next, use the Query Card Details to retrieve card information, including the card product name, account number, card type, masked card number, cardholder name, card transaction restrictions, available balance, and other related details.

Asynchronous Processing

Card creation is processed asynchronously, so the card status may not be updated immediately after the request completes. We recommend periodically calling the Query Card Details to check the latest status. To avoid indefinite polling, configure a reasonable retry limit or timeout based on your business requirements.