对接准备

联系业务人员开通平台帐号，获取接口参数(appKey、appSecret)

A

公共请求参数

公共请求参数

签名和解密

签名（sign）

• 将所有非空参数及appSecret，按参数名升序排序。
• 用 key=value 方式拼接，多个用 & 连接。
• 对拼接后的整个字符串进行 小写32位MD5。

签名格式：

md5(key1=value1&key2=value2&...&keyN=valueN)

示例：

拼接前:

amount=1&appId=YTUvZeeOdx&appSecret=owfwFkDnlCuiUTYz&callbackUrl=http://127.0.0.1:8921/api/callback/test&itemId=100001&outOrderId=2975857684279803&timestamp=20200717133601001&uuid=18898810602

MD5结果:

2f64566717836f1b62276519ac71aaf3

提示：

• appSecret 仅用于签名，不要作为参数上传。
• 排序应为全字节升序，空值参数不参与签名。
• 常见签名失败原因：时间戳不一致、未加 appSecret、排序错误、空参数被用于签名等。

签名示例代码

Go 示例

package main

import (
    "crypto/md5"
    "encoding/hex"
    "fmt"
    "sort"
    "strings"
)

// 构建签名字符串
func BuildSignString(params map[string]string, appSecret string) string {
    keys := make([]string, 0)
    for k, v := range params {
        if v != "" {
            keys = append(keys, k)
        }
    }
    keys = append(keys, "appSecret")
    sort.Strings(keys)
    var list []string
    for _, k := range keys {
        var val string
        if k == "appSecret" {
            val = appSecret
        } else {
            val = params[k]
        }
        if val != "" {
            list = append(list, fmt.Sprintf("%s=%s", k, val))
        }
    }
    return strings.Join(list, "&")
}

func Md5Lower(s string) string {
    h := md5.New()
    h.Write([]byte(s))
    return hex.EncodeToString(h.Sum(nil))
}

func main() {
    params := map[string]string{
        "amount":      "1",
        "appId":       "YTUvZeeOdx",
        "callbackUrl": "http://127.0.0.1:8921/api/callback/test",
        "itemId":      "100001",
        "outOrderId":  "2975857684279803",
        "timestamp":   "20200717133601001",
        "uuid":        "18898810602",
    }
    appSecret := "owfwFkDnlCuiUTYz"
    signStr := BuildSignString(params, appSecret)
    fmt.Println("待签名字符串:", signStr)
    fmt.Println("MD5签名:", Md5Lower(signStr))
}

Rust 示例

// md5 = "0.7"
use std::collections::BTreeMap;
use md5::{Md5, Digest};

// 将参数按名称升序拼接 & md5
fn build_sign_string<'a>(mut params: BTreeMap<&'a str, &'a str>, app_secret: &'a str) -> String {
    params.insert("appSecret", app_secret);
    params.iter()
        .filter(|(_, v)| !v.is_empty())
        .map(|(k, v)| format!("{}={}", k, v))
        .collect::<Vec<_>>()
        .join("&")
}

fn md5_lower(s: &str) -> String {
    let mut hasher = Md5::new();
    hasher.update(s.as_bytes());
    format!("{:x}", hasher.finalize())
}

fn main() {
    let mut params = BTreeMap::new();
    params.insert("amount", "1");
    params.insert("appId", "YTUvZeeOdx");
    params.insert("callbackUrl", "http://127.0.0.1:8921/api/callback/test");
    params.insert("itemId", "100001");
    params.insert("outOrderId", "2975857684279803");
    params.insert("timestamp", "20200717133601001");
    params.insert("uuid", "18898810602");
    let app_secret = "owfwFkDnlCuiUTYz";
    let sign_str = build_sign_string(params, app_secret);
    let sign = md5_lower(&sign_str);
    println!("待签名字符串: {}", sign_str);
    println!("MD5签名: {}", sign);
}

解密（AES）

• 算法: AES/ECB/PKCS5Padding，无盐
• 密钥: appSecret
• 输入: base64编码的密文

示例：

• 密文: jvU9Vaz67Gj+Xn/qlaXKHA==
• AES密钥: uDMGUIodDeKcja0nDbIBzpfDJFIHld56
• 解密后: 110

Go 示例

package main

import (
    "crypto/aes"
    "crypto/cipher"
    "encoding/base64"
    "fmt"
)

// 去除PKCS#7填充
func PKCS7Unpad(data []byte) []byte {
    padlen := int(data[len(data)-1])
    if padlen > len(data) {
        return data
    }
    return data[:len(data)-padlen]
}

func AESDecryptBase64(ciphertextBase64, key string) (string, error) {
    data, err := base64.StdEncoding.DecodeString(ciphertextBase64)
    if err != nil {
        return "", err
    }
    // 密钥长度应为 16/24/32
    block, err := aes.NewCipher([]byte(key))
    if err != nil {
        return "", err
    }
    if len(data)%aes.BlockSize != 0 {
        return "", fmt.Errorf("密文不是块大小的倍数")
    }
    decrypted := make([]byte, len(data))
    mode := newECBDecrypter(block)
    mode.CryptBlocks(decrypted, data)
    decrypted = PKCS7Unpad(decrypted)
    return string(decrypted), nil
}

// -------- 下面是 ECB mode 支持 --------------
type ecb struct{ b cipher.Block }
type ecbDecrypter ecb

func newECBDecrypter(b cipher.Block) cipher.BlockMode {
    return (*ecbDecrypter)(&ecb{b})
}
func (x *ecbDecrypter) BlockSize() int        { return x.b.BlockSize() }
func (x *ecbDecrypter) CryptBlocks(dst, src []byte) {
    bs := x.b.BlockSize()
    for len(src) > 0 {
        x.b.Decrypt(dst[:bs], src[:bs])
        src = src[bs:]
        dst = dst[bs:]
    }
}

func main() {
    encrypted := "U88v0HHTLxUp9LUkj95AJA=="
    key := "sBOvCZZurSbbdJiA" // 16字节
    plain, err := AESDecryptBase64(encrypted, key)
    if err != nil {
        fmt.Println("解密失败:", err)
    } else {
        fmt.Println("解密结果:", plain)
    }
}

Rust 示例

