HipoPay API 开发文档 NAV
python java php javascript C#

1 / 简介

HipoPay 开放 API 采用 REST 风格设计。所有接口请求都是面向资源的。使用标准响应代码来表示请求结果的正确或错误。所有的 API 请求都会以规范友好的 JSON 对象格式返回(包括错误信息),每个response都会包含meta信息(请求本身的状态数据)和data信息(请求返回的响应数据)

2 / 认证

Request

{
    "MerchantNO": '123456',
    "Signature": '539cae75aacf7d6533d288ded0f47b07',
    "Version": '1.0',
    "Timestamp": ''
}

商户发出的所有的请求都要在 header 中加上四个参数: ​

先准备公钥和私钥

2.1 / MerchantNO

商户号由HipoPay统一分配

2.2 / Signature

签名规则如下:

  1. 将请求参数(GET请求的querystring,POST请求的form内容)按照参数名ASCII码从小到大排序(字典序)并将参数值URL编码,然后使用URL键值对的格式(即key1=value1&key2=value2…)拼接成签名字符串。
  2. 在签名字符串后面拼接上Timestamp,用’,‘隔开。
  3. 将最终字符串的用RSA加密,哈希算法采用SHA256,密钥使用申请服务时提交的密钥对的私钥。
  4. 将加密结果base64编码,即为最终的签名结果。

Request

def data_sign(data, timestamp, private_key):
    """
    :param data: 表单数据
    :param timestamp: 时间戳
    :param private_key: 私钥
    :return: 签名
    """
    def format_code(x):
        """ 处理编码问题, 兼容unicode, int和 float
        """
        if isinstance(x, unicode):
            return quote(x.encode("utf-8"), safe="")
        elif isinstance(x, (float, int)):
            return str(x)
        else:
            return quote(x, safe="")

    # 按照key的拼音排序成key=value形式
    signature_str = "&".join((
        "=".join(map(format_code, i)) for i in sorted(data.items())
    ))
    # 用 utf-8 编码
    signature_str = signature_str.encode("utf-8")
    # 将时间戳附到最后,用逗号隔开
    signature_str += "," + str(timestamp)
    print signature_str
    pri_key = rsa.PrivateKey.load_pkcs1(private_key)

    signature = base64.b64encode(rsa.sign(signature_str, pri_key, "SHA-256"))
    return signature

2.3 / Version

当前最新版本:1.0

历史版本:无

2.4 / Timestamp

Unix 时间戳 参考链接

3 / 错误处理

Status Code 说明
400 Bad Request – 请求参数错误
401 Unauthorized – 签名错误
411 Timestamp Error – 请求已过时
403 Forbidden – 权限错误
404 Not Found – 未找到资源或对象
500 internal Server Error – 内部服务出错,请稍后重试
503 Service Unavailable – 服务不可用,请稍后重试
555 Wechat Service Error– 微信服务错误

如果遇到555错误代码,message参数是一个json字符串(结构如下),请根据message内的微信错误描述获取更多错误信息。

参数 说明
wx_message 微信错误信息
wx_code 微信错误编码

wx_code代表的错误解释在这里可以具体查到:微信错误编码查询

4 / Payment (微信大陆钱包)

微信跨境支付的收款对象是经过实名认证的大陆微信账号,以下多种场景的接口只能对大陆微信账号进行收款:

收款场景 说明 文档
公众号支付 适用于线下收款场景 4.1 / 公众号支付
扫一扫收款 适用于线下收款场景 4.2 / 扫一扫收款
二维码收款 线上 & 线下都适用 4.3 / 二维码收款
小程序支付 适用于线上收款场景 4.4 / 小程序支付

4.1 / 公众号支付

所谓公众号支付,是指在微信内打开的H5页面中进行支付的方式。

接入过程由以下几步完成:

第一步,拿到用户授权(openid)

用户授权完成后,我们会将商户自己的支付页面run在我们的容器当中(这个页面地址需要提前告知我们,我们会和商户绑定,我们会把授权url里面的参数全部带回去,同时会增加一个参数:openid)。

第二步,H5页面中进行支付下单

消费者输入金额之后,需要调用下列的接口:

POST /mp_pay

参数如下:

参数 说明 是否必填
merchant_no 商户号
amount 金额
openid openid
currency 币种
product_info 产品信息
agent_order_id 服务商内部单号
notify_url 支付结果通知地址

该接口返回呼唤起微信app支付的参数

第三步,唤起微信客户端的付款界面

用上面接口的参数唤起微信客户端付款界面,示例代码如下

var js_api_param = {};

//调用微信JS api 支付
function jsApiCall() {
  WeixinJSBridge.invoke('getBrandWCPayRequest', js_api_param,
                        function (res) {
    if (res.err_msg == "get_brand_wcpay_request:ok") {
      alert('支付成功');
    }

    if (res.err_msg == "get_brand_wcpay_request:cancel") {
       alert('取消支付');
    }

    if (res.err_msg == "get_brand_wcpay_request:fail") {
       alert('支付失败');
    }
  });
}

//点击确认支付
$('#pay-btn').on('click', function () {

  $.ajax({
    async: true,
    url: 'https://api.wisecashier.com/mp_pay',
    type: 'POST',
    data: {
      'merchant_no': $('#merchant_no').val(),
      'amount': $('#amt').val(),
      'openid': $('#openid').val()
    },
    headers: {
      'Version': '1.0'
    },
    beforeSend: function () {
    },
    success: function (r) {
      if (r.meta.success) {
        js_api_param = r.data.js_param;
        if (typeof WeixinJSBridge == "undefined") {
          if (document.addEventListener) {
            document.addEventListener('WeixinJSBridgeReady', jsApiCall, false);
          } else if (document.attachEvent) {
            document.attachEvent('WeixinJSBridgeReady', jsApiCall);
            document.attachEvent('onWeixinJSBridgeReady', jsApiCall);
          }
        } else {
          jsApiCall();
        }
      }
    },
    complete: function () {
    }
  });
});

第四步,查询订单状态

请参考 4.9 / 查询支付单

4.2 / 扫一扫收款

POST /order/scan_pay

所谓扫一扫付款,是指商家用设备(如扫码枪)扫描消费者的微信二维码,输入金额后即可完成收款。

这个接口做的事情就是带着消费者的二维码内容+金额等向微信发起收款请求,请求完成后,消费者在手机上点击确认支付即可完成收款

Request

def scan_pay():
    url = HOST + '/order/scan_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        product_info='这里是商品的描述',
        ip='102.142.32.12',
        auth_code='135605691981176449'
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.post(url, data, headers=header)
    return response.content

Response

{
  "data": {
    "order": {
      "agent_order_id": "xxxx",
      "amount": "100",
      "currency": "HKD",
      "exchange_rate":""0.8789"",
      "ip": "102.142.32.12",
      "merchant_no": "xxx",
      "no": "2017062313070231980966651",
      "product_info": "这里是商品的描述",
      "pay_amount": "0.1"
      "status": "PAID",
      "settle_rate": "1",
      "trade_type": "MICRO"
    }
  },
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}
参数 说明 是否必填
merchant_no 商户号
currency 币种
amount 金额
product_info 产品信息
ip 终端IP
auth_code 客户二维码内容
agent_order_id 服务商内部单号
product_id 产品编号
device_info 设备信息
notify_url 支付结果通知地址

返回内容为json,订单数据结构详情见 附录14.1

4.3 / 二维码收款

POST /order/scanned_pay

所谓二维码付款,是指商家先用设备生成收款二维码(内含收款金额等信息),再让消费者扫描二维码支付后完成收款。

这个接口做的事情就是向微信发送一个支付请求,微信会返回支付单信息 + 二维码url,消费者扫描这个二维码即完成了支付

Request

def scanned_pay():
    url = HOST + '/order/scanned_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        product_info='这是一个商品的名称',
        ip='102.142.32.12'
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.post(url, data, headers=header)
    return response.content

Response

{
    "meta": {
        "status_code": 200,
        "message": "请求成功",
        "success": true
    },
    "data": {
        "code_url": "weixin://wxpay/bizpayurl?pr=3CaDEKX",
        "order": {
            "status": "INIT",
            "trade_type": "NATIVE",
            "no": "2017062312381442716795237",
            "ip": "102.142.32.12",
            "currency": "HKD",
            "amount": "100",
            "merchant_no": "xxx",
            "agent_order_id": "xxxx"
            "pay_amount": "0.1"
            "settle_rate": "0.1"
            "trade_time": "xxxxx"
            "product_info": "这是一个商品的名称",
            "exchange_rate": "0.8789"
        }
    }
}
参数 说明 是否必填
merchant_no 商户号
currency 币种
amount 金额
product_info 产品信息
ip 终端IP
notify_url 支付结果通知地址
agent_order_id 服务商内部单号
product_id 产品编号
device_info 设备信息

