SnapPay OpenAPI

API Endpoint

API Rules

1. Protocol Rules

While integrating with the SnapPay Open Service Gateway, please follow the following API rules.

Rule Explanation
Transfer Mode To secure the transactions, HTTPS is used for the production environment.
Submit Mode Use POST method
Data Format Except for some File Upload and Download APIs, the Requests and Responses are in JSON format.
Char Encoding Use UTF-8 Character encoding.
Signature Algorithm MD5 or RSA.
Signature Requirement Requests, Responses, and the Asynchronous Notification all require signatures. For detail sign method, please refer to Security Specifications.
Logic Judgment Determine protocol (HTTP status) response, service field, and transaction status.
Language Support en-US,zh-CN.

2. Access Nodes

Environment Access Nodes
SnapPay Production Environment https://open.snappay.ca/api/gateway

3. Parameters For Test Merchant Account 

Test merchant account in the Production Environment
Merchant ID: 901800000116
Store No.: 80519419
AppID: 9f00cd9a873c511e
Signature Sign Key: 7e2083699dd510575faa1c72f9e35d43 (MD5)

4. Merchant Production Parameters

To get the integration parameters for your real merchant account, refer here.

5. Parameter Specification

Mandatory

  • M - Mandatory

  • C - Mandatory for certain conditions

  • O - Optional

Parameter Types

KEY Name Example Notes
NUMBER Numbers 123
AMOUNT Amount 88.05 The value here is based on the settlement currency. Eg. if USD is the settlement currency, the value here is for USD amount.
TEXT Text This is a string.
DATE Time 2018-08-02 15:16:51 (UTC-0）Format: YYYY-MM-DD HH:mm:ss
BOOLEAN Boolean true true OR false
JSONObject JSON {“key”:“value”}
JSONArray JSON array [1,2,3,4,5]

6. Requests - Common Parameters

KEY Name Type Mandatory Description
app_id Application ID TEXT(32) M Provided by SnapPay Open Service Gateway. Please contact SnapPay support to get this.
format Request data format TEXT(4) M Only JSON
charset Encoding for requests TEXT(8) M Only UTF-8
sign_type Sign type TEXT(8) M MD5 or RSA
sign Signature TEXT(32) M API Signature to authenticate merchant, prevent alteration. Refer to Security Specifications.
version Version TEXT(8) M Only 1.0 for now
timestamp Request time DATE O Note: If the field is provided, please convert local timestamp to UTC time. Can’t be 15 mins apart from the standard UTC time. If it is not provided, current UTC time is used as default.

7. Response - Common Parameters

KEY Name Type Mandatory Description
code Status code TEXT(32) M Status code. 0 means success. Others mean failed.
msg Error Message TEXT(128) M When there is an error, this is the error message.
sign Signature TEXT(32) M API signature to authenticate merchants, prevent alteration. Refer to Security Specifications. When app_id and sign_type are invalid, no signature will be returned.
total Total data returned NUMBER M Total numbers meeting certain conditions. It is effective when data is paginated.
data Response data JSONArray M The array includes 1 or more JSON objects.
psn API serial number TEXT(32) M API serial number for error checkups.

Security Specifications

1. Select Sign algorithms

The sign algorithm can support RSA (SHA256), MD5.

When using RSA to sign, Public Key and Private Key are used together for signing. The Private key and the public key are both generated from OPENSSL (Note the key length is 2048). Merchants exchange the public key with the public key from the SnapPay Open Service gateway. Therefore, when signing, the merchant will use its own private key and the public key from the Open Service gateway.

When using MD5 to sign, MD5 Sign Key is used for signing. The Sign Key is composed of 32 alpha numeric digits. This key is distributed by SnapPay. Make sure the Sign key is not disclosed.

2. Generate the String used for signing

Step 1: Establish the parameters to be signed.

Sign all the API request parameters and responses from the Open Service Gateway and the Asynchronous Notification parameters, except for the sign_type, sign and byte[] type parameters and NULL or empty string parameters.

The sign applies for both Common Request/Response fields and Service Request/Response parameters.

Note: Based on the HTTP protocol requests, if there are special chars (such as &, @ etc) in the transmission parameters, URL encoding is needed so that the recipient can receive the correct parameters. In this case, the data to be signed should be the original values, not the values after encoding. For example, if some API requires signature for the email field, the sign data should be [email protected], but not email=test%40msn.com.

For example, for the following parameters:

String[] parameters = {
  "app_id=wxd16bdc77aa30ce7e",
  "method=pay.orderquery",
  "provider_id=2088101568338364",
  "format=JSON",
  "charset=UTF-8",
  "sign_type=MD5",
  "version=1.0",
  "timestamp=2018-10-30 14:19:23",
  "merchant_no=100001876",
  "out_trade_no=TB20181030000875",
  "trans_no="
};

The parameters that need to be signed after post processing are: (based on the specs, sign_type and trans_no don’t need to be signed)

String[] parameters = {
  "app_id=wxd16bdc77aa30ce7e",
  "method=pay.orderquery",
  "provider_id=2088101568338364",
  "format=JSON",
  "charset=UTF-8",
  "version=1.0",
  "timestamp=2018-10-30 14:19:23",
  "merchant_no=100001876",
  "out_trade_no=TB20181030000875"
};

Step 2: Reorder the parameters

Reorder the parameters based on the ASCII values. Rank them from a to z. If the first char is the same, check the second char, and so on. After reordering the parameters, the look like below:

String[] parameters = { 
  "app_id=wxd16bdc77aa30ce7e",
  "charset=UTF-8",
  "format=JSON",
  "merchant_no=100001876",
  "method=pay.orderquery",
  "out_trade_no=TB20181030000875",
  "provider_id=2088101568338364",
  "timestamp=2018-10-30 14:19:23",
  "version=1.0"
};

Step 3: Merge the parameters

Merge all the chars using “&”. Based on the above example, the final string looks like below:

app_id=wxd16bdc77aa30ce7e&charset=UTF-8&format=JSON&merchant_no=100001876&method=pay.orderquery&out_trade_no=TB20181030000875&provider_id=2088101568338364&timestamp=2018-10-30 14:19:23&version=1.0

3. Signature

MD5 Signature

  1. Generate the signature for the REQUESTs

After having the string to be signed, add the Sign Key to the end of the string to form a new string.

app_id=wxd16bdc77aa30ce7e&charset=UTF-8&format=JSON&merchant_no=100001876&method=pay.orderquery&out_trade_no=TB20181030000875&provider_id=2088101568338364&timestamp=2018-10-30 14:19:23&version=1.042fa0a3a1bf293f9c58d556ac1b67ea0

Use the MD5 algorithm to generate the signature and convert the string to all lower case characters. The final sign result is a 32 digit string. This sign result will be the ‘sign’ field in the request.

  1. Signature Verification for Asynchronous Notification or API Responses

After having the string to be signed in the Asynchronous Notification or API Responses, merge the Sign Key to the end of the string to form a new string. Use MD5 algorithm to generate the signature which is a 32 digit string. Verify if this Sign value is the same as the Sign value in the Asynchronous Notification or API Response. If it is the same, signature verification passes.

RSA Signature

  1. Generate the signature for the REQUESTs

After having the string to be signed, put both the String to be signed and the merchant private key to the RSA sign algorithm to calculate the signature (SHA256 with Base 64 encoding) result.

  1. Signature Verification for Asynchronous Notification or API Responses

After having the String to be signed from the Asynchronous notification or the API Response, put 1, the String to be signed, 2, Public Key, 3, Sign value from the notification or the response into the RSA signature algorithm to do the asymmetric calculation (SHA256 with 64 encoding). For detailed sign methods, please refer to the SDK Sign and Verify methods. For RSA key generation and signature verification, please refer to the tool provided by Alipay.

Pay APIs

Barcode Pay API

POST Try JavaTry PHP
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.barcodepay",
  "merchant_no": "901800002555",
  "payment_method": "WECHATPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "auth_code": "131234567677911364",
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "attach": "{\"orderId\": \"12345\"}\"",
  "effective_minutes": 15,
  "extension_parameters": "{\"store_no\": \"80000026\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "SUCCESS",
      "payment_method": "ALIPAY",
      "pay_operation_method": 4,
      "pay_user_account_id": "2088101117955611",
      "pay_user_account_name": "15900000000",
      "trans_currency": "CAD",
      "exchange_rate": 5.21,
      "trans_amount": 100.5,
      "c_trans_fee": 0.5,
      "customer_paid_amount": 524.09,
      "discount_bmopc": 0.1,
      "discount_bpc": 0.1,
      "trans_end_time": "2018-08-02 15:16:55"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.barcodepay",
  "merchant_no": "901800002555",
  "payment_method": "ALIPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "auth_code": "281234567885302264",
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "extension_parameters": "{\"store_no\": \"80000026\"}\""
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "SUCCESS",
      "payment_method": "ALIPAY",
      "pay_operation_method": 4,
      "pay_user_account_id": "2088101117955611",
      "pay_user_account_name": "15900000000",
      "trans_currency": "CAD",
      "exchange_rate": 5.21,
      "trans_amount": 100.5,
      "c_trans_fee": 0.5,
      "customer_paid_amount": 524.09,
      "discount_bmopc": 0.1,
      "discount_bpc": 0.1,
      "trans_end_time": "2018-08-02 15:16:55"
    }
  ]
}

