1. Description of The Document
1.2. Global Planning
-
Server address: https://api.payingcloud.cn
-
Data Format: json
-
The asynchronous notification interface must return "success" when it was completed.
1.3. Signature Rules
HTTP requests should add a Authorization' Header to include ‘Signature’that the message has been authorized.
HmacUtils.hmacSha1Hex( (1)
key, (2)
verb + "\n" + (3) (4)
resource + "\n" + (5)
body + "\n" + (6)
timestamp + "\n"); (7)
1 | Using hmacSha1 algorithm to get the M-16. |
2 | key——Signature required keys that is generated in the console. |
3 | verb——HTTP request Method that include PUT, GET, POST, HEAD, DELETE. |
4 | \n——newline |
5 | resource——Stitching parameter string is used for the request interface. path+?+query |
6 | body——Content of the request body |
7 | timestamp——Said the operation time, and must be in GMT format,like "Sun, 22 Nov 2015 08:16:38 GMT". This timestamp will also be added to * Header *,and the key is * Date *. |
The signature body of the HttpMethod without the request body is represented by an empty string.
HmacUtils.hmacSha1Hex("3zKciJOwhWE4SSRUxXzCsABcIhJWd5Gb",
"POST" + "\n" +
"/charges?a=a&b=b&c=c" + "\n" +
"{"a":"a","b":"b","c":"c"}" + "\n" +
"Sun, 22 Nov 2015 08:16:38 GMT" + "\n"
Add your signature to accessKeyId,then base64 encoding.Add the result to the Basic+blank to compose Authorization.
"Basic " + Base64.encodeBase64String((accessKeyId + ":" + signature).getBytes()));
Content-Type:application/json; charset=UTF-8
Authorization:Basic NTgzMTM1NDZlZjE5MGM1MWMwYmVhYzZmOjA2NzY2NTUwMzdhOTQyZDc5M2JjOGM5YzRmNzE5M2QzZTRhYjY5YjE=
Date:Tue, 13 Dec 2016 03:22:13 GMT
1.4. Checking Steps
In order to prevent damage caused by hackers fake transaction results,all asynchronous notification using RSA signatures were sent to the merchant.And put the signature with Base64 encoding in Http request headers kbd: [sign].Developers need to use SHA1WithRSA algorithm and IBS provides RSA public key to validate it.
// Gets a signature from asynchronous notification request headers.
String sign = request.getHeader("sign");
// Using base64 decoding the signature String to bytes.
byte[] signBytes = Base64.decodeBase64(sign)
//Gets the asynchronous notification request body.
String content = ...
// Using UTF-8 character to decode the request body.
byte[] contentBytes = content.getBytes("UTF-8")
// SHA1WithRSA algorithm is used to validate it.
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
byte[] encodedKey = Base64.decodeBase64(PayingCloud.DEFAULT_PUBLIC_KEY); // 使用PayingCloud提供的RSA公钥
PublicKey key = keyFactory.generatePublic(new X509EncodedKeySpec(encodedKey));
Signature signature = Signature.getInstance("SHA1WithRSA"); // 验签算法SHA1WithRSA
signature.initVerify(key);
signature.update(contentBytes);
return signature.verify(signBytes);
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCPymtLbRkHgvVfUT933LrwWns6YZHLPpT1pP9TKJ+cgIZiQwZ4mtqoqPHSVtiT5HA8fwFzWuJ/6qWaQhER7TOISUFUHZlHyBjNK/Z5px6PNB7rT4OrLP0KuZ7nuX5qdnOKuAbrj1MBLSinOHQ8tDJhPrPKxuZlKw3SeL5auHlKWwIDAQAB
2. OPEN API
2.1. Payment Interface
2.1.3. Request Parameters
Parameters | Required | Type | Example | Description |
---|---|---|---|---|
mer_order_no |
Yes |
String(32) |
20150806125346 |
Vendor Order Number,Lengths from 4 to 32 characters. |
subject |
Yes |
String(128) |
iPhone7-32G |
Item Details |
total |
Yes |
Int |
888 |
The total amount charged or refunded. The units are expressed in cents and must be an integer. |
currency |
Yes |
String(16) |
GBP |
ISO-4217 standard compliant and be described by three characters based code. For more information, see Currency Type Form. |
channel |
YES |
Enum |
UMF_CREDIT_CARD |
Channel Type. For more information, see Channel Type. |
external_customer_id |
NO |
String |
oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
The customer unique id in merchant system.Lengths from 1 to 32 characters. |
user_ip |
YES |
String(16) |
123.12.12.123 |
This is the IP address when a customer makes a payment request. |
extra |
YES |
Map<String, Object> |
{"returnUrl": "https://api.payingcloud.cn/returnUrl"} |
Channel Extra Parameters.Map of key-value pairs store between the different channels of Channel Extra Parameters. |
notifyUrl |
YES |
String(100) |
https://api.payingcloud.cn/callback |
Specifies the callback address for receiving payment notifications. |
3. Remark
3.1. Channel Type
Name | Description |
---|---|
UMF_CREDIT_CARD |
UMF_Pay by credit card. |
UMF_DEBIT_CARD |
UMF_ Pay by debit card. |
UMF_WECHAT_SCAN |
UMF return a QR-Code String. The customer may use their WeChat scan the QR-Code to pay. |
UMF_WECHAT_WEB |
UMF_The customer may pay for the order inside the WeChat browser. |
UMF_WECHAT_IN_APP |
UMF_The customer may pay for the order inside a native app. |
UMF_ALIPAY_SCAN |
UMF returns a QR-Code String. The customer may use their Alipay to scan the QR-Code to pay. |
WX_CODE |
The Vendor generates a transaction QR Code according to the WeChat Payment Protocol and the Payer goes to "Scan QR Code" in their WeChat in order to complete payment. |
WX_APP |
In-App payment also refers to a mobile-based payment in which the Vendor calls the WeChat payment module by using the open SDK integrated in their mobile-based app to pay for transactions. |
WX_JSAPI |
The Payer opens the Vendor’s HTML5 pages on their WeChat and calls the WeChat payment module via the JSAPI interface to pay their transaction. |
3.2. Transaction Credential Sample
"url":"<form name=\"punchout_form\"method=\"post\" action=\"https://pay.yizhifubj.com/prs/user_payment.checkit?v_md5info=b00a57dc732366cbfed3da03fe064af5&v_orderstatus=1&v_rcvname=9466&v_moneytype=0&v_oid=20161222-9466-585b77b5ab5c986f049a0faa&v_ymd=20161222&v_url=http%3A%2F%2F127.0.0.1%3A9000%2Forder%2Fcharge%2Freturn&v_rcvaddr=9466&v_ordername=9466&v_rcvtel=9466&v_mid=9466&v_amount=0.01&v_rcvpost=9466\">\n<input type=\"submit\" value=\"[0xe7][0xab][0x8b][0xe5][0x8d][0xb3][0xe6][0x94][0xaf][0xe4][0xbb][0x98]\" style=\"display:none\" >\n</form>\n<script>document.forms[0].submit();</script>"
3.3. Transaction Credential Details
-
BDPAY_WEB
-
BDPAY_WAP
-
Get: url from credentials
-
servletResponse.sendRedirect(charge.getCredentials().get("url"));
-
ALIPAY_DIRECT
-
BJPAY_WEB
-
CHINAPAY_WEB
-
JDPAY_WEB
-
JDPAY_WAP
-
YEEPAY_WAP
-
ALIPAY_WAP
-
Get html(utf-8) from credentials
-
servletResponse.setContentType("text/html;charset=UTF-8");
servletResponse.getWriter().write(charge.getCredentials().get("html"));
-
YEEPAY_WEB
-
Get html(gbk) from credentials
-
servletResponse.setContentType("text/html;charset=gbk");
servletResponse.getWriter().write(charge.getCredentials().get("html"));
-
BDPAY_QR
-
Get url from credentials
-
-
WXPAY_NATIVE
-
BJPAY_WX
-
ALIPAY_QR
-
KFTPAY_WX
-
KFTPAY_ALI
-
JDPAY_QR
-
CMBCPAY_T0_ALI
-
CMBCPAY_T1_ALI
-
CMBCPAY_T0_WX_QR
-
CMBCPAY_T1_WX_QR
-
CMBCPAY_T0_QQ
-
CMBCPAY_T1_QQ
-
WEBANKPAY_WX_QR
-
Get codeUrl from credentials
-
-
WXPAY_JSAPI
-
CMBCPAY_T0_WX_JSAPI
-
CMBCPAY_T1_WX_JSAPI
-
WEBANKPAY_WX_JSAPI
-
Get form credentials:
-
appId
-
timeStamp
-
nonceStr
-
package
-
signType
-
paySign
-
-
3.4. Channel Extra Parameters
Parameter | Required | Description | Constraints |
---|---|---|---|
sub_orders |
YES |
Each sub_order can only have same type goods. |
Object Array.For more information, see sub_order. |
goods_type |
YES |
Category of commodities |
ENUM:0 virtual goods;1 physical goods |
receiver_name |
YES |
Name of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
receiver_moblie_id |
YES |
Phone number of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
shipping_address |
YES |
Address of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
real_name |
YES |
Real name purchase |
ENUM.0 not real name system ;1 real name system |
phone |
YES |
The phone number registered in the bank card issuer. |
String |
card_holder |
YES |
The name of card holder. |
String |
citizen_id_number |
YES |
Citizen id number. |
String |
bank_code |
YES |
The abbreviation of bank. |
String. |
number |
YES |
The card number. |
String |
valid_date |
YES |
The valid date of bank card. |
String |
cvv2 |
YES |
CVV2 of bank card. |
String |
Parameter | Required | Description | Constraints |
---|---|---|---|
sub_orders |
YES |
Each sub_order can only have same type goods. |
Object Array.For more information, see sub_order. |
goods_type |
YES |
Category of commodities |
ENUM:0 virtual goods;1 physical goods |
receiver_name |
YES |
Name of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
receiver_moblie_id |
YES |
Phone number of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
shipping_address |
YES |
Address of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
real_name |
YES |
Real name purchase |
ENUM.0 not real name system ;1 real name system |
phone |
YES |
The phone number registered in the bank card issuer. |
String |
card_holder |
YES |
The name of card holder. |
String |
citizen_id_number |
YES |
Citizen id number. |
String |
bank_code |
YES |
The abbreviation of bank. |
String. |
number |
YES |
The card number. |
String |
Parameter | Required | Description | Constraints |
---|---|---|---|
sub_orders |
YES |
Each sub_order can only have same type goods. |
Object Array.For more information, see sub_order. |
goods_type |
YES |
Category of commodities |
ENUM:0 virtual goods;1 physical goods |
receiver_name |
YES |
Name of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
receiver_moblie_id |
YES |
Phone number of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
shipping_address |
YES |
Address of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
real_name |
YES |
Real name purchase |
ENUM.0 not real name system ;1 real name system |
phone |
YES |
The payer’s phone number. |
String |
name |
YES |
The name of payer. |
String |
citizen_id_number |
YES |
Citizen id number. |
String |
open_id |
YES |
The OpenID is a unique encrypted WeChat ID for each user of an official account, and users can have separate OpenIDs corresponding to different official accounts. |
String. |
Parameter | Required | Description | Constraints |
---|---|---|---|
sub_orders |
YES |
Each sub_order can only have same type goods. |
Object Array.For more information, see sub_order. |
goods_type |
YES |
Category of commodities |
ENUM:0 virtual goods;1 physical goods |
receiver_name |
YES |
Name of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
receiver_moblie_id |
YES |
Phone number of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
shipping_address |
YES |
Address of the recipient |
String.When goods_type is either 1 , it is required to send this field. |
real_name |
YES |
Real name purchase |
ENUM.0 not real name system ;1 real name system |
phone |
YES |
The payer’s phone number. |
String |
name |
YES |
The name of payer. |
String |
citizen_id_number |
YES |
Citizen id number. |
String |
Parameter | Required | Description | Constraints |
---|---|---|---|
mer_sub_reference_id |
YES |
The ID of sub_order object. |
Lengths from 4 to 16 characters. |
sub_total |
YES |
The amount of sub_order. |
Maximum length is 12 digits including 2 decimal places. |
rans_code |
YES |
The transaction code of goods. |
ENUM |
is_customs |
YES |
If the merchant needs UMF to submit the payment information to customs. |
TRUE FALSE |
invoice_id |
YES |
This receipt of sub_order. |
Lengths from 1 to 20 characters. |
mer_item_id |
YES |
The ID in merchant system. |
Lengths from 1 to 32 characters. |
type |
YES |
The type of goods. |
ENUM |
name |
NO |
The goods name. |
Lengths from 1 to 256 characters. |
description |
NO |
The description of goods. |
Lengths from 1 to 64 characters. |
mer_total |
YES |
The amount object. The price of goods. |
Maximum length is 12 digits including 2 decimal places. |
quantity |
YES |
Number. The quantity of goods. |
Maximum length is 2 |
Parameter |
Required |
Type |
Example |
Description |
attach |
NO |
String(128) |
Additional description |
Allow vendors an additional field to be returned in the payment notification after submitting a payment to the Query Order API. |
detail |
NO |
String(6000 |
{ "goods_id":"iphone6s_32G", "wxpay_goods_id":"1002", "goods_name":"iPhone6s 32G", "quantity":1,"price":608800, "goods_category":"123789", "body":"iPhones" } |
Detailed product list described in JSON format. |
goods_tag |
NO |
String(32) |
WXG |
Specifies the label of goods, which is a parameter in the coupon feature for businesses. |
product_id |
NO |
String(32) |
1.22354E+22 |
This field is only required when trade_type is NATIVE. This ID contains the product ID as set by the Vendor. |
3.5. Currency Type Form
Parameter Name | Description |
---|---|
GBP |
Great Britain pound |
HKD |
Hong Kong dollar |
USD |
United States dollar |
JPY |
Japanese yen |
CAD |
Canadian dollar |
AUD |
Australian dollar |
EUR |
Euro |
NZD |
New Zealand Dollar |
KRW |
South Korean won |
THB |
Thailand baht |
Notes: The currency type for payment and refund must be identical.