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

1 / 简介

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

2 / 认证

Request

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

所有的请求都要在 header 中加上四个参数:

先准备公钥和私钥

2.1 / AgentNO

由WiseCashier分配

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.7 / 查询支付单

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,订单数据结构详情见 附录10.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.5 / 查询支付单 order_no在第三步中获得

4.5 / APP支付

4.5.1 / 说明

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

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

注册地址:微信开放平台

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

4.5.3 / 集成

共三个步骤:

第一步 / 请求预支付接口

POST /order/app_pay

Response

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

    "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"
    },
    "prepay_params": {
        "timeStamp": "1509692687",
        "appid": "2619692747",
        "prepayId": "20180210XXXXXXXXX",
        "PartnerId": "wc1312341312312",
        "packageValue": "Sign=WXPay",
        "nonceStr": "casd135Defg",
        "sign": "55511808baf7f301b5270d7334a4cec0",
        }
 }


参数 说明 是否必填
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.7/ 查询支付单(或9 / 异步通知)获取订单准确的支付状态。

4.6 / 退款

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 外部退款单号

如果不传入退款金额参数,则全额退款。 返回结果为退款信息,退款数据结构详情见 附录10.2

4.7 / 查询支付单

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.8 / 查询退款单

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.9 / 查询汇率

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 币种,支持的币种请见附录6.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)或异步通知(13.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 币种,支持的币种请见附录6.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 查询支付单或异步通知(13.1)获取到的结果为最终付款成功的依据。

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 币种,支持的币种请见附录6.3
amount 金额
exchange_rate 汇率,汇率的语义是:一个外币 = 多少个人民币
subject 商品描述
product_info 商品描述
trade_type 交易类型
trade_time 交易时间
out_order_no 服务商内部单号
status 订单状态,INIT :等待付款;PAID :支付成功;FAIL :支付失败; EXPIRED: 订单失效
pay_method 支付方式

6.4 / 查询支付单

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 币种,支持的币种请见附录6.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.5 / 退款

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.6 / 查询退款

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.7 / 查询汇率

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 币种,支持的币种请见附录6.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 币种,支持的币种请见附录6.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 / 辅助接口

8.1 / 微信支付报关

POST /wechatpay/declaration
参数 说明 是否必填
out_order_no 商户订单号
payment_no Wisecashier支付单号
customs 海关编号(如:SHENZHEN)
mch_customs_no 商户海关备案号
sub_order_no 商户子订单号(如需拆单,则必传此参数)
sub_order_amount 应付金额(如需拆单,则必传此参数)
transport_amount 物流费(如需拆单,则必传此参数)
product_amount 商品价格(如需拆单,则必传此参数)

返回结果如下:

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

8.2 / 微信支付报关查询

GET /wechatpay/declaration
参数 说明 是否必填
out_order_no 商户订单号
payment_no Wisecashier支付单号

返回结果如下:

参数 说明
out_order_no 商户订单号
payment_no Wisecashier支付单号
customs 海关编号
state UNDECLARED – 未申报
SUBMITTED – 申报已提交(订单已经送海关,商户重新申报,并且海关还有修改接口,那么记录的状态会是这个)
PROCESSING – 申报中
SUCCESS – 申报成功
FAIL– 申报失败
EXCEPT –海关接口异常
sub_order_no 商户子订单号(如进行拆单,则有此返回值)
sub_order_amount 应付金额(如进行拆单,则有此返回值)
transport_amount 物流费(如进行拆单,则有此返回值)
product_amount 商品价格(如进行拆单,则有此返回值)

8.3 / 支付宝报关

POST /alipay/declaration
参数 说明 是否必填
out_order_no 商户订单号
payment_no Wisecashier支付单号
customs 海关编号(如:SHENZHEN)
mch_customs_no 商户海关备案号
merchant_customs_name 商户海关备案名称
sub_order_no 商户子订单号(如需拆单,则必传此参数)
sub_order_amount 应付金额(如需拆单,则必传此参数)

返回结果如下:

参数 说明
out_order_no 商户订单号
payment_no Wisecashier支付单号
customs 海关编号
state “SUCCESS” 成功 “FAIL” 失败
err_detail state 为“FAIL”时会有返回,描述失败原因

8.4 / 支付宝报关查询

GET /alipay/declaration
参数 说明 是否必填
out_order_no 商户订单号
payment_no Wisecashier支付单号
参数 说明
out_order_no 商户订单号
payment_no Wisecashier支付单号
customs 海关编号
state “SUCCESS” 成功 “FAIL” 失败
err_detail state 为“FAIL”时会有返回,描述失败原因
sub_order_no 商户子订单号(如进行拆单,则有此返回值)
sub_order_amount 应付金额(如进行拆单,则有此返回值)

9 / 支付通知

9.1 / 通知规则

9.2 / 通知内容

字段 说明
status 订单状态,通知时次状态只会是PAID(支付成功)
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"
}

9.3 / 验签

签名规则如下:

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

10 / 附录

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

字段 说明
no 订单编号
merchant_no 商户编号
currency 币种,支持的币种请见附录6.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 可退款金额

10.2 / 退款单数据结构说明

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

10.3 / 货币编码

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

10.4 / 微信海关编码

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

10.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

10.6 / SDK和示例代码

11 / 帮助