HTML5 Integration Specification.md 11 KB
HTML5 Integration Specification V4.2.1
Shanghai AllPay Technology Co., Ltd.
- Version:English V4.2.0
- Update Time:April 2018
1.Overview
AllPay provides customers with unified API access to help them implement fast, secure and centralized access payment channels.
2.General API specification
Common interface between merchant server and AllPay gateway, each channel has functions including: Purchase, Refund, Inqiury interface.
3. Signature
2.1. Signature String and Calculated the Signature
1.For a POST request message sent to the ALLPAY system, in which all incoming parameters (except signature parameters) according to the field name of ASCII smallest sequence (dictionary), using the format of the URL key/value pair (key1 = value1 & key2 = value2... ) spliced into a string String1.
2.At the end of String1, the signature key K1(assigned at ALLPAY upon access) agreed by both parties is spliced directly (no need to connect with "&"), resulting in a stringSignTemp string, and an md5 operation on stringSignTemp to get the value of signature.
3.Sample signature string:acqID=99020344&backURL=https://www.baidu.com&charSet=UTF-8&frontURL=nil&goodsInfo=iPhone x&merID=800039253992510&merReserve=&orderAmount=1.00&orderCurrency=INR&orderNum=ap0180417163142&paymentSchema=EB&signType=MD5&transTime=20180417163142&transType=PURC&trxn_email_id=benson.zhang@allpayx.com&trxn_firstname=benson zhang&trxn_is_coupon_enabled=1&trxn_phone=15026528888&unique_id=abcde12345&version=VER000000002f3e0e436cd24430aa4aaaed597450f26
2.2. General API access address
| Transaction Type | Test URL | Production URL |
|---|---|---|
| Purchase | https://mchapi.allpayx.com/testjspay | https://mchapi.allpayx.com/jspay |
| Inquiry | https://testapi.allpayx.com/pay/v1 | https://api.allpayx.com/pay/v1 |
| Refund | https://testapi.allpayx.com/pay/v1 | https://api.allpayx.com/pay/v1 |
3. API Interface
3.1. Purchase interface
Merchant could use purchase interface to initiate a transaction, send transaction information to payment channels through AllPay gateway.
| No. | Field Name | Max.Length | Type | Parameter Name | Comment |
|---|---|---|---|---|---|
| 1 | Message Version | 12 | Text | version | "VER000000002" |
| 2 | Character set coding | 6 | Text | charSet | "UTF-8" |
| 3 | Transaction type | 4 | Text | transType | "PURC" |
| 4 | Order Number | 60 | Text | orderNum | The merchant shall define it by itself, and the order number of the same merchant number shall not be repeated |
| 5 | Order Amount | 12 | Text | orderAmount | 100 is displayed as 100 or 100.00 |
| 6 | Order Currency | 3 | Text | orderCurrency | Fill in "CNY" in RMB and "USD" in USD |
| 7 | Frontend URL Address | 400 | Text | frontURL | Payment results are notified to this address front |
| 8 | Backend URL Address | 400 | Text | backURL | Payment results are notified to this address asynchronously |
| 9 | Merchant Reserved | 1024 | Text | merReserve | Merchant reserved content, can pass any content, such as purchase information, account number, etc., but do not pass special symbols, such as commas. |
| 10 | Merchant ID | 15 | Text | merID | Merchant ID, assigned by AllPay |
| 11 | Acquirer ID | 11 | Text | acqID | "99020344" |
| 12 | Payment Channel Code | 10 | Text | paymentSchema | UnionPay:"UP",Wechat:"WX,Alipay:"APMP" |
| 13 | Goods Information | 60 | Text | goodsInfo | Goods Information |
| 14 | Transaction Time | 14 | Text | transTime | Transaction time, format :" yyymmddhhmmss" |
| 15 | Signature Type | 3 | Text | signType | MD5 |
| 16 | Signature Data | 32 | Text | signature | MD5 signature |
3.2. Purchase Response from AllPay
| No. | Field Name | Max.Length | Type | Parameter name | Comment |
|---|---|---|---|---|---|
| 1 | Message Version | 12 | Text | version | "VER000000002" |
| 2 | Character set coding | 6 | Text | charSet | "UTF-8" |
| 3 | Transaction type | 4 | Text | transType | "PURC" |
| 4 | Order Number | 60 | Text | orderNum | The merchant shall define it by itself, and the order number of the same merchant number shall not be repeated |
| 5 | Order Amount | 12 | Text | orderAmount | 100 is displayed as 100 or 100.00 |
| 6 | Order Currency | 3 | Text | orderCurrency | Fill in "CNY" in RMB and "USD" in USD |
| 7 | Settlement Amount | 12 | Text | settAmount | 100 is displayed as 100 or 100.00 |
| 8 | Settlement Currency | 3 | Text | settCurrency | Comply with ISO standards and fill in the number type |
| 9 | Settlement FX Rate | 7 | Text | rate | Real exchange rate, 7 digits |
| 10 | Merchant Reserved | 1024 | Text | merReserve | Merchant reserved content, can pass any content, such as purchase information, account number, etc., but do not pass special symbols, such as commas. |
| 11 | Gateway Transaction ID | 32 | Text | transID | The unique transaction id generated by the gateway. |
| 12 | Merchant ID | 15 | Text | merID | Merchant ID, assigned by AllPay |
| 13 | Acquirer ID | 11 | Text | acqID | "99020344" |
| 14 | Payment Channel Code | 10 | Text | paymentSchema | UnionPay:"UP",Wechat:"WX,Alipay:"APMP" |
| 15 | Response Code | 2 | Text | RespCode | 00 stands for success; 01 stands for fail. |
| 16 | Response Message | 20 | Text | RespMsg | Response message, all English characters |
| 17 | Transaction Time | 14 | Text | transTime | Transaction time, format :" yyymmddhhmmss" |
| 18 | Gateway process time | 14 | Text | GWTime | YYYYMMDDHHMMSS this should be a GWtime, currently is local transaction time |
| 19 | Signature Type | 3 | Text | signType | MD5 |
| 20 | Signature Data | 32 | Text | signature | MD5 signature |
3.3. Inqiury interface
- Interface specification
This interface provides the function of inqiury transaction for access merchants.
- Request message format
| No. | Field Name | Max.Length | Type | Parameter name | Comment |
|---|---|---|---|---|---|
| 1 | Message Version | 12 | Text | version | "VER000000002" |
| 2 | Character set coding | 6 | Text | charSet | "UTF-8" |
| 3 | Transaction type | 4 | Text | transType | "INQY" |
| 4 | Order Number | 60 | Text | orderNum | The merchant shall define it by itself, and the order number of the same merchant number shall not be repeated |
| 5 | Merchant Reserved | 1024 | Text | merReserve | Merchant reserved content |
| 6 | Merchant ID | 15 | Text | merID | Merchant ID, assigned by AllPay |
| 7 | Acquirer ID | 11 | Text | acqID | "99020344" |
| 8 | Payment Channel Code | 10 | Text | paymentSchema | UnionPay:"UP",Wechat:"WX,Alipay:"APMP" |
| 9 | Transaction Time | 14 | Text | transTime | Transaction time, format :" yyymmddhhmmss" |
| 10 | Signature Type | 3 | Text | signType | MD5 |
| 11 | Signature Data | 32 | Text | signature | MD5 signature |
- Response message format
| No. | Field Name | Max.Length | Type | Parameter name | Comment |
|---|---|---|---|---|---|
| 1 | Message Version | 12 | Text | version | "VER000000002" |
| 2 | Character set coding | 6 | Text | charSet | "UTF-8" |
| 3 | Transaction type | 4 | Text | transType | "INQY" |
| 4 | Order Number | 60 | Text | orderNum | The merchant shall define it by itself, and the order number of the same merchant number shall not be repeated |
| 5 | Gateway Transaction ID | 32 | Text | transID | The unique transaction id generated by the gateway. |
| 6 | Merchant ID | 15 | Text | merID | Merchant ID, assigned by AllPay |
| 7 | Acquirer ID | 11 | Text | acqID | "99020344" |
| 8 | Response Code | 2 | Text | RespCode | 00 stands for success; 01 stands for fail. |
| 9 | Response Message | 20 | Text | RespMsg | Response message, all English characters |
| 10 | Transaction Time | 14 | Text | transTime | Transaction time, format :" yyymmddhhmmss" |
| 11 | Gateway process time | 14 | Text | GWTime | YYYYMMDDHHMMSS this should be a GWtime, currently is local transaction time |
| 12 | Signature Type | 3 | Text | signType | MD5 |
| 13 | Signature Data | 32 | Text | signature | MD5 signature |
3.4. Refund interface
1.Interface specification
This interface provides the function of refund transaction for access merchants.
2.Request message format
| No. | Field Name | Max.Length | Type | Parameter name | Comment |
|---|---|---|---|---|---|
| 1 | Message Version | 12 | Text | version | "VER000000002" |
| 2 | Character set coding | 6 | Text | charSet | "UTF-8" |
| 3 | Transaction type | 4 | Text | transType | "REFD" |
| 4 | Order Number | 60 | Text | orderNum | The merchant shall define it by itself, and the order number of the same merchant number shall not be repeated |
| 5 | Return Amount | 12 | Text | returnAmount | 100 is displayed as 100 or 100.00 |
| 6 | Order Currency | 3 | Text | orderCurrency | Fill in "CNY" in RMB and "USD" in USD |
| 7 | Merchant Reserved | 1024 | Text | merReserve | Merchant reserved content, can pass any content, such as purchase information, account number, etc., but do not pass special symbols, such as commas. |
| 8 | Merchant ID | 15 | Text | merID | Merchant ID, assigned by AllPay |
| 9 | Acquirer ID | 11 | Text | acqID | "99020344" |
| 10 | Payment Channel Code | 10 | Text | paymentSchema | UnionPay:"UP",Wechat:"WX,Alipay:"APMP" |
| 11 | Transaction Time | 14 | Text | transTime | Transaction time, format :" yyymmddhhmmss" |
| 12 | Signature Type | 3 | Text | signType | MD5 |
| 13 | Signature Data | 32 | Text | signature | MD5 signature |
3.Response message format
| No. | Field Name | Max.Length | Type | Parameter name | Comment |
|---|---|---|---|---|---|
| 1 | Message Version | 12 | Text | version | "VER000000002" |
| 2 | Character set coding | 6 | Text | charSet | "UTF-8" |
| 3 | Transaction type | 4 | Text | transType | "REFD" |
| 4 | Order Number | 60 | Text | orderNum | The merchant shall define it by itself, and the order number of the same merchant number shall not be repeated |
| 5 | Gateway Transaction ID | 32 | Text | transID | The unique transaction id generated by the gateway. |
| 6 | Merchant ID | 15 | Text | merID | Merchant ID, assigned by AllPay |
| 7 | Acquirer ID | 11 | Text | acqID | "99020344" |
| 8 | Response Code | 2 | Text | RespCode | 00 stands for success; 01 stands for fail. |
| 9 | Response Message | 20 | Text | RespMsg | Response message, all English characters |
| 10 | Transaction Time | 14 | Text | transTime | Transaction time, format :" yyymmddhhmmss" |
| 11 | Gateway process time | 14 | Text | GWTime | YYYYMMDDHHMMSS this should be a GWtime, currently is local transaction time |
| 12 | Signature Type | 3 | Text | signType | MD5 |
| 13 | Signature Data | 32 | Text | signature | MD5 signature |
4. error code
| code | msg |
|---|---|
| U1 | Clientid not found |
| U2 | Signature error |
| V1 | Parameter missing |
| E1 | Exceed the limit |
| R1 | Orderno repeat |
| C1 | Order currency is not set |
| P1 | paychannel error |
| I1 | Illegal request address |
| T1 | Parameter missing（version或tranType） |
| T2 | Txntype error |
| T3 | transaction is not exist or fail |
| T4 | The maximum amount exceeds the upper limit |
| 99 | System error |
5.Technical support
If you have problems with debugging, please contact us:support@allpayx.com