Back to top

SnapPay OpenAPI

Getting Started

Audience

This API development guide is targeted for Architect, Developers, QA, DevOps who are responsible for the merchant’s payment enablement and system integration.

Development Guide

First find the payment scenario you want to support for your business.

Integration Steps

Test Parameters

For testing, you can use the test merchant account, including:

  • Test Merchant ID

  • Test Store Number (only if you are using the offline in-person payment scenario)

  • Test AppID

  • Test MD5 Sign key

To find the test parameters, click here.

Merchant Parameters

Before you go live, you can replace the test parameters with your real merchant parameters.

These parameters (Merchant ID, AppID, MD5 Sign Key) can be found on your merchant dashboard by following these steps:

  1. Login to the merchant portal, using the email address you provided to SnapPay.

  2. Click ‘Payment Service’ on the left menu.

  3. Click ‘Service List’

  4. Find ‘Open API Integration’ . In the ‘Security Management’ section, click ‘Click to show’

  5. Enter your login password

  6. You will see the App ID and the MD5 Sign key.

MD5 Sign Key MD5 Sign Key

To find your Merchant ID,

  1. Login to your merchant portal, click ‘Accounts’ from the left menu.

  2. Click ‘Merchant Information’.

  3. You will find the Merchant ID in this page.

If you have trouble getting the Merchant ID/AppID/Sign Key, please contact SnapPay Customer Service.

Don’t forget to switch to our production access node before going live.

Technical Support

For technical issues, please contact customerservice@snappay.ca

For merchant account set up related question, please contact SnapPay customer service: 1(888) 660-7729

Version Update

  • December, 2018.
    Uploaded the API documents.

  • March, 2019.
    Updated the Website payment scenario, WeChat H5 Payment scenario.

  • June, 2019.
    Added the WeChat and Alipay In-app Purchase support.

  • November, 2019.
    Reformated API document in API Blueprint.
    Added WeChat Mini program payment scenarios.

Payment Scenarios

1. Barcode (Scanning) Payment

Barcode Payment is also referred as Scanning Payment. It is an offline QR payment scenario.

The merchant will use the POS terminal or the Scanner to scan the customer’s QR code displayed on WeChat/Alipay App to conduct payment. The user only needs to display the QR code. The rest of the operations is done by the merchant.

Scenario Introduction

The following steps uses WeChat as an example to explain the Barcode payment scenario. Alipay flow is very similar to the WeChat payment flow.

Step 1: After logging into WeChat, the payer enters “Me”->“Wallet”->“Money” as shown in image 1 and image 2.

Step 2: Cashier creates a transaction order and the payer confirms the payment amount on the Mobile App.

Step 3: Cashier scans the customer’s QR code using the POS terminal or the Scanner. Merchant’s POS system will submit the transaction order to the OpenAPI gateway.

Step 4: After the payment request is received by WeChat’s transaction system, the transaction system determines if the payer’s password must be verified. If the payment password is not required, the payment is made directly. Otherwise, the payer is prompted to enter the password. If the payment is successful, the payer will see a ‘successful payment’ message in WeChat as shown in image 3. If the payment fails, a payment error page will be displayed instead.

Screens

Payment Workflow

Workflow

Detailed payment workflow

  1. Cashier scans the payer’s QR code (Barcode) displayed on WeChat or Alipay App.

  2. The scanner uploads the Barcode information to the Merchant Cashier Application.

  3. The Cashier Application creates the order.

  4. The Cashier Application submits the payment request to the Merchant Backend.

  5. The Merchant Backend calls the Barcode (Scanning) API to submit the payment request to SnapPay’s Open Service Gateway.

  6. SnapPay’s Open Service Gateway verifies the payment request and submits the request to WeChat/Alipay server.

  7. WeChat/Alipay server handles the payment and prompts the user to enter the password if needed.

  8. WeChat/Alipay server returns the payment result to SnapPay’s Open Service Gateway. (If password is required, it returns the transaction status as “In-process”.)

  9. SnapPay’s Open Service Gateway returns the payment result to Merchant Server. (If password is required, it returns the transaction status as “In-process”.)

  10. Merchant Server returns the result to the Merchant Cashier Application to show the result to the cashier.

  11. WeChat/Alipay notifies the payer’s app regarding to the payment result asynchronously.

  12. For Status Unknown transactions, the Open Service Gateway will Query the transaction status.

  13. For Status Unknown transactions, Merchant Server will Query the transaction Status from SnapPay gateway. Please refer to the Query Order API for more details.

  14. When payment is successful, the Open Service Gateway will notify the Merchant Server Asynchronously. Please refer to the Asynchronous Notification for more details.