Barcode Pay API
POST

Cashier uses the scanning equipment to read the “Payment Barcode” from the user’s WeChat or Alipay App, the cashier system sends the payment request to SnapPay’s Open Service Gateway by using this API.

Note 1: If the Error Code is 0, it means the Payment Request is successful but NOT the transaction is successful. Once the payment request is submitted, SnapPay’s Open Service Gateway will return the payment result. If the request expires, the merchant server waits for 5 seconds and calls Query Order API to query the payment result. If the transaction status is returned as “USERPAYING”, the merchant server can wait (10 seconds for example) before re-querying the payment result until payment success or expires (recommends 30 seconds).

Note 2: Call Revoke Order API if it returns an uncertain trade status when calling Query Order API. After revoking, the successful order will be refunded, while failed order will be closed. If Revocation has no response or returns error, call it again.

Note 3: NOT call Revoke Order API immediately after the order is created. It is recommended to wait for 15s.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
method Request Method TEXT(128) M Fixed as: pay.barcodepay
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay. It is used to identify the merchant.
payment_method Payment Method TEXT(16) O Currently Supports:
ALIPAY
WECHATPAY
UNIONPAY_QR
SnapPay will override this parameter by checking the auth_code format. This means, SnapPay is able to tell if the barcode scanned is a WeChat Barcode or an Alipay Barcode, by analyzing the numbers given by the scanner. Your POS system doesn’t have to tell SnapPay if it is for Alipay or WeChat pay.
out_order_no Merchant Order No. TEXT(64) M The Order No. can be treated as payment serial number, and for each merchant has to be unique. It can’t be duplicated, even the transaction is not success.
trans_currency Transaction Currency TEXT(8) O 3 letter code from ISO 4217, such as CAD or USD. The transaction currency has to be the same as the settlement currency. Only CAD and USD are currently supported. If not filled, CAD is used as default.
trans_amount Order Amount AMOUNT M Max: 100000000.00
auth_code Auth Code TEXT(256) M Auth code for Transaction QR payment. Example:
Alipay-281234567885302264
WeChat-131234567677911364
description Order Description TEXT(128) M Example: Ipad mini 16G white
notify_url Notify URL TEXT(256) O This is the notify URL to receive Asynchronous Notification from SnapPay’s Open Service Gateway.
attach Merchant additional info TEXT(127,JSON Format) O Additional data. This field is used to carry the merchant’s own customized order data and has to follow JSON format. It will be returned in the Query API and the Notification the same way as sent here.
effective_minutes Order effective minutes NUMBER O Use to set up the Order expiry time (in min). Payment will fail If it exceeds this number. The order will be closed. Default value: 5.
The valid range is: 5min — 60min
extension_parameters Extension parameters TEXT(JSON Format) O This is for extended parameters. The new parameters can be stored in this JSON. See Extension Parameters.

Extension Parameters

KEY Name Type Mandatory Description
store_no Store Number assigned by SnapPay TEXT(8) O Store Number is used to identify the store of a merchant. One merchant might have more than 1 stores. The number is given by SnapPay after the merchant account is created. We recommend you to provide the store number to pass Alipay’s risk control rules.
Example: {“store_no”:“80000026”}

Response Parameters

Common Parameters

Refer to Response - Common Parameters

Service Parameters

When code=0, data[0] returns the following parameters:

KEY Name Type Mandatory Description
trans_no Transaction No. TEXT(32) M Transaction No. from SnapPay’s Open Service Gateway.
out_order_no Merchant Order No. TEXT(64) M Internal Order No. from the Merchant System.
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
trans_status Transaction Status TEXT(32) M Transaction Status
USERPAYING - Transaction created, waiting for the customer to enter the password. Cashier’s POS system should wait for 5 seconds and then iteratively call the Query Order API to check the transaction status. The cashier’s POS system can query for 1 min - 2 min.
CLOSE-Transaction Close, including revocation close, close due to non-payment after expiry time, close due to failure.
SUCCESS-Transaction completed.

When the trans_status is: SUCCESS - Transaction completed, data[0] returns the following parameters:

KEY Name Type Mandatory Description
payment_method Payment method TEXT(16) M Currently Supports:
ALIPAY
WECHATPAY
UNIONPAY_QR
pay_operation_method Payment operation method NUMBER M 4: Transaction QR Code Payment
5: Barcode Payment
6: H5 Payment
8: APP Payment
9: PC Web Payment
pay_user_account_id Buyer User ID TEXT(32) M User ID returned by Alipay, looks like 2088101117955611
Unique user ID from WeChat per Merchant appID, looks like: wx37150978513678
pay_user_account_name User Account Name TEXT(32) O 159****5620 or [email protected]
Note: returned for Alipay. Null for WeChat Pay.
trans_currency Transaction currency TEXT(32) M 3 letter code from ISO 4217. such as CAD, USD
exchange_rate Exchange rate TEXT(16) M Exchange rate between the transaction currency to RMB.
trans_amount Transaction amount AMOUNT M Transaction Amount
c_trans_fee Customer pays transaction fee AMOUNT O Transaction fee the customer needs to pay
customer_paid_amount Total Customer paid AMOUNT M The actual amount being deducted from the user’s account.
discount_bmopc Discount offered by the Merchant through payment channels (alipay or wechat) AMOUNT O This is the discounted amount offered by merchant through the promotion events (payment deduction, coupon, discount, single product discount etc) via the payment channels (WeChat, Alipay)
discount_bpc Discount offer by the payment channels (alipay or wechat) AMOUNT O This is the discounted amount offered by Payment Channels through promotion events: such as Red envelope, random discount etc.
trans_end_time Transaction completion time DATE M

Recommended merchant side implementation process

For POS systems who leverage scanners to conduct payment, we recommend to following this procedure.

For more details, refer here.

Transaction QR Code Pay API

POST Try JavaTry PHP
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.qrcodepay",
  "merchant_no": "901800002555",
  "payment_method": "WECHATPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "attach": "{\"orderId\": \"12345\"}\"",
  "effective_minutes": 15,
  "extension_parameters": "{\"store_no\": \"80000026\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "qrcode_url": "https://qrcode-url"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.qrcodepay",
  "merchant_no": "901800002555",
  "payment_method": "ALIPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "extension_parameters": "{\"store_no\": \"80000026\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "qrcode_url": "https://qrcode-url"
    }
  ]
}

Transaction QR Code Pay API
POST

Merchant Server calls this API to create a pre-pay transaction request in SnapPay’s Open Service Gateway. The gateway returns the QR code to display in the merchant portal.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
method Request Method TEXT(128) M Fixed as: pay.qrcodepay
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
payment_method Payment Method TEXT(16) M Currently supports:
ALIPAY
WECHATPAY
UNIONPAY_QR
out_order_no Merchant Order No. TEXT(64) M The Order No. can be treated as payment serial number, and for each merchant has to be unique. It can’t be duplicated, even the transaction is not success.
trans_currency Transaction Currency TEXT(8) O 3 letter code from ISO 4217. such as CAD or USD. The transaction currency has to be the same as the settlement currency. Only CAD and USD are currently supported. If not filled, CAD is used as default.
trans_amount Order Amount AMOUNT M Max: 100000000.00
description Order Description TEXT(128) M Example: Ipad mini 16G white
notify_url Notify URL TEXT(256) O This is the notify URL to receive Asynchronous Notification from SnapPay’s Open Service Gateway.
attach Merchant additional info TEXT(127,JSON Format) O Additional data. This field is used to carry the merchant’s own customized order data and has to follow JSON format. It will be returned in the Query API and the Notification the same way as sent here.
effective_minutes Order effective minutes NUMBER O Use to set up the Order expiry time (in min). Payment will fail If it exceeds this number. The order will be closed. Default value: 5.
The valid range is: 5min — 60min
extension_parameters Extension parameters TEXT(JSON Format) O This is for extended parameters. The new parameters can be stored in this JSON. See Extension Parameters.

Extension Parameters

KEY Name Type Mandatory Description
store_no Store Number assigned by SnapPay TEXT(8) O Store Number is used to identify the store of a merchant. One merchant might have more than 1 stores. The number is given by SnapPay after the merchant account is created. We recommend you to provide the store number to pass Alipay’s risk control rules.
Example: {“store_no”:“80000026”}

Response Parameters

Common Parameters

Refer to Response - Common Parameters

Service Parameters

When code=0, data[0] returns the following parameters:

KEY Name Type Mandatory Description
trans_no Transaction No. TEXT(32) M Transaction No. from SnapPay’s Open Service Gateway.
out_order_no Merchant Order No. TEXT(64) M Internal Order No. from the Merchant System.
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
trans_status Transaction Status TEXT(32) M Transaction Status
USERPAYING - Order created, waiting for the buyer to pay
CLOSE - Order closed, including revocation close, close due to non-payment after expiry time, close due to failure
qrcode_url URL for the QR Code TEXT(128) M This URL can be turned into the QR code for the merchant to display and for the user to scan.
When the payment method is UNIONPAY_QR, this parameter is a QR code image encoded by BASE64

H5 Pay API

POST Try JavaTry PHP
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.h5pay",
  "merchant_no": "901800002555",
  "payment_method": "WECHATPAY",
  "pay_channel_trade_type": "MWEB",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "return_url": "https://return-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "SUCCESS",
      "h5pay_url: `https://h5pay_url`": "Hello, world!",
      "alipay_trade_no": "201xxxxxxxxxxx3221"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.h5pay",
  "merchant_no": "901800002555",
  "payment_method": "ALIPAY",
  "pay_channel_trade_type": "JSAPI",
  "pay_user_account_id": "2088101106499364",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "return_url": "https://return-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "SUCCESS",
      "h5pay_url: `https://h5pay_url`": "Hello, world!",
      "alipay_trade_no": "201xxxxxxxxxxx3221"
    }
  ]
}

