API对接技术文档

法币 (印尼盾) 代收下单

# 代码示例

  • 代码示例仅供参考，具体参数说明请参考请求参数说明
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import java.util.Map;
import java.util.TreeMap;

public class TopPayDemo {
  private static final String MCH_ID = "S820211021094748000001"; // 商户号
  private static final String PLAT_PUBLIC_KEY = "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC2JoMfFqLsSJjAiCahEnlP3aRj8yCT+WHzR+VvPBTw9S1i7iYWb+MY09CG/HYuHF4+IxshXDJygmndxKf/esuwPybS8mAd//yubHpmZsmBqg1FffT8VH1APa6ZRWASUp4U01ZrbCCp35QA8FuWrJGMJxGx4xk7KUtV2yujxC8noQIDAQAB"; // 平台公钥
  private static final String MCH_PRIVATE_KEY = "MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAJU8gKFKD0luIYx7X8+JRdCIE0UDBctS6LjXxWLEv/EO7jDBTid6zYP1KmNgpd2DAWWtBFBSQ+gcNwVZZSBHJiSDqVvvJVs2FEbeBvfdv4X93+IYRAXksBasSW5Tpdshbo82pVL4V7wuKCuFLk9UxBHbpQjWAbfyF66RmwIbZD71AgMBAAECgYBjPe7UU2nDDSfmQg0++CyjNjqKRC5QPfxhH6w1uF1kMueXKJWOj42n2RutJpJmsj31nY8m0u4xpsG4HvCu/GGSFhhKZCHLvzp41oY2ubYj9nuFNU//81LycQjulWo2y0UUBY0k2piEt+SwPaiUNbT6nMxNMjlnjRe2okp/3rw+KQJBANG3YlZWoVbCEqzy64bJJLxiPsCA5ErGB0NzRGitq44xkhqGtR8ZZQyVz40pruNa58d73O2xyJSy5+fmZGn4E+sCQQC2LBnguj0CSCKub0mPDcunTTz9V79VXBBZdlB1/YGmRUx2s4sQrJNZS7rL4EqBQ3maIRnG+s+AXCSTfsYrV6CfAkEAxugnVfpelhoGepEAgNuggyivmgfl/2Gpm/jk5l/qOjib+ZrQiQmeBPzGWX4yiSM8eMDrP2sC8r5pJFMp5DRONwJBAJ4n4XuSFJ9jgwCPy3vvzSv9SYLk6E6yM9uHdUlKgoGYzk6Lh6M9QFuY/J49plFdBDiEnj16yCU3WeXXfTJpzB8CQQDMNMR/rIOTE9xGybS3mlQbt22AUnO6XhupWcckEKW4nPGxATwYBQzCY3i/9FTGN0vA+9ZPC2cwHtNxI2kXf3Vp"; // 商户私钥
  private static final String payUrl = "https://id-openapi.toppay.asia/gateway/prepaidOrder";
  private static final String cashUrl = "https://id-openapi.toppay.asia/gateway/cash";
  private static final String payNotify = "your notify url";
  private static final String cashNotify = "http://host:port/notify";