Merchant side recommended implementation process

Workflow

If code = 0, trans_status = USERPAYING

Cashier’s POS system should wait for 5 seconds and then iteratively calls the Query Order API to check the transaction status. The cashier’s POS system can query for 1 min - 2 min. If the user is still trying to enter the password after the query process expires, the cashier’s POS system can display two options: Continue waiting and Cancel.

If code = 0, trans_status = CLOSE

Treat this transaction as failed.

Cashier can choose to initiate a new transaction.

If code = 0, trans_status = SUCCESS

Treat this transaction as succeeded.

Cashier’s POS system displays the success message.

If code != 0

Treat this transaction as failed.

Cashier can choose to initiate a new transaction.

If code != 0 due to system error, there is no need to do the automatic queries.

If no response is received from SnapPay due to timeout between Tender System and SnapPay

Cashier’s system should call Query Order API or give the option to the cashier to manually trigger the Query.

Additional Notes regarding to the system error

when system error happens, 99.99% of the chance the transaction failed. There is 0.01% chance that the transaction went through on the user’s phone, but money will return to the user’s account shortly after automatically.


2. Transaction QR Code Payment

Transaction QR Code Payment refers to the Scenario when the user opens the Alipay/WeChat app to scan the QR code displayed on the Merchant’s portal. This scenario can be used for in-store payment or Online E-commerce payment.

Scenario Introduction

The following instructions use Alipay payment as an example. WeChat payment scenario is very similar.

Payer scans the QR code displayed on the Merchant’s portal or POS terminal to conduct payment.

Step 1: Merchant will display the QR code on the POS terminal, a customer facing screen, or the website for the user to scan.

Step 2: Payer uses the “Scan” function from the Alipay App, scans the QR code, and views the transaction amount.

Step 3: Payer confirms payment by entering the password or through face recognition (if needed).

Step 4: Payment success message will be displayed on the App.

Workflow

Payment workflow

Workflow

Detailed payment workflow

  1. Cashier creates an order.

  2. Merchant Cashier Application submits the payment request to Merchant Server.

  3. Merchant Server calls the Transaction QR Code Pay API to submit the pre-Pay request to SnapPay’s Open Service Gateway.

  4. SnapPay’s Open Service Gateway verifies the pre-Pay request and submits the request to WeChat/Alipay server.

  5. WeChat/Alipay server returns the QR code information to Open Service Gateway.

  6. Open Service Gateway returns the QR code information back to the Merchant server.

  7. Merchant Server returns the QR code to the Cashier Application.

  8. Cashier Application displays the QR code to the Payer.

  9. Payer scans the QR code using the “Scan” function from his WeChat/Alipay App.

  10. WeChat/Alipay server handles the payment request, prompts the user to enter the password if needed.

  11. WeChat/Alipay notifies the Payer about the payment result asynchronously on his App.

  12. For Status Unknown transactions, Open Service Gateway queries the transaction result.

  13. For Status Unknown transactions, Merchant Server queries the transaction result. Please refer to the Query Order API.

  14. If payment is successful, Open Service Gateway will notify the Merchant Server Asynchronously. Please refer to the Asynchronous Notification for more details.


3. WeChat In-app Web-based/H5 Payment

WeChat In-app Web-based Payment, also called Offical Account Payment. The buyer opens the merchant’s HTML5 pages on their WeChat app in the mobile device and calls the WeChat payment module via the JSAPI interface to pay their transaction. This mode applies in the following scenarios:

  • The buyer enters the Vendor’s official account and completes payment on the transaction page.

  • The buyer’s friend shares the payment URL in a chat or in Moments and the buyers clicks the link to complete their payment.

  • The buyer scans the payment QR code displayed within the merchant’s page and opens it in a browser to complete their payment.

This API also support AliPay payment, and the payment process is similar to WeChat.

Scenario Introduction

Step 1: Merchant sends the link of his website via WeChat chat window; The buyer clicks the link and opens the merchant website.

Step 2: The buyer enters the shopping pages, chooses the product and clicks to pay.

