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, you need to complete the required configurations and prepare the necessary parameters, including setting up request headers, creating a cardholder, retrieving card product and account information, and configuring card transaction restrictions. We recommend following the workflow below before calling the Create Card.

Confirm the Creation Mode

NOTE

Please select a card fund management method that suits your needs.

Standalone Account Management Mode

Merchants can create multiple standalone accounts (account_id). When issuing a card, the card must be associated with a specific account. Cards linked to the same account share the account-level spending limit, while funds across different accounts are fully segregated.

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 /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/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.	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.