返回数据为json,data内容包括两部分

4.4 / 小程序支付

第一步 获取用户登录凭证

需要在小程序中调用 wx.login(),从返回的结果中获取到用户登录凭证(code,有效期五分钟)

第二步 获取用户登录凭证

GET /wx_openid

参数 说明 是否必填
code 用户登录凭证
merchant_no 商户号

Response

{
    "meta": {
        "status_code":200 ,
        "message": "请求成功",
        "success": true
    },
    "data": {
        "openid":"kxc13i13J123"
    }
}

第三步 下单,调用下列接口,传入参数

POST /mini_program_pay

Response

{
    "meta": {
        "status_code":200 ,
        "message": "请求成功",
        "success": true
    },
    "data": {
        "timeStamp": "1509692687",
        "prepay_id": "wc1312341312312",
        "nonceStr": "casd135Defg",
        "paySign": "55511808baf7f301b5270d7334a4cec0",
        "order_no": "2017062317201074212938080"
        }
 }


参数 说明 是否必填
merchant_no 商户号
openid 微信openid
currency 币种
amount 金额
product_info 产品信息
agent_order_id 服务商内部单号
notify_url 支付结果通知地址
appid 小程序appid

第四步 唤起微信客户端的付款界面

示例代码如下,其中timeStamp,nonceStr,prepay_id,sign由上一步获得


wx.requestPayment({
   'timeStamp': timeStamp,
   'nonceStr': nonceStr,
   'package': 'prepay_id=' + prepay_id,
   'signType': 'MD5',
   'paySign': sign,
   'success': function(res) {
   console.log (res) ;
   },
   'fail': function (res) {
   console.log (res) ;
   }
})

第五步 查询订单状态

请参考 4.9 / 查询支付单 order_no在第三步中获得

4.5 / APP支付

4.5.1 / 说明

所谓APP支付,是指在商户APP内唤起微信,用户在微信内完成支付后再回到商户APP内这一过程。

4.5.2 / 在微信开放平台注册APP

注册地址:微信开放平台

注册完成后需要将app_id提交给HipoPay。

4.5.3 / 集成

共三个步骤:

第一步 / 请求预支付接口

POST /order/app_pay

Response