// aes = "0.8"
// block-modes = "0.9"
// block-padding = "0.3"
// base64 = "0.21"
use aes::Aes128;
use block_modes::{BlockMode, Ecb};
use block_modes::block_padding::Pkcs7;
use base64::{engine::general_purpose, Engine as _};

/// AES/ECB/PKCS5Padding 解密（Base64输入）
/// Java 兼容：Cipher.getInstance("AES/ECB/PKCS5Padding")
fn aes_ecb_decrypt_base64(cipher_base64: &str, key: &str) -> Result<String, Box<dyn std::error::Error>> {
    let cipher_bytes = general_purpose::STANDARD.decode(cipher_base64)?;

    let key_bytes = key.as_bytes();
    if !matches!(key_bytes.len(), 16 | 24 | 32) {
        return Err("密钥长度必须为 16 / 24 / 32 字节".into());
    }

    let cipher = Ecb::<Aes128, Pkcs7>::new_from_slices(key_bytes, &[])?;
    let decrypted = cipher.decrypt_vec(&cipher_bytes)?;

    Ok(String::from_utf8(decrypted)?)
}

fn main() {
    let encrypted = "jvU9Vaz67Gj+Xn/qlaXKHA==";
    let key = "uDMGUIodDeKcja0nDbIBzpfDJFIHld56"; // 32 字节 → AES-256

    match aes_ecb_decrypt_base64(encrypted, key) {
        Ok(plain) => println!("解密结果: {}", plain),
        Err(e) => println!("解密失败: {}", e),
    }
}

KYC

查询

简要描述

查看KYC申请状态

请求URL

POST ${baseUrl}/api/card/kyc/query

请求方式

• Method: POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "cardNumber": "1234567891234567",
        "completeTime": "",
        "createTime": "2023-04-02 17:07:09",
        "ext": "",
        "merOrderNo": "345342352343",
        "orderNo": "4534234363464342",
        "failReason": "",
        "status": 0
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data-下单订单信息

业务状态码说明

webhook

接口描述

当 KYC 状态发生变更时，平台会通知状态并返回申请卡号。

接口地址

由申请接口提供具体请求地址。

请求方式

POST

内容类型

Content-Type: application/json

请求参数

响应示例

body 内容为字符串：

ok

注意事项

如果未按要求返回 ok，平台将视为推送失败，并将按照指数退避（Exponential Backoff）策略进行重试：

• 首次失败后，1 分钟后重试，后续每次重试间隔时间翻倍（2、4、8、16 分钟），共推送 5 次。
• 若 5 次仍未成功，将在 10 分钟后再次进行重试。
• 只有返回字符串 ok 表示推送成功，平台才会停止重试。

MASTER-E

简要描述

MASTER-E 卡的 KYC 提交

请求URL

POST ${baseUrl}/api/card/kyc/apply/master/E
Content-Type: application/json

请求参数

返回示例

{
  "data": {
    "completeTime": "",
    "createTime": "2023-04-23 20:08:35",
    "ext": "",
    "merOrderNo": "230423200834215712",
    "orderNo": "230423200835147904",
    "status": 1
  },
  "msg": "操作成功",
  "status": 200,
  "success": true
}

返回参数说明

总体返回

data 字段

职位代码

职业代码

VISA-H

简要描述

VISA-H KYC 认证接口

请求URL

${baseUrl}/api/card/kyc/apply/visa/H

请求方式

• 方法：POST
• Content-Type：application/json

请求参数

返回示例