Step 3: Merchant’s web page calls SnapPay’s H5 payment address, SnapPay’s server will call WeChat’s payment module, the user will enter the payment password.

Step 4: Once password is verified, payment is done. Merchant’s server will receive the notification from SnapPay.

Screens

Interaction Details

The following are the interaction details. Please read carefully when designing the merchant page logics.

  1. Buyer opens the merchant page to choose the products, initiate payment. The webpage will call SnapPay interface with JavaScript and send WeChat payment request. The user enters into the payment flow.

  2. When the user finishes the payment and clicks ‘DONE’, it will return back to the merchant web page. Merchant can directs to a static payment success page to show the result.

  3. Merchant server will receive the Asynchronous notification from SnapPay, notifying that the payment is successful.

Please note that step 2 and 3 can happen in any sequence. The frond end page change can signal the merchant web page’s redirect, however, merchant can only treat this payment to be successful after receiving the asynchronous notification from SnapPay.

Detailed Payment Flow

Workflow

Detailed flows

  1. The buyer visits the merchant’s H5 pages inside WeChat’s browser and creates an order.

  2. The merchant website submits the order request to the merchant server.

  3. Merchant server submits the Prepay request to SnapPay using H5 Payment API.

  4. SnapPay server verifies the request, saves the order information, returns SnapPay’s H5 cashier webpage URL to the merchant server.

  5. Merchant server returns SnapPay’s H5 cashier webpage URL to the merchant front end.

  6. Merchant frontend will go to SnapPay H5 page.

  7. SnapPay’s H5 page will submit the PrePay request to SnapPay server.

  8. SnapPay server will submit the PrePay request to WeChat server.

  9. WeChat server returns the payment information.

  10. SnapPay server returns the payment information to SnapPay’s H5 page.

  11. SnapPay’s H5 page will wake up WeChat’s payment module using JSSDK.

  12. WeChat App sends the payment request to the WeChat server.

  13. WeChat Server handles the request and asks to enter the password if needed.

  14. WeChat returns the payment result asynchronously.

  15. For unknown status, SnapPay server will query the payment result.

  16. For unknown status, Merchant server needs to query the SnapPay server for the payment result. Refer to Query Order API

  17. If payment is successful, SnapPay server will return the payment success via Asynchronous notification. Refer to Asynchronous Notification


4. Native App Payment

This is for integrating Alipay/WeChat pay functions in merchant’s native mobile applications.

Merchant App will call the SDK provided by Alipay/WeChat, SDK will call the payment module from Alipay/WeChat pay. When the transaction is completed, it will be redirected to Merchants’ App, where the payment result is displayed.

The supported OSs include iOS, Android.

Scenario Introduction

The following uses Alipay as an example. It introduces the in-app payment scenarios. WeChat and Alipay are very similar.

Step 1: The user chooses the merchandize in the merchant app, confirms the order, enters the payment flow, choose Alipay, clicks Confirm, as in picture 1.

Step 2: Wakes up the Alipay payment module and shows the payment confirmation page, as in picture 2.

Step 3: The users enters the password as in picture 3.

Step 4: Alipay display the success message as in picture 4.

Step 5: Redirects to the merchant App. Merchant can customize the success page.

Workflow

Interaction Details

The following is the interaction details for Alipay. Read carefully when designing the merchant page logic.

  1. The user opens the merchant APP and selects products, initiates the payment. Merchant backend calls SnapPay open API, initiates the Alipay payment request. The user enters the payment flow.

  2. When the user finishes the payment, merchant backend calls SnapPay’s Query API to check the result. If it succeeds, display the payment success page. If it fails, shows the payment failed page.

  3. Merchant backend will receive the asynchronous notification from SnapPay open API indicating the payment is successful.

Note: 2 and 3 might happen in any sequence. Either 2 or 3 can be used to confirm a successful payment.

Payment Workflow

Alipay Payment flow chart

Workflow