  public static void main(String[] args) throws Exception {
    pay();
  }
  private static void pay() throws Exception {
    Map<String, String> requestParams = new TreeMap<>();
    requestParams.put("merchantCode", MCH_ID);
    requestParams.put("orderType", "0"); // 订单类型（0-法币交易）
    requestParams.put("method", "BCA"); // 支付渠道
    requestParams.put("orderNum", "T1642592278863"); // 商户订单号
    requestParams.put("payMoney", "150"); // 订单金额
    requestParams.put("name", "JackMa"); // 客户名称
    requestParams.put("phone", "082122965511"); // 手机号
    requestParams.put("email", "[email protected]"); // 客户邮箱
    requestParams.put("notifyUrl", payNotify); // 回调地址
    requestParams.put("dateTime", "20220101235959"); // 时间戳 格式 yyyyMMddHHmmss
    requestParams.put("expiryPeriod", "1440"); // 过期时间 单位(分)
    requestParams.put("productDetail", "Test Pay"); // 订单详情
    requestParams.put("redirectUrl", "http://123.com"); // 返回跳转地址（仅限收银台使用）

    StringBuilder stringBuilder = new StringBuilder();
    for (String key : requestParams.keySet()) {
      stringBuilder.append(requestParams.get(key));  // 拼接参数
    }

    String keyStr = stringBuilder.toString(); // 得到待加密的字符串
    System.out.println("keyStr:" + keyStr);
    String signedStr = TopPayRequestUtil.privateEncrypt(keyStr, TopPayRequestUtil.getPrivateKey(MCH_PRIVATE_KEY)); // 私钥加密
    requestParams.put("sign", signedStr);

    String postJson = new Gson().toJson(requestParams);
    System.out.println("Post Json Params:" + postJson);

    String responseJson = TopPayRequestUtil.doPost(payUrl, postJson); // 发送 post json请求
    System.out.println("Response Msg:" + responseJson);

    boolean pass = TopPayRequestUtil.verifySign(new Gson().fromJson(responseJson, JsonObject.class), PLAT_PUBLIC_KEY); // 签名验证
    if (pass) {
      // ... 签名验证通过,执行正常的业务逻辑
    } else {
      // ... 签名验证错误
    }
  }
}



<?php
// 平台公钥，从密钥配置中获取
// platform public key, from Secret key config
$platPublicKey = 'MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiaKBgQCcEUIvQ/5L+SWbHOeR8VFeZvLbUk7V7OeEAQlQwIVLSZMTef3KtsOKKAsUYPf/aAcKRzZZXECODsPQiDPcdZvM/rFkgrFWkR7lPjTj5SiPxGaiK2Z2sne7A8aDF7fV/D7lfmEwNdZ7FWKVEB84/81BHnlGUwb5HpRTISG+boSO6wIDAQAB';
// 商户私钥，商户自己生成
// mchchant private key
$mchPrivateKey = 'MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBAMigm7rtWnTeNagwFzGTH+Uw1ypbiy7VhIoFJbgSYSSHdCaXWdT/l2+2fQlEYgAETVZ/IXB29MCnrf3O0dwRFXiipIbsm5zyqSLiS6cKXe8zN1/PlQWUbEt5wyWm0GADB/4bV6eu6gA7sGXmjQqrzfKZkcie3aK7+7ry1NFxTI51AgMBAAECgYEAklqXQAVlt1tiSQ7L3J425jp6u6uMHN4lkYmvuleuBbfKQ1yla3wIPLYjAF+iHeEFidOz0Rb19JRdmIkHDkJoJg2W27LvO6RdUwzgRnsuA3OuNz97w08B3aXXbPmB91nTFjKSlUsbh3IQWP71noxW+iKn844EW5hC5Gvn4L3quAECQQDrz1r0VKIbBSBB2aLuz1XyD/TBT2aRhvOKf0XtTRiQhNjtJxoQmvNbbhvUwj8an7HyCuihAbdbrC2ymFFyOSDZAkEA2c4Yudi48C6COrroi1cWgPlEFeGJXP/V1k5loZ1n2vstYAGPhAB4wUnFBLDvMqaBzWJt7MRkiazT8KnBQCDY/QJAMXpNlEyZwt+deBOpO0BnwSWV7mWxmMFfImU4D+WITPbC7aexsWBBxaJh1o93XCe715RwYTAR//stj3akSDoyaQJAa4FKuxC51/Nc3Fg9R+modeiTLqmv/3NXvPvdNjRXesLX1rduex0wfVdII9ShfEKrdxDKaT9W0NyzD+r6NAkCkQJBAMAnTgPYf0f7rh417GdoP7R7Nwi8KBKwPHlmfRukibOQlKt9xjqpsKJwglLn8pcnXbYbswXIdqzuBvIGAe3OWNg=';
// 商户ID，从商户信息中获取
// merchent ID from idntask, from User info
$merchantCode = 'YOUR MERCHANT ID';
// 支付金额 pay money
$payMoney = '10000';
// 支付方式 
// Payment method
$method = 'BCA';
// 订单类型（0-法币交易）
$orderType = '0';
// 商户订单号
// Merchant system unique order number
$orderNum = 'T'.date("YmdHis",time());
// 描述
// The virtual account description
$productDetail = 'Test Pay';
$dateTime = date("YmdHis",time());
// 邮箱
// Customer's email address
$email = '[email protected]';
// 手机号码
// Customer's mobile number
$phone = '082112345678';
// 在付款确认页面显示的转账对象
// Display name on bank confirmation display
$name = 'Neo';
// 回调地址
// url for callback
$notifyUrl = 'http://example.com/callback';
// 订单过期时间 Order expiration time
$expiryPeriod = '1440';
// 返回跳转地址 redirectUrl
$redirectUrl = 'http://123.com';
$params = array(
  'merchantCode' => $merchantCode,
  'orderType' => $orderType,
  'method' => $method,
  'orderNum' => $orderNum,
  'payMoney' => $payMoney,
  'name' => $name,
  'email' => $email,
  'phone' => $phone,
  'notifyUrl' => $notifyUrl,
  'dateTime' => $dateTime,
  'expiryPeriod' => $expiryPeriod,
  'productDetail' => $productDetail
);