{
  "data": {
    "appid": "wx247c9d9d6191b108",
    "nonceStr": "718493141562",
    "order_no": "2018061311325825321166783",
    "packageValue": "Sign=WXPay",
    "partnerId": "41391056",
    "prepayId": "wx131132587279817e5df5a42a2456209955",
    "sign": "46150629E5B2AC8EB4CDB160D38DAA6C",
    "timeStamp": "1528860778"
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}
参数 说明 是否必填
merchant_no 商户号
currency 币种
amount 金额
product_info 产品信息
appid 微信开放平台分配的appid
agent_order_id 服务商内部单号
notify_url 支付结果通知地址

第二步 / 调用微信支付SDK

iOS SDK: 下载

Android SDK: 下载

iOS集成文档: iOS集成微信跨境支付.pdf

Android集成文档: Android集成微信跨境支付.pdf

第三步 / 获取订单状态

返回APP后,请通过调用4.9 / 查询支付单(或14 / 支付通知 )获取订单准确的支付状态。

4.6 / PC收银台支付

4.6.1 / 说明

PC收银台是一种供PC网站快速接入的支付方式,仅需两个步骤即可完成支付。

  1. 引导用户跳转到收银台(4.6.2),用户支付完成后会跳转到商户指定的页面。

  2. 商户通过主动查询(4.9)订单信息或接收异步通知(14.1)的方式确认交易状态。

4.6.2 / 进入收银台

GET /wechatpay/cashier_desk
参数 说明 是否必填
merchant_no 商户号
currency 币种
amount 金额
product_info 产品信息
return_url 返回地址
agent_order_id 商户单号
notify_url 支付结果通知地址

示例:

4.6.3 / 跳转

顾客在收银台支付成功后,通过GET方式跳转上一步传入的return_url, 并会附带以下参数。

参数 说明 示例
no 订单号 20181201043212345678
agent_order_id 商户订单号 XCY2018392812346127
merchant_no 商户号 WC58dc50dc59xxx
currency 币种 HKD
amount 金额 100
exchange_rate 交易汇率 1.2312
tarde_type 交易方式 PC_DESK
product_info 产品信息 演示订单
trade_time 交易时间 2017-06-22 21:29:47
status 交易状态 PAID

示例:

4.6.4 / 注意事项

  1. 前端跳转时附带的数据仅可作为参考,实际支付结果,需通过主动查询订单信息((4.9)或接收异步通知(14.1)的方式确认交易状态。
  2. 进入收银台(4.6.2)接口可以传入额外的参数,支付完成跳转时会附带额外参数,但不能和接口规定的参数名重复。

4.7 / 公众号收银台支付

4.7.1 / 说明

公众号收银台是一种供微信公众号快速接入的支付方式,仅需两个步骤即可完成支付。

  1. 引导用户跳转到收银台(4.7.2),用户支付完成后会跳转到商户指定的页面。

  2. 商户通过主动查询(4.9)订单信息或接收异步通知(14.1)的方式确认交易状态。

4.7.2 / 进入收银台

GET /wechatpay/mp_cashier_desk
参数 说明 是否必填
merchant_no 商户号
currency 币种
amount 金额
product_info 产品信息
return_url 返回地址
agent_order_id 商户单号
notify_url 支付结果通知地址

示例:

4.7.3 / 跳转

顾客在收银台支付成功后,通过GET方式跳转上一步传入的return_url, 并会附带以下参数。

参数 说明 示例
no 订单号 20181201043212345678
agent_order_id 商户订单号 XCY2018392812346127
merchant_no 商户号 WC58dc50dc59xxx
currency 币种 HKD
amount 金额 100
exchange_rate 交易汇率 1.2312
tarde_type 交易方式 MP_DESK
product_info 产品信息 演示订单
trade_time 交易时间 2017-06-22 21:29:47
status 交易状态 PAID

示例:

4.7.4 / 注意事项

  1. 前端跳转时附带的数据仅可作为参考,实际支付结果,需通过主动查询订单信息 4.9或接收异步通知( 14.1)的方式确认交易状态。
  2. 进入收银台( 4.7.2)接口可以传入额外的参数,支付完成跳转时会附带额外参数,但不能和接口规定的参数名重复。

4.8 / 退款

POST /refund

Request

def refund():
    url = HOST + '/refund'
    data = dict(
        order_no='2017062015040461510',
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.post(url, data, headers=header)
    return response.content

Response

{
  "data": {
    "refund": {
      "no": "2017062313110444111557843",
      "order_no": "2017062313070231980966651",
      "outer_refund_no": "2017062313070231980966651",
      "refund_amount": "0.1",
      "status": "SUCCESS"
    }
  },
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}


参数 说明 是否必填
order_no 订单编号
refund_amount 退款金额
outer_refund_no 外部退款单号

如果不传入退款金额参数,则全额退款。 返回结果为退款信息,退款数据结构详情见 15.2/退款单数据结构说明

4.9 / 查询支付单

GET /order

Request

def query_order():
    url = HOST + '/order'
    data = dict(
        order_no='xxxx',
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.get(url, data, headers=header)
    return response.content


Version1.0 Response

{
    "meta": {
        "status_code": 200,
        "message": "请求成功",
        "success": true
    },
    "data": {
        "order": {
            "status": "FAIL",
            "openid": "oQx43wJiwtsjv8C0lT5Lj7Mw1QZ4",
            "trade_type": "JSAPI",
            "exchange_rate": "0.8777",
            "ip": "47.52.77.110",
            "no": "xxxx",
            "device_info": "",
            "currency": "HKD",
            "amount": "1",
            "trade_time": "2017-06-22 21:29:47",
            "merchant_no": "xx",
            "pay_currency": "CNY",
            "product_info": "扫码支付 - xx科技有限公司",
            "settle_rate": "1",
            "pay_amount": "0.87",
            "refund_status": "None",
            "refundable_amount": "1"
        }
    }
}

Version2.0 Response

{
        "meta": {"status_code":200,
        "message": "请求成功",
        "success": true
    },
    "data": {
        "order": {
            "status": "FAIL",
            "openid":"oQx43wJiwtsjv8C0lT5Lj7Mw1QZ4",
            "trade_type": "JSAPI",
            "exchange_rate": 0.8777,
            "ip": "47.52.77.110",
            "no" :"2017062221294656822821341",
            "device_info": "",
            "currency": "HKD",
            "amount": 1,
            "trade_time": "2017-06-22 21:29:47",
            "merchant_no":"test-mer",
            "pay_currency": "CNY",
            "product_info": "扫码支付 - xx科技有限公司",
            "pay_amount": 0.877
        },
        "refunds": [
            {
                "no":"2017073101xxxxx",
                "order_no": "20170731xxxx",
                "refund_amount":50,
                "status":"SUCCESS"
            },{
                "no":"2017073101xxxxx",
                "order_no": "20170731xxxx",
                "refund_amount":50,
                "status":"SUCCESS"
            }
         ]
    }
参数 说明 是否必填
order_no 订单编号
agent_order_id 服务商内部单号

用order_no或agent_order_id获取订单信息,两个参数不能都为空。

4.10 / 查询退款单

GET /refund

Request

def query_refund():
    url = HOST + '/refund'
    data = dict(
        refund_no="2017073101xxxxx",
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.get(url, data, headers=header)
    return response.content

参数 说明 是否必填
refund_no 退款单号
order_no 订单编号
agent_order_id 服务商内部单号
outer_refund_no 外部退款单号
4个参数不能同时为空
参数传refund_no或refund_order_no时,返回如下
{
    "meta": {
        "status_code": 200,
        "message": "请求成功",
        "success": true
    },
    "data": {
        "info": {
            "no":"2017073101xxxxx"
            "order_no": "20170731xxxx",
            "outer_refund_no": "20170731xxxx",
            "refund_amount": "100",
            "status": "SUCCESS"
        }
    }
}
参数传order_no或agent_order_id时,返回如下
"refunds": [
   {
   "no":"2017073101xxxxx",
   "order_no": "20170731xxxx",
   "outer_refund_no": "20170731xxxx",
   "refund_amount":50,
   "status":"SUCCESS"
   },{
   "no":"2017073101xxxxx",
   "order_no": "20170731xxxx",
   "outer_refund_no": "20170731xxxx",
   "refund_amount":50,
   "status":"SUCCESS"
}]

4.11 / 查询汇率

GET /rate

Request

def query_rate():
    url = HOST + '/rate'
    data = dict(
        merchant_no='xxx',
        currency='USD',
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.get(url, data, headers=header)
    return response.content


Response

{
  "data": {
    "currency": "USD",
    "rate": "6.8575"
  },
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}
参数 说明 是否必填
merchant_no 商户编号
currency 币种

5 / Payment (微信香港钱包)

适用收款对象:香港微信钱包

5.1 / 扫一扫收款

目前微信官方仅支持“扫一扫收款”的方式对香港钱包进行收款,也就是仅支持面对面的线下收款场景

开发文档请见 4.2 / 扫一扫收款

5.2 / 退款

和微信大陆钱包一致,开发文档请见 4.6 / 退款

5.3 / 查询支付单

和微信大陆钱包一致,开发文档请见 4.7 / 查询支付单

5.4 / 查询退款单

和微信大陆钱包一致,开发文档请见 4.8 / 查询退款单

6 / Payment (支付宝线上支付)

6.1 / 二维码收款

POST /alipay/scanned_pay

所谓二维码付款,是指商户请求此接口后会获取到支付单信息 + 二维码url,将二维码展示在PC页面上。消费者打开支付宝扫码即完成了支付。

Request

def scanned_pay():
    url = HOST + '/alipay/scanned_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        subject='这是一个商品的名称'
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.post(url, data, headers=header)
    return response.content

Response

{
    "meta": {
        "status_code": 200,
        "message": "请求成功",
        "success": true
    },
    "data": {
        "url": "https://mapi.alipay.com/gateway.do?_input_charset=UTF-8&body=for+test&currency=HKD&out_trade_no=2018020810241642236276717&partner=2088021966645500&payment_inst=ALIPAYCN&product_code=NEW_WAP_OVERSEAS_SELLER&qr_pay_mode=4&qrcode_width=200&service=create_forex_trade&subject=wisecasheir+test&total_fee=0.10&sign=X0UzNA4Ygd%2FY5jLL9Dm8069pMUaWTAOiGwY1N1ihdSxjb6uKFu970y7Z8SI%2FptovMYanGRhgbzAMjBNsVCSNQGZSgSsBJf%2BI9GPmsNydLwXP2rGzFiMA0hUnL9uj25AASrNYtsVF%2Be%2BeZuafJwXbEj%2BK%2FHo8KoUA%2F0eay4DvQ8g%3D&sign_type=RSA",
        "order": {
            "status": "INIT",
            "trade_type": "NATIVE",
            "payment_no": "2017062312381442716795237",
            "currency": "HKD",
            "amount": "100",
            "merchant_no": "xxx",
            "outer_order_no": "xxxx",
            "trade_time": "xxxxx",
            "subject": "这是一个商品的名称",
            "exchange_rate": "0.8789"
        }
    }
}
参数 说明 是否必填
merchant_no 商户号
currency 币种
amount 金额
subject 产品信息
notify_url 支付结果通知地址
out_order_no 服务商内部单号

返回数据为json,data内容包括两部分

字段 说明
payment_no 订单编号
merchant_no 商户编号
currency 币种,支持的币种请见15.3/货币编码
amount 金额
exchange_rate 汇率,汇率的语义是:一个外币 = 多少个人民币
subject 商品描述
product_info 商品描述
trade_type 交易类型
trade_time 交易时间
out_order_no 服务商内部单号
status 订单状态,INIT :等待付款;PAID :支付成功;FAIL :支付失败; EXPIRED: 订单失效
pay_method 支付方式

6.2 / APP支付

所谓APP支付,是指顾客在商户的app内唤起支付宝完成支付。整个过程需要以下三个步骤

  1. APP请求接口6.2.1,获取prepay_string。
  2. 使用prepay_string调用SDK(6.2.2)唤起支付宝。
  3. 服务端通过查询订单(6.3)或异步通知(14.1)获取支付状态完成支付。

6.2.1 / 获取prepay_string

POST /alipay/app_pay

Response

{
    "meta": {
        "status_code": 200,
        "message": "请求成功",
        "success": true
    },
    "data": {
       "prepay_string":"_input_charset=\"utf-8\"&body=\"fortest\"&currency=\"HKD\"&forex_biz=\"FP\"&out_trade_no=\"2018022322365133840xxxx74\"&partner=\"208882182xxxx743\"&payment_type=\"1\"&seller_id=\"208882182xxxx743\"&service=\"mobile.securitypay.pay\"&subject=\"wisecasheirtest\"&total_fee=\"0.10\"&sign=\"Dld8ki9s26LB6s0UgJpX6ItU7AR5SAIcoCTbSxcl34Ka1mvrtRPZNyLfiHtGmhCzrPGU7WnZ12P%2BV1bS8EftQXMhHJbw07SG6apnHwNMjAHSFgGaZ78k8prlJfWwggMgks1TxN6MNrF2FPMQvsHGpzG1dLqgbdNlKGGe7uW1VBnFSgLtJWjTBFO3ceYtMIOcUPLON1uKu0Z%2F0NcsNdWQIu03yiqU2tgik9XthCTOmVYh6mFSocL9Q87SXL9fgfSrPEUPS%2FHb%2BNHhosKckc3%2BESXYfiRsKoQmos%2FU7vbuYoJSXCkW68r2T1gC3m2Ltfcn45W4Wro5JgcOlUD3FFf%2BRg%3D%3D\"&sign_type=\"RSA\"",
        "order": {
            "status": "INIT",
            "trade_type": "NATIVE",
            "payment_no": "201706231238144271679XXX",
            "currency": "HKD",
            "amount": "100",
            "merchant_no": "xxx",
            "outer_order_no": "xxxx",
            "trade_time": "xxxxx",
            "subject": "这是一个商品的名称",
            "exchange_rate": "0.8789"
        }
    }
}
参数 说明 是否必填
merchant_no 商户号
currency 币种
amount 金额
subject 产品信息
notify_url 支付结果通知地址
out_order_no 服务商内部单号

返回数据为json,data内容包括两部分

字段 说明
payment_no 订单编号
merchant_no 商户编号
currency 币种,支持的币种请见15.3/货币编码
amount 金额
exchange_rate 汇率,汇率的语义是:一个外币 = 多少个人民币
subject 商品描述
product_info 商品描述
trade_type 交易类型
trade_time 交易时间
out_order_no 服务商内部单号
status 订单状态,INIT :等待付款;PAID :支付成功;FAIL :支付失败; EXPIRED: 订单失效
pay_method 支付方式

6.2.2 / 获取调用SDK

iOS-SDK: 下载

Android-SDK:下载

iOS-DEMO-SRC: 下载

Android-DEMO:下载

Android-DEMO-SRC:下载

iOS:

iOS 应用集成支付宝跨境支付: 文档下载

Android:

唤起支付

接口名称: payTask

方法名称:payTask.pay

方法原型:PayTask payTask = new PayTask(activity); payTask.pay(prepay_string, true);

方法功能:提供给商户订单支付功能。

方法参数: 实例化PayTask,传入参数activity 的实例。

参数名称 参数说明
String prepay_string 由前一步获取
boolean isShowPayLoading 用户在商户app内部点击付款,是否需要一个loading做为在钱包唤起之前的过渡,这个值设置为true,将会在调用pay接口的时候直接唤起一个loading,直到唤起H5支付页面或者唤起外部的钱包付款页面loading才消失。(建议将该值设置为true,优化点击付款到支付唤起支付页面的过渡过程。)

返回结果

Response

    resultStatus={9000};memo={};

    result={partner="2088101568358171"&out_trade_no="0819145412-6177"&

    subject="测试"&body="测试测试"&total_fee="0.01"&

    notify_url="http://notify.msp.hk/notify.htm"

    &service="mobile.securitypay.pay"&payment_type="1"&_input_charset="utf-8"

    &it_b_pay="30m"&success="true"&sign_type="RSA"

    &sign=".../3cr3UwmEV4L3Ffir/02RBVtU=..."}

如右:返回结果在resultStatus=9000,并且result->success=“true”的情况下,视为支付成功,但此结果不可信,请以服务器调用6.3 查询支付单或异步通知(14)获取到的结果为最终付款成功的依据。

6.3 / WAP支付

POST /alipay/wap_pay

所谓WAP支付,是指用户在移动端H5页面中使用支付宝支付的方式。

此支付方式有三个步骤:

Request

def scanned_pay():
    url = HOST + '/alipay/wap_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        subject='这是一个商品的名称'
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.post(url, data, headers=header)
    return response.content

Response

{
    "meta": {
        "status_code": 200,
        "message": "请求成功",
        "success": true
    },
    "data": {
        "url": "https://mapi.alipay.com/gateway.do?_input_charset=UTF-8&body=for+test&currency=HKD&out_trade_no=2018020810241642236276717&partner=2088021966645500&payment_inst=ALIPAYCN&product_code=NEW_WAP_OVERSEAS_SELLER&qr_pay_mode=4&qrcode_width=200&service=create_forex_trade&subject=wisecasheir+test&total_fee=0.10&sign=X0UzNA4Ygd%2FY5jLL9Dm8069pMUaWTAOiGwY1N1ihdSxjb6uKFu970y7Z8SI%2FptovMYanGRhgbzAMjBNsVCSNQGZSgSsBJf%2BI9GPmsNydLwXP2rGzFiMA0hUnL9uj25AASrNYtsVF%2Be%2BeZuafJwXbEj%2BK%2FHo8KoUA%2F0eay4DvQ8g%3D&sign_type=RSA",
        "order": {
            "status": "INIT",
            "trade_type": "NATIVE",
            "payment_no": "2017062312381442716795237",
            "currency": "HKD",
            "amount": "100",
            "merchant_no": "xxx",
            "outer_order_no": "xxxx",
            "trade_time": "xxxxx",
            "subject": "这是一个商品的名称",
            "exchange_rate": "0.8789"
        }
    }
}
参数 说明 是否必填
merchant_no 商户号
currency 币种
amount 金额
subject 产品信息
notify_url 支付结果通知地址
out_order_no 服务商内部单号
return_url 支付完成后返回的地址

返回数据为json,data内容包括两部分

字段 说明
payment_no 订单编号
merchant_no 商户编号
currency 币种,支持的币种请见15.3/货币编码
amount 金额
exchange_rate 汇率,汇率的语义是:一个外币 = 多少个人民币
subject 商品描述
product_info 商品描述
trade_type 交易类型
trade_time 交易时间
out_order_no 服务商内部单号
status 订单状态,INIT :等待付款;PAID :支付成功;FAIL :支付失败; EXPIRED: 订单失效
pay_method 支付方式

6.4 / PC收银台支付

6.4.1 / 说明

PC收银台是一种供PC网站快速接入的支付方式,仅需两个步骤即可完成支付。

  1. 引导用户跳转到收银台(6.4.2),用户支付完成后会跳转到商户指定的页面。

  2. 商户通过主动查询(6.5)订单信息或接收异步通知(14.1)的方式确认交易状态。

6.4.2 / 进入收银台

GET /alipay/cashier_desk
参数 说明 是否必填
merchant_no 商户号
currency 币种
amount 金额
subject 产品信息
return_url 返回地址
out_order_no 商户订单号
notify_url 支付结果通知地址

示例:

6.4.3 / 跳转

顾客在收银台支付成功后,通过GET方式跳转上一步传入的return_url, 并会附带以下参数。

参数 说明 示例
no 订单号 20181201043212345678
out_order_no 商户订单号 XCY2018392812346127
merchant_no 商户号 WC58dc50dc59xxx
currency 币种 HKD
amount 金额 100
exchange_rate 交易汇率 1.2312
tarde_type 交易方式 DESK
subject 产品信息 演示订单
trade_time 交易时间 2017-06-22 21:29:47
status 交易状态 PAID

示例:

6.4.4 / 注意事项

  1. 前端跳转时附带的数据仅可作为参考,实际支付结果,需通过主动查询订单信息(6.5)或接收异步通知(14.1)的方式确认交易状态。
  2. 进入收银台(6.4.3)接口可以传入额外的参数,支付完成跳转时会附带额外参数,但不能和接口规定的参数名重复。

6.5 / 查询支付单

GET /alipay/order

Request

def query_order():
    url = HOST + '/alipay/order'
    data = dict(
        out_order_no='xxxx',
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.get(url, data, headers=header)
    return response.content

Repsonse

{
  "data": {
    "order": {
      "amount": "0.10",
      "buyer_email": "18624@163.com",
      "channel": "ALIPAYCN",
      "charge_amount": "0.01",
      "currency": "HKD",
      "exchange_rate": "0.804740",
      "merchant_no": "test-mer",
      "payment_no": "2018020716122408862056356",
      "buyer_id": "2088702631783753",
      "pay_amount": "0.08",
      "pay_currency": "CNY",
      "product_info": "for test",
      "refund_status": "None",
      "refundable_amount": "0.10",
      "status": "PAID",
      "subject": "wisecasheir test",
      "trade_time": "2018-02-07 16:12:24",
      "trade_type": "NATIVE",
      "out_order_no": "2018020721001003750533954072"
    }
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}
参数 说明 是否必填
payment_no 订单编号
out_order_no 服务商内部单号

用payment_no或out_order_no获取订单信息,两个参数不能都为空。

字段 说明
payment_no 订单编号
merchant_no 商户编号
buyer_email 顾客Email
buyer_id 顾客id
currency 币种,支持的币种请见15.3/货币编码
amount 金额
exchange_rate 汇率,汇率的语义是:一个外币 = 多少个人民币
subject 商品描述
product_info 商品描述
trade_type 交易类型
trade_time 交易时间
out_order_no 服务商内部单号
status 订单状态,INIT :等待付款;PAID :支付成功;FAIL :支付失败; EXPIRED: 订单失效
pay_method 支付方式
refund_status 退款状态,NONE :未退款;PART :部分退款;FULL :全部退款
refundable_amount 可退款金额

6.6 / 退款

POST /alipay/refund

Request

def refund():
    url = HOST + '/alipay/refund'
    data = dict(
        payment_no='2017062015040461510',
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.post(url, data, headers=header)
    return response.content

Response

{
  "data": {
    "refund": {
      "refund_no": "2017062313110444111557843",
      "payment_no": "2017062313070231980966651",
      "outer_refund_no": "2017062313070231980966651",
      "refund_amount": "0.1",
      "status": "SUCCESS"
    }
  },
  "meta": {
    "message": "请求成功",
    "status_code": 200,
    "success": true
  }
}


参数 说明 是否必填
payment_no 订单编号
outer_refund_no 外部退款单号
refund_amount 退款金额

如果不传入退款金额参数,则全额退款。

返回结果为退款信息:

字段 说明
payment_no 订单编号
refund_no 订单编号
refund_amount 退款金额
status 退款状态
outer_refund_no 外部退款单号

6.7 / 查询退款

GET /alipay/refund

Request

def query_refund():
    url = HOST + '/alipay/refund'
    data = dict(
        refund_no="2017073101xxxxx",
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.get(url, data, headers=header)
    return response.content

参数 说明 是否必填
refund_no 退款单号
payment_no 订单编号
outer_order_no 外部订单号
outer_refund_no 外部退款单号

Request

def query_refund():
    url = HOST + '/refund'
    data = dict(
        refund_no="2017073101xxxxx",
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.get(url, data, headers=header)
    return response.content

4个参数不能同时为空
参数传refund_no或refund_order_no时,返回如下
{
    "meta": {
        "status_code": 200,
        "message": "请求成功",
        "success": true
    },
    "refund": {
        "no":"2017073101xxxxx"
         "order_no": "20170731xxxx",
         "agent_order_id": "20170731xxxx",
         "outer_refund_no": "20170731xxxx",
        "refund_amount": "100",
        "status": "SUCCESS"
    }
}
参数传order_no或agent_order_id时,返回如下
"refunds": [
    {
    "no":"2017073101xxxxx"
         "order_no": "20170731xxxx",
         "refund_no": "20170731xxxx",
         "agent_order_id": "20170731xxxx",
         "outer_refund_no": "20170731xxxx",
        "refund_amount": "100",
        "status": "SUCCESS"
    },
    {
    "no":"2017073101xxxxx"
         "order_no": "20170731xxxx",
         "refund_no": "20170731xxxx",
         "agent_order_id": "20170731xxxx",
         "outer_refund_no": "20170731xxxx",
        "refund_amount": "100",
        "status": "SUCCESS"
    }
]

6.8 / 查询汇率

GET /alipay/rate

此接口返回请求币种对人民币的参考汇率,实际汇率以交易时的汇率为准。

Request

def query_refund():
    url = HOST + '/alipay/rate'
    data = dict(
        currency="HKD",
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.get(url, data, headers=header)
    return response.content

Response

{
    "meta": {
        "status_code": 200,
        "message": "请求成功",
        "success": true
    },
    "rate": {
        "currency": "HKD",
        "rate": "0.860000"
    }
}
参数 说明 是否必填
currency 币种

返回结果为:

字段 说明
currency 订单编号
rate 汇率

7 / Payment (支付宝线下支付)

7.1 / 动态二维码支付

POST /alipay/qrcode_pay

所谓动态二维码支付,是指商户请求如下接口获取qrcode,顾客用支付宝扫描完成支付。

此支付方式有三个步骤:

Request

def scanned_pay():
    url = HOST + '/alipay/qrcode_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        subject='这是一个商品的名称'
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.post(url, data, headers=header)
    return response.content

Response

{
    "meta": {
        "status_code": 200,
        "message": "请求成功",
        "success": true
    },
    "data": {
         "qrcode": "https://qr.alipay.com/bax04448a1pogrhduko280d3",
        "order": {
            "status": "INIT",
            "trade_type": "NATIVE",
            "payment_no": "2017062312381442716795237",
            "currency": "HKD",
            "amount": "100",
            "merchant_no": "xxx",
            "outer_order_no": "xxxx",
            "trade_time": "xxxxx",
            "subject": "这是一个商品的名称",
            "exchange_rate": "0.8789"
        }
    }
}
参数 说明 是否必填
merchant_no 商户号
currency 币种
amount 金额
subject 产品信息
notify_url 支付结果通知地址
out_order_no 服务商内部单号

返回数据为json,data内容包括两部分

字段 说明
payment_no 订单编号
merchant_no 商户编号
currency 币种,支持的币种请见15.3/货币编码
amount 金额
exchange_rate 汇率,汇率的语义是:一个外币 = 多少个人民币
subject 商品描述
product_info 商品描述
trade_type 交易类型
trade_time 交易时间
out_order_no 服务商内部单号
status 订单状态,INIT :等待付款;PAID :支付成功;FAIL :支付失败; EXPIRED: 订单失效
pay_method 支付方式

7.2 / 扫码支付

POST /alipay/scan_pay

所谓扫码支付,是指商户用扫描枪或其他方式扫描顾客展示的支付宝付款码,商户用此付款码请求下列接口完成支付。

此支付方式有三个步骤:

Request

def scanned_pay():
    url = HOST + '/alipay/scan_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        auth_code='123456',
        subject='这是一个商品的名称'
    )
    timestamp = str(time.time())
    sign = data_sign(data, timestamp, pri_key)

    header = HEADER.copy()
    header['Signature'] = sign
    header['Timestamp'] = timestamp

    response = requests.post(url, data, headers=header)
    return response.content

Response

{
    "meta": {
        "status_code": 200,
        "message": "请求成功",
        "success": true
    },
    "data": {
        "order": {
            "status": "INIT",
            "trade_type": "NATIVE",
            "payment_no": "2017062312381442716795237",
            "currency": "HKD",
            "amount": "100",
            "merchant_no": "xxx",
            "outer_order_no": "xxxx",
            "trade_time": "xxxxx",
            "subject": "这是一个商品的名称",
            "exchange_rate": "0.8789"
        }
    }
}
参数 说明 是否必填
merchant_no 商户号
auth_code 支付宝付款码
currency 币种
amount 金额
subject 产品信息
notify_url 支付结果通知地址
out_order_no 服务商内部单号

返回数据为json

字段 说明
payment_no 订单编号
merchant_no 商户编号
currency 币种,支持的币种请见15.3/货币编码
amount 金额
exchange_rate 汇率,汇率的语义是:一个外币 = 多少个人民币
subject 商品描述
product_info 商品描述
trade_type 交易类型
trade_time 交易时间
out_order_no 服务商内部单号
status 订单状态,INIT :等待付款;PAID :支付成功;FAIL :支付失败; EXPIRED: 订单失效
pay_method 支付方式

7.3 / 退款

和支付宝线上一致,开发文档见 6.5 / 退款

7.4 / 查询支付单

和支付宝线上一致,开发文档见 6.4 / 查询支付单

7.5 / 查询退款

和支付宝线上一致,开发文档见 6.6 / 查询退款

8 / Merchant (商户)

8.1 / 创建Merchant

POST /merchant

Response

{
  "data": {
    "merchant": {
      "account": "123@123.com",
      "country_code": "HKG",
      "is_sub_merchant": 1,
      "name": "for test put",
      "no": "SM5a5f1d19b6b15",
      "parent_merchant_no": "WC5985cd2280082",
      "remark": "test put remark",
      "settle_currency": "HKD",
      "settled_balance": "189000.00",
      "short_name": "test put",
      "unsettled_balance": "0"
    }
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

在HipoPay中,有两种类型的Merchant对象:一种是真实的Merchant,它与签约主体一一对应;另一种是虚拟Merchant,是我们提供给商户进行分账的虚拟子商户,一个虚拟商户一定归属于一个真实商户(所以文档中如果不做特殊约定,若提到“子商户”,即指虚拟子商户)。目前我们仅允许创建虚拟商户,真实商户需要通过签约流程开通,虚拟Merchant只能接受来自其他Merchant的转账,并不具备收款的功能。创建一个虚拟的Merchant参数如下:

参数 说明 是否必填
name (子)商户名称
short_name (子)商户简称
country_code (子)商户所在国家
settle_currency 结算币种
parent_merchant_no 父商户编号
account saas登录账号,必须是邮箱
password sass登录密码
remark 商户备注

返回参数说明:

参数 说明
no 商户编号
parent_merchant_no 父商户编号
account 账号
name 商户名称
short_name 商户简称
country_code 注册国家编码
is_sub_merchant 是否是子商户
settle_currency 结算币种
settled_balance 已结算余额
unsettled_balance 未结算余额
remark 备注

8.2 / 查询Merchant

GET /merchant

Response

{
  "data": {
    "merchant": {
      "account": "123@123.com",
      "country_code": "HKG",
      "is_sub_merchant": 1,
      "name": "for test put",
      "no": "SM5a5f1d19b6b15",
      "parent_merchant_no": "XXXXXXXX",
      "remark": "test put remark",
      "settle_currency": "HKD",
      "short_name": "test put",
       "balance":[
         {
            "currency":"HKD",
            "settled_balance":92199,
            "trade_balacnce":2121
          },
          {
            "currency":"EUR",
            "settled_balance":212,
            "trade_balacnce":310
          }
       ]
    }
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

无论是真实商户还是虚拟子商户,都可以通过该API查询Merchant信息,输入是Merchant编号,返回一个Merchant对象

参数 说明 是否必填
merchant_no 商户编号或子商户编号

返回参数说明:

参数 说明
no 商户编号
parent_merchant_no 父商户编号
account 账号
name 商户名称
short_name 商户简称
country_code 注册国家编码
is_sub_merchant 是否是子商户
settle_currency 结算币种
settled_balance 已结算余额
remark 备注

8.3 / 更新Merchant

PUT /merchant

Response

{
  "data": {
    "merchant": {
      "account": "123@123.com",
      "country_code": "HKG",
      "is_sub_merchant": 1,
      "name": "for test put",
      "no": "SM5a5f1d19b6b15",
      "parent_merchant_no": "XXXXXXXX",
      "remark": "test put remark",
      "settle_currency": "HKD",
      "settled_balance": "189000.00",
      "short_name": "test put",
      "unsettled_balance": "0"
    }
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

目前API不支持对真实Merchant进行任何修改,该API只支持对虚拟子商户进行更新。

对于虚拟子商户只能修改名称和简称。如果确实要修改其他属性,请删除子商户后后重新创建。

参数 说明 是否必填
merchant_no 子商户编号
name 商户名称
short_name 商户简称

返回参数说明:

参数 说明
no 商户编号
parent_merchant_no 父商户编号
account 账号
name 商户名称
short_name 商户简称
country_code 注册国家编码
is_sub_merchant 是否是子商户
settle_currency 结算币种
settled_balance 已结算余额
unsettled_balance 未结算余额
remark 备注

8.4 / 删除Merchant

DELETE /merchant

Response

{
  "data": {},
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

目前API不支持对真实Merchant进行删除,该API只支持对虚拟子商户进行删除。

若子商户中有余额时默认无法删除,若要强制删除,请设置force = YES,强制删除子商户后,余额清零,请务必知道该参数的风险。

参数 说明 是否必填
merchant_no 子商户编号
force 是否强制删除,默认是NO

8.5 / 查询Merchant列表

GET /merchants

Response

{
  "data": {
    "merchant": [
      {
        "account": "123@123.com",
        "country_code": "HKG",
        "is_sub_merchant": 1,
        "name": "for test put",
        "no": "SM5a5f1d19b6b15",
        "parent_merchant_no": "XXXXXX",
        "remark": "test put remark",
        "settle_currency": "HKD",
        "short_name": "test put",
        "balance":[
         {
            "currency":"HKD",
            "settled_balance":92199,
            "trade_balacnce":2121
          },
          {
            "currency":"EUR",
            "settled_balance":212,
            "trade_balacnce":310
          }
       ]
      },
      {
        "account": "1234@1234.com",
        "country_code": "HKG",
        "is_sub_merchant": 1,
        "name": "test 2",
        "no": "SM5a6206fb392ff",
        "parent_merchant_no": "XXXXX",
        "remark": "",
        "settle_currency": "HKD",
        "short_name": "test 2",
        "balance":[
         {
            "currency":"HKD",
            "settled_balance":92199,
            "trade_balacnce":2121
          },
          {
            "currency":"EUR",
            "settled_balance":212,
            "trade_balacnce":310
          }
       ]
      }
      ]
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

该API查询真实商户下的虚拟子商户,所以输入是真实商户编号,返回虚拟商户对象列表。

参数 说明 是否必填
merchant_no 商户编号

返回参数说明:

参数 说明
no 商户编号
parent_merchant_no 父商户编号
account 账号
name 商户名称
short_name 商户简称
country_code 注册国家编码
is_sub_merchant 是否是子商户
settle_currency 结算币种
settled_balance 已结算余额
unsettled_balance 未结算余额
remark 备注

8.6 / 查询支付渠道

GET /pay_channels

通过该接口可以查询已开通的支付渠道

参数 说明 是否必填
- -

此接口无须传参

返回参数说明:

参数 说明
channel 渠道
channel_name 渠道名称
pricing_currency 计价币种
settle_currency 结算币种
cate 渠道类型

Response

{
  "data": {
    "pay_channels": [
      {
        "channel": "wechatpay",
        "channel_name": "微信跨境",
         "pricing_currency":"HKD",
         "settle_currency":"HKD",
         "cate":"wechatpay-ext",
      },
      {
        "channel": "apipay",
        "channel_name": "支付宝线上",
         "pricing_currency":"CNY",
         "settle_currency":"EUR",
         "cate":"alipay-global",
      },
     ]

  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

9 / SettleAccount (结算账户)

9.1 / 创建结算账户

POST /settle_account

Response

{
  "data": {
    "settle_account": {
      "account": "12345678",
      "account_name": "test card",
      "address": "SC chengdu",
      "bank": "no bank",
      "branch": "no branch",
      "country_code": "HKG",
      "currency_codes": "HKG,CNY",
      "no": "5a620ade49aec",
      "status": "INIT",
      "swift_code": "HKGHKHKHKHK"
    }
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

目前API不支持对真实Merchant添加结算账户,该API只支持对虚拟子商户添加结算账户。货币币种请参考 15.3/货币编码

参数 说明 是否必填
merchant_no 子商户编号
account 银行账户(卡号)
account_name 账户名
bank 银行名称
branch 分行
country_code 银行国家编号
swift_code swift_code
currency_codes 接受币种,逗号分隔
address 地址

返回参数说明:

参数 说明
no 账户编号
account 账号
account_name 账户名称
country_code 银行所在国家编码
bank 银行名称
branch 分行
address 地址
currency_codes 支持币种
status 状态
swift_code swift_code

9.2 / 查询结算账户

GET /settle_account

Response

{
  "data": {
    "settle_account": {
      "account": "12345678",
      "account_name": "test card",
      "address": "SC chengdu",
      "bank": "no bank",
      "branch": "no branch",
      "country_code": "HKG",
      "currency_codes": "HKG,CNY",
      "no": "5a620ade49aec",
      "status": "INIT",
      "swift_code": "HKGHKHKHKHK"
    }
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

输入参数是settle_account_no,返回一个结算账户的对象。

参数 说明 是否必填
settle_account_no 结算账户编号

返回参数说明:

参数 说明
no 账户编号
account 账号
account_name 账户名称
country_code 银行所在国家编码
bank 银行名称
branch 分行
address 地址
currency_codes 支持币种
status 状态
swift_code swift_code

9.3 / 查询结算账户列表

GET /settle_accounts

查询商户或者子商户下绑定的结算账户。

参数 说明 是否必填
merchant_no 商户编号或子商户编号

返回参数说明:

参数 说明
no 账户编号
account 账号
account_name 账户名称
country_code 银行所在国家编码
bank 银行名称
branch 分行
address 地址
currency_codes 支持币种
status 状态
swift_code swift_code

Response

{
  "data": {
    "settle_account": [
      {
        "account": "12345678",
        "account_name": "test card",
        "address": "SC chengdu",
        "bank": "no bank",
        "branch": "no branch",
        "country_code": "HKG",
        "currency_codes": "HKG,CNY",
        "no": "5a5f7f5ab3c24",
        "status": "INIT",
        "swift_code": "HKGHKHKHKHK"
      },
      {
        "account": "12345678",
        "account_name": "test card",
        "address": "SC chengdu",
        "bank": "no bank",
        "branch": "no branch",
        "country_code": "HKG",
        "currency_codes": "HKG,CNY",
        "no": "5a5f7f84939c7",
        "status": "INIT",
        "swift_code": "HKGHKHKHKHK"
      }
    ]
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

10 / 导出对账单

GET /download_bill
参数 说明 是否必填
merchant_no 商户号
start_date 开始时间
end_date 结束时间

该接口只能查询三个月以内的记录,返回一个txt文件。

11 / Withdrawal (提现)

11.1 / 创建提现

POST /withdrawal

Response

{
  "data": {
    "withdrawal": {
      "forex_rate": 7.8409,
      "gst": 0.00,
      "no": "2018011923161675515520294",
      "service_fee": 6.00,
      "source_amount": 1000.00,
      "source_currency": "HKD",
      "status": "INIT",
      "target_amount": 69.37,
      "target_currency": "USD",
      "withdrawal_fee": 450.00
    }
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

通过该API能够将商户账户中的资金提现到结算银行账户中,同时提现的时候可以选择其他货币,货币编号请参考15.3/货币编码

参数 说明 是否必填
merchant_no 商户编号或子商户编号
source_amount 提现金额
source_currency 提现原币种
target_currency 提现目标币种
settle_account_no 结算账户编号

返回参数说明:

参数 说明
no 提现编号
forex_rate 账号
gst 税费(目前只有新西兰地区才会有)
service_fee 服务费
source_amount 结算金额
source_currency 结算币种
target_amount 目标金额
target_currency 目标币种
withdrawal_fee 手续费
status 状态

11.2 / 查询提现

GET /withdrawal

Response

{
  "data": {
    "withdrawal": {
      "forex_rate": 7.8409,
      "gst": 0,
      "no": "2018011923161675515520294",
      "service_fee": 6.00,
      "source_amount": 1000.00,
      "source_currency": "HKD",
      "status": "INIT",
      "target_amount": 69.37,
      "target_currency": "USD",
      "withdrawal_fee": 450
    }
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

通过提现编号查询提现状态,输入为提现编号,输出为提现对象

参数 说明 是否必填
withdrawal_no 提现编号

返回参数说明:

参数 说明
no 提现编号
forex_rate 费率
gst 税费(目前只有新西兰地区才会有)
service_fee 服务费
source_amount 结算金额
source_currency 结算币种
target_amount 目标金额
target_currency 目标币种
withdrawal_fee 手续费
status 状态

11.3 / 查询提现列表

GET /withdrawals
参数 说明 是否必填
merchant_no 商户编号或子商户编号
date 日期:YYYY-MM-DD

Response

{
  "data": {
    "withdrawal": [
      {
        "forex_rate": 7.8409,
        "gst": 0,
        "no": "2018011922052090560811376",
        "service_fee": 6.00,
        "source_amount": 1000.00,
        "source_currency": "HKD",
        "status": "INIT",
        "target_amount": 69.37,
        "target_currency": "USD",
        "withdrawal_fee": 450
      },
      {
        "forex_rate": 7.8409,
        "gst": 0,
        "no": "2018011922053150790173487",
        "service_fee": 6.00,
        "source_amount": 1000.00,
        "source_currency": "HKD",
        "status": "INIT",
        "target_amount": 69.37,
        "target_currency": "USD",
        "withdrawal_fee": 450
      }
    ]
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

返回参数说明:

参数 说明
no 提现编号
forex_rate 费率
gst 税费(目前只有新西兰地区才会有)
service_fee 服务费
source_amount 结算金额
source_currency 结算币种
target_amount 目标金额
target_currency 目标币种
withdrawal_fee 手续费
status 状态

12 / Transfer (转账)

12.1 / 创建转账

POST /transfer

通过该API能够将商户账户中的资金 transfer 到其他商户/子商户中,同时转账的时候可以选择其他货币,货币编号请参考15.3/货币编码

参数 说明 是否必填
source_merchant_no 商户编号或子商户编号
source_amount 转账金额
target_merchant_no 目标商户编号
target_merchant_name 目标商户名称merchant name
remark 附言

Response

{
  "data": {
    "transfer": {
      "forex_rate": 1,
      "no": "TS2018012122391005986366833",
      "remark": "test transfer",
      "source_amount": 1000,
      "source_currency": "HKD",
      "source_merchant_no": "SM5a5f1d19b6b15",
      "status": "INIT",
      "target_amount": 1000.00,
      "target_currency": "HKD",
      "target_merchant_name": "test 2",
      "target_merchant_no": "SM5a6206fb392ff",
      "time": "2018-01-21 12:39:10"
    }
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

返回参数说明:

参数 说明
no 提现编号
forex_rate 费率
source_merchant_no 转账商户号
source_amount 结算金额
source_currency 结算币种
target_merchant_no 收款商户号
target_amount 收款金额
target_currency 收款币种
target_merchant_name 目标商户名称
status 状态
remark 备注
time 时间

12.2 / 查询转账

GET /transfer
参数 说明 是否必填
transfer_no 转账编号

Response

{
  "data": {
    "transfer": {
      "forex_rate": 1,
      "no": "TS2018012122391005986366833",
      "remark": "test transfer",
      "source_amount": 1000,
      "source_currency": "HKD",
      "source_merchant_no": "SM5a5f1d19b6b15",
      "status": "SUCCESS",
      "target_amount": 1000.00,
      "target_currency": "HKD",
      "target_merchant_name": "test 2",
      "target_merchant_no": "SM5a6206fb392ff",
      "time": "2018-01-21 12:39:10"
    }
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}

返回参数说明:

参数 说明
no 提现编号
forex_rate 费率
source_merchant_no 转账商户号
source_amount 结算金额
source_currency 结算币种
target_merchant_no 收款商户号
target_amount 收款金额
target_currency 收款币种
target_merchant_name 目标商户名称
status 状态
remark 备注
time 时间

12.3 / 查询转账列表

GET /transfers
参数 说明 是否必填
merchant_no 商户编号
date 日期:YYYY-MM-DD

Response

{
  "data": {
    "transfer": [
        {
          "forex_rate": 1,
          "no": "TS2018012122391005986366833",
          "remark": "test transfer",
          "source_amount": 1000,
          "source_currency": "HKD",
          "source_merchant_no": "SM5a5f1d19b6b15",
          "status": "SUCCESS",
          "target_amount": 1000.00,
          "target_currency": "HKD",
          "target_merchant_name": "test 2",
          "target_merchant_no": "SM5a6206fb392ff",
          "time": "2018-01-21 12:39:10"
        },
        {
          "forex_rate": 1,
          "no": "TS2018012122391005986366833",
          "remark": "test transfer",
          "source_amount": 1000,
          "source_currency": "HKD",
          "source_merchant_no": "SM5a5f1d19b6b15",
          "status": "SUCCESS",
          "target_amount": 1000.00,
          "target_currency": "HKD",
          "target_merchant_name": "test 2",
          "target_merchant_no": "SM5a6206fb392ff",
          "time": "2018-01-21 12:39:10"
        }
    ]
  },
  "meta": {
    "message": "Requset Successes",
    "status_code": 200,
    "success": true
  }
}
参数 说明
no 提现编号
forex_rate 费率
source_merchant_no 转账商户号
source_amount 结算金额
source_currency 结算币种
target_merchant_no 收款商户号
target_amount 收款金额
target_currency 收款币种
target_merchant_name 目标商户名称
status 状态
remark 备注
time 时间

13 / 辅助接口

13.1 / 微信支付报关

POST /wechatpay/declaration
参数 说明 是否必填 类型 示例
out_order_no 商户订单号 String 18051893975650968
payment_no HipoPay支付单号 String 20180518163203689
customs 海关编号(如:SHENZHEN) String SHENZHEN
mch_customs_no 商户海关备案号 String 123456789BTW
duty 关税(部分海关需要此参数) int 88
action_type ADD(新增) or MODIFY(修改) 默认为ADD,当action_type 为 MODIFY,参数需要与第一次报关的参数保持一致。 String ADD

若拆单则需要填以下参数

参数 说明 是否必填 类型 示例
sub_order_no 商户子订单号 String 2018051716124
sub_order_amount 子订单金额 float 46.44
transport_amount 物流费 float 23.22
product_amount 商品价格 float 23.22

若要身份验证则需要填以下参数

参数 说明 是否必填 类型 示例
cert_id 身份证号 String 510921199308772318
name 姓名 String Lisa

注意:应付金额=物流费+商品费

返回结果如下:

参数 说明
out_order_no 商户订单号
payment_no HipoPay支付单号
customs 海关编号
wechatpay_no 微信支付单据号
state UNDECLARED – 未申报
SUBMITTED – 申报已提交(订单已经送海关,商户重新申报,并且海关还有修改接口,那么记录的状态会是这个)
PROCESSING – 申报中
SUCCESS – 申报成功
FAIL– 申报失败
EXCEPT –海关接口异常
modify_time 最后修改时间

若拆单会返回以下参数

参数 说明
sub_order_no 商户子订单号
sub_order_amount 子订单金额
transport_amount 物流费
product_amount 商品价格

若进行身份验证会返回以下结果

参数 说明
cert_check_result 身份验证结果:
UNCHECKED 商户未上传订购人身份信息
SAME 商户上传的订购人身份信息与支付人身份信息一致
DIFFERENT 商户上传的订购人身份信息与支付人身份信息不一致

13.2 / 微信重推报关

POST /wechatpay/redeclaration

以下三个请求参数三选一,若拆单则传sub_order_no,若未拆单则传payment_no或out_order_no

参数 说明 是否必填 类型 示例
payment_no HipoPay订单号 String 2018051716124
out_order_no 商户订单号 String 18051893975650968
sub_order_no 子订单号 String 20180518939756968

以下两个参数必填

参数 说明 是否必填 类型 示例
customs 海关编号 String SHENZHEN
mch_customs_no 商户海关备案号 String 123456789BTW

返回结果如下:

参数 说明
out_order_no 商户订单号
payment_no HipoPay支付单号
customs 海关编号
wechatpay_no 微信支付单据号
state UNDECLARED – 未申报
SUBMITTED – 申报已提交(订单已经送海关,商户重新申报,并且海关还有修改接口,那么记录的状态会是这个)
PROCESSING – 申报中
SUCCESS – 申报成功
FAIL– 申报失败
EXCEPT –海关接口异常
modify_time 最后修改时间
explanation 申报结果说明(若申报失败此项返回失败原因)

13.3 / 微信支付报关查询

GET /wechatpay/declaration

以下三个请求参数三选一,若拆单则传sub_order_no,若未拆单则传payment_no或out_order_no

参数 说明 是否必填 类型 示例
payment_no HipoPay订单号 String 2018051816320384498567689
out_order_no 商户订单号 String 1805123918160384498567689
sub_order_no 子订单号 String 18051816320384338567689
customs 海关 String BEIJING

返回结果如下:

参数 说明
out_order_no 商户订单号
payment_no HipoPay支付单号
customs 海关编号
wechatpay_no 微信支付单据号
state UNDECLARED – 未申报
SUBMITTED – 申报已提交(订单已经送海关,商户重新申报,并且海关还有修改接口,那么记录的状态会是这个)
PROCESSING – 申报中
SUCCESS – 申报成功
FAIL– 申报失败
EXCEPT –海关接口异常
modify_time 最后修改时间

若拆单会返回以下参数

参数 说明
sub_order_no 商户子订单号
sub_order_amount 子订单金额
transport_amount 物流费
product_amount 商品价格

若进行身份验证会返回以下结果

参数 说明
cert_check_result 身份验证结果:
UNCHECKED 商户未上传订购人身份信息
SAME 商户上传的订购人身份信息与支付人身份信息一致
DIFFERENT 商户上传的订购人身份信息与支付人身份信息不一致

13.4 / 支付宝报关

POST /alipay/declaration
参数 说明 是否必填 类型 示例
out_order_no 商户订单号 String 180518939756568
payment_no HipoPay支付单号 String 20180518163203
customs 海关编号(如:SHENZHEN) String SHENZHEN
mch_customs_no 商户海关备案号 String 123456789BTW
merchant_customs_name 商户海关备名称 String xxxhanguo_card

若拆单则需要填以下参数

参数 说明 是否必填 类型 示例
sub_order_no 商户子订单号 String 2018051716124
sub_order_amount 子订单金额 float 46.44

若要身份验证则需要填以下参数

参数 说明 是否必填 类型 示例
cert_id 身份证号 String 510921199308772318
name 姓名 String Lisa

返回结果如下:

参数 说明
out_order_no 商户订单号
payment_no HipoPay支付单号
customs 海关编号
alipay_no 支付宝支付单据号
state “SUCCESS” 成功
modify_time 最后修改时间

若拆单会返回以下参数

参数 说明
sub_order_no 商户子订单号
sub_order_amount 子订单金额

若进行身份验证会返回以下结果

参数 说明
cert_check_result 身份验证结果:
T表示商户传入的订购人姓名和身份证号和支付人的姓名和身份证号一致。
F代表商户传入的订购人姓名和身份证号和支付人的姓名和身份证号不一致。

13.5 / 支付宝重推报关

POST /alipay/redeclaration

以下三个订单号三选一,若拆单则传sub_order_no,若未拆单则传payment_no或out_order_no

参数 说明 是否必填 类型 示例
payment_no HipoPay订单号 String 20180518184498567689
out_order_no 商户订单号 String 18051893975650968
sub_order_no 子订单号 String 18051893315650968
customs 海关编号(如:SHENZHEN) String SHENZHEN
mch_customs_no 商户海关备案号 String 123456789BTW
merchant_customs_name 商户海关备名称 String xxxhanguo_card

若拆单则需要填以下参数

参数 说明 是否必填 类型 示例
sub_order_no 商户子订单号 String 2018051716124
sub_order_amount 子订单金额 float 46.44

若要身份验证则需要填以下参数

参数 说明 是否必填 类型 示例
cert_id 身份证号 String 510921199308772318
name 姓名 String Lisa

返回结果如下:

参数 说明
out_order_no 商户订单号
payment_no HipoPay支付单号
customs 海关编号
alipay_no 支付宝支付单据号
state “SUCCESS” 成功
modify_time 最后修改时间

若拆单会返回以下参数

参数 说明
sub_order_no 商户子订单号
sub_order_amount 子订单金额

若进行身份验证会返回以下结果

参数 说明
cert_check_result 身份验证结果:
T表示商户传入的订购人姓名和身份证号和支付人的姓名和身份证号一致。
F代表商户传入的订购人姓名和身份证号和支付人的姓名和身份证号不一致。

13.6 / 支付宝报关查询

GET /alipay/declaration

以下三个订单号三选一,若拆单则传sub_order_no,若未拆单则传payment_no或out_order_no

参数 说明 是否必填 类型 示例
payment_no HipoPay订单号 String 201805181632038449
out_order_no 商户订单号 String 180512391816038449
sub_order_no 子订单号 String 18051816320384338

若拆单则需要填以下参数

参数 说明 是否必填 类型 示例
sub_order_no 商户子订单号 String 2018051716124
sub_order_amount 子订单金额 float 46.44

若要身份验证则需要填以下参数

参数 说明 是否必填 类型 示例
cert_id 身份证号 String 510921199308772318
name 姓名 String Lisa

返回结果如下:

参数 说明
out_order_no 商户订单号
payment_no HipoPay支付单号
customs 海关编号
alipay_no 支付宝支付单据号
state “SUCCESS” 成功
modify_time 最后修改时间

若拆单会返回以下参数

参数 说明
sub_order_no 商户子订单号
sub_order_amount 子订单金额

若进行身份验证会返回以下结果

参数 说明
cert_check_result 身份验证结果:
T表示商户传入的订购人姓名和身份证号和支付人的姓名和身份证号一致。
F代表商户传入的订购人姓名和身份证号和支付人的姓名和身份证号不一致。

14 / 支付通知

14.1 / 通知规则

14.2 / 通知内容

字段 说明
status 订单状态,INIT :等待付款;PAID :支付成功;FAIL :支付失败; EXPIRED: 订单失效
openid openID
trade_type 交易类型
exchange_rate 汇率,汇率的语义是:一个外币 = 多少个人民币
no 订单编号
currency 币种
amount 金额
trade_time 交易时间
pay_currency 支付币种
pay_amount 支付金额
agent_order_id 渠道商的订单编号

Response

{
    "status": "PAID",
    "openid": "oQx43wJiwtsjv8C0lT5Lj7Mw1QZ4",
    "trade_type": "JSAPI",
    "exchange_rate": "0.8777",
    "no": "xxxx",
    "currency": "HKD",
    "amount": "1",
    "trade_time": "2017-06-22 21:29:47",
    "pay_currency": "CNY",
    "pay_amount": "0.87",
    "agent_order_id": "xxxx"
}

14.3 / 验签

签名规则如下:

  1. 将POST请求的form内容按照参数名ASCII码从小到大排序(字典序),然后使用URL键值对的格式(即key1=value1&key2=value2…)拼接成签名字符串。
  2. 在签名字符串后面拼接上header中的Timestamp,用’,‘隔开,得到query_string。
  3. 将query_string以及header中的Signature用SHA256验签。
  4. 公钥请联系 HipoPay获取。

15 / 附录

15.1 / 支付订单数据结构说明

字段 说明
no 订单编号
merchant_no 商户编号
currency 币种,支持的币种请见15.3/货币编码
amount 金额
exchange_rate 汇率,汇率的语义是:一个外币 = 多少个人民币
device_info 设备信息
product_info 商品描述
ip 收银终端IP
product_id 商品ID
trade_type 交易类型
trade_time 交易时间
agent_order_id 渠道商的订单编号
status 订单状态,INIT :等待付款;PAID :支付成功;FAIL :支付失败; EXPIRED: 订单失效
pay_method 支付方式
refund_status 退款状态,NONE :未退款;PART :部分退款;FULL :全部退款
refundable_amount 可退款金额

15.2 / 退款单数据结构说明

字段 说明
no 退款单编号
order_no 支付订单编号
outer_refund_no 外部退款单号
refund_amount 退款金额
status 退款单状态

15.3 / 货币编码

名称 三位编码
人民币 CNY
英镑 GBP
港币 HKD
美元 USD
日元 JPY
加拿大元 CAD
澳元 AUD
欧元 EUR
新西兰元 NZD
韩元 KRW
泰铢 THB

15.4 / 微信海关编码

海关编码 海关名称
GUANGZHOU_ZS 广州(总署版)
GUANGZHOU_HP_GJ 广州黄埔国检(需推送订单至黄埔国检的订单需分别推送广州(总署版)和广州黄埔国检,即需要请求两次报关接口)
GUANGZHOU_NS_GJ 广州南沙国检(需推送订单至南沙国检的订单需分别推送广州(总署版)和广州南沙国检,即需要请求两次报关接口)
HANGZHOU_ZS 杭州(总署版)
NINGBO 宁波
ZHENGZHOU_BS 郑州(保税物流中心)
CHONGQING 重庆
XIAN 西安
SHANGHAI_ZS 上海(总署版)
SHENZHEN 深圳
ZHENGZHOU_ZH_ZS 郑州综保(总署版)
TIANJIN 天津
BEIJING 北京

15.5 / 支付宝海关编码

海关名称 统一版各属地报关方案 海关编码
杭州海关 推送HANGZHOU_ZONGSHU HANGZHOU_ZONGSHU
广州海关 推送ZONGSHU ZONGSHU
河南保税物流中心 推送ZHENGZHOU ZHENGZHOU
新郑综合保税区(空港) 先推送HENAN报送地方国检,再推送ZONGSHU HENAN,ZONGSHU
宁波海关 推送NINGBO NINGBO
重庆海关 推送ZONGSHU ZONGSHU
深圳海关 先推送SHENZHEN_ZS报送地方国检,再推送ZONGSHU SHENZHEN_ZS,ZONGSHU
上海海关 推送SHANGHAI_CBT SHANGHAI_CBT
西安海关 推送ZONGSHU ZONGSHU
南沙国检 推送NANSHAGJ NANSHAGJ
天津海关 推送ZONGSHU ZONGSHU
合肥海关 推送ZONGSHU ZONGSHU
苏州海关 推送ZONGSHU ZONGSHU
广州黄埔海关 推送GUANGZHOU_HUANGPU GUANGZHOU_HUANGPU

15.6 / SDK和示例代码

http://s.transfereasy.com/wc/document/WiseCashier%20Java%20SDK.zip

http://s.transfereasy.com/wc/document/Signature.cs