NAV
Java Demo

1 接入说明

1.1 生成消息签名

import org.apache.commons.codec.digest.HmacUtils;

/**
 * 计算消息签名
 *
 * @param merchantSecretKey 商户密钥,开户后由在线支付系统提供
 * @param messageData       发送或者接收到的消息中的所有参数
 * @return 计算出的签名结果
 */
public static String calculateSignature(String merchantSecretKey,
                                        Map<String, Object> messageData) {

    // 按参数名排序,并组装待签名字符串
    String rawSignature = messageData.entrySet().stream()
            .filter(e -> !"signature".equals(e.getKey()))
            .sorted(Comparator.comparing(Map.Entry::getKey))
            .map(Map.Entry::getValue)
            .filter(Objects::nonNull)
            .map(String::valueOf)
            .collect(Collectors.joining("|"));

    // 调用 HMAC_SHA256 算法计算签名
    return new HmacUtils(HMAC_SHA_256, merchantSecretKey).hmacHex(rawSignature);
}

在消息交换中,为了验证消息的真实性和完整性,在提交请求请求响应 以及 回调通知 中传递的消息都需要附带上签名信息。

生成签名的步骤如下:

1.2 常用参数说明

参数名称 参数说明
merchantId 商户号。开户时由在线支付提供。
merchantSecretKey 商户密钥。开户时由在线支付提供。
merchantOrderId 商户订单号。由商户系统生成,要求商户订单号保持唯一性。已使用过的订单号不能用来重复提交。
amount 订单金额。例如:125.50。
currency 订单币种。支持币种包括 CNY,THB,MYR,JPY。
nonce 随机字符串。用来保证签名的不可预测性。建议使用随机UUID。例如:b228f8de-0fc1-47a1-8727-c7a07c05484d
createdAt 订单创建时间(UTC+8)。格式:yyyy-MM-dd HH:mm:ss 。例如:2019-03-12 00:38:40。生成消息签名时请务必使用相同的格式。

2 通用接口

2.1 查询可用支付方式

private static String merchantId = "8101";
private static String merchantUserId = "testUser01";
private static String merchantSecretKey = "NjE5NDA4NWUtYmVlMi00OWQ1";
private static String methodsGatewayUrl = "https://api.fundsguard.net/methods";

public ResponseEntity getAvailableMethods() {
    Map<String, Object> mapData = new HashMap<>();
    mapData.put("merchantId", merchantId);
    mapData.put("merchantUserId", merchantUserId);
    mapData.put("type", "DEPOSIT");
    mapData.put("currency", "CNY");
    mapData.put("nonce", UUID.randomUUID().toString());
    
    // 计算消息签名
    mapData.put("signature", calculateSignature(merchantSecretKey, mapData));

    // 组装订单查询URL地址
    UriComponentsBuilder uriBuilder = UriComponentsBuilder.fromHttpUrl(depositGatewayUrl);
    mapData.entrySet().stream().forEach(e -> uriBuilder.queryParam(e.getKey(), e.getValue()));

    return new RestTemplate().getForEntity(uriBuilder.toUriString(), String.class);
}

当请求成功时,在线支付系统会返回以下结构的JSON响应数据:

[
    {
        "type": "DEPOSIT",
        "currency": "CNY",
        "method": "BANK_TRANSFER",
        "minimumAmount": "100",
        "maximumAmount": "3000"
    },
    {
        "type": "DEPOSIT",
        "currency": "CNY",
        "method": "BANK_TRANSFER",
        "minimumAmount": "100",
        "maximumAmount": "5000"
    }
]

该接口由商户发起,用来获取当前可用的支付方式以及限额。

请求方式

GET https://api.fundsguard.net/methods?merchantId=&merchantUserId=&type=&nonce=&signature=

参数说明

参数名 是否必需? 参数描述
merchantId 商户号。
merchantUserId 存款用户在商户系统中的编号。
type 支付类型。存款:DEPOSIT,代付:PAYOUT
currency 支付币种。CNYTHB 或其它支持币种。
nonce 随机字符串。用来增加签名不可预测性。
signature 消息签名。签名方法请参考 接入说明 - 消息签名说明

响应数据

如果请求成功,在线支付系统会返回存款或者代付的所有可用支付方式以及限额。请查看右侧JSON响应数据。

2.2 查询账号余额

private static String merchantId = "8101";
private static String merchantSecretKey = "NjE5NDA4NWUtYmVlMi00OWQ1";
private static String balanceGatewayUrl = "https://api.fundsguard.net/balance";

public ResponseEntity queryAccountBalance() {
    Map<String, Object> mapData = new HashMap<>();
    mapData.put("merchantId", merchantId);
    mapData.put("currency", "CNY");
    mapData.put("nonce", UUID.randomUUID().toString());
    
    // 计算消息签名
    mapData.put("signature", calculateSignature(merchantSecretKey, mapData));

    // 组装订单查询URL地址
    UriComponentsBuilder uriBuilder = UriComponentsBuilder.fromHttpUrl(depositGatewayUrl);
    mapData.entrySet().stream().forEach(e -> uriBuilder.queryParam(e.getKey(), e.getValue()));

    return new RestTemplate().getForEntity(uriBuilder.toUriString(), String.class);
}

当请求成功时,在线支付系统会返回以下结构的JSON响应数据:

{
    "merchantId": 5001,
    "merchantName": "测试商户",
    "currency": "CNY",
    "totalBalance": "32205.68",
    "availableBalance": "32205.68",
    "timestamp": "2019-06-14 17:19:14"
}

该接口由商户发起请求,用来查询商户账号的当前余额。

请求方式

GET https://api.fundsguard.net/balance?merchantId=&type=&nonce=&signature=

参数说明

参数名 是否必需? 参数描述
merchantId 商户号。
currency 支付币种。CNYTHB 或其它支持币种。
nonce 随机字符串。用来增加签名不可预测性。
signature 消息签名。签名方法请参考 接入说明 - 消息签名说明