ksort($params);
$params_str = '';
foreach ($params as $key => $val) {
  $params_str = $params_str . $val;
}
$sign = pivate_key_encrypt($params_str, $mchPrivateKey);

$params['sign'] = $sign;

$params_string = json_encode($params);
$url = 'https://id-openapi.toppay.asia/gateway/prepaidOrder';
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $params_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/json',
  'Content-Length: ' . strlen($params_string))
);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

// execute post
$request = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if($httpCode == 200)
{
  $result = json_decode($request, true);
  echo "platRespCode :". $result['platRespCode'] . "\n";
  echo "platRespMessage :". $result['platRespMessage'] . "\n";
  echo "platOrderNum :". $result['platOrderNum'] . "\n";
  echo "orderNum :". $result['orderNum'] . "\n";
  echo "method :". $result['method'] . "\n";
  echo "name :". $result['name'] . "\n";
  echo "email :". $result['email'] . "\n";
  // 如果使用模式1，则获取url参数,收银台链接
  echo "url :". $result['url'] . "\n";
  // 如果使用模式2，则获取payData参数,支付信息
  echo "payData :". $result['payData'] . "\n";
  echo "payMoney :". $result['payMoney'] . "\n";
  echo "payFee :". $result['payFee'] . "\n";
  echo "productDetail :". $result['productDetail'] . "\n";
  echo "platSign :". $result['platSign'] . "\n";

  $decryptStr = public_key_decrypt($result['platSign'], $platPublicKey);
  echo "decryptStr :". $decryptStr . "\n";
}
else {
  echo $httpCode;
}

function pivate_key_encrypt($data, $pivate_key)
{
  $pivate_key = '-----BEGIN PRIVATE KEY-----'."\n".$pivate_key."\n".'-----END PRIVATE KEY-----';
  $pi_key = openssl_pkey_get_private($pivate_key);
  $crypto = '';
  foreach (str_split($data, 117) as $chunk) {
    openssl_private_encrypt($chunk, $encryptData, $pi_key);
    $crypto .= $encryptData;
  }

  return base64_encode($crypto);
}

function public_key_decrypt($data, $public_key)
{
  $public_key = '-----BEGIN PUBLIC KEY-----'."\n".$public_key."\n".'-----END PUBLIC KEY-----';
  $data = base64_decode($data);
  $pu_key =  openssl_pkey_get_public($public_key);
  $crypto = '';
  foreach (str_split($data, 128) as $chunk) {
    openssl_public_decrypt($chunk, $decryptData, $pu_key);
    $crypto .= $decryptData;
  }

  return $crypto;
}