Detailed payment work flow

  1. The user browses the products in the merchant app. Merchant App triggers the Create Order event.

  2. Merchant backend calls Native APP Pay API to submit the Prepay request to SnapPay Open API gateway.

  3. Open API Gateway returns the Order info to the merchant server synchronously.

  4. Merchant server returns the Order Info to the merchant App.

  5. Merchant App calls the Alipay App using the responses returned by SnapPay gateway.

  6. Alipay SDK will send the payment request to Alipay server based on the Order info.

  7. Alipay backend processes the payment request, asks the user to enter the password if needed.

  8. Returns the payment result to the Alipay SDK.

  9. Alipay SDK will return the result to the merchant App.

  10. Merchant App queries the result from the merchant server.

  11. Merchant server calls the Query API using Query Order API

  12. SnapPay Open API gateway sends the query request to Alipay.

  13. Alipay returns the payment result synchronously.

  14. SnapPay Open API gateway returns the payment result to the merchant server.

  15. Merchant server returns to the merchant App. App displays the payment result to the user.

  16. If the payment is successful, Alipay will return the payment result asynchronously to SnapPay payment gateway.

  17. SnapPay gateway will return the result to the merchant server Asynchronously. Refer to Asynchronous Notification

WeChat Payment Flow Chart

Workflow

Detailed payment workflow

  1. The user browses the products in the merchant app. Merchant App triggers the Create Order event.

  2. Merchant backend calls Native APP Pay API to submit the Prepay request to SnapPay Open API gateway.

  3. Open API Gateway authenticates the request, sends the Prepay request to WeChat server.

  4. WeChat servers returns the Prepay Order Info synchronously to the Open API Gateway.

  5. Open API Gateway sends the Prepay Order Info to the merchant server synchronously.

  6. Merchant server returns the order info to the merchant App.

  7. Merchant App wakes up the WeChat app using the returned Order Info.

  8. WeChat SDK will send the payment request to WeChat server.

  9. WeChat server processes the request. It will ask the user to enter the password if necessary.

  10. Interface returns the payment result to WeChat SDK.

  11. WeChat SDK will send the payment result to merchant App.

  12. Merchant App will send the Query Order request to the merchant server.

  13. Merchant server sends the query order request to the SnapPay gateway. Refer to Query Order API.

  14. Open API Gateway sends the query request to the WeChat server.

  15. WeChat returns the payment result synchronously.

  16. SnapPay Open API gateway returns the payment result to the merchant server.

  17. Merchant server returns the result to the merchant App. App displays the payment result to the user.

  18. If the payment is successful, WeChat will return the payment result asynchronously to SnapPay payment gateway.

  19. SnapPay gateway will return the result to the merchant server Asynchronously. Refer to Asynchronous Notification

WeChat In-App Application procedure

In order for the merchant to enable the WeChat Pay function in their App, the following procedures need to happen before development.

  1. Merchant needs to apply an account in WeChat Open Platform website: https://open.weixin.qq.com/

  2. Once it passes the WeChat approval, register the Mobile APP service. Merchant will then receive the APPID.
    For more details, please refer to: https://pay.weixin.qq.com/wiki/doc/api/app/app_sl.php?chapter=8_5

  3. Once the merchant receives the APPID, send APPID and Company Name (recommend same as Company Name when merchant registered on SnapPay) to SnapPay Customer Service customerservice@snappay.ca. SnapPay will contact WeChat to combine the APP ID with merchant account.

  4. Once SnapPay notifies you the setup is complete, Merchant can start development.

Where to get Company Name for Mobile APP on in WeChat Open Platform website.

screenshot
Example

For example, SnapPay will send the following info to WeChat Support 

    SnapPay Institution Information:
    Merchant ID:1234567890 
    Institution Name:Snappay
    Official Account:wx1234567890abcdef

    Merchant APP Information:  
    Mobile APPID: wx0987654321abcdef
    Sub Merchant ID: 123456789
    Company Name: Super Merchant Inc.

5. Website Payment

Website payment is offered by AliPay and China UnionPay to pay for online merchants.

It gives your buyers a simplified and secure payment experience that keeps them local to your website throughout the payment process. Once integrated the Alipay or China Union Pay online payment service, you should present an Alipay or China UnionPay payment button on your website for the consumer to complete the payment and check out.

Once the customers click the check out button, the website will be redirected to Alipay or China UnionPay’s cashier page. The customers enter the account information to complete payment.

Scenario Introduction

We use Alipay as an example. China UnionPay offers a similar user flow.

Step 1: The buyer chooses the products, and puts them in the shopping cart. The buyer clicks the Alipay button. As in picture 1.

Step 2: The page will be redirected to Alipay’s third-party cashier page.

