5.5 KiB

Raw Blame History Unescape Escape

Overview

域名

生产环境

https://mpay.royalpay.com.au/

请求方式和参数格式

支付单和退款单提交均为PUT方式，订单查询均为GET方式；包含Request Entity的请求参数格式为json

除跳转页面外，所有的Accept均为application/json；所有的PUT/POST请求Content-Type为application/json

系统使用UTF-8字符集

参数分为三种：Path Variable/Query Param/JSON entity

PathVariable:包含在URI内的参数
Query Param:在URI末尾?后的key=value形式的参数
JSON entity:只在PUT/POST请求中使用

所有返回JSON的API，成功访问返回状态值均为200（不论执行结果）。JSON固定包含字段return_code，若值为SUCCESS则表示执行成功；其他值表示执行失败，此时可查询错误码了解对应的错误类型，此时还会携带return_msg字段作为错误描述信息

多语言支持

系统错误提示支持中文、英文两种语言，默认根据Request Header中的Accept-Language值自动选择，如需调整亦可以添加locale cookie进行指定。

选择接入API

支付宝渠道区分

支付宝根据调用接口不同分为线上和线下两个渠道，两个渠道分别使用不同的汇率和手续费费率，为避免混淆在此区分：

线上渠道：包含H5 Mobile、Web支付、APP SDK、JSAPI、QR Code 5种支付方式
线下渠道：Retail Pay 支付方式

相似接口区别

JSAPI和H5 Mobile：JSAPI只能在支付宝客户端内访问的页面调起支付，H5可以在移动设备任意浏览器或App的WebView调起支付
Web支付和QR Code: Web支付会跳转到支付宝官方收银台，用户可以选择登陆账号或用客户端扫码完成支付；QR Code方式商户可以自行展示创建的二维码，也可以跳转到RoyalPay展示的收银台页面显示二维码，用户只能用支付宝客户端扫码完成支付。

签名算法

每次请求都必须加入签名信息作为请求校验。校验参数全部以Query Param参数的方式附加在URL后面，顺序不分先后。

签名过程：

连接生成签名的原始字符串，需要4个参数，使用&连接，无需转码

valid_string=partner_code&time&nonce_str&credential_code

参数说明：

partner_code:商户编码，由4位大写字母或数字构成
time:UTC毫秒时间戳，取当前UTC时间的毫秒数时间戳，Long类型，5分钟内有效
nonce_str:随机字符串，无长度限制，请使用URL安全字符（避开&,=等符号），请注意HTTP URL的最大长度限制，建议长度在10到30位
credential_code:系统为商户分配的开发校验码，请妥善保管，不要在公开场合泄露

使用SHA256进行签名，并转为Hex小写字符串

sign=hex(sha256(valid_string)).toLowerCase()

在请求中把签名使用的time,nonce_str和生成的sign一同作为Query Param参数发送

案例

valid_string=RPAY&1468691301081&aaf2a94c8c2d56d5b43a1a3d9d811102&pQ5Jc9eoTcsxqPY5uQ3p2WmvSy0zEYeP sign=64712672795f94fa3bfb2e88ac09cb75d09bcf8a3c3dcaa529d8290dd6587060

测试地址：https://mpay.royalpay.com.au/sign_test.html

币种代码

由于微信端限制原因，RoyalPay只接受人民币和澳元两个币种的支付订单

AUD:澳元
CNY:人民币

业务规则

QRCode支付是在网页上展示二维码，用户使用微信扫一扫扫码后直接进入微信支付页面，适用于商城类web网站；
JSAPI支付是在微信浏览器内直接跳转到RoyalPay让用户选择支付订单，页面只能在微信客户端打开，适用于微店；
创建订单时需要提供订单号，同一个订单允许重复提交，系统会自动根据订单状态判断是否创建新订单并关闭旧订单。因此商户端应该同一个订单只用一个单号，避免重复付款；
由于存在自动创建新订单机制，创建订单后返回的RoyalPay单号不代表最终支付的单号；
QRCode支付订单创建后会直接返回QRCode和pay_url，商户可以自行选择展示支付二维码或跳转至RoyalPay支付页；
JSAPI支付订单创建后会返回pay_url，商户应该跳转到这个地址让用户完成支付；
跳转pay_url时必须加上签名信息；
每次请求都应该生成新的签名；
订单成功支付后会调用订单中提供的notify_url，详情可以查看API定义；若创建订单时未提供，商户需要在创建订单后轮询订单状态接口，直到订单被支付或过期；
订单支付有效期为5分钟，超时可以用相同的订单号重新发起请求，建议重新发起请求的时机为用户再次打开支付页的时候；
使用跳转支付页前应该先调用后台服务输入金额等参数创建订单后再跳转；
创建订单、创建退款接口都允许同订单号重复调用，但是具体参数以初次请求的参数为准；
所有和金额相关的数字均以货币最小面值为单位，以AUD为例，100表示AUD 1.00。

案例

https://example.royalpay.com.au/api/payment/order

5.5 KiB Raw Blame History Unescape Escape