暂无示例

暂无示例

暂无示例

暂无示例

# 请求地址

  • 收银台 (模式1) : 使用收银台链接中展示的支付信息
    • 请求方式 : POST
    • 请求地址 : https://id-openapi.toppay.asia/gateway/prepaidOrder
  • 直连 (非收银台) 模式 (模式2) : 直接获取支付信息 (适用于有自己收银台页面的商户)
    • 请求方式 : POST
    • 请求地址 : https://id-openapi.toppay.asia/gateway/pay

# 请求参数

注：所有的参数中，不要填写中文！！！

  • 收银台模式 (模式1)：
参数 类型 必填 描述 示例
merchantCode string(32) Y 商户ID，在商户平台-个人中心-个人信息获取 S820211021094748000001
orderType string(10) Y 订单类型 0-法币交易
method string(10) N 支付方式
1.如果需要指定支付方式，可以在右侧的示例支付方式列表中选择其一。
2.如果不指定支付方式，则可不传该参数，可以在我们的收银台页面中选择某个支付方式。		 BCA
BNC
BNI
BRI
BSI
CIMB
PERMATA
MANDIRI
MAYBANK
LINKAJA
OVO
QRIS
GOPAY_QRIS
DANA
DANAMON
SHOPEEPAY
ALFAMART
orderNum string(32) Y 商户订单号 10000001
payMoney int(10) Y 付款金额 (只能为整数，不能有小数) 150000
productDetail string(32) Y 付款描述 Test goods
notifyUrl string(100) Y 订单支付成功异步通知地址 (用来接收订单交易成功后的通知) https://host:port/notifyUrl
dateTime string(32) Y 时间戳 (格式：yyyyMMddHHmmss) 20190101235959
expiryPeriod int(5) Y 订单过期时间 (单位：分钟) 。如无特殊要求，过期时间尽量设置大一点，时间太短容易过期 1440
name string(16) Y 客户名称 Jack
email string(64) Y 用户邮箱 [email protected]
phone string(14) Y 用户手机号码 (08开头的手机号) 08123456789
redirectUrl string(200) N 返回跳转地址 http://123.com
sign string(255) Y 签名 fnbSOvY83pr8hXg+FdNNYi2ubQUGNv/qGYc4TjRl+XxO2jo92dyjKHFU9/4hNECilMooOcH
  • 直连 (非收银台) 模式 (模式2)：
    • 注1：模式2 无法使用OVO进行支付，OVO需要在收银台上输入手机号。
    • 注2：模式2 QRIS会返回两种数据：二维码Url和二维码原始数据，可以通过 payData 是否以Http开头来判断。
参数 类型 必填 描述 示例
merchantCode string(32) Y 商户ID，商户平台-个人中心-个人信息获取 S820211021094748000001
orderType string(10) Y 订单类型 0-法币交易
method string(10) Y 支付方式
需要指定支付方式，可以在右侧的示例支付方式列表中选择其一。		 BCA
BNC
BNI
BRI
BSI
CIMB
PERMATA
MANDIRI
MAYBANK
LINKAJA
OVO
QRIS
GOPAY_QRIS
DANA
DANAMON
SHOPEEPAY
ALFAMART
orderNum string(32) Y 商户订单号 10000001
payMoney int(10) Y 付款金额 (只能为整数，不能有小数) 150000
productDetail string(32) Y 付款描述 Test goods
notifyUrl string(100) Y 订单支付成功异步通知地址 (用来接收订单交易成功后的通知) https://host:port/notifyUrl
dateTime string(32) Y 时间戳 (格式：yyyyMMddHHmmss) 20190101235959
expiryPeriod int(5) Y 订单过期时间 (单位：分钟) 。如无特殊要求，过期时间尽量设置大一点，时间太短容易过期 1440
name string(16) Y 客户名称 Jack
email string(64) Y 用户邮箱 [email protected]
phone string(14) Y 用户手机号码 (08开头的手机号) 08123456789
sign string(255) Y 签名 fnbSOvY83pr8hXg+FdNNYi2ubQUGNv/qGYc4TjRl+XxO2jo92dyjKHFU9/4hNECilMooOcH