Step 3:

  • The buyer can use the Alipay App to scan the QR code, enter the username and password to complete payment. As in picture 2.

  • Or if the buyer doesn’t use the mobile device, he can click the ‘Login to Pay’ button, enter Alipay Account’s username and password to login. As in picture 3.

  • After login, the buyer will see exchange rate, account balance, payment account, and some other information. If the buyer enters the payment password, confirms the payment, the payment result will be returned afterwards.

Step 4: Payment success.

Product

Select products and add to cart

Scan

Scan QR

Login

Enter Alipay user name and password.

Detailed Payment Flow

Workflow

Detailed flows

  1. The buyer views the products and creates an order.

  2. Merchant website (buyer browser) submits the Payment Order request to the Merchant server.

  3. Merchant server submits the Prepay request to SnapPay’s server using the Website Payment API.

  4. SnapPay server verifies the payment request, submits the PrePay request to Alipay/UnionPay server.

  5. UnionPay / Alipay server returns the payment result to SnapPay’s server synchronously.

  6. SnapPay server returns Alipay / UnionPay’s web URL to the merchant server.

  7. Merchant server returns Alipay / UnionPay’s URL to the merchant website (buyer browser).

  8. Merchant website (buyer browser) redirects to Alipay / UnionPay’s third party payment web page.

  9. Alipay / UnionPay’s server handles the request. If payment successful, buyer browser redirects to the merchant’s success page.

  10. If the transaction status is unknown, SnapPay server will query the payment result.

  11. If the transaction status is unknown, merchant server will query the payment result. Refer to Query Order API.

  12. If the payment is successful, SnapPay server will notify the merchant server asynchronously. Refer to Asynchronous Notification.


6. WeChat Mini Program Payment.

At present, we can only use the method of mini program payment API to invoke WeChat payment.

Scenario Introduction

Step 1: The buyer chooses the products in merchant’s mini program, and puts them in the shopping cart. The buyer clicks the checkout button. As in picture 1.

Step 2: Mini program will invoke WeChat payment module. The user will enter the payment password.

Step 3: Once password is verified, payment is done. Merchant’s server will receive the notification from SnapPay.

Product

chooses the products

Scan

invoke WeChat payment module

Detailed flows

  1. The buyer views the products and creates an order in merchant’s mini program.

  2. Merchant mini program submits the Payment Order request to the Merchant server.

  3. Merchant server submits the Prepay request to SnapPay’s server using the Mini Program Payment API.

  4. SnapPay server verifies the payment request, submits the PrePay request to WeChat server.

  5. WeChat server returns the payment result to SnapPay’s server synchronously.

  6. SnapPay server returns the payment result to the merchant server.

  7. Merchant server returns the payment result to the merchant mini program.

  8. Merchant mini program invoke WeChat payment.

  9. WeChat server handles the request. If payment successful, the payment result will be returned to merchant mini program.

  10. If the transaction status is unknown, SnapPay server will query the payment result.

  11. If the transaction status is unknown, merchant server will query the payment result. Refer to Query Order API.

  12. If the payment is successful, SnapPay server will notify the merchant server asynchronously. Refer to Asynchronous Notification.

WeChat Mini Program Application procedure

In order for the merchant to enable the WeChat Pay function in their mini program, the following procedures need to happen before development.

  1. Merchant needs to apply an account in WeChat Official Accounts Platform website: https://mp.weixin.qq.com

  2. Once it passes the WeChat approval, register the Mini Program service. Merchant will then receive the APPID.
    For more details, please refer to: https://developers.weixin.qq.com/miniprogram/introduction

  3. Once the merchant receives the APPID, send APPID and Company Name (recommend same as Company Name when merchant registered on SnapPay) to SnapPay Customer Service customerservice@snappay.ca. SnapPay will contact WeChat to combine the APP ID with merchant account.

  4. Once SnapPay notifies you the setup is complete, Merchant can start development.

Where to get Company Name for Mini Program on in WeChat Open Platform website.

screenshot
Example

For example, SnapPay will send the following info to WeChat Support 

    SnapPay Institution Information:
    Merchant ID:1234567890 
    Institution Name:Snappay
    Official Account:wx1234567890abcdef

    Merchant Mini Program Information:  
    Mini Program APPID: wx0987654321abcdef
    Sub Merchant ID: 123456789
    Company Name: Super Merchant Inc.

API Documents(openapi.html)

Created by SnapPay Inc. on 15 Jul 2020