响应数据

如果请求成功,在线支付系统会返回该商户账号当前的余额。请查看右侧JSON响应数据。

2.3 查询历史订单

private static String merchantId = "8101";
private static String merchantSecretKey = "NjE5NDA4NWUtYmVlMi00OWQ1";
private static String balanceGatewayUrl = "https://api.fundsguard.net/orders";

public ResponseEntity searchOrders() {
    Map<String, Object> mapData = new HashMap<>();
    mapData.put("merchantId", merchantId);
    mapData.put("type", "DEPOSIT");
    mapData.put("nonce", UUID.randomUUID().toString());
    
    // 计算消息签名
    mapData.put("signature", calculateSignature(merchantSecretKey, mapData));

    // 下面这些参数不需要参与签名
    mapData.put("createdFrom", "2021-02-01 00:00:00");
    mapData.put("createdTo", "2021-02-10 00:00:00");
    mapData.put("page", "0");
    mapData.put("size", "10");

    // 组装订单查询URL地址
    UriComponentsBuilder uriBuilder = UriComponentsBuilder.fromHttpUrl(depositGatewayUrl);
    mapData.entrySet().stream().forEach(e -> uriBuilder.queryParam(e.getKey(), e.getValue()));

    return new RestTemplate().getForEntity(uriBuilder.toUriString(), String.class);
    
    // 查询结果会已分页形式返回
}

当请求成功时,在线支付系统会返回以下结构的JSON响应数据:

{
    "merchantId": 5001,
    "nonce": "c6161266-6646-40c9-afd3-df916891aac8",
    "signature": "e966c19e0ac3aaf8aa4270b46019cd21c2debda616521cc6eb1df364a1635fc8",
    "totalElements": 419,
    "results": [
        {
            "id": "P832010",
            "type": "DEPOSIT",
            "merchantId": 5001,
            "merchantOrderId": "1566420066766",
            "merchantUserId": "david_0730",
            "method": "BANK_TRANSFER",
            "amount": "144.00",
            "currency": "CNY",
            "remark": "备注信息",
            "status": "SUCCESS",
            "createdAt": "2019-08-21 21:41:09",
            "lastModifiedAt": "2019-08-21 21:41:32"
        },
        {
            "id": "P832011",
            "type": "DEPOSIT",
            "merchantId": 5001,
            "merchantOrderId": "1566481656813",
            "merchantUserId": "david_0730",
            "method": "BANK_TRANSFER",
            "amount": "111.00",
            "currency": "CNY",
            "remark": "备注信息",
            "status": "SUCCESS",
            "createdAt": "2019-08-22 14:47:40",
            "lastModifiedAt": "2019-08-22 14:48:00"
        },
        {
            "id": "P832012",
            "type": "DEPOSIT",
            "merchantId": 5001,
            "merchantOrderId": "1566481722265",
            "merchantUserId": "david_0730",
            "method": "BANK_TRANSFER",
            "amount": "208.00",
            "currency": "CNY",
            "remark": "备注信息",
            "status": "SUCCESS",
            "createdAt": "2019-08-22 14:48:42",
            "lastModifiedAt": "2019-08-22 14:48:58"
        },
        {
            "id": "P832013",
            "type": "DEPOSIT",
            "merchantId": 5001,
            "merchantOrderId": "1566481761857",
            "merchantUserId": "david_0730",
            "method": "ALIPAY",
            "amount": "552.00",
            "currency": "CNY",
            "remark": "备注信息",
            "status": "SUCCESS",
            "createdAt": "2019-08-22 14:49:22",
            "lastModifiedAt": "2019-08-22 14:49:54"
        },
        {
            "id": "P832017",
            "type": "DEPOSIT",
            "merchantId": 5001,
            "merchantOrderId": "1566507623156",
            "merchantUserId": "david_0730",
            "method": "ALIPAY",
            "amount": "130.00",
            "currency": "CNY",
            "remark": "备注信息",
            "status": "SUCCESS",
            "createdAt": "2019-08-22 22:00:23",
            "lastModifiedAt": "2019-08-22 22:00:36"
        },
        {
            "id": "P832018",
            "type": "DEPOSIT",
            "merchantId": 5001,
            "merchantOrderId": "1566507627910",
            "merchantUserId": "david_0730",
            "method": "ALIPAY",
            "amount": "1085.00",
            "currency": "CNY",
            "remark": "备注信息",
            "status": "SUCCESS",
            "createdAt": "2019-08-22 22:00:30",
            "lastModifiedAt": "2019-08-22 22:00:49"
        },
        {
            "id": "P832019",
            "type": "DEPOSIT",
            "merchantId": 5001,
            "merchantOrderId": "1566507669397",
            "merchantUserId": "david_0730",
            "method": "ALIPAY",
            "amount": "673.00",
            "currency": "CNY",
            "remark": "备注信息",
            "status": "FAILED",
            "createdAt": "2019-08-22 22:01:09",
            "lastModifiedAt": "2019-08-22 23:01:09"
        },
        {
            "id": "P832020",
            "type": "DEPOSIT",
            "merchantId": 5001,
            "merchantOrderId": "1566507670657",
            "merchantUserId": "david_0730",
            "method": "ALIPAY",
            "amount": "256.00",
            "currency": "CNY",
            "remark": "备注信息",
            "status": "SUCCESS",
            "createdAt": "2019-08-22 22:01:10",
            "lastModifiedAt": "2019-08-22 22:01:25"
        },
        {
            "id": "P832021",
            "type": "DEPOSIT",
            "merchantId": 5001,
            "merchantOrderId": "DEB345E629B044CA1A2540830FA854D8",
            "merchantUserId": "david_0730",
            "method": "ALIPAY",
            "amount": "841.00",
            "currency": "CNY",
            "remark": "备注信息",
            "status": "FAILED",
            "createdAt": "2019-08-23 21:15:54",
            "lastModifiedAt": "2019-08-23 22:15:55"
        },
        {
            "id": "P832035",
            "type": "DEPOSIT",
            "merchantId": 5001,
            "merchantOrderId": "1566653881710",
            "merchantUserId": "david_0730",
            "method": "ALIPAY",
            "amount": "5000.00",
            "currency": "CNY",
            "remark": "备注信息",
            "status": "SUCCESS",
            "createdAt": "2019-08-24 14:38:07",
            "lastModifiedAt": "2019-08-24 14:38:37"
        }
    ]
}

该接口由商户发起请求,用来查询指定时间范围内的订单。结果以分页形式返回。

请求方式

GET https://api.fundsguard.net/orders?merchantId=&type=&nonce=&signature=&createdBefore=&createdAfter=

参数说明

参数名 是否必需? 参数描述
merchantId 商户号。
type 订单支付类型。存款:DEPOSIT,代付:PAYOUT
currency 支付币种。CNYTHB 或者其它支持币种。
nonce 随机字符串。用来增加签名不可预测性。
signature 消息签名。签名方法请参考 接入说明 - 消息签名说明
createdFrom 起始时间(包含)。格式示例:2021-05-01 00:00:00。该参数不参与签名。
createdTo 截止时间(不包含)。格式示例:2021-05-02 00:00:00。该参数不参与签名。
page 查询页数。起始页为0,默认值为0。该参数不参与签名。
size 每页订单数。默认值为10。该参数不参与签名。

响应数据

如果请求成功,在线支付系统会按照时间顺序返回查询范围和指定页数内的订单数据。返回数据中,只要merchantIdnonce参数用来计算和验证签名。

3 存款接口

3.1 存款流程介绍

3.2 提交存款订单

private static String merchantId = "8101";
private static String merchantSecretKey = "NjE5NDA4NWUtYmVlMi00OWQ1";
private static String depositGatewayUrl = "https://api.fundsguard.net/deposit";

public ResponseEntity submitDepositOrder() {
    MultiValueMap<String, Object> formData = new LinkedMultiValueMap<>();
    formData.add("merchantId", merchantId);
    formData.add("merchantOrderId", String.valueOf(System.currentTimeMillis()));
    formData.add("merchantUserId", "demo.user");
    formData.add("method", "BANK_TRANSFER");
    formData.add("amount", "150");
    formData.add("currency", "CNY");
    formData.add("remark", "订单备注信息");
    formData.add("depositBank", "ICBC");
    formData.add("redirectUrl", "https://merchant.domain.com/redirectUrl");
    formData.add("callbackUrl", "https://merchant.domain.com/callbackUrl");
    formData.add("nonce", UUID.randomUUID().toString());

    // 计算消息签名
    Map<String, Object> mapData = formData.toSingleValueMap();
    formData.add("signature", calculateSignature(merchantSecretKey, mapData));

    HttpHeaders httpHeaders = new HttpHeaders();
    httpHeaders.add(CONTENT_TYPE, APPLICATION_FORM_URLENCODED_VALUE);
    HttpEntity httpEntity = new HttpEntity(formData, httpHeaders);

    return new RestTemplate().exchange(depositGatewayUrl, POST, httpEntity, String.class);
}

当请求成功时,在线支付系统会返回以下结构的JSON响应数据:

{
   "id": "P832045",
   "type": "DEPOSIT",
   "merchantId": 8101,
   "merchantOrderId": "1557608872316",
   "merchantUserId": "demo.user",
   "method": "BANK_TRANSFER",
   "amount": "150",
   "currency": "CNY",
   "remark": "订单备注信息",
   "paymentUrl": "https://cashier.[domain.name]/deposit/8913a8aa8393c96b1bdc14e2830be4ceac7fe337",
   "status": "CREATED",
   "createdAt": "2019-05-12 05:07:55",
   "nonce": "3b5c7f8c-1e6d-40cd-9d0c-f1613631c089",
   "signature": "47e307e815b3e5630ab07621fd5f02fd11faca9784c9e03b4b6bfb64b9786531"
}

该接口由商户发起请求,如果请求成功,在线支付系统会创建新存款订单,并返回该订单的详细信息。

请求格式

POST https://api.fundsguard.net/deposit

参数格式

application/x-www-form-urlencoded

参数说明

参数名 是否必需? 参数描述
merchantId 商户号。
merchantOrderId 商户系统内部的订单号。
merchantUserId 存款用户在商户系统中的编号。
method 支付方式。详见 附录 - 支付方式列表
amount 订单金额。
currency 支付币种。CNYTHB 或者其它支持币种。
callbackUrl 接收支付结果异步通知回调地址。若商户已配置使用固定回调地址,则不用提供该参数。
redirectUrl 订单支付成功时,收银台页面返回地址。
depositBank 银行编码。当支付方式为 BANK_TRANSFERLBT_QR 时必需。
depositName 持卡人姓名。当支付方式为 BANK_TRANSFERLBT_QR 时必需。
depositBankAccount 银行账号。当支付方式为 LBT_QR 时必需。
depositFromAddress 转账来源地址。当支付方式为 USDT 时必需。
remark 商户提供的附加备注信息。在响应和异步回调通知时该信息会原值返回。
nonce 随机字符串。用来增加签名不可预测性。
signature 消息签名。签名方法请参考 接入说明 - 消息签名说明

响应数据

当成功提交存款订单时,在线支付系统会返回订单信息和存款页面地址 paymentUrl。请查看右侧JSON响应数据。

3.3 查询存款订单

private static String merchantId = "8101";
private static String merchantSecretKey = "NjE5NDA4NWUtYmVlMi00OWQ1";
private static String depositGatewayUrl = "https://api.fundsguard.net/deposit";