# 请求报文示例

  • 收银台模式(模式1)：(method参数可不传,跳转的页面不一样)
{
    "merchantCode": "S820211021094748000001",
    "orderType": "0",
    "method": "BCA",
    "orderNum": "T1642593166888",
    "payMoney": "150",
    "productDetail": "Test Pay",
    "notifyUrl": "your notify url",
    "dateTime": "2022-01-01 10:55:00",
    "expiryPeriod": "1440",
    "name": "JackMa",
    "email": "[email protected]",
    "phone": "082122965511",
    "sign": "fnbSOvY83pr8hXg+FdNNYi2ubQUGNv/qGYc4TjRl+Xxd1yc9fpkpTx5UQEDTgmhwdCKBkhHVsx2AiQbYDxZ5WBuU1GZeiJ"
}
  • 直连(非收银台)模式(模式2)：(method参数必传)
{
    "merchantCode": "S820211021094748000001",
    "orderType": "0",
    "method": "BCA",
    "orderNum": "T1642593166888",
    "payMoney": "150",
    "productDetail": "Test Pay",
    "notifyUrl": "your notify url",
    "dateTime": "2022-01-01 10:55:00",
    "expiryPeriod": "1440",
    "name": "JackMa",
    "email": "[email protected]",
    "phone": "082122965511",
    "sign": "fnbSOvY83pr8hXg+FdNNYi2ubQUGNv/qGYc4TjRl+Xxd1yc9fpkpTx5UQEDTgmhwdCKBkhHVsx2AiQbYDxZ5WBuU1GZeiJ"
}

# 响应参数

注：如果是QRIS，则payData返回的二维码会有两种方式：图片链接和二维码源码，请注意识别！！！

参数 类型 必填 描述 示例
platRespCode String Y 请求业务是否成功 FAIL:失败\SUCCESS:成功
platRespMessage String Y 接口响应信息提示 Request Transaction Success
platOrderNum String Y 平台订单号 PI1453242857400963072
payMoney String Y 支付金额 150000
payFee String N 手续费金额 5.32
method String N 支付方式 BCA
productDetail String Y 产品详情 apple
name String Y 客户名称 Jack
email String Y 客户邮件 [email protected]
orderNum String Y 商户订单号 23645782
url String N 收银台链接 收银台模式(模式1)，'platRespCode'为SUCCESS时返回
payData String N 支付信息 直连模式(模式2)，'platRespCode'为SUCCESS时返回

# 响应报文示例

  • 模式1响应报文示例（url是收银台链接）
{
    "platOrderNum": "BCA1483771634191044608",
    "payMoney": "150",
    "productDetail": "Test Pay",
    "name": "JackMa",
    "orderNum": "T1642593166888",
    "platRespCode": "SUCCESS",
    "platRespMessage": "Request Transaction Success",
    "url": "https://id-openapi.toppay.asia/gateway/order/BCA1483771634191044608",
    "email": "[email protected]"
}
  • 模式2响应报文示例
{
  "platOrderNum": "BCA1483771634191044608",
  "payMoney": "150",
  "payFee": "16",
  "method": "BCA",
  "productDetail": "Test Pay",
  "name": "JackMa",
  "orderNum": "T1642593166888",
  "platRespCode": "SUCCESS",
  "platRespMessage": "Request Transaction Success",
  "payData": "874961198466",
  "email": "[email protected]"
}
  • 失败响应报文示例
{
    "platRespCode": "FAIL",
    "platRespMessage": "the orderNum already exists"
}

# 代收异步通知

  • 请注意：当前业务只有在订单支付成功的时候才有回调通知
  • 进行验签时，要用 商户后台-收付款配置-API配置中提供的平台公钥进行解密！！！
  • 接受异步通知后,需响应 SUCCESS 字符串,不包含引号,不是Json格式。否则TopPay将继续发起5次通知。

import com.google.gson.JsonObject;

public class TopPayNotify {
  // 测试账号 
  private static final String MCH_ID = "S820211021094748000001";  // 商户号
  private static final String PLAT_PUBLIC_KEY = "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC2JoMfFqLsSJjAiCahEnlP3aRj8yCT+WHzR+VvPBTw9S1i7iYWb+MY09CG/HYuHF4+IxshXDJygmndxKf/esuwPybS8mAd//yubHpmZsmBqg1FffT8VH1APa6ZRWASUp4U01ZrbCCp35QA8FuWrJGMJxGx4xk7KUtV2yujxC8noQIDAQAB";  // 平台公钥
  public static void main(String[] args) throws Exception {
    // 代收
    JsonObject notifyBody = new jsonObject();
    boolean verifyResult = TopPayRequestUtil.verifySign(notifyBody,PLAT_PUBLIC_KEY);
    if (verifyResult) {
      // ... 签名验证通过,处理正常的业务逻辑
    } else {
      // ... 签名验证错误
    }
  }
}


<?php

$res = json_decode(file_get_contents('php://input'), true);
$platSign = $res['platSign'];
unset($res['platSign']);
$public_key = 'MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDFJ/AmUV4Z8udG8aOBUt/kEwc/DbxF5Gtfw6Y00NHQ4Pz2X2x9IxjUZxn2dnFxmrmhqKNlfwXOqyejhBzi0pSHyGoI4XP9IEfZGO6YkSb9DCY1ZxX8fDl2G+tPCbWYTVO4JutFmzTWgk1Uhhu6L9dlOMUHvZf3/6czA/a9C7azXwIDAQAB';
$decryptSign = public_key_decrypt($platSign, $public_key);

$params = $res;
ksort($params);
$params_str = '';
foreach ($params as $key => $val) {
  $params_str = $params_str . $val;
}

if($params_str == $decryptSign) {
  if($res['code'] == '00') {
    echo 'success';
  }
  else {
    echo 'fail';
  }
}
else {
  echo 'fail';
}

function public_key_decrypt($data, $public_key)
{
  $public_key = '-----BEGIN PUBLIC KEY-----'."\n".$public_key."\n".'-----END PUBLIC KEY-----';
  $data = base64_decode($data);
  $pu_key =  openssl_pkey_get_public($public_key);
  $crypto = '';
  foreach (str_split($data, 128) as $chunk) {
    openssl_public_decrypt($chunk, $decryptData, $pu_key);
    $crypto .= $decryptData;
  }

  return $crypto;
}

暂无示例

暂无示例

暂无示例

暂无示例

# 通知参数

参数 描述 示例
code 响应状态 00
msg 响应信息 SUCCESS
status 支付结果 查看订单状态描述
platOrderNum 平台订单号 BK_1563278763273
orderNum 商户订单号 T1231511321515
method 支付方式 Requested method
name 客户名称 Neo
payMoney 代收金额 100000
payFee 手续费金额 500
email 邮箱 [email protected]
phone 手机号 08123456789
platSign 平台签名 ja6R8eukQY9jc8zrhtf34654ungj7u8sdgdfjfs

# 异步通知报文示例

{
    "code": "00",
    "msg": "SUCCESS",
    "status": "SUCCESS",
    "platOrderNum": "BCA1483771634191044608",
    "orderNum": "T1642593166888",
    "method": "BCA",
    "name": "JackMa",
    "payMoney": "150",
    "payFee": "16",
    "email": "[email protected]",
    "phone": "08123456789",
    "platSign": "ja6R8eukQY9jc8zrhtf34654ungj7u8sdgdfjfs"
}

数字货币代收下单