Oceanpayment Developer

概述

用于创建卡片并分配至指定账户或卡产品。卡片创建后可用于线上或线下支付，并可通过交易限制规则（如额度、地区、商户类别等）进行使用控制，以保障资金安全与合规性。

开始之前

创建卡片前，需要先完成必要的参数准备和基础配置，包括请求头设置、持卡人创建、卡产品及账户信息获取，以及卡交易限制规则配置。建议按照流程图的顺序完成相关配置后，再调用创建卡片。

确认创建模式

提示

请选择以下适合您的卡片资金管理方式。

独立账户管理模式
共享账户管理模式

商户可以创建多个独立的账户(account_id)。在创建卡片时，必须指定把这张卡挂在某个账户下面。同一个账户里的卡片共享这个账户的额度，不同账户之间的资金完全物理隔离。

流程图

商户在系统下拥有一个默认的账户(account_id)。在创建卡片时，系统会自动把所有卡都绑定到这一个默认账户里，所有卡片共同消耗这个账户的总额度。

流程图

设置请求头组

获取已创建的授权Token。

Resquest

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

创建持卡人

如果账户已存在默认持卡人，card_holder_id为可选参数；
如果账户不存在默认持卡人，则需先创建持卡人，获取持卡人 ID card_holder_id。

Response

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

获取卡产品名称

product_name用于标识卡产品名称（Card Product Name），即卡片所属的卡产品、卡段或发卡方案，用于区分不同的卡类型或发卡计划。您可以通过查询卡产品名称获取product_name。

Response

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

获取账户唯一标识

系统生成的账户唯一标识，用于区分不同的商户账户或子账户资金池。创建卡片时可使用account_id指定卡片归属的主账户或子账户。

Response

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

获取账户卡类型

通过账户卡类型列表获取program_value类型：

Response

{
  "program_value": 2,
  "program_cn_name": "美金单币卡_USD",
  "program_en_name": "Oceanpayment Merchant USD"
}

设置您的卡交易限制

设置您的交易限制，其中交易限制的key为trade_risk_name，value值为trade_risk_value。
设置多个限制：当您的卡交易限制有多个规则时，可以通过risk_list进行设置。

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"
       }
    ]
}

开始创建卡片

Resquest

cURL -X POST /card-api/v1/cards/create
-H 'Content-Type: application/json'
-H 'Authorization: {token}'
-d '{
	"card_name": "Personal Card",
	"card_holder_id": "1814356660259814571",
	"card_desc": "Personal spending card",
	"card_validity_time": "203010",
	"product_name": "***26452香港Mastercard",
	"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"
		}
	]

   }'

参数名	类型	长度	是否必填	描述	示例
card_name	string	0-50	否	卡片名称	Personal Card
card_holder_id	string	0-20	有条件	持卡人ID	1814356660259814571
card_desc	string	0-200	否	卡片描述	Personal spending card
card_validity_time	string	0-10	否	卡有效期格式： yyyyMM	203010
product_name	string	1-10	是	卡产品名称卡产品通过BIN段、发卡国家及卡组织进行区分	***26452香港Mastercard
account_id	string	0-20	有条件	商户账户唯一标识号与`program_value`至少传一个，优先级高于`program_value`	1016X10007530070724
program_value	int	0-10	有条件	账户卡类型与`account_id`至少传一个通过查询卡详细信息查找已设置的卡片交易限制在更新卡设置信息修改您的卡片交易限制	2
+risk_list	object	-	是	交易风险列表	{ "risk_list": [{ "trade_risk_name":"purchase_1d", "trade_risk_value":"100" }] }

卡片创建成功

创建卡片成功后，需要使用card_id来关联您的卡号信息。

Response

{
    "code": "200",
    "msg": "操作成功",
    "trace_id": "6b9884b1583847c4a72b2b28525b2535",
    "data": {
        "product_name": "****26452香港Mastercard",
        "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"
    }
}

使用查询卡号与CVV获取您的卡号和CVV信息。
接下来使用查询卡详细信息获取卡产品名称、账户号、卡片类型、脱敏卡号、持卡人、卡交易限制、余额等信息。

异步处理说明

创卡完成后，卡片状态可能无法立即同步。建议通过查询卡片状态轮询获取最新状态，并设置合理的重试次数或超时时间，避免无限轮询。

概述​

开始之前​

确认创建模式​

设置请求头组​

创建持卡人​

获取卡产品名称​

获取账户唯一标识​

获取账户卡类型​

设置您的卡交易限制​

开始创建卡片​

卡片创建成功​

异步处理说明​

概述