public ResponseEntity queryDepositOrder() {
    Map<String, Object> mapData = new HashMap<>();
    mapData.put("merchantId", merchantId);
    mapData.put("merchantOrderId", "1557608872316");
    mapData.put("nonce", UUID.randomUUID().toString());
    
    // 计算消息签名
    mapData.put("signature", calculateSignature(merchantSecretKey, mapData));

    // 组装订单查询URL地址
    UriComponentsBuilder uriBuilder = UriComponentsBuilder.fromHttpUrl(depositGatewayUrl);
    mapData.entrySet().stream().forEach(e -> uriBuilder.queryParam(e.getKey(), e.getValue()));

    return new RestTemplate().getForEntity(uriBuilder.toUriString(), String.class);
}

当请求成功时,在线支付系统会返回以下结构的JSON响应数据:

{
  "id": "P832045",
  "type": "DEPOSIT",
  "merchantId": 8101,
  "merchantOrderId": "1557608872316",
  "merchantUserId": "demo.user",
  "method": "BANK_TRANSFER",
  "amount": "150",
  "currency": "CNY",
  "remark": "订单备注信息",
  "status": "PENDING",
  "createdAt": "2019-05-12 05:07:55",
  "nonce": "e8bf2c7e-b20a-4213-8fd8-1225951d28d7",
  "signature": "93587fb7825e37f55c364fa561d72090d5c89f17c5d0e69918477a8bb56a642d"
}

该接口由商户发起请求,如果请求成功,在线支付系统会返回所查询存款订单的详细信息。

请求方式

GET https://api.fundsguard.net/deposit?merchantId=&merchantOrderId=&nonce=&signature=

参数说明

参数名 是否必需? 参数描述
merchantId 商户号。
merchantOrderId 商户系统内部的订单号。
nonce 随机字符串。用来增加签名不可预测性。
signature 消息签名。签名方法请参考 接入说明 - 消息签名说明

响应数据

如果查询订单请求成功,在线支付系统会返回所查询订单的详细信息。请查看右侧JSON响应数据。

4 代付接口

4.1 代付流程介绍

4.2 提交代付订单

private static String merchantId = "8101";
private static String merchantSecretKey = "NjE5NDA4NWUtYmVlMi00OWQ1";
private static String payoutGatewayUrl = "https://api.fundsguard.net/payout";

public ResponseEntity submitPayoutOrder() {
    MultiValueMap<String, Object> formData = new LinkedMultiValueMap<>();
    formData.add("merchantId", merchantId);
    formData.add("merchantOrderId", String.valueOf(System.currentTimeMillis()));
    formData.add("merchantUserId", "demo.user");
    formData.add("method", "BANK_TRANSFER");
    formData.add("amount", "150");
    formData.add("currency", "CNY");
    formData.add("remark", "订单备注信息");
    formData.add("bankCode", "ICBC");
    formData.add("bankAccountName", "孙悟空");
    formData.add("bankAccountNumber", "1234567890123456");
    formData.add("callbackUrl", "https://merchant.domain.com/callbackUrl");
    formData.add("nonce", UUID.randomUUID().toString());

    // 计算消息签名
    Map<String, Object> mapData = formData.toSingleValueMap();
    formData.add("signature", calculateSignature(merchantSecretKey, mapData));

    HttpHeaders httpHeaders = new HttpHeaders();
    httpHeaders.add(CONTENT_TYPE, APPLICATION_FORM_URLENCODED_VALUE);
    HttpEntity httpEntity = new HttpEntity(formData, httpHeaders);

    return new RestTemplate().exchange(payoutGatewayUrl, POST, httpEntity, String.class);
}

当请求成功时,在线支付系统会返回以下结构的JSON响应数据:

{
  "id": "P832046",
  "type": "PAYOUT",
  "merchantId": 8101,
  "merchantOrderId": "1557623282534",
  "merchantUserId": "demo.user",
  "method": "BANK_TRANSFER",
  "amount": "150",
  "currency": "CNY",
  "remark": "订单备注信息",
  "status": "CREATED",
  "createdAt": "2019-05-12 09:08:06",
  "nonce": "b0059feb-cf05-4a54-9311-11c265dae895",
  "signature": "7ed31c2664d5f3ed869f356b5bab90e2d838c836575dc78dbe310d3a9409bea4"
}

该接口由商户发起请求,如果请求成功,在线支付系统会创建新的代付订单,并返回该订单的详细信息。

请求方式

POST https://api.fundsguard.net/payout

参数格式

application/x-www-form-urlencoded

参数说明

参数名 是否必需? 参数描述
merchantId 商户号。
merchantOrderId 商户系统内部的订单号。
merchantUserId 收款用户在商户系统中的编号。
method 支付方式。目前支持 BANK_TRANSFERUSDT
amount 订单金额。单位为元。
currency 支付币种。CNYTHB 或者其它支持币种。
callbackUrl 接收支付结果异步通知回调地址。若商户已配置使用固定回调地址,则不用提供该参数。
alipayAccountName 收款人支付宝账号名。当支付方式为ALIPAY时必需。
bankCode 收款银行代码。当支付方式为BANK_TRANSFER时必需。例如:ICBC。请查看 附录 - 支持银行列表
bankAccountNumber 收款银行账号号。当支付方式为BANK_TRANSFER时必需。例如:6217003250022956518
bankAccountCode 收款银行账号IFSC代码。当币种是INR, 支付方式为BANK_TRANSFER时必需。例如:IOBA0003123
bankAccountName 账号姓名。当支付方式为BANK_TRANSFER时必需。例如:张三丰
bankProvince 开户省份。例如:湖南
bankCity 开户城市。例如:长沙
bankBranch 支行名称。例如:明主路支行
usdtAddress 收款钱包地址。当支付方式为USDT时必需。
remark 商户提供的附加备注信息。在响应和异步回调通知时该信息会原值返回。
nonce 随机字符串。用来增加签名不可预测性。
signature 消息签名。签名方法请参考 接入说明 - 消息签名说明

响应数据

当成功提交代付订单时,在线支付系统会返回订单的信息。请查看右侧 JSON响应数据。

4.3 查询代付订单

private static String merchantId = "8101";
private static String merchantSecretKey = "NjE5NDA4NWUtYmVlMi00OWQ1";
private static String payoutGatewayUrl = "https://api.fundsguard.net/payout";

public ResponseEntity queryPayoutOrder() {
    Map<String, Object> mapData = new HashMap<>();
    mapData.put("merchantId", merchantId);
    mapData.put("merchantOrderId", "1557623282534");
    mapData.put("nonce", UUID.randomUUID().toString());

    // 计算消息签名
    mapData.put("signature", calculateSignature(merchantSecretKey, mapData));

    // 组装订单查询URL地址
    UriComponentsBuilder uriBuilder = UriComponentsBuilder.fromHttpUrl(payoutGatewayUrl);
    mapData.entrySet().stream().forEach(e -> uriBuilder.queryParam(e.getKey(), e.getValue()));

    return new RestTemplate().getForEntity(uriBuilder.toUriString(), String.class);
}

当请求成功时,在线支付系统会返回以下结构的 JSON响应数据:

{
  "id": "P832046",
  "type": "PAYOUT",
  "merchantId": 8101,
  "merchantOrderId": "1557623282534",
  "merchantUserId": "demo.user",
  "method": "BANK_TRANSFER",
  "amount": "150",
  "currency": "CNY",
  "remark": "订单备注信息",
  "status": "PENDING",
  "createdAt": "2019-05-12 09:08:06",
  "nonce": "b69c4957-1b55-47df-87fb-f91fed9b0625",
  "signature": "f3f285718cf797b1796bea76a97046da8b31ad7e2fe554f0c851c71093c8a8d4"
}

该接口由商户发起请求,如果请求成功,在线支付系统会返回所查询代付订单的详细信息。

请求方式

GET https://api.fundsguard.net/payout?merchantId=&merchantOrderId=&nonce=&signature=

参数说明

参数名 参数描述 是否必需?
merchantId 商户号。
merchantOrderId 商户系统内部的订单号。
nonce 随机字符串。用来增加签名不可预测性。
signature 消息签名。签名方法请参考 接入说明 - 消息签名说明

响应数据

如果查询订单请求成功,在线支付系统会返回所查询订单的详细信息。请查看右侧 JSON响应数据。

5 商户提款接口

5.1 提款流程介绍

5.2 提交提款订单

private static String merchantId = "8101";
private static String merchantSecretKey = "NjE5NDA4NWUtYmVlMi00OWQ1";
private static String settlementGatewayUrl = "https://api.fundsguard.net/settlement";

public ResponseEntity submitSettlementRequest() {
    MultiValueMap<String, Object> formData = new LinkedMultiValueMap<>();
    formData.add("merchantId", merchantId);
    formData.add("merchantOrderId", String.valueOf(System.currentTimeMillis()));
    formData.add("merchantUserId", "demo.user");
    formData.add("method", "BANK_TRANSFER");
    formData.add("amount", "150");
    formData.add("currency", "CNY");
    formData.add("remark", "备注信息");
    formData.add("bankCode", "ICBC");
    formData.add("bankAccountName", "孙悟空");
    formData.add("bankAccountNumber", "1234567890123456");
    formData.add("callbackUrl", "https://merchant.domain.com/callbackUrl");
    formData.add("nonce", UUID.randomUUID().toString());

    // 计算消息签名
    Map<String, Object> mapData = formData.toSingleValueMap();
    formData.add("signature", calculateSignature(merchantSecretKey, mapData));

    HttpHeaders httpHeaders = new HttpHeaders();
    httpHeaders.add(CONTENT_TYPE, APPLICATION_FORM_URLENCODED_VALUE);
    HttpEntity httpEntity = new HttpEntity(formData, httpHeaders);

    return new RestTemplate().exchange(settlementGatewayUrl, POST, httpEntity, String.class);
}

当请求成功时,在线支付系统会返回以下结构的JSON响应数据:

{
  "id": "P832046",
  "type": "PAYOUT",
  "merchantId": 8101,
  "merchantOrderId": "1557623282534",
  "merchantUserId": "demo.user",
  "method": "BANK_TRANSFER",
  "amount": "150",
  "currency": "CNY",
  "remark": "备注信息",
  "status": "CREATED",
  "createdAt": "2019-05-12 09:08:06",
  "nonce": "b0059feb-cf05-4a54-9311-11c265dae895",
  "signature": "7ed31c2664d5f3ed869f356b5bab90e2d838c836575dc78dbe310d3a9409bea4"
}

该接口由商户发起请求,如果请求成功,在线支付系统会创建新的提款请求,并返回该请求的详细信息。

请求方式

POST https://api.fundsguard.net/settlement

参数格式

application/x-www-form-urlencoded

参数说明

参数名 是否必需? 参数描述
merchantId 商户号。
merchantOrderId 商户系统内部的提款请求编号。
merchantUserId 发起提款请求的用户名。
method 支付方式。目前仅支持 BANK_TRANSFER
amount 订单金额。单位为元。
currency 支付币种。CNYTHB 或者其它支持币种。
callbackUrl 接收提款结果异步通知回调地址。若商户已配置使用固定回调地址,则不用提供该参数。
bankCode 收款银行代码。例如:ICBC。请查看 附录 - 支持银行列表
bankAccountNumber 收款银行卡号。例如:6217003250022956518
bankAccountName 持卡人姓名。例如:张三丰
bankProvince 开户省份。例如:湖南
bankCity 开户城市。例如:长沙
bankBranch 支行名称。例如:明主路支行
remark 商户提供的附加备注信息。在响应和异步回调通知时该信息会原值返回。
nonce 随机字符串。用来增加签名不可预测性。
signature 消息签名。签名方法请参考 接入说明 - 消息签名说明

响应数据

当成功提交提款请求时,在线支付系统会返回请求的信息。请查看右侧 JSON响应数据。

6 异步回调

6.1 发起回调通知

商户系统接收在线支付异步回调的API接口 代码示例:

private static String merchantId = "8101";
private static String merchantSecretKey = "NjE5NDA4NWUtYmVlMi00OWQ1";

@SneakyThrows
@PostMapping(name = "/demo/callback", consumes = APPLICATION_JSON_VALUE)
public ResponseEntity koingDemoCallbackEndpoint(@RequestBody String requestData) {
    Map<String, Object> mapData = objectMapper.readValue(requestJsonData, Map.class);

    // 验证回调的消息签名
    String expectedSignature = calculateSignature(merchantSecretKey, mapData);
    if (!expectedSignature.equals(mapData.get("signature"))) {
        // 验签失败,或者其它原因失败,返回 失败状态码
        return ResponseEntity.badRequest().build();
    }

    // 商户业务代码,核实回调数据(订单号,订单状态,订单金额等)
    // 并进行相应的处理,比如更新订单状态,更新用户数据,用户上分等

    // 返回 成功状态码 200
    return ResponseEntity.ok().build();
}

在线支付发起的异步回调,会发送以下结构的 JSON数据:

{
  "id": "P832045",
  "type": "DEPOSIT",
  "merchantId": 8101,
  "merchantOrderId": "1557608872316",
  "merchantUserId": "demo.user",
  "method": "BANK_TRANSFER",
  "amount": "150",
  "currency": "currency",
  "remark": "订单备注信息",
  "status": "FAILED",
  // "failureReason": "Failed due to timeout", // 可选参数,详情参考参数说明
  // "overrideStatus": "yes", // 可选参数,详情参考参数说明
  "createdAt": "2019-05-12 05:07:55",
  "nonce": "59bf85fc-f90f-43e0-a38a-b2952cfb1e9e",
  "signature": "3eb593a9b4349db248359c5efa5c138f6c941002533d6609f9709409fbdd0933"
}

异步回调是由在线支付后台发起,发送请求到商户后台 (商户配置的固定回调地址,或在提交订单请求时指定的动态回调地址callbackUrl),以通知商户订单的状态更新。

商户收到异步回调通知,并正确处理以后,需要返回 HTTP状态码 200。如果在线支付系统没有收到正确的响应码,会定期重新尝试发送异步回调通知。在线支付最多一共会重试发送8次,每次重试之间的时间间隔大约为:0秒, 3秒, 9秒, 27秒, 1分21秒, 4分3秒, 12分9秒, 36分27秒

请求方式

POST [商户指定回调地址]

参数格式

application/json

参数说明

参数名 是否必需? 参数描述
id 流水号。在线支付系统内订单流水号。
type 订单类型。存款:DEPOSIT,代付:PAYOUT
merchantId 商户号。
merchantOrderId 商户系统内部的订单号。
merchantUserId 收款用户在商户系统中的编号。
remark 附加备注信息。由商户提交订单时所提供。
method 支付方式。
amount 订单金额。单位为元。
currency 支付币种。CNYTHB 或者其它支持币种。
status 订单状态。成功:SUCCESS,失败:FAILED
failureReason 失败原因。仅当订单状态是失败的时候才会发送改参数。可能的失败原因包括但不限于:”Failed due to timeout”, “Failed to submit to upstream”, “Failed to process in the upstream”。
overrideStatus 仅当存款订单先失败后来又成功,或者代付订单先成功后来又失败时才会发送该参数,参数值固定为yes。如果收到该参数时,该参数要参与签名。
createdAt 订单创建时间。格式:yyyy-MM-dd HH:mm:ss
nonce 随机字符串。用来增加签名不可预测性。
signature 消息签名。签名方法请参考 接入说明 - 消息签名说明

7 附录

7.1 CNY 支付方式和银行列表

7.1.1 CNY 支付方式

支付方式代码 类型 支付方式 描述
BANK_TRANSFER 存款 网银转账 网银转账
ALIPAY 存款 支付宝 支付宝
ALIPAY_S 支付宝小额 支付宝小额
ALIPAY_M 支付宝中额 支付宝中额
WECHAT 存款 微信支付 微信支付
BANK_TRANSFER 代付 网银转账 网银转账
ALIPAY 代付 存款 支付宝

7.1.2 CNY 银行列表

银行代码 银行名称 支持存款 支持代付
BC0001 中国银行 Yes Yes
BC0002 中国农业银行 Yes Yes
BC0003 中国建设银行 Yes Yes
BC0004 中国工商银行 Yes Yes
BC0005 中国邮政储蓄银行 Yes Yes
BC0006 中国交通银行 Yes Yes
BC0007 招商银行 Yes Yes
BC0008 中国民生银行 Yes Yes
BC0009 中信银行 Yes Yes
BC0010 平安银行 Yes Yes
BC0011 华夏银行 Yes Yes
BC0012 广发银行 Yes Yes
BC0013 浦发银行 Yes Yes
BC0014 光大银行 Yes Yes
BC0015 兴业银行 Yes Yes
BC0020 北京银行 Yes Yes
BC0021 广州银行 Yes Yes

7.2 MYR 支付方式和银行列表

7.2.1 MYR 支付方式

支付方式代码 类型 支付方式 描述
ONLINE_DEBIT 存款 在线网银 FPX
E_WALLET 存款 电子钱包 eWallet
QR 存款 扫码支付 DuitNow
BANK_TRANSFER 存款 银行转帐 银行转帐
BANK_TRANSFER 代付 银行转帐 银行转帐

7.2.2 MYR 银行列表

银行代码 银行名称 支持存款 支持代付
BM0001 Public Bank Yes Yes
BM0002 Bank Rakyat Yes Yes
BM0003 Alliance Bank Yes Yes
BM0004 Maybank2U Yes Yes
BM0005 Bank Islam Yes Yes
BM0006 Bank Muamalat Yes Yes
BM0007 Affin Bank Yes Yes
BM0008 RHB Bank Yes Yes
BM0009 OCBC Bank Yes Yes
BM0010 Standard Chartered Yes Yes
BM0011 Hong Leong Bank Yes Yes
BM0012 UOB Bank Yes Yes
BM0013 CIMB Clicks Yes Yes
BM0014 AmBank Yes Yes
BM0015 HSBC Bank Yes Yes
BM0016 Bank of China Yes Yes
BM0017 Bank Simpanan Nasional Yes Yes

7.3 THB 支付方式和银行列表

7.3.1 THB 支付方式

支付方式代码 类型 支付方式 描述
QR 存款 扫码支付 PromptPay/TrueMoney
LBT_QR 存款 扫码银行转帐 扫码银行转帐
BANK_TRANSFER 存款 银行转帐 银行转帐
BANK_TRANSFER 代付 银行转帐 银行转帐

7.3.2 THB 银行列表

银行代码 银行名称 支持存款 支持代付
BT0001 Bangkok Bank Yes Yes
BT0002 Kasikorn Bank Yes Yes
BT0003 Krung Thai Bank Yes Yes
BT0004 TMBThanachart Bank Yes Yes
BT0005 Siam Commercial Bank Yes Yes
BT0006 Citibank Yes Yes
BT0007 Standard Chartered Yes Yes
BT0008 CIMB Thai Yes Yes
BT0009 UOB Yes Yes
BT0010 Bank of Ayudhya Yes Yes
BT0011 Mega International Yes Yes
BT0012 Bank of America Yes Yes
BT0013 Government Savings Bank Yes Yes
BT0014 HSBC Yes Yes
BT0015 Deutsche Bank Yes Yes
BT0016 Government Housing Bank Yes Yes
BT0017 BAAC Yes Yes
BT0018 Mizuho Bank Yes Yes
BT0019 BNP Paribas Yes Yes
BT0020 Bank of China Yes Yes
BT0021 Thanachart Bank Yes Yes
BT0022 Islamic Bank of Thailand Yes Yes
BT0023 TISCO Bank Yes Yes
BT0024 Kiatnakin Phatra Bank Yes Yes
BT0025 ICBC (Thai) Yes Yes
BT0026 Thai Credit Bank Yes Yes
BT0027 Land and Houses Bank Yes Yes

7.4 IDR 支付方式和银行列表

7.4.1 IDR 支付方式

支付方式代码 类型 支付方式 描述
QR 存款 QRIS QRIS
BANK_TRANSFER 存款 VA转账 VA转账
BANK_TRANSFER 代付 银行转帐 银行转帐

7.4.2 IDR 银行列表

银行代码 银行名称 支持存款 支持代付
BI0001 Bank Rakyat Indonesia No Yes
BI0002 Bank Mandiri (Persero) Tbk No Yes
BI0003 Bank Negara Indonesia No Yes
BI0004 Bank Danamon Indonesia Tbk No Yes
BI0005 PT Bank Permata Tbk No Yes
BI0006 PT Bank Permata Tbk Syariah No Yes
BI0007 Bank Central Asia Tbk No Yes
BI0008 PT Bank Internasional Indonesia Tbk No Yes
BI0009 PT Bank Panin Tbk No Yes
BI0010 PT Bank CIMB Niaga Tbk No Yes
BI0011 PT Bank UOB Buana Tbk No Yes
BI0012 PT Bank OCBC NISP Tbk No Yes
BI0013 Citibank N.A. No Yes
BI0014 Bank of America NA No Yes
BI0015 PT Bank Windu Kentjana International Tbk No Yes
BI0016 PT Bank Artha Graha Internasional Tbk No Yes
BI0017 Bank of Tokyo-Mitsubishi UFJ, Ltd. No Yes
BI0018 DBS Bank Ltd. No Yes
BI0019 Bank Resona Perdania No Yes
BI0020 Bank Mizuho Indonesia No Yes
BI0021 Standard Chartered Bank No Yes
BI0022 PT Bank Capital Indonesia Tbk No Yes
BI0023 Bank BNP Paribas Indonesia No Yes
BI0024 PT ANZ Panin Bank No Yes
BI0025 Bank of China Limited No Yes
BI0026 PT Bank Bumi Arta Tbk No Yes
BI0027 HSBC Bank (Indonesia) No Yes
BI0028 Bank ANTAR DAERAH No Yes
BI0029 PT Bank Rabobank International Indonesia No Yes
BI0030 PT Bank JTrust Indonesia No Yes
BI0031 PT Bank Mayapada Internasional Tbk No Yes
BI0032 Bank Jawa Barat dan Banten Tbk No Yes
BI0033 Bank DKI No Yes
BI0034 Bank Pembangunan Daerah Istimewa Yogyakarta No Yes
BI0035 Bank Jateng No Yes
BI0036 Bank Jatim No Yes
BI0037 Bank Jambi No Yes
BI0038 Bank Jambi Syariah No Yes
BI0039 Bank Aceh No Yes
BI0040 Bank Aceh Syariah No Yes
BI0041 Bank Sumut No Yes
BI0042 Bank Nagari No Yes
BI0043 Bank Riau No Yes
BI0044 Bank Riau Syariah No Yes
BI0045 Bank Sumsel Babel No Yes
BI0046 Bank Sumsel Babel Syariah No Yes
BI0047 Bank Lampung No Yes
BI0048 Bank Kalsel No Yes
BI0049 Bank Kalbar No Yes
BI0050 Bank Pembangunan Daerah Kalimantan Timur No Yes
BI0051 Bank Pembangunan Daerah Kalimantan Tengah No Yes
BI0052 Bank Sulawesi Selatan dan Sulawesi Barat No Yes
BI0053 Bank Sulut No Yes
BI0054 Bank Nusa Tenggara Barat No Yes
BI0055 Bank Nusa Tenggara Barat Syariah No Yes
BI0056 Bank Pembangunan Daerah Bali No Yes
BI0057 Bank Nusa Tenggara Timur No Yes
BI0058 Bank Maluku No Yes
BI0059 Bank Pembangunan Daerah Papua No Yes
BI0060 Bank Bengkulu No Yes
BI0061 Bank Sulawesi Tengah No Yes
BI0062 Bank Sultra No Yes
BI0063 Bank Banten No Yes
BI0064 Bank Nusantara Parahyangan No Yes
BI0065 Bank of India Indonesia No Yes
BI0066 Bank Muamalat Indonesia No Yes
BI0067 Bank Mestika No Yes
BI0068 Shinhan Bank No Yes
BI0069 PT Bank Sinarmas Tbk No Yes
BI0070 PT Bank Maspion Indonesia Tbk No Yes
BI0071 Bank Ganesha No Yes
BI0072 Industrial and Commercial Bank of China (ICBC) No Yes
BI0073 PT Bank QNB Kesawan Tbk No Yes
BI0074 Bank Tabungan Negara No Yes
BI0075 Bank Woori Saudara 1906 Tbk No Yes
BI0076 PT Bank Tabungan Pensiunan Nasional Tbk No Yes
BI0077 PT Bank Victoria Syariah No Yes
BI0078 Bank Jabar Banten Syariah No Yes
BI0079 Bank Mega Tbk No Yes
BI0080 Bank Bukopin No Yes
BI0081 Bank Syariah Indonesia No Yes
BI0082 Bank Jasa Jakarta No Yes
BI0083 KEB Hana Bank No Yes
BI0084 PT Bank MNC Internasional Tbk No Yes
BI0085 Bank Yudha Bhakti No Yes
BI0086 Bank Rakyat Indonesia (Agroniaga) No Yes
BI0087 Bank SBI Indonesia (Indomonex) No Yes
BI0088 Bank Royal No Yes
BI0089 Bank Nationalnobu No Yes
BI0090 Bank Mega Syariah No Yes
BI0091 Bank Ina Perdana No Yes
BI0092 Bank Panin Syariah No Yes
BI0093 Bank Prima Master No Yes
BI0094 Bank Syariah Bukopin No Yes
BI0095 Bank Sahabat Sampoerna No Yes
BI0096 Bank Dinar Indonesia No Yes
BI0097 Bank Amar Indonesia No Yes
BI0098 Bank Seabank Indonesia No Yes
BI0099 Bank Central Asia Syariah No Yes
BI0100 PT Bank Artos Indonesia No Yes
BI0101 Bank Tabungan Pensiunan Nasional Syariah No Yes
BI0102 Bank Multiarta Sentosa No Yes
BI0103 PT Bank Mayora Indah Tbk No Yes
BI0104 PT Bank Index Selindo No Yes
BI0105 Central Nasional Bank No Yes
BI0106 PT Bank Mantap Sejahtera No Yes
BI0107 PT Bank Victoria International No Yes
BI0108 PT Bank Harda Internasional Tbk No Yes
BI0109 Bank Pembangunan Daerah Kepulauan Selayar No Yes
BI0110 PT Bank IFI No Yes
BI0111 Bank Aladin Syariah No Yes
BI0112 China Trust Commercial Bank, Indonesia Branch No Yes
BI0113 Commonwealth Bank of Australia No Yes

7.5 VND 支付方式和银行列表

7.5.1 VND 支付方式

支付方式代码 类型 支付方式 描述
QR 存款 QR QR
E_WALLET 存款 MOMO MOMO
BANK_TRANSFER 存款 银行转帐 银行转帐
BANK_TRANSFER 代付 银行转帐 银行转帐

7.5.2 VND 银行列表

银行代码 银行名称 支持存款 支持代付
BV0011 Military Bank No Yes
BV0012 Nam A Bank No Yes
BV0013 National Citizen Bank No Yes
BV0015 Orient Commercial Joint Stock Bank No Yes
BV0016 Prosperity and Growth Bank No Yes
BV0017 Public Vietnam Commercial Bank No Yes
BV0018 Sacombank No Yes
BV0020 Saigon Bank No Yes
BV0022 SeABank No Yes
BV0024 Tien Phong Bank No Yes
BV0026 VietABank No Yes
BV0027 Vietcombank No Yes
BV0028 Vietinbank No Yes
BV0029 Vietnam Export Import Bank No Yes
BV0030 Vietnam International Bank No Yes
BV0031 Vietnam Prosperity Bank No Yes
BV0032 BaoViet Bank No Yes
BV0036 Kien Long Bank No Yes
BV0037 LienVietPostBank No Yes
BV0039 Shinhan Bank No Yes
BV0046 WOORI BANK No Yes
BV0054 Cake Digital Bank by VPBank No Yes
BV0070 Cooperative Bank of Vietnam No Yes

7.6 INR 支付方式和银行列表

7.6.1 INR 支付方式

支付方式代码 类型 支付方式 描述
QR 存款 UPI 扫码支付 UPI 扫码支付
BANK_TRANSFER 代付 IMPS 银行转账 IMPS 银行转账

7.6.2 INR 银行列表

银行代码 银行名称 支持存款 支持代付
BD0001 State Bank of India No Yes
BD0002 HDFC Bank No Yes
BD0003 ICICI Bank No Yes
BD0004 Bank of Baroda No Yes
BD0005 Punjab National Bank No Yes
BD0006 Canara Bank No Yes
BD0007 Union Bank of India No Yes
BD0008 Axis Bank No Yes
BD0009 Indian Bank No Yes
BD0010 Indian Overseas Bank No Yes