{
    "data": {
        "completeTime": "",
        "createTime": "2023-04-23 20:08:35",
        "ext": "",
        "merOrderNo": "230423200834215712",
        "orderNo": "230423200835147904",
        "status": 1
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

响应基础字段

data 参数-订单信息

虚拟卡

VIRTUAL-L

简要描述

此处 KYC 理解为开卡接口。
开卡成功会返回一个卡号。
注意：如未提交 firstRecharge，开卡会默认扣除 10 USD，且发卡系统默认会为卡充值 10 USD。

请求URL

• ${baseUrl}/api/card/kyc/apply/virtual/L
• ${baseUrl}/api/card/kyc/apply/virtual/L/en

请求方式

• Method : POST
• Content-Type : application/json

请求参数

返回示例

{
    "data": {
        "completeTime":"",
        "createTime":"2023-04-23 20:08:35",
        "ext":"",
        "merOrderNo":"230423200834215712",
        "orderNo":"230423200835147904",
        "status":1
    },
    "msg":"操作成功",
    "status":200,
    "success":true
}

返回参数说明

通用响应字段

data 字段参数说明

VIRTUAL-P

简要描述

开卡接口 注意：firstRecharge 默认为10，可以为0则开卡没有首充

请求URL

• ${baseUrl}/api/card/kyc/apply/virtual/P

请求方式

• Method: POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "cardNumber": "",
        "completeTime": "",
        "createTime": "2024-08-29 12:56:36",
        "ext": "",
        "merOrderNo": "100007893",
        "orderNo": "240829125636170528",
        "status": 1
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

通用响应字段

data字段参数说明

卡片管理

充值

简要描述

用于为卡片充值余额。

变更记录

请求URL

${baseUrl}/api/card/top/up

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "cardNumber": "6244810070000117",
        "completeTime": "",
        "createTime": "2023-04-02 17:07:09",
        "ext": "",
        "merOrderNo": "345342352343",
        "orderNo": "4534234363464342",
        "settleAmount": "20.00",
        "status": 0
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

响应字段

data - 订单信息

业务状态码说明

充值查询

简要描述

用于查询提交的充值订单。

请求URL

${baseUrl}/api/card/top/up/query

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "amount": "20",
        "cardNumber": "6244810070000117",
        "completeTime": "",
        "createTime": "2023-04-02 17:07:09",
        "ext": "",
        "merOrderNo": "345342352343",
        "orderNo": "4534234363464342",
        "settleAmount": "20.00",
        "status": 0
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

通用响应字段

data - 订单信息

业务状态码说明

充值Webhook

接口描述

当充值订单完成后，如果提交订单时填写了通知地址（notifyUrl），平台会向该地址发送通知请求。

• 接口地址：由订单接口中的 notifyUrl 参数决定
• 请求方式：POST
• Content-Type：application/json

请求参数

响应示例

接口返回内容需为字符串：ok

ok

注意事项

• 如果接口未按要求返回 ok，平台会认定为推送失败。
• 推送失败时，采用指数退避重试机制：
  • 首次失败后，每隔 1分钟 重试一次，连续重试最多 5次 （即共6次）。
  • 如果仍未收到正确响应，则在最后一次失败后 10分钟 后再次进行推送。
  • 若依然失败，平台会停止进一步自动推送，请及时排查并手动处理相关通知。

MASTER-E

卡片信息

简要描述

查询卡片基本信息（包括余额）

请求URL

${baseUrl}/op/card/E/info

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "available": 0,
        "availableLimit": 0,
        "balance": 0,
        "cardLimit": 0,
        "cardNo": "4242424242459888",
        "dailyAtmLimit": 0,
        "dailyPurchaseLimit": 0,
        "embossedName": "HUIBIN HUANG",
        "expiryMonth": "12",
        "expiryYear": "23",
        "status": 3
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data - 卡片信息

挂失/解挂

简要描述

用于卡片挂失、解挂。

请求URL

• 挂失：${baseUrl}/op/card/E/lock
• 解挂：${baseUrl}/op/card/E/un/lock

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "availableLimit": 0,
        "cardLimit": 0,
        "cardNo": "4242424242459888",
        "dailyAtmLimit": 0,
        "dailyPurchaseLimit": 0,
        "expiryMonth": "12",
        "expiryYear": "23",
        "status": 3
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data - 卡片信息

修改/设置ATM密码

简要描述

用于修改或设置ATM密码，PIN（密码）使用AES加密传输，保障安全性。

请求URL

• 安全设置（PIN加密）：${baseUrl}/op/card/E/change/pin/secure
• 普通设置（PIN明文）：${baseUrl}/op/card/E/change/pin

请求方式

• 方法：POST
• Content-Type：application/json

请求参数

返回示例

{
    "data": "succeed",
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

修改每日限额

简要描述

用于修改卡片每日的消费限额和ATM限额。

请求URL

${baseUrl}/op/card/E/set/daily/limit

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "availableLimit": "0",
        "cardLimit": "0",
        "dailyAtmLimit": "100",
        "dailyPurchaseLimit": "100",
        "embossedName": "HUIBIN HUANG",
        "expiryMonth": "12",
        "expiryYear": "23"
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data - 卡片信息

查询交易记录

简要描述

用于查询卡片的交易记录。

请求URL

${baseUrl}/op/card/E/transaction

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": [
        {
            "amount": "10",
            "cardAccountId": "938b56b2-3437-4295-8393-b5e407504c39",
            "cardEmbossedName": "",
            "cardId": "",
            "cardLast4": "",
            "createdAt": "2023-12-13T06:52:55.919Z",
            "currency": "HKD",
            "description": "增值",
            "entryType": "DEBIT",
            "id": "bb5bbae7-d987-4983-bf75-01b90c8e0f3f",
            "intent": "transfer",
            "merchant": "{\"country\":\"\",\"name\":\"\",\"mcc\":\"\",\"category\":\"\"}",
            "refId": "CTNAUG5382",
            "status": "posted"
        },
        {
            "amount": "500",
            "cardAccountId": "938b56b2-3437-4295-8393-b5e407504c39",
            "cardEmbossedName": "",
            "cardId": "",
            "cardLast4": "",
            "createdAt": "2023-12-13T03:30:50.390Z",
            "currency": "HKD",
            "description": "CREDIT BALANCE ADJUSTMENT",
            "entryType": "CREDIT",
            "id": "da8295d2-df35-4c61-b7df-85ea8e740b51",
            "intent": "topup",
            "merchant": "{\"country\":\"\",\"name\":\"\",\"mcc\":\"\",\"category\":\"\"}",
            "refId": "CTD8U71NPV",
            "status": "posted"
        }
    ],
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data - 交易记录信息

查询交易记录-分页

简要描述

用于查询卡片的交易记录，支持分页查询。

• 第一次查询时不传 pageToken
• 查询返回后，如果返回了 nextPageToken、prevPageToken，可根据这些 token 翻页再次查询

请求URL

${baseUrl}/op/card/E/transaction/page

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "nextPageToken": "eyJpZCI6IjZhNTExYmRiLTU0NmItNGM4Mi1iOGI0LWY5Yzc1NGJlMmI4OSIsInBhZ2VTaXplIjozLCJjdXJyZW50IjoyLCJkaXJlY3Rpb24iOiJuZXh0In0=",
        "prevPageToken": "",
        "transactions": [
            {
                "amount": "2",
                "cardAccountId": "938b56b2-3437-4295-8393-b5e407504c39",
                "cardEmbossedName": "",
                "cardId": "",
                "cardLast4": "",
                "createdAt": "2024-04-17 14:23:00",
                "currency": "HKD",
                "description": "增值",
                "entryType": "DEBIT",
                "id": "885d2247-27a8-4405-9db6-e5031d44e6fc",
                "intent": "transfer",
                "merchant": "{\"country\":\"\",\"name\":\"\",\"mcc\":\"\",\"category\":\"\"}",
                "refId": "CT156Z3CV6",
                "status": "posted",
                "xid": "accttrans_1780482111940837376"
            },
            {
                "amount": "22",
                "cardAccountId": "938b56b2-3437-4295-8393-b5e407504c39",
                "cardEmbossedName": "",
                "cardId": "",
                "cardLast4": "",
                "createdAt": "2024-03-19 18:56:38",
                "currency": "HKD",
                "description": "test",
                "entryType": "DEBIT",
                "id": "942a75ad-acf2-4718-b7ce-3b46a71f3804",
                "intent": "transfer",
                "merchant": "{\"country\":\"\",\"name\":\"\",\"mcc\":\"\",\"category\":\"\"}",
                "refId": "CTB7R765KX",
                "status": "posted",
                "xid": "accttranstest_1770039366362087424"
            },
            {
                "amount": "11",
                "cardAccountId": "938b56b2-3437-4295-8393-b5e407504c39",
                "cardEmbossedName": "",
                "cardId": "",
                "cardLast4": "",
                "createdAt": "2024-03-19 16:09:07",
                "currency": "HKD",
                "description": "test20240319",
                "entryType": "DEBIT",
                "id": "6a511bdb-546b-4c82-b8b4-f9c754be2b89",
                "intent": "transfer",
                "merchant": "{\"country\":\"\",\"name\":\"\",\"mcc\":\"\",\"category\":\"\"}",
                "refId": "CTJ4NT62GR",
                "status": "posted",
                "xid": "accttrans_1769997341692542976"
            }
        ]
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data - 分页数据

transactions - 交易信息

说明：

• 如果交易状态为 posted（Cleared），原交易记录状态保持不变，退款会新增一条交易记录。
• 如果交易状态为 pending（Locked），该记录会变为 void，并退还额度给客户，不会再有一条退款（Refund）记录。

VISA-H

卡片信息

简要描述

卡信息及余额查询

变更记录

请求URL

${baseUrl}/op/card/H/balance

请求方式

• Method: POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "availableCredit": 123,
        "currentBillingEndDate": 1724342400000,
        "cvv": "WBM3cgTCXY2Yt6ARQ82IVQ==",
        "expiry": "202707",
        "overallCreditLimit": 123,
        "panFirst6": "451888",
        "panLast4": "0229",
        "status": "activated",
        "totalBalance": 0
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

通用参数

data 字段说明

挂失/解挂

简要描述

卡挂失、解挂操作

请求URL

• POST ${baseUrl}/op/card/H/lock — 挂失
• POST ${baseUrl}/op/card/H/un/lock — 解挂

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": true,
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

修改/设置PIN

简要描述

用于修改或设置ATM密码，区别在于PIN需加密传输，更加安全。
原接口 ${baseUrl}/op/card/H/change/pin 已废弃。

请求URL

${baseUrl}/op/card/H/change/pin/secure

请求方式

• 方法：POST
• Content-Type：application/json

请求参数

返回示例

{
    "data": true,
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

查询交易记录

简要描述

用于查询交易记录。
在每日24点前的充值记录，会在次日7点生成账单。

更新记录

请求URL

${baseUrl}/op/card/H/transactions

请求方式

• 方法：POST
• Content-Type：application/json

请求参数

返回示例

{
  "data": [
    {
      "amount": 10,
      "creationTime": "2024-07-17T23:00:20.609Z",
      "currency": "HKD",
      "isATM": false,
      "isAuthorization": false,
      "isInCountry": true,
      "isOnline": false,
      "isPos": false,
      "memo": "Repayment for order r-2342342422342343 (501)",
      "reversal": false,
      "settlementDate": "2024-07-18T00:00:00Z",
      "transactionId": 1000001081427,
      "transactionSource": "6",
      "transactionType": "5",
      "txCompleted": true,
      "acquirerCurrency": "",
      "acquirerAmount": 0,
      "cardAcceptorName": ""
    },
    {
      "amount": 11,
      "creationTime": "2024-07-18T23:00:43.07Z",
      "currency": "HKD",
      "isATM": false,
      "isAuthorization": false,
      "isInCountry": true,
      "isOnline": false,
      "isPos": false,
      "memo": "Repayment for order r-240718180106121536 (501)",
      "reversal": false,
      "settlementDate": "2024-07-19T00:00:00Z",
      "transactionId": 1000001081883,
      "transactionSource": "6",
      "transactionType": "5",
      "txCompleted": true,
      "acquirerCurrency": "HKD",
      "acquirerAmount": 235,
      "cardAcceptorName": "AlipayHK*ALIPAY"
    }
  ],
  "msg": "操作成功",
  "status": 200,
  "success": true
}

返回参数说明

data - 交易记录字段说明

字典说明

transactionType - 交易类型字典

transactionSource - 交易来源字典

OOB

接口说明

当客户线上消费时，会触发 OOB 推送，将相关信息展示给客户，并提供按钮让客户进行确认。此流程详见 Visa 官方文档。

• 接口地址：后台安全中心配置的接收地址
• 请求方式：POST
• Content-Type：application/json

请求参数

data 字段参数说明及示例：

{
  "cardNumber": "7662222584726493096",
  "acsTransactionId": "41ce7a7d-9d57-4d87-b6e4-310acfa4b276",
  "transactionInformation": [
    {
      "merchantName": "Amazon",
      "purchaseAmount": "31.81",
      "purchaseCurrency": "USD",
      "purchaseDate": 1722212389000,
      "merchantCountryCode": 840,
      "acquirerMerchantID": "784959000762203",
      "maskedPAN": "451888******8888"
    }
  ],
  "threeDsRequestorAppUrl": "",
  "status": 1,
  "createdDate": 1722212395829,
  "lastModifiedDate": 1722212395829,
  "expireDate": 1722212495829
}

data 内部参数说明

transactionInformation 字段说明

status 字段字典

响应示例

body 内容为字符串：“ok”

ok

重要说明

• 未按要求返回 ok，平台将视为推送失败。由于有时效性，失败的推送不会重试。
• 如果多次推送失败，请采用指数退避策略重试，即每次重试延迟的时间逐步增加，建议最大重试次数不超过 5 次。

OOB处理

简要描述

当触发OOB时，用户收到OOB信息，由客户确认后提交处理动作。

请求URL

${baseUrl}/op/card/H/oob

请求方式

• Method：POST
• Content-Type：application/json

请求参数

返回示例

{
    "data": {
        "confirmationStatus": 2
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data 字段说明

confirmationStatus 字典说明

模拟触发OOB

简要描述

用于模拟触发一条 OOB（Out of Band）通知。

请求URL

${baseUrl}/op/card/H/oob/simulate

请求方式

• Method: POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": true,
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

VIRTUAL-P

说明

• 本卡与其他卡产品不同。
• 开卡时返回的卡号并非真实卡号，而是卡ID，仅用于API操作。
• 真实的卡号、有效期、CVV信息需通过卡信息中的 secureUrl 获取。
• secureUrl 需每次重新获取，使用一次后即失效。
• 可将 secureUrl 内嵌展示给用户使用。

获取卡头

简要描述

• 获取卡头，开卡时使用

请求URL

POST ${baseUrl}/op/card/P/bin
Content-Type: application/json

更新记录

请求方式

• 方法：POST
• Content-Type: application/json

返回示例

{
    "data": [
        {
            "bin": "537100",
            "issuerCountry": "US",
            "network": "MasterCard",
            "platforms": [
                {
                    "platformLabel": "Invideo AI",
                    "successRate": "1"
                },
                {
                    "platformLabel": "Notion",
                    "successRate": "1"
                }
            ]
        },
        {
            "bin": "428852",
            "issuerCountry": "US",
            "network": "Visa",
            "platforms": [
                {
                    "platformLabel": "Select Media",
                    "successRate": "1"
                },
                {
                    "platformLabel": "Victoria's Secret",
                    "successRate": "1"
                }
            ]
        },
        {
            "bin": "517746",
            "issuerCountry": "US",
            "network": "MasterCard",
            "platforms": [
                {
                    "platformLabel": "Replicate",
                    "successRate": "1"
                },
                {
                    "platformLabel": "Whoop",
                    "successRate": "1"
                }
            ]
        }
    ],
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

一级返回参数

data字段结构

platforms字段结构

卡信息

简要描述

获取卡信息，需要在兼容 v1 的接口前提下使用。

请求URL

${baseUrl}/op/card/P/info/v2

请求方式

• Method：POST
• Content-Type：application/json

请求参数

返回示例

{
    "data": {
        "balance": {
            "available": "10",
            "currency": "USD",
            "frozen": "0",
            "pending": "0"
        },
        "billingAddress": {
            "addressLine1": "456 Elm Street San Francisco",
            "addressLine2": "",
            "city": "DC",
            "country": "USA",
            "postalCode": "94101",
            "state": "WA"
        },
        "bin": "537100",
        "firstName": "Dennis",
        "last4": "0729",
        "lastName": "Huang",
        "cardInfo": {
            "cardNo":"2532hd2ubdebdebdebd",
            "cvv":"2532hd2ubdebdebdebd",
            "expYear":"2532hd2ubdebdebdebd",
            "expMonth":"2532hd2ubdebdebdebd"
        },
        "status": "Active"
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data 字段说明

billingAddress 字段说明

balance 字段说明

cardInfo 字段说明

status 字段说明

查询交易记录

简要描述

查询卡片的交易记录，查询时间跨度最大为3个月。

请求URL

POST ${baseUrl}/op/card/P/transaction
Content-Type: application/json

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "currentPage": 1,
        "pageSize": 2,
        "totalRecords": 1,
        "transactions": [
            {
                "amount": "10",
                "cardNumber": "5592922156696856",
                "currency": "USD",
                "debitOrCreditFlag": "D",
                "id": "ac4cef2d-8d1b-4ee9-a15e-b751ebaefad0",
                "status": "Closed",
                "transactionTime": "2024-11-29T02:24:14.578Z",
                "type": "TopUp"
            }
        ]
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data 字段说明（交易记录信息）

type 字段枚举值说明

status 字段枚举值说明

解冻/冻结

简要描述

• 对指定卡片进行冻结或解冻操作，用于临时锁定或解锁使用权限。

请求URL

冻结卡片

POST ${baseUrl}/op/card/P/lock
Content-Type: application/json

解冻卡片

POST ${baseUrl}/op/card/P/un/lock
Content-Type: application/json

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": true,
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

销卡

简要描述

卡注销操作

• 返回成功表示操作接收成功，后台会执行卡注销动作，该操作需要一定时间处理
• 注销成功后会有通知推送，推送内容会包含卡内金额退还信息

请求URL

POST ${baseUrl}/op/card/P/close
Content-Type: application/json

请求参数

返回示例

{
    "data": true,
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

Webhook

接口描述

通知信息，包括卡余额变动、3ds 消息等。

接口地址

由后台设置

请求方式

POST
Content-Type: application/json

指数退避

如遇推送失败，建议使用指数退避算法进行重试，例如初次失败后 1 秒，第二次 2 秒、4 秒、8 秒等递增，最多重试五次。

请求参数

请求示例

{
  "data": "{\"id\":\"e6a54b44-1a38-4d51-824c-6f7bf6e1fb3e\",\"currency\":\"USD\",\"amount\":\"9\",\"type\":\"TopUp\",\"cardNo\":\"5592922156696856\",\"status\":\"Closed\",\"transactionTime\":\"2024-11-29T07:14:18.157Z\"}",
  "sign": "dc227220340c874fec3bba43bad08b32",
  "appKey": "psqxrezci72955wqxlhar898vx2q8lts",
  "type": "CardTransaction"
}

响应示例

body 内容直接返回字符串 ok

ok

各通知类型说明

1. CardTransaction（卡交易通知）

type 枚举值

status 枚举值

2. DeleteCard（销卡通知）

status 枚举值

3. Card3dsOtp（3ds 验证码）

4. ThreeDomainSecureForwarding（3ds 跳转）

备注：有些卡需要跳转指定页面提交验证码

VIRTUAL-L

获取卡头

接口描述：
获取卡头信息，用于展示给客户查看。

请求URL：
${baseUrl}/op/card/L/head
${baseUrl}/op/card/L/head/en

请求方式：
POST

请求头部：
Content-Type: application/json

返回示例

{
    "data": [
        {
            "ChatGPT": [
                {
                    "美国": [
                        {
                            "VISA": [
                                "440872",
                                "489607",
                                "491090",
                                "485997"
                            ]
                        },
                        {
                            "万事达": [
                                "559292",
                                "556371"
                            ]
                        }
                    ]
                }
            ],
            "电商消费": [
                {
                    "美国": [
                        {
                            "VISA": [
                                "491090",
                                "489607",
                                "485997"
                            ]
                        },
                        {
                            "万事达": [
                                "559292",
                                "556371",
                                "556167",
                                "553437"
                            ]
                        }
                    ],
                    "中国香港": [
                        {
                            "VISA": [
                                "438357",
                                "493193"
                            ]
                        }
                    ]
                }
            ],
            "广告投放": [
                {
                    "美国": [
                        {
                            "VISA": [
                                "491090",
                                "489607",
                                "483317"
                            ]
                        },
                        {
                            "万事达": [
                                "559292",
                                "556371"
                            ]
                        }
                    ],
                    "中国香港": [
                        {
                            "VISA": [
                                "438357",
                                "493193"
                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

卡信息

简要描述：
获取卡信息

请求URL：
${baseUrl}/op/card/L/info

请求方式：
POST

请求头部：
Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "balance": "12.00",
        "cardExpiryDate": "08/2026",
        "cardNo": "5561672373861111",
        "cardStatus": "1",
        "cardStatusDesc": "使用中",
        "cardUserInfo": {
            "birthDate": "1992-09-20",
            "email": "[email protected]",
            "firstName": "dennis",
            "lastName": "hhb",
            "mobile": "9375161772"
        },
        "cvv": "1Hqa1r3Kb6nWIpVRn8/odg==",
        "localCurrency": "USD",
        "startActiveDate": "2024-08-10"
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data字段说明

cardUserInfo 字段说明

查询交易记录

简要描述：
查询指定卡号的交易记录。单次查询时间范围最大为 3 个月。

请求URL：
${baseUrl}/op/card/L/transaction

请求方式：
POST

请求头部：
Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "currentPage": 1,
        "pageSize": 2,
        "totalRecords": 3,
        "transactions": [
            {
                "cardId": "2408032111001269724",
                "crossBoardType": "1",
                "localCurrency": "USD",
                "localCurrencyAmt": "",
                "occurTime": 1722682107000,
                "platformType": "消费",
                "recordNo": "2408031848060073804",
                "respCode": "000000",
                "respCodeDesc": "交易成功",
                "transCurrency": "CNY",
                "transCurrencyAmt": "38.48",
                "transStatus": "APPROVED",
                "transType": "AUTH"
            },
            {
                "cardId": "2408032111001269724",
                "crossBoardType": "1",
                "localCurrency": "USD",
                "localCurrencyAmt": "",
                "occurTime": 1722682107000,
                "platformType": "消费",
                "recordNo": "2408031848060073804",
                "respCode": "000000",
                "respCodeDesc": "交易成功",
                "transCurrency": "CNY",
                "transCurrencyAmt": "38.48",
                "transStatus": "APPROVED",
                "transType": "AUTH"
            }
        ]
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data 字段说明（transactions 列表项）

解冻/冻结

接口描述：
用于对卡片进行挂失（冻结）或解挂（解冻）操作。

请求URL：
${baseUrl}/op/card/L/lock — 挂失
${baseUrl}/op/card/L/un/lock — 解挂

请求方式：
POST

请求头部：
Content-Type: application/json

请求参数

返回示例

{
    "data": true,
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

销卡

接口描述：
注销卡片。调用接口后若返回成功，仅代表操作已提交，后台系统会进行实际注销处理，此过程可能需要一定时间。待注销完成后会异步推送通知，通知中将包含退款金额等信息。

请求URL：
${baseUrl}/op/card/P/close

请求方式：
POST

请求头部：
Content-Type: application/json

请求参数

返回示例

{
    "data": true,
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

注意事项：

• 该接口仅提交注销请求，具体注销及退款流程需等待后台处理。
• 注销完成后会有专门的通知推送，包含退款金额（退还到备用金账户）。

OTP-Webhook

接口描述：
OTP通知，用户在使用卡片时，若需要验证码，会通过本接口推送当前OTP，需将OTP及时提供给用户。

接口地址：
后台设置

请求方式：
POST

请求头部：
Content-Type: application/json

请求参数

响应示例

接口响应内容为字符串 “ok”：

ok

注意事项：

• OTP具有时效性，仅通知一次

Bill-Webhook

接口描述：
当卡余额有变动时，平台会推送通知至指定后台地址。

接口地址：
后台配置通知地址

请求方式：
POST

请求头部：
Content-Type: application/json

请求参数

请求示例

{
    "localCurrencyAmt": "10",
    "occurTime": "2024-09-03 17:40:06",
    "platformType": "开卡预存",
    "sign": "d1fd48a0268506f4a131442a27485385",
    "localCurrency": "USD",
    "transCurrency": "USD",
    "recordNo": "2409031607063343947",
    "crossBoardType": "1",
    "transType": "TOP UP",
    "respCodeDesc": "交易成功",
    "appKey": "psqxrezci72955wqxlhar898vx2q8lts",
    "respCode": "000000",
    "transCurrencyAmt": "10",
    "transStatus": "APPROVED"
}

响应示例

ok （body内容为字符串“ok“）

注意事项

1. 若未按要求返回ok，平台将视为推送失败，平台将采用指数退避策略进行重试，初次推送失败后每隔1分钟进行重复推送5次。
2. 若依然未成功回应，将在10分钟后再进行新一轮推送，如此共10组（共计最多50次）。
3. 请确保及时正确响应，避免消息丢失。

close-Webhook

接口描述：
先提交注销请求，注销成功后进行通知。
退款金额将退回备用金账户，客户端需自行处理退款。
需在中台-安全中心配置通知地址。

接口地址：
后台设置

请求方式：
POST

请求头部：
Content-Type: application/json

请求参数

请求示例

{
    "localCurrencyAmt": "10",
    "occurTime": "2024-09-03 17:40:06",
    "sign": "d1fd48a0268506f4a131442a27485385",
    "localCurrency": "USD",
    "recordNo": "2409031607063343947",
    "appKey": "psqxrezci72955wqxlhar898vx2q8lts",
    "transCurrencyAmt": "10"
}

响应示例

请求成功时，body 内容需返回字符串 ok：

ok

注意事项

1. 未按要求返回 ok 时，平台将视为推送失败，将使用指数退避（exponential backoff）策略：首次失败后，每1分钟重试一次，连续推送5次为一组。
2. 若5次重试仍未回应，间隔10分钟后，将开始下一组重试。共重试10组，总计50次。
3. 若持续不回应，可能导致卡片注销退款未能及时处理，请务必保证消息接收与正确回应。

模拟验证码

简要描述：
用于模拟客户触发验证码功能，若已绑定通知地址，通知地址会收到本次模拟消息。仅适用于测试环境。

请求URL：
${baseUrl}/op/card/L/simulation/otp

请求方式：
POST

请求头部：
Content-Type: application/json

请求参数

返回示例

{
    "data": true,
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

模拟交易

简要描述：
用于模拟客户发起一笔交易。若已绑定通知地址，通知地址会收到本次模拟消息。仅适用于测试环境。

请求URL：
${baseUrl}/op/card/L/simulation/transaction

请求方式：
POST

请求头部：
Content-Type: application/json

请求参数

返回示例

{
    "data": true,
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

B

快速开始

API 公共参数

API 涉及的公共请求参数和返回参数如下：

请求参数

返回参数

所有返回均为 JSON 格式，数据结构如下：

获取 Token

默认 token 有效期为 2 小时。token 过期后，可以重新获取新 token。

• 请求方法：POST
• 请求地址：/oauth/api/v1/token

请求参数

返回参数

卡操作

创建卡片

说明：

• 批量开卡需循环调用本接口，建议调用频率不超过每秒2次。
• 开卡成功后，系统将发送异步通知。如未收到通知，可通过查询接口补偿获取结果。

请求方式：POST
请求地址：/card/api/v1/op/create

请求参数

返回参数

卡详情查询

请求方式：GET
请求地址：/card/api/v1/op/queryCardDetail

请求参数

以下参数二选一传：

返回参数

卡充值

对子卡无需充值，仅需充值主卡。

请求方式：POST
请求地址：/card/api/v1/op/recharge

请求参数

返回参数

卡提现

仅主卡可提现。

请求方式：POST
请求地址：/card/api/v1/op/withdraw

请求参数

返回参数

卡注销

请求方式：POST
请求地址：/card/api/v1/op/cancel

请求参数

返回参数

调整限额

请求方式：POST
请求地址：/card/api/v1/op/updateTotalAuthLimit

请求参数

卡操作记录查询

请求方式：GET
请求地址：/card/api/v1/trade/queryCardOpDetail

请求参数

返回参数

CardOpDetail 字段

MerchantFee 字段

MerchantFeeDetail 字段

卡操作类型

交易查询

交易列表

请求方式：GET
请求地址：/card/api/v1/trade/queryCardTransactions

请求参数

返回参数

CardTransactionDetail 字段说明

MerchantFee 字段说明

MerchantFeeDetail 字段说明

交易类型

Webhook 异步通知

重要说明

• 异步通知时，商户系统需正确响应参数，返回字符串 “ok”，否则视为未成功。
• 交易完成后，系统会根据商户订阅的 webhook 地址，通过 POST，将结果以 application/json 格式发送给商户。
• 请务必验证签名，防止数据泄漏和伪造通知。

注意事项

1. 幂等性
   同一通知可能多次发送，商户系统需能正确处理重复通知。建议做法：收到通知后，先检查业务数据状态，仅对未处理的通知进行处理，已处理直接返回 200 和 "OK"。状态检查和数据操作前须加锁，避免并发导致状态混乱。

2. 时效性
   极少数情况下通知可能因网络等原因未送达，请务必通过主动查询接口补偿。建议根据实际业务，合理设置补偿查单的时机，如支付1小时后未收到通知可主动查单。

3. 防抵赖
   商户侧须对通知内容做签名校验（签名公钥见商户后台），并校验通知内容与本地数据一致，防止伪造通知导致资金风险。

通知类型

CardApply

开卡结果

注销结果

CardOperate

Authorization

参见交易查询

MerchantFee

FeeDetail

Inbound

| 字段说明 | 参见 InboundDetail |

签名验证参考

Go 示例

import (
    "crypto/rsa"
    "crypto/x509"
    "crypto"
    "encoding/pem"
    "encoding/base64"
    "net/http"
    "io/ioutil"
)

// 验证签名
func verifySign(content, signBase64, pubKeyPEM string) bool {
    block, _ := pem.Decode([]byte(pubKeyPEM))
    if block == nil {
        return false
    }
    pub, err := x509.ParsePKIXPublicKey(block.Bytes)
    if err != nil {
        return false
    }
    rsaPub := pub.(*rsa.PublicKey)
    sig, _ := base64.StdEncoding.DecodeString(signBase64)
    h := crypto.SHA256.New()
    h.Write([]byte(content))
    return rsa.VerifyPKCS1v15(rsaPub, crypto.SHA256, h.Sum(nil), sig) == nil
}

// Webhook Handler 示例
func WebhookHandler(w http.ResponseWriter, r *http.Request) {
    appId := "1569641270953589506"
    publicKey := `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsIHIQAp4TToRZuF+/g/fr4xxJg/hGxyZGwp66l1LSS7sfsx/EnaCY0mYzEBZZ6qqEShdrtlowJa2SudemqeWbbH75vkcwvwL7cMX58pXNPny4vACaKSnIdz1wwue/tUWmubQdhb7wwJDDKB+TQoyhrZbNsW9tsASCu8WjdmxqH0i0It/FjrMw7R4pv0jrZfMmoZs0mhxnrF5HnPzRW+kFgKwDGIRzhsy32iMTk7lbOkSrBK923TuWy/mb5h3Vzw1c/PVtl9udFG2SbQsl848jXQx5TUhyh0XIVLVMRu/EAiq54bIsh/YNWx75nfCkH+h7T6d0L8qxIdQB/qdt/RZQwIDAQAB
-----END PUBLIC KEY-----`

    sign := r.Header.Get("sign")
    timestamp := r.Header.Get("x-timestamp")
    body, _ := ioutil.ReadAll(r.Body)
    content := appId + timestamp + string(body)

    if !verifySign(content, sign, publicKey) {
        // 签名有误，记录日志
        w.WriteHeader(http.StatusBadRequest)
        w.Write([]byte("sign error"))
        return
    }
    w.Write([]byte("ok"))
}

Rust 示例

use base64::{Engine as _, engine::general_purpose};
use ring::signature::{UnparsedPublicKey, RSA_PKCS1_2048_8192_SHA256};

fn verify_sign(content: &str, sign_b64: &str, public_key_der: &[u8]) -> bool {
    let signature = match general_purpose::STANDARD.decode(sign_b64) {
        Ok(sig) => sig,
        Err(_) => return false,
    };
    let pub_key = UnparsedPublicKey::new(&RSA_PKCS1_2048_8192_SHA256, public_key_der);
    pub_key.verify(content.as_bytes(), &signature).is_ok()
}

fn main() {
    let app_id = "1569641270953589506";
    let timestamp = "1716350279000";
    let body = r#"{"partner_order_id":"xxxx","status":"Success"}"#;
    let content = format!("{}{}{}", app_id, timestamp, body);

    let public_key_pem = r#"-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsIHIQAp4TToRZuF+/g/fr4xxJg/hGxyZGwp66l1LSS7sfsx/EnaCY0mYzEBZZ6qqEShdrtlowJa2SudemqeWbbH75vkcwvwL7cMX58pXNPny4vACaKSnIdz1wwue/tUWmubQdhb7wwJDDKB+TQoyhrZbNsW9tsASCu8WjdmxqH0i0It/FjrMw7R4pv0jrZfMmoZs0mhxnrF5HnPzRW+kFgKwDGIRzhsy32iMTk7lbOkSrBK923TuWy/mb5h3Vzw1c/PVtl9udFG2SbQsl848jXQx5TUhyh0XIVLVMRu/EAiq54bIsh/YNWx75nfCkH+h7T6d0L8qxIdQB/qdt/RZQwIDAQAB
-----END PUBLIC KEY-----"#;

    let public_key_der = pem::parse(public_key_pem)
        .expect("parse PEM")
        .contents();

    let sign_base64 = "xxxx";

    if verify_sign(&content, sign_base64, &public_key_der) {
        println!("签名验证通过");
    } else {
        println!("签名验证失败");
    }
}

Transfer

v4

获取所有报价

简要描述
获取所有可用的报价信息

请求URL
${baseUrl}/tf/v4/quotes/all

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

返回示例

{
    "rates": [
        {
            "input": "USD",
            "output": "EUR",
            "rate": 0.840138
        },
        {
            "input": "USD",
            "output": "AUD",
            "rate": 1.521811
        },
        {
            "input": "USD",
            "output": "BDT",
            "rate": 122.5773
        }
    ],
    "lastUpdateTime": 1753683680263
}

返回参数说明

data 信息说明

查询支持的业务模式

简要描述

查询当前支持的业务模式。

请求URL

${baseUrl}/tf/v4/business

请求方式

• Method: POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": [
        {
            "business": "C2C"
        },
        {
            "business": "B2B"
        }
    ],
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data 信息

获取报价

简要描述

获取汇率报价信息。

更新记录

请求URL

${baseUrl}/tf/v4/quotes

请求方式

• Method: POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "input": "USD",
        "output": "CNY",
        "rate": 6.402552,
        "fixedFee": 5,
        "preRatedFee": 0.012,
        "fullPay": true,
        "fullPayFee": 20
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data 信息

获取可发送国家

简要描述
获取可发送的国家列表，用于创建订单时的 sourceCountry 字段。

请求URL
POST ${baseUrl}/tf/v4/sourceCountry

请求方式

• Method: POST
• Content-Type: application/json

返回示例

{
    "data": [
        {
            "code": "ABW",
            "name": "Aruba",
            "shortCode": "AW"
        },
        {
            "code": "AFG",
            "name": "Afghanistan",
            "shortCode": "AF"
        }
    ],
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data 对象字段说明

创建订单

简要描述

发起汇款。字段较多，分为几部分组成。可结合业务理解参考中台订单创建流程。不同下发模式所需信息不一致，主要可分为 wire 和其他（bank_account、cash_pickup、ewallet）。其他类型均为 C2C 模式，仅 wire 支持 B2B、B2C、C2B，wire 的校验较少。

请求URL

${baseUrl}/tf/v4/order/create

请求方式

• Method：POST
• Content-Type：application/json

参数说明

金额相关

下发路径

收款账号相关

收款方信息

发送方信息

订单附属信息

字段规则说明

• sourceMobileNumber，targetMobileNumber
  • business=C2C && type=bank_account && country in (CMR, COG, GHA, KEN, UGA, BGD, CAD, IDN, KRW, NPL, USA, VNM)
  • business=C2C && type=ewallet && country in (BEN, CMR, COG, GHA, MDG, MWI, MOZ, NER, RWA, SEN, TZA, TGO, UGA, ZMB, BGD, IDN, NPL)
  • business=C2C && type=cash_pickup && country in (BGD, KHM, IDN, KRW, NPL, PHP, VNM)
• sourceIdNumber
  • country=IDN && business=C2C && type=ewallet
  • country=CHN && business=C2C && type=bank_account
  • type=wire && country=HKG && currency=HKD
  • type=wire && country=AUS && currency=AUD
  • type=wire && country=SGP && currency=SGD
• sourceAddressCountry、targetAddressCountry
  • type=wire && country=HKG && currency=HKD
  • type=wire && country=AUS && currency=AUD
  • type=wire && country=SGP && currency=SGD

返回示例

{
    "data": {
        "account": "543435",
        "completeTime": "",
        "createTime": "2024-08-31 23:08:58",
        "ext": "",
        "failReason": "",
        "merOrderNo": "240831230857132800",
        "orderNo": "240831230858245344",
        "sendAmount": 0,
        "chargeCode": "FP",
        "fullPayFee": "20",
        "fixedFee": 5,
        "preRatedFee": 0.012,
        "sourceAmount": 1586.15,
        "sourceCurrency": "USD",
        "status": 0,
        "targetAmount": 10000,
        "targetCurrency": "CNY"
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data-下单订单信息说明

业务状态码说明

订单查询

简要描述

查询提交的订单。
UETR需在订单结束5-30分钟后获取，如有需要可主动查询。

更新记录

请求URL

${baseUrl}/tf/v4/order/query

请求方式

• Method: POST
• Content-Type: application/json

请求参数

返回示例

{
    "data": {
        "account": "543435",
        "completeTime": "2024-08-31 15:17:56",
        "createTime": "2024-08-31 15:03:25",
        "ext": "",
        "failReason": "",
        "merOrderNo": "240831150324112064",
        "orderNo": "240831150325224032",
        "sourceAmount": 1586.150,
        "sendAmount": 0,
        "sourceCurrency": "USD",
        "status": 1,
        "targetAmount": 10000,
        "targetCurrency": "CNY",
        "fixedFee": 5,
        "preRatedFee": 0.012,
        "chargeCode": "FP",
        "fullPayFee": 20
    },
    "msg": "操作成功",
    "status": 200,
    "success": true
}

返回参数说明

data - 订单信息

ext - 订单额外信息

订单通知

接口描述

当订单完成且提交订单时有通知地址，平台将会通知此接口。

更新记录

接口地址

由订单接口提供请求地址

请求方式

• 方法：POST
• Content-Type: application/json

请求参数

ext 字段说明

响应示例

body 内容为字符串 ok：

ok