H5 Pay API
POST

Merchant system calls this interface to create a PrePay order, redirects to SnapPay’s payment URL after receiving the correct PrePay transaction ID. When the H5 payment is done, it will redirect to the merchant’s web page.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
method Request Method TEXT(128) M Fixed as: pay.h5pay
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
payment_method Payment Method TEXT(16) M Currently supports:
ALIPAY
WECHATPAY
pay_channel_trade_type Payment channel trade type TEXT(16) O MWEB: this is the default value, and the API will return payment URL. The merchant redirect to this URL to complete payment.
ORDERSTR: Only support Alipay in Alipay App’s built-in browser. Open the e-commerce website in the built-in browser submits the obtained order_str directly to Alipay via AlipayJSBridge. WeChat does not support ORDERSTR. Reference: 2.2 No Alipay transaction number evokes payment (use method 2) link
out_order_no Merchant Order No. TEXT(50) M The Order No. can be treated as payment serial number, and for each merchant has to be unique. It can’t be duplicated, even the transaction is not success.
trans_currency Transaction Currency TEXT(8) O 3 letter code from ISO 4217. such as CAD, USD. The transaction currency has to be the same as the settlement currency. Only CAD and USD are currently supported. If not filled, CAD is used as default.
trans_amount Order Amount AMOUNT M Max: 100000000.00
description Order Description TEXT(128) M Example: Ipad mini 16G white
notify_url Notify URL TEXT(256) O This is the notify URL to receive Asynchronous Notification from SnapPay’s Open Service Gateway.
return_url Return URL TEXT(1024) O This is the return URL the merchant page will direct to after payment is successful.
attach Merchant additional info TEXT(127,JSON Format) O Additional data. This field is used to carry the merchant’s own customized order data and has to follow JSON format. It will be returned in the Query API and the Notification the same way as sent here.
effective_minutes Order effective minutes NUMBER O Use to set up the Order expiry time (in min). Payment will fail If it exceeds this number. The order will be closed. Default value: 5.
The valid range is: 5min — 60min
extension_parameters Extension parameters TEXT(JSON Format) O This is for extended parameters. The new parameters can be stored in this JSON.

Response Parameters

Common Parameters

Refer to Response - Common Parameters

Service Parameters

When code=0, data[0] returns the following parameters:

KEY Name Type Mandatory Description
out_order_no Merchant Order No. TEXT(50) M Internal Order No. from the Merchant System.
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
trans_status Transaction Status TEXT(32) M Transaction Status
USERPAYING - Transaction created, waiting to be paid.
CLOSE - Transaction Close, including revocation close, close due to non-payment after expiry time, close due to failure
SUCCESS - Transaction completed
h5pay_url H5 payment URL TEXT(128) C The payment URL returned from SnapPay’s server. The merchant webpage will be directed to this address for payment.
order_str AliPay trade string TEXT(1024) C When using AliPay ORDERSTR, this parameter will contain the trade string. Reference: 2.2 No Alipay transaction number evokes payment (use method 2) link

Native App Pay API

POST 
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.inapppay",
  "merchant_no": "901800002555",
  "payment_method": "WECHATPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "subject": "iPad",
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "refer_url": "https://refer-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "extension_parameters": "{\"sub_app_id\": \"wxd930ea5d5a258f4f\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "sdk_params": {
        "alipay_request_params": "key1=value1&key2=value2",
        "appid": "wxd930ea5d5a258f4f",
        "partnerid": "10000100",
        "prepayid": "1101000000140415649af9fc314aa427",
        "package": "Sign=WXPay",
        "noncestr": "random",
        "timestamp": "1397527777",
        "sign": "XXXXXXXXXXX"
      },
      "trade_no": "201xxxxxxxxxxx3221"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.inapppay",
  "merchant_no": "901800002555",
  "payment_method": "ALIPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "subject": "iPad",
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "refer_url": "https://refer-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "sdk_params": {
        "alipay_request_params": "key1=value1&key2=value2",
        "appid": "wxd930ea5d5a258f4f",
        "partnerid": "10000100",
        "prepayid": "1101000000140415649af9fc314aa427",
        "package": "Sign=WXPay",
        "noncestr": "random",
        "timestamp": "1397527777",
        "sign": "XXXXXXXXXXX"
      },
      "trade_no": "201xxxxxxxxxxx3221"
    }
  ]
}

Native App Pay API
POST

Merchant system calls this API first to create the Prepay Order. Once the prepay order is created successfully, call the Alipay/WeChat SDK to complete payment.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
method Request Method TEXT(128) M Fixed as: pay.inapppay
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
payment_method Payment Method TEXT(16) M Currently supports:
ALIPAY
WECHATPAY
out_order_no Merchant Order No. TEXT(64) M The Order No. can be treated as payment serial number, and for each merchant has to be unique. It can’t be duplicated, even the transaction is not success.
trans_currency Transaction Currency TEXT(8) O 3 letter code from ISO 4217. such as CAD, USD. The transaction currency has to be the same as the settlement currency. Only CAD and USD are currently supported. If not filled, CAD is used as default.
trans_amount Order Amount AMOUNT M Max: 100000000.00
subject Product name TEXT(128) M Example: iPad
description Order Description TEXT(128) M Example: Ipad mini 16G white
notify_url Notify URL TEXT(256) O This is the notify URL to receive Asynchronous Notification from SnapPay’s Open Service Gateway.
refer_url Merchant website URL TEXT(256) M Merchant website URL
attach Merchant additional info TEXT(127,JSON Format) O Additional data. This field is used to carry the merchant’s own customized order data and has to follow JSON format. It will be returned in the Query API and the Notification the same way as sent here.
effective_minutes Order effective minutes NUMBER O Use to set up the Order expiry time (in min). Payment will fail If it exceeds this number. The order will be closed. Default value: 5.
The valid range is: 5min — 60min
extension_parameters Extension parameters TEXT(JSON Format) O This is for extended parameters. The new parameters can be stored in this JSON.

Extension Parameters

KEY Name Type Mandatory Description
sub_app_id App id generated by WeChat Open Platform TEXT(18) C The APPID obtained by WeChat Open Platform, when merchant has applied for the Mobile APP or Mini Program (this APPID needs to send an email to SnapPay for binding). If merchant have multiple APPIDs, the parameter is mandatory, specifying the APPID used by the current transaction request.

Response Parameters

Common Parameters

Refer to Response - Common Parameters

Service Parameters

When code=0, data[0] returns the following parameters:

KEY Name Type Mandatory Description
out_order_no Merchant Order No. TEXT(64) M Internal Order No. from the Merchant System.
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
trans_status Transaction Status TEXT(32) M Transaction Status
USERPAYING - Transaction created, waiting to be paid.
CLOSE - Transaction Close, including revocation close, close due to non-payment after expiry time, close due to failure.
SUCCESS - Transaction completed
sdk_params The parameter required to call the Alipay and WeChat SDK TEXT(JSON Format) M The parameter required to call the Alipay and WeChat SDK
trade_no Order No TEXT(128) M Prepay Order No

When payment_method=ALIPAY, sdk_params returns the following JSON parameters:

KEY Name Type Mandatory Description
alipay_request_params Parameter used to call the Alipay SDK TEXT(256) M Parameter used to call the Alipay SDK

How to call Alipay SDK​

Please follow the Alipay official instructions on how to call Alipay SDK.
https://global.alipay.com/doc/app/sdk_integration
https://global.alipay.com/doc/app/android_sdk

When payment_method=WECHATPAY, sdk_params returns the following JSON parameters:

KEY Name Type Mandatory Description
appid Sub-merchant AppID TEXT(32) M Merchant App ID applied in WeChat’s Open Platform.
partnerid SnapPay Merchant ID TEXT(32) M SnapPay’s merchant ID.
prepayid Prepay Order ID TEXT(32) M WeChat PreOrder No.
package Extension TEXT(128) M Use the fixed value: Sign=WXPay
noncestr Random string TEXT(32) M Random String
timestamp Timestamp TEXT(10) M timestamp
sign Signature TEXT(32) M Signature created by SnapPay

How to call WeChat SDK​

Please follow the WeChat official instructions on how to call WeChat SDK.

https://pay.weixin.qq.com/wiki/doc/api/app/app_sl.php?chapter=8_5

Donwload SnapPay Android Native App Demo

Download SnapPay Native App apk, click here
Download SnapPay Native App source code, click here

Website Pay API

POST Try JavaTry PHP
RequestsAliPayUnionPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.webpay",
  "merchant_no": "901800002555",
  "payment_method": "ALIPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "return_url": "https://return-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "browser_type": "WAP"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "webpay_url": "https://webpay-url"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.webpay",
  "merchant_no": "901800002555",
  "payment_method": "UNIONPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "return_url": "https://return-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "browser_type": "PC"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "webpay_url": "https://webpay-url"
    }
  ]
}

Website Pay API
POST

This is not for WeChat Pay.

Merchant system first calls this interface to generate the Prepay order, then redirects to the payment URL returned by SnapPay to enter Alipay/UnionPay’s 3rd-party cashier page to complete payment.

Once payment is successful, it will redirect back to the merchant page. If the user opens the website using the mobile browser, it will open Alipay’s mobile WAP cashier page to complete payment.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
method Request Method TEXT(128) M Fixed as: pay.webpay
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
payment_method Payment Method TEXT(16) M Currently supports:
ALIPAY
UNIONPAY
out_order_no Merchant Order No. TEXT(64) M The Order No. can be treated as payment serial number, and for each merchant has to be unique. It can’t be duplicated, even the transaction is not success.
trans_currency Transaction Currency TEXT(8) O 3 letter code from ISO 4217. such as CAD, USD. The transaction currency has to be the same as the settlement currency. Only CAD and USD are currently supported. If not filled, CAD is used as default.
trans_amount Order Amount AMOUNT M Max: 100000000.00
description Order Description TEXT(128) M Example: Ipad mini 16G white
notify_url Notify URL TEXT(256) O This is the notify URL to receive Asynchronous Notification from SnapPay’s Open Service Gateway.
return_url Return URL TEXT(1024) O The merchant return URL after a successful payment.
attach Merchant additional info TEXT(127,JSON Format) O Additional data. This field is used to carry the merchant’s own customized order data and has to follow JSON format. It will be returned in the Query API and the Notification the same way as sent here.
effective_minutes Order effective minutes NUMBER O Use to set up the Order expiry time (in min). Payment will fail If it exceeds this number. The order will be closed. Default value: 5.
The valid range is: 5min — 60min
extension_parameters Extension parameters TEXT(JSON Format) O This is for extended parameters. The new parameters can be stored in this JSON.
browser_type Browser type TEXT(8) O PC: PC web browser payment (Default)
WAP: Mobile web browser payment
UNIONPAY only supports PC web browser view

Response Parameters

Common Parameters

Refer to Response - Common Parameters

Service Parameters

When code=0, data[0] returns the following parameters:

KEY Name Type Mandatory Description
trans_no Transaction No. TEXT(32) M SnapPay’s transaction No.
out_order_no Merchant Order No. TEXT(64) M Internal Order No. from the Merchant System.
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
trans_status Transaction Status TEXT(32) M Transaction Status
USERPAYING - Transaction created, waiting to be paid.
CLOSE - Transaction Close, including revocation close, close due to non-payment after expiry time, close due to failure.
SUCCESS - Transaction completed
webpay_url The Cashier page payment URL TEXT(128) M The payment URL returned by SnapPay. Merchant website needs to direct to this link to complete payment.

Mini Program API

POST 
RequestsWeChatPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.minipay",
  "merchant_no": "901800002555",
  "payment_method": "WECHATPAY",
  "out_order_no": "12345678",
  "trans_currency": "CAD",
  "trans_amount": 100.5,
  "pay_user_account_id": "xxxxxx",
  "description": "this is a test transaction",
  "notify_url": "https://notify-url",
  "attach": "{\"orderId\": \"12345\"}",
  "effective_minutes": 15,
  "extension_parameters": "{\"sub_app_id\": \"wxd930ea5d5a258f4f\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "USERPAYING",
      "request_payment": {
        "appid": "wxd930ea5d5a258f4f",
        "timestamp": "1397527777",
        "noncestr": "random",
        "package": "prepay_id=wx2017033010242291fcfe0db70013231072",
        "signType": "MD5",
        "paySign": "xxxxxx"
      },
      "trade_no": "TW0xxxxxxx"
    }
  ]
}

Mini Program API
POST

Merchant system calls this API first to create the Prepay Order. Once the prepay order is created successfully, call WeChat payment API for mini program to complete payment.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
method Request Method TEXT(128) M Fixed as: pay.minipay
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
payment_method Payment Method TEXT(16) M Currently supports:
WECHATPAY
out_order_no Merchant Order No. TEXT(64) M The Order No. can be treated as payment serial number, and for each merchant has to be unique. It can’t be duplicated, even the transaction is not success.
trans_currency Transaction Currency TEXT(8) O 3 letter code from ISO 4217. such as CAD, USD. The transaction currency has to be the same as the settlement currency. Only CAD and USD are currently supported. If not filled, CAD is used as default.
trans_amount Order Amount AMOUNT M Max: 100000000.00
pay_user_account_id User Tag TEXT(128) M It is the only user identification under the current appid. About how to get openid, please refer to here
description Order Description TEXT(128) M Example: Ipad mini 16G white
notify_url Notify URL TEXT(256) O This is the notify URL to receive Asynchronous Notification from SnapPay’s Open Service Gateway.
attach Merchant additional info TEXT(127,JSON Format) O Additional data. This field is used to carry the merchant’s own customized order data and has to follow JSON format. It will be returned in the Query API and the Notification the same way as sent here.
effective_minutes Order effective minutes NUMBER O Use to set up the Order expiry time (in min). Payment will fail If it exceeds this number. The order will be closed. Default value: 5.
The valid range is: 5min — 60min
extension_parameters Extension parameters TEXT(JSON Format) O This is for extended parameters. The new parameters can be stored in this JSON.

Extension Parameters

KEY Name Type Mandatory Description
sub_app_id App id generated by WeChat Official Accounts Platform TEXT(18) C The APPID obtained by WeChat Official Accounts Platform, when merchant has applied for the Mobile APP or Mini Program (this APPID needs to send an email to SnapPay for binding). If merchant have multiple APPIDs, the parameter is mandatory, specifying the APPID used by the current transaction request.

Response Parameters

Common Parameters

Refer to Response - Common Parameters

Service Parameters

When code=0, data[0] returns the following parameters:

KEY Name Type Mandatory Description
out_order_no Merchant Order No. TEXT(64) M Internal Order No. from the Merchant System.
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
trans_status Transaction Status TEXT(32) M Transaction Status
USERPAYING - Transaction created, waiting to be paid.
CLOSE - Transaction Close, including revocation close, close due to non-payment after expiry time, close due to failure.
SUCCESS - Transaction completed
request_payment The parameter required to call WeChat TEXT(JSON Format) M The parameter required to call the WeChat payment API, don’t change.
trade_no Order No TEXT(128) M Prepay Order No

request_payment returns the following JSON parameters:

KEY Name Type Mandatory Description
appid Sub-merchant AppID TEXT(32) M Merchant mini program AppID applied in WeChat’s Open Platform.
timestamp Timestamp TEXT(10) M timestamp
noncestr Random string TEXT(32) M Random String
package Extension TEXT(128) M Use value: prepay_id=*
signType Sign Type TEXT(32) M MD5
paySign Pay Sign TEXT(32) M Generate and return by SnapPay

How to call WeChat payment API Please follow the WeChat official instructions on how to call WeChat payment API. click here

Donwload SnapPay Mini program demo souce code click here

Order APIs

Query Order API

POST Try JavaTry PHP
RequestsByOrderNoByTransNo
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.orderquery",
  "merchant_no": "901800002555",
  "out_order_no": "12345678"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "SUCCESS",
      "payment_method": "ALIPAY",
      "pay_user_account_id": "2088101106499364",
      "trans_currency": "CAD",
      "exchange_rate": 5.21,
      "trans_amount": 100.5,
      "customer_paid_amount": 524.09,
      "discount_bmopc": 0.1,
      "discount_bpc": 0.1,
      "trans_end_time": "2018-08-02 15:16:55",
      "pay_operation_method": 4,
      "attach": "{\"orderId\": \"12345\"}"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.orderquery",
  "merchant_no": "901800002555",
  "trans_no": "TRANS12345"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "merchant_no": "901800002555",
      "trans_status": "SUCCESS",
      "payment_method": "ALIPAY",
      "pay_user_account_id": "2088101106499364",
      "trans_currency": "CAD",
      "exchange_rate": 5.21,
      "trans_amount": 100.5,
      "customer_paid_amount": 524.09,
      "discount_bmopc": 0.1,
      "discount_bpc": 0.1,
      "trans_end_time": "2018-08-02 15:16:55",
      "pay_operation_method": 4,
      "attach": "{\"orderId\": \"12345\"}"
    }
  ]
}

Query Order API
POST

This interface allows inquiry of all payment orders (pay, revoke, refund). Merchants can query the order status proactively using this API to determine the next business flow.

The following are situations when to use the Query Order API:

  1. The Merchant doesn’t receive any payment result notification due to an exception in the Vendor’s backend, network, or server.

  2. A system error or unknown transaction status is returned after calling the payment APIs.

  3. USERPAYING status is returned after calling the Transaction QR Code API.

  4. To confirm payment status before calling the Revoke Order API.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
method Request Method TEXT(128) M Fixed as: pay.orderquery
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
out_order_no Merchant Order No. TEXT(64) C Internal Order No. from the Merchant System. Either out_order_no or trans_no needs to be provided.
trans_no Transaction No. TEXT(32) C Transaction No. created by SnapPay gateway. Either out_order_no or trans_no needs to be provided.
extension_parameters Extension parameters TEXT(JSON Format) O For extended parameters defined in the future. The new parameters can be stored in this JSON.

Response Parameters

Common Parameters

Refer to Response - Common Parameters

Service Parameters

When code=0, data[0] returns the following parameters:

KEY Name Type Mandatory Description
trans_no Transaction No. TEXT(32) M SnapPay’s transaction No.
out_order_no Merchant Order No. TEXT(64) M Internal Order No. from the Merchant System.
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
trans_status Transaction Status TEXT(32) M Transaction Status
USERPAYING - Transaction created, waiting to be paid.
CLOSE - Transaction Closed, including 1 - Revoke Close, 2 - Close due to non-payment after expiry, 3 - Close due to transaction failure
SUCCESS - Transaction completed

When trans_status is SUCCESS，data[0] returns the following parameters:

KEY Name Type Mandatory Description
payment_method Payment method TEXT(16) M Currently supports: ALIPAY WECHATPAY UNIONPAY
pay_user_account_id User account ID TEXT(32) M User ID returned by Alipay, looks like 2088101117955611
Unique user ID from WeChat per Merchant appID, looks like: wx37150978513678
Account number returned for card transctions looks like 6226****1982
pay_user_account_name User account name TEXT(32) O 159****5620 or [email protected] Note: Alipay will return the account name, WeChat will return NULL
trans_currency Transaction currency TEXT(32) O 3 letter code from ISO 4217. such as CAD, USD
exchange_rate Exchange rate TEXT(16) O Exchange rate between the transaction currency to RMB.
trans_amount Transaction amount AMOUNT M Transaction amount
c_trans_fee Customer pays transaction fee AMOUNT O Transaction fee the customer needs to pay
customer_paid_amount Total customer paid AMOUNT M The actual amount being deducted from the user’s account.
discount_bmopc Discount offered by the merchant via payment channels AMOUNT O This is the discounted amount offered by merchant through the promotion events (payment deduction, coupon, discount, single product discount etc) via the payment channels (WeChat, Alipay)
discount_bpc Discount offered by the payment channels AMOUNT O This is the discounted amount offered by Payment Channels through promotion events: such as Red envelope, random discount etc.
trans_end_time Transaction completion time DATE M Transaction success or fail time.
pay_operation_method Payment operation method NUMBER M 4: Transaction QR Code Payment
5: Barcode (Scanning) Payment
6: H5 Payment
8: APP Payment
9: PC Web Payment
attach Merchant additional info TEXT(127,JSON Format) O Additional data. This field is used to carry the merchant’s own customized order data and has to follow JSON format. It will be returned in the Query API and the Notification the same way as sent here.

Asynchronous Notification

POST 
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "merchant_no": "901800002555",
  "trans_no": "TRANS12345",
  "out_order_no": "12345678",
  "trans_status": "SUCCESS",
  "payment_method": "WECHATPAY",
  "pay_user_account_id": "wx37150978513678",
  "trans_currency": "CAD",
  "exchange_rate": 5.21,
  "trans_amount": 100.5,
  "c_trans_fee": 0.5,
  "customer_paid_amount": 524.09,
  "discount_bmopc": 0.1,
  "discount_bpc": 0.1,
  "trans_end_time": "2018-08-02 15:16:55",
  "attach": "{\"orderId\": \"12345\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0"
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "merchant_no": "901800002555",
  "trans_no": "TRANS12345",
  "out_order_no": "12345678",
  "trans_status": "SUCCESS",
  "payment_method": "ALIPAY",
  "pay_user_account_id": "2088101106499364",
  "pay_user_account_name": "159****5620",
  "trans_currency": "CAD",
  "exchange_rate": 5.21,
  "trans_amount": 100.5,
  "c_trans_fee": 0.5,
  "customer_paid_amount": 524.09,
  "discount_bmopc": 0.1,
  "discount_bpc": 0.1,
  "trans_end_time": "2018-08-02 15:16:55",
  "attach": "{\"orderId\": \"12345\"}"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0"
}

Asynchronous Notification
POST

After completing a payment, SnapPay’s Open Service Gateway will send the relevant payment result and user information to the Vendor. When this happens, the vendor’s backend will need to receive the result and return a reply to the WeChat payment system.

When interacting with this API, if SnapPay’s Open Service Gateway doesn’t receive a response from the Vendor backend including success, SnapPay will consider it as an unreceived notification and initiate further payment result notifications at a regular interval to ensure successful receipt. SnapPay backend cannot ensure successful receipt of payment notifications in every case.

Notification frequency: 15/15/30/180/1800/1800/1800/1800/3600s

Note: As payment result notifications maybe sent from SnapPay to the vendor’s backend multiple times, a single payment result might be notified to the vendor multiple times. For this reason, the vendor’s system must be able to handle duplicate notifications properly.

The best practices for dealing with such case: when a notification is received and processed, the enclosed payment data should be checked first to confirm whether the payment result has previously been processed or not. If so, return the processed result; if not, proceed with processing the result first before returning. Before checking the payment data, a transaction lock shall be used for concurrency to prevent data corruption caused by transaction race conditions.

Note: To avoid receiving fake notifications, merchants must verify the signature of the notification and check whether the order amount in the notification is the same with the one in the merchant’s system.

API URL

This URL maybe configured via notify_url, a parameter submitted via the “Pay API”. If vendors can’t open this URL, they will not be able to receive any notifications sent from SnapPay gateway.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
trans_no Transaction No. TEXT(32) M Transaction No. created by SnapPay gateway.
out_order_no Merchant Order No. TEXT(64) M Internal Order No. from the Merchant System.
trans_status Transaction Status TEXT(32) M SUCCESS
payment_method Payment method TEXT(16) M Currently supports: ALIPAY WECHATPAY UNIONPAY
pay_user_account_id User account ID TEXT(32) M User ID returned by Alipay, looks like 2088101117955611
Unique user ID from WeChat per Merchant appID, looks like: wx37150978513678
Account number returned for card transctions looks like 6226****1982
pay_user_account_name User account name TEXT(32) O 159****5620 or [email protected] Note: Alipay will return the account name, WeChat will return NULL
trans_currency Transaction currency TEXT(32) O 3 letter code from ISO 4217. such as CAD, USD
exchange_rate Exchange rate TEXT(16) O Exchange rate between the transaction currency to RMB.
trans_amount Transaction amount AMOUNT M Transaction amount
c_trans_fee Customer pays transaction fee AMOUNT O Transaction fee the customer needs to pay
customer_paid_amount Total customer paid AMOUNT M The actual amount being deducted from the user’s account.
discount_bmopc Discount offered by the merchant via payment channels AMOUNT O This is the discounted amount offered by merchant through the promotion events (payment deduction, coupon, discount, single product discount etc) via the payment channels (WeChat, Alipay)
discount_bpc Discount offered by the payment channels AMOUNT O This is the discounted amount offered by Payment Channels through promotion events: such as Red envelope, random discount etc.
trans_end_time Transaction completion time DATE M Transaction success or fail time.
attach Merchant additional info. TEXT(127,JSON Format) O Additional data. This field is used to carry the merchant’s own customized order data and has to follow JSON format. It will be returned in the Query API and the Notification the same way as sent here.

Response Parameters

The parameters sent by the vendor to the SnapPay gateway:

KEY Name Type Mandatory Description
code status code TEXT(32) M Fixed: 0

Revoke Order API

POST Try JavaTry PHP
RequestsCancelOrder
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.ordercancel",
  "merchant_no": "901800002555",
  "out_order_no": "12345678"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678"
    }
  ]
}

Revoke Order API
POST

When a payment transaction isn’t successfully returned or the payment system times out, this API is called to cancel the transaction. After revoking, the successful order will be refunded, while the failed order will be closed.

Note: This API can be called for the current day transactions only, while the “Submit Refund API” should be used for transactions paid successfully. After a transaction is submitted, “Query Order API” needs to be called. When there is no clear query result, “Revoke Order API” needs to be called. Please note that the Revoke Order API should be called at least 15s later after the order is created.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
method Request Method TEXT(128) M Fixed as: pay.ordercancel
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
out_order_no Merchant Order No. TEXT(64) M Original Order No. from the Merchant System.
extension_parameters Extension parameters TEXT(JSON Format) O This is for extended parameters. The new parameters can be stored in this JSON.

Response Parameters

Common Parameters

Refer to Response - Common Parameters

Service Parameters

When code=0, data[0] returns the following parameters:

KEY Name Type Mandatory Description
trans_no Transaction No. TEXT(32) M SnapPay’s transaction No.
out_order_no Merchant Order No. TEXT(64) M Original Order No. from the Merchant System.

Refund API

POST Try JavaTry PHP
RequestsOrderRefund
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.orderrefund",
  "merchant_no": "901800002555",
  "out_order_no": "12345678",
  "out_refund_no": "87654321",
  "refund_amount": 50,
  "refund_desc": "defect product"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "trans_no": "TRANS12345",
      "out_order_no": "12345678",
      "out_refund_no": "87654321",
      "trans_status": "SUCCESS",
      "refund_trans_no": "TRANS67890",
      "refund_trans_end_time": "2018-08-02 15:18:25"
    }
  ]
}

Refund API
POST

For a period after a payment transaction has been completed and a refund is required by either the Payer or Vendor, the vendor can refund the Payer via this API. After the WeChat payment system receives and verifies the refund request successfully, the Payer will be refunded with the request refund amount according to the refund rules.

Note:

1. For any transaction completed more than 3 months prior, a refund is not supported.

2. A refund for a transaction can be processed in the form of multiple partial refunds. In this case, the original order number is required and multiple refund numbers must be set. The total amount cannot exceed the original payment amount. If the refund request is failed, please use the same out_refund_no for retrying. Don’t update the refund order No.

3. The total number of partial refunds should be less than or equal to 10.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
method Request Method TEXT(128) M Fixed as: pay.orderrefund
merchant_no Merchant No. TEXT(32) M Merchant ID. It is generated by SnapPay system. It is used to identify the merchant.
out_order_no Merchant Order No. TEXT(64) M Original Order No. from the Merchant System.
out_refund_no Merchant Refund No. TEXT(64) M The Refund transaction No. in the Merchant’s system. It has to be unique for each merchant. For multiple refund requests with the same refund No., only one refund can be processed.
refund_amount Refund amount AMOUNT M Refund amount for this refund request
refund_desc Refund reason TEXT(64) O Eg. Sold out.
extension_parameters Extension parameters TEXT(JSON Format) O This is for extended parameters. The new parameters can be stored in this JSON.

Response Parameters

Common Parameters

Refer to Response - Common Parameters

Service Parameters

When code=0, data[0] returns the following parameters:

KEY Name Type Mandatory Description
trans_no Transaction No. TEXT(32) M SnapPay’s transaction No.
out_order_no Merchant Order No. TEXT(64) M Original Order No. from the Merchant System.
out_refund_no Merchant refund No. TEXT(64) M The Refund transaction No. in the Merchant’s system.
trans_status Transaction Status TEXT(8) M Transaction status
REFUNDING - transaction created, waiting for refund
CLOSE - transaction closed, refund failed.
SUCCESS - Refund success

When trans_status is SUCCESS，data[0] returns the following parameters:

KEY Name Type Mandatory Description
refund_trans_no Refund No. TEXT(32) M The refund transaction No. given by SnapPay’s Open Service Gateway
refund_trans_end_time Refund completed time DATE M

Query Exchange Rate

POST Try JavaTry PHP
RequestsWeChatPayAliPay
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.exchangerate",
  "basic_currency_unit": "CAD",
  "payment_method": "WECHATPAY"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "exchange_rate": "5.21"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "app_id": "6bf9403d0c97bd24",
  "format": "JSON",
  "charset": "UTF-8",
  "sign_type": "MD5",
  "sign": "7e2083699dd510575faa1c72f9e35d43",
  "version": "1.0",
  "timestamp": "2018-08-02 15:16:51",
  "method": "pay.exchangerate",
  "basic_currency_unit": "CAD",
  "payment_method": "ALIPAY",
  "pay_type": "ONLINE"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "code": "0",
  "msg": "success",
  "sign": "u897whekrh38h2h8363udg46hh8745hd",
  "total": 1,
  "psn": "11109748736492756478",
  "data": [
    {
      "exchange_rate": "5.21"
    }
  ]
}

Query Exchange Rate
POST

Query the reference exchange rate from a specified currency to CNY. Currently it supports WeChat Pay, and AliPay Online or Offline mode.

Request Parameters

Common Parameters

Refer to Request - Common Parameters

Service Parameters

KEY Name Type Mandatory Description
method Request Method TEXT(128) M Fixed as: pay.exchangerate
basic_currency_unit Currency code TEXT(8) M Eg, CAD, USD
payment_method Payment Method TEXT(16) M Currently Supports: ALIPAY WECHATPAY
pay_type Payment Type TEXT(16) O AliPay only, currently supports:
ONLINE
OFFLINE
ONLINE is used if not specified

Response Parameters

Common Parameters

Refer to Response - Common Parameters

Service Parameters

When code=0, data[0] returns the following parameters:

KEY Name Type Mandatory Description
exchange_rate Exchange rate TEXT M Eg, 6.917600

Created by SnapPay Inc. on 15 Jul 2020