× 中文
Overview

Request And Parameters

Sign Algorithm

Success Notification

Refund Notification

QR Code Payment
Create QR Code Payment     - QR Payment in AlpayPay
UnionPay/Alipay Online
Create UnionPay/Alipay Online Order
JSAPI
Create JSAPI Order     - WeChat Pay JSAPI     - Alipay JSAPI Create Native JSAPI Order
Mobile H5
Create H5 Payment     - H5 Rediret
APP - SDK
Create SDK Order
Mini Program
Create Mini Program Order
Retail Payment
Retail Passive Payment Retail Active Payment
Common API
Get Current Exchange Rate Query Order Status Apply For Refund Query Refund Order Status Check Orders Query Daily Transactions Query Settlement Details Suspend Settlement Release Suspended Settlement

Overview



Prepare


  • Before starting technology integration, merchants need to sign a contract with AlphaPay for related products. For assistance, please contact AlphaPay Business Team.
  • Merchants get the Partner Code and Credential Code for test.
  • Integrating APP and Miniprogram Payment should provide APPID to AlphaPay.
  • Please select the current trading currency:   CAD     USD


Payment Scenarios









Different Channel


According to different Api used, Channel was distributed to Retail channel and Online channel. Each channel has a different exchange rate and surcharge rate:
  • Online Channel: QR CODE, Web, JSAPI, H5, APP SDK, MiniProgram
  • Retail Channel: Including Retail Pay
Difference：
  • JSAPI and H5 Mobile: JSAPI can only be called in the webpage opened in WeChat/Alipay Client. H5 Mobile can call the payment panel in any browser or webview in App in the mobile device.
  • Online Payment and QR Code: Online payment will redirect to UnionPay/Alipay Official payment page. Customers can scan the QR Code displayed on the webpage or sign in their accounts directly to finish the payment. Merchants can display the QR Code on their webpage or redirect to AlphaPay to display the QR Code. Customers can only scan the QR Code with their UnionPay/Alipay Client to finish the payment.


Currency Codes


AlphaPay can only accept the following currencies at the moment. Please note that the settlement currency will always be Canadian Dollar:
  • CAD
  • CNY


Business Roles


  • QR Code Payment displays a QR code image on a webpage. Customers will scan the code via their WeChat and complete the payment on the following webpage. It is the solution for online shopping websites.
  • JSAPI Payment redirects customers to a webpage in WeChat/Alipay. This page can only be opened within the WeChat/Alipay app and it is the solution for payment from micro-shops on the WeChat/Alipay platform.
  • Retail passive payment (Scan Payment QR Code or BarCode from customers’ WeChat/Alipay/UnionPay Wallet) and active the payment (Generate Payment QR Code for customers to scan) is used in retail environments such as payment terminals and POS machines.
  • Order_id is required when creating an order. Please do not create multiple orders with the same order_id.
  • QR Code order creation will return the QR Code and pay_url. Merchants may decide whether to display the QR code on their website or to redirect the customer to the payment page available at pay_url.
  • JSAPI order creation will return pay_url. Merchants shall redirect the customer to the payment page available at pay_url, and complete the payment.
  • When redirecting to pay_url, sign data is required.
  • Each request shall use new timestamp, nonce_str, and sign.
  • Our system will notify the caller after an order is paid successfully if notify_url was provided when creating an order. Otherwise, Merchants shall call the order query method repeatedly until the order is paid or closed.
  • Each unpaid order will be valid for 5 minutes. Expired order can be renewed with same the order id. It is suggested to trigger the event when the user opens the payment page again. The unpaid order valid time can be changed in the login.
  • Always redirect to AlphaPay’s payment page after calling the order creation method.
  • The same order id is only allowed when creating a new payment order and creating a refund order but order details shall refer back to the initial request details.
  • Price is specified in the base unit of the given currency. Using currency CAD as an example, 105 means 105 cents or $1.05.




















API Endpoint


https://pay.alphapay.ca/api/v1.0

Request And Parameters



Parameters Format


Request for payment or refund shall use the PUT method. Request for querying order shall use the GET method. All requests including Request Entity are in JSON format.
Accept in the request header shall be set to application/json for all requests except redirect pages. Content-Type in the request header shall be set to application/json for all PUT/POST requests.
The system charset is UTF-8.

There are 3 groups of parameters：Path Variable/Query Param/JSON entity
  • Path Variable: included in the path as patterns
  • Query Param: parameters after the URI '?' symbol and formatted like key=value
  • JSON entity: only used in PUT/POST requests

Our API server will return 200 in JSON if the request has successfully reached the server, which does not indicate the success or failure of the actual operation.
All responses in JSON format will include a return_code field which contains the operation result.
  • The value SUCCESS indicates that the operation was successful while other values show the type of error that happened.
  • Response will also contain a return_msg field for the detailed error message.

Transport Layer Security


Only TLS 1.2 is supported.


Multi-Language


The system error message supports Simplified Chinese and English. The system by default will automatically choose the language according to the Accept-Language value in the request header. Cookie "locale" value (zh-CN or en-US) will affect the resulting language.






Sign Algorithm



Sign messages are required in each request for validation. Sign parameters are all attached to URL as query params, and the order is irrelevant.


Sign Process：

  1. Connect 4 parameters with '&' symbol into an original valid string. Escape value is not required.
    valid_string = partner_code&time&nonce_str&credential_code
    valid_string=TestPay&1468691301081&aaf2a94c8c2d56d5b43a1a3d9d811102&pQ5Jc9eoTcsxqPY5uQ3p2WmvSy0zEYeP
    Parameters:
    • partner_code: Code for partner, including four uppercase letters or numbers.
    • time: UTC timestamp in milliseconds. Take the current timestamp of UTC. The data type is Long. The difference between time and AlphaPay server time should be less than 5 minutes.
    • nonce_str: Random number and string. No limit for length. URL-Safe characters are required. The proposed length is 10-30 characters.
    • credential_code: Partner credential code for development provided by AlphaPay system. Keep it safe and never disclose it to the public. If compromised, contact us to change it.

  2. Sign the valid string with SHA256 and turn to lowercase Hex string
    3. sign=hex(sha256(valid_string)).toLowerCase()
  3. Include the time,nonce_str and sign into Query Param when calling api
    4. time=1468691301081
    nonce_str=123
    sign=64712672795f94fa3bfb2e88ac09cb75d09bcf8a3c3dcaa529d8290dd6587060





Success Notification - Asynchronous Notification



If notify_url is provided when order is created. The system will post the JSON package to this URL when payment succeeds. Different from Server APIs, sign parameters will be included in the JSON entity. The merchant system shall valid them to prevent fake requests. The system will retry the notification up to 3 times. The merchant system shall be able to handle the repeated requests. Use POST to get the returned JSON data.



JSON

Field Type Description
time Long UTC timestamp in millis
nonce_str String Random string
sign String Sign, use time and nonce_str to get sign and check if this sign equals to the sign you make
partner_order_id String Partner order id
order_id String AlphaPay order ID
total_fee String Order amount
real_fee String Actual paid amount
rate Double Exchange Rate used while trading, 1CAD=?CNY
currency String Currency
channel String Payment Channel Alipay, Wechat, UnionPay
create_time String Time when order is created(according to the latest order)(yyyy-MM-dd HH:mm:ss, UTC-8)
pay_time String Time when order is paid(yyyy-MM-dd HH:mm:ss, UTC-8)


Double guarantee to make sure payment success


  1. Asynchronous Notification：When the payment is successful, AlphaPay server will push the payment success data to the merchant server.
  2. Query order status activly：Obtain order status by querying the order status API on the redirect page.
    • Orders need to be queried several times to prevent data from not being updated














Refund Notification - Asynchronous Notification



If notify_url is provided when refunding. The system will post the JSON package to this URL when refund completes. Different from Server APIs, sign parameters will be included in the JSON entity. The merchant system shall valid them to prevent fake requests. The system will retry the notification up to 3 times. The merchant system shall be able to handle the repeated requests. Use POST to get the returned JSON data.



JSON

Field Type Description
amount int Refund amount
nonce_str String Random string and number, for validation
channel_refund_id String Channel Refund id, it will show if it has
sign String Sign of the refund order, for validation
channel String Payment channel, Wechat, Alipay or UnionPay
currency String Refund currency
result_code String
  • WAITING: Order is being submitted
  • CREATE_FAILED: Fail to submit
  • SUCCESS: Submission succeeded
  • FAILED: Refund failed
  • FINISHED: Refund success(funds has already been returned to user's account)
  • CHANGE: Refund can not return to user's account. Manual operation is required
time String UTC timestamp in milliseconds, for validation
refund_id String AlphaPay Refund id
partner_refund_id String Partner Refund id


Double guarantee to make sure refund completes


  1. Asynchronous Notification：When the refund is completed, AlphaPay server will push the refund status data to the merchant server.
  2. Query refund status activly：Obtain refund status by querying the Refund status API after applying.
    • Refund orders need to be queried several times to prevent data from not being updated
















JSON Example


{
      "amount": 1,
      "nonce_str": "ML9wwG7pb9otbAu",
      "channel_refund_id": "50000503822020030515001953629",
      "sign": "6e06db070d87f3abeb26427a55af16849bec5002346dad4a1dbbb2488a571175",
      "channel": "Wechat",
      "currency": "CAD",
      "result_code": "SUCCESS",
      "time": "1675325195148",
      "refund_id": "ZZZ6R20200304163001069H5HILC9JBW",
      "partner_refund_id": "ZZZ620200304151231",
}






QR Code - Create QR Code Payment



QR Code Payment is used for webpage/application on PC or mobile. Customers use WeChat, Alipay or UnionPay app to scan the QR Code generated when creating order and finish the payment.


PUT
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}


Integration Process






The return value contains a QR Code string, QR Code image and pay_url. Merchants can decide how to finish the payment. Pay_url should contain Sign (Details on Sign) If the currency is CNY, the equivalent CAD amount shall never less than 0.01CAD, otherwise, the user will get Invalid Amount Error from WeChat when making the payment.



Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order.(Maximum length 50 characters)


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent CAD 1.00).
currency String Currency
Default value: CAD
Allowed values: CAD , CNY
channel String Payment channel, case sensitive
Allowed values: Alipay , Wechat
notify_url String AlphaPay System will post Json Package to notify url (if provided) when the payment succeeds. (Details on Payment Success Notification)
operator String Note for the operator who created this order.


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
partner_order_id String Partner order id
full_name String Partner's full company name when registered
partner_name String Partner's name
channel String Payment channel
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
order_id String Order id in AlphaPay
return_code String Execution result
code_url String QR Code string. Partners can create the payment QR Code according to this value.
pay_url String Payment page in AlphaPay
qrcode_img String QR Code image formatted in Base64. Can be used as the src attribute on img element


Error Code

Name Description
ORDER_MISMATCH Order is not belong to this partner.
ORDER_PAID Order has already been paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description


Two ways to display the QR code for payment


  1. Show Qr Code on Partner Webpage, use
    • qrcode_img: QR Code image formatted in Base64. It can be used as the src attribute on img element
    • code_url: QR Code string. Partners can create the payment QR Code according to this value.
  2. Redirect to AlphaPay Payment Page (need to add parameters, details on QR Code Payment Page in AlphaPay.













Requeset Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/ZZZ620200303133408?time=1583271769776&nonce_str=123&sign=2456084a967ca84b0e3d9a4e26d99ddc2ef040ac3b611e9a3349ed2d24da1ac7




























































Request JSON


{
      "description": "DEVELOPER TEST",
      "price": 1,
      "currency": "CAD",
      "channel": "Wechat",
      "notify_url": "www.alphapay.com/success.php",
      "operator": "dev01"
}




















Response Example


{
      "partner_order_id": "ZZZ620200303133408",
      "full_name": "Hello Alpha Pay",
      "code_url": "https://pay.alphapay.ca/api/v1.0/payment/partners/ZZZ6/orders/0240520200303134355902940/retail_pay",
      "partner_name": "Hello Alpha Pay",
      "channel": "Wechat",
      "result_code": "SUCCESS",
      "partner_code": "ZZZ6",
      "order_id": "0240520200303134355902940",
      "return_code": "SUCCESS",
      "pay_url": "https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/ZZZ620200303133408/pay",
      "qrcode_img": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAACKElEQVR42u2aS27tIBBE2yMvwzu1zU5ZQoaM4HVVQZT4OtKb0sKyLGzOHaQp+kes/c/1ZQtb2MIWtrAIWDVc595uO6rfe0stn3vG1z0WhnG+iuFuPnvQDPnqU5GwbLt/zKcdifxW3BT+CitFxKAB2gQaaC0uVo6E1T9uNwXFEBGTpPFdz42/fd8LU2PdceXH/Yd/mxjT5RbYCrS9QeQd+IxZU2MegO6d/opey7SXX5Z+fowBN2nQx77BMU4tFNYYfU4svQYOQOHnQ+QBMEYfOmrI+2p9O1/MMUJhpf/tXGvfztjRzDRc/KGw2hWuHU0P5ljxVBmvkbCGzQs7MPqAacMUv+w2PyaDyE3Voe1UFIhDYap3vAqgHbLS45upssXCqg23DM/ck+TE+1Gwz451OyASjYA7xFD3aJjkzUKgZ4/QfDmCYVVVAJ8S9s1XhadomDLkvu7IkwVvLRjGLTyaaefIqU57LP30WGMzrYchNmHYQkSKZbEwNWE2TqWeMSqzOmowDEEWX5QuVqVV9M+pBcNU2SHBSGqTDhN9JBiTYyP6aKEZedleK89O4/yYvLGqOZqiHPd3URAI6401Y09Y3f43kQfA1Cz1qY0i5xMe+6Mymh/70QCn4+IPh+ZjYdy/nOURlZqKZvYSs0JgI/+HBkwHOm8GmR5T6ztRACxm4bvezrOmxngAR0d9FRWwvQ9jwbBxUKUe6Uga1SsOha1/cVnYwha2sPjYP8qU4+heQswIAAAAAElFTkSuQmCC"
}





QR Code - QR Code Payment Page in AlphaPay


This page must be called after the payment order has been created. When jumping to redirect Page, it is recommended to call the Order Query API to make sure the payment has succeeded.

GET
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/pay


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. It shall have already been created


Query Params

Field Type Description
redirect String Required, Redirect url when payment succeeded. Details on Payment Success Notification
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Error Code

Name Description
ORDER_NOT_EXIST Order does not exist
ORDER_MISMATCH Order is not belong to this partner.
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description








Redirect Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/ZZZ620200303140443/pay?redirect=http%3A%2F%2Flocalhost%2FAlphaPay_PHP%2Fexample%2Fsuccess.php%3Forder_id%3DZZZ620200303140443&time=1583273083823&nonce_str=b4toxf372pt8rqaguwkbyg8wcixy4s&sign=cb4d424cac22f15232836c730cf422222d8e8e974bb9c7b77acea3243f2056a3



UnionPay/Alipay Online Payment - Create UnionPay/Alipay Online Order


Use for UnionPay and Alipay Payment in PC Website. After creating the order, redirect to the pay_url returned and attach sign params and redirect param. Then enter the UnionPay/Alipay page to finish the payment. Only available for UnionPay and Alipay channel.


PUT
  https://pay.alphapay.ca/api/v1.0/web_gateway/partners/{partner_code}/orders/{order_id}


Integration Process







Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order.(Maximum length 50 characters)


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent CAD 1.00).
currency String Currency
Default value: CAD
Allowed values: CAD , CNY
channel String Payment channel, case sensitive
Allowed values: Alipay , UnionPay
notify_url String AlphaPay System will post Json Package to notify url (if provided) when the payment succeeds. (Details on Payment Success Notification)
operator String Note for the operator who created this order.


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
partner_order_id String Partner order id
full_name String Partner's full company name when registered
partner_name String Parter Name
channel String AlipayOnline
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
order_id String Order id in AlphaPay
return_code String Execution result
pay_url String Payment page in AlphaPay


Error Code

Name Description
ORDER_MISMATCH Order is not belong to this partner.
ORDER_PAID Order has already been paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner


ERROR

Name Description
return_code Error Code
return_msg Error Description










Request Example


https://pay.alphapay.ca/api/v1.0/web_gateway/partners/ZZZ6/orders/ZZZ620200303133409?time=1583273723299&nonce_str=123&sign=c3884addcc5a1615e8c9c1181f74b5793aef8de19385726918a54c2c3b0b051c
























































Request JSON


{
      "description": "DEVELOPER TEST",
      "price": 1,
      "currency": "CAD",
      "channel": "Alipay",
      "notify_url": "www.alphapay.com/success.php",
      "operator": "dev01"
}






















Response Example


{
      "partner_order_id": "ZZZ620200303133409",
      "full_name": "Hello Alpha Pay",
      "partner_name": "Hello Alpha Pay",
      "channel": "AlipayOnline",
      "result_code": "SUCCESS",
      "partner_code": "ZZZ6",
      "order_id": "0240520200303141625039278",
      "return_code": "SUCCESS",
      "pay_url": "https://pay.alphapay.ca/api/v1.0/alipay/partners/ZZZ6/orders/ZZZ620200303133409/web_pay"
}






Redirect to Alipay


https://pay.alphapay.ca/api/v1.0/alipay/partners/ZZZ6/orders/ZZZ620200303133409/web_pay?time=1535761172065&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=124d2ba7eca94c8adedad84aa3dd892f3558d1aa310bf702945700ecbfe54dfb


Redirect to UnionPay


https://pay.alphapay.ca/api/v1.0/web_gateway/partners/ZZZ6/orders/ZZZ620200424133655/pay?time=1587778141636&nonce_str=123&sign=85518b7c1288e967b80a7b81f53ad4ed7691ec86a47ae8f5a7a4b5f4eeea1010




JSAPI - Create JSAPI Payment Order


JSAPI Payment is used to pay on the webpage which was opened in WeChat or Alipay app. If customers enter this page from WeChat Official Account, this Official Account is required to be authorized. Customers will jump to AlphaPay order page and call WeChat or Alipay Payment Board to finish payment.


PUT
  https://pay.alphapay.ca/api/v1.0/jsapi_gateway/partners/{partner_code}/orders/{order_id}

Integration Process






The return value contains a payment page. Partners shall guide users to redirect to the page. Sign params are required when the redirect happens. If the currency is CNY, the equivalent CAD amount shall never less than 0.01CAD, otherwise, the user will get Invalid Amount Error from WeChat when making the payment.


Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order.(Maximum length 50 characters)


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent CAD 1.00).
currency String Currency
Default value: CAD
Allowed values: CAD , CNY
channel String Payment channel, case sensitive
Allowed values: Alipay , Wechat
notify_url String AlphaPay System will post Json Package to notify url (if provided) when the payment succeeds. (Details on Payment Success Notification)
operator String Note for the operator who created this order.


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
partner_order_id String Partner order id
full_name String Partner's full company name when registered
partner_name String Partner Name
channel String Payment channel
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
order_id String Order id in AlphaPay
return_code String Execution result
pay_url String Payment page in AlphaPay


Error Code

Name Description
ORDER_MISMATCH Order is not belong to this partner.
ORDER_PAID Order has already been paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description


Make a payment

pay_url needs to add parameters, details on WeChat JSAPI Payment Page or Alipay JSAPI Payment Page












Request Example


https://pay.alphapay.ca/api/v1.0/jsapi_gateway/partners/ZZZ6/orders/ZZZ620200303133410?time=1583274791491&nonce_str=123&sign=b3aad28aafc0ba0e4723457df54fc6b9b6ee7a4800a4eaaa7a49fa9a043b5b15





























































Request JSON


{
      "description": "DEVELOPER TEST",
      "price": 1,
      "currency": "CAD",
      "channel": "Wechat",
      "notify_url": "www.alphapay.com/success.php",
      "operator": "dev01"
}





















Response Example


{
      "partner_order_id": "ZZZ620200303133410",
      "full_name": "Hello Alpha Pay",
      "partner_name": "Hello Alpha Pay",
      "channel": "Wechat",
      "result_code": "SUCCESS",
      "partner_code": "ZZZ6",
      "order_id": "ZZZ6-20200303143358581-SRA6NDCRH",
      "return_code": "SUCCESS",
      "pay_url": "https://pay.alphapay.ca/api/v1.0/wechat_jsapi_gateway/partners/ZZZ6_order_ZZZ620200303133410"
}


JSAPI - WeChat JSAPI Payment Page


This page must be called after the payment order has been created. The actual URL shall be referencing to pay_url param from order creation. When jumping to the redirect page, it is recommended to call the Order Query API to make sure the payment has succeeded.


GET
  https://pay.alphapay.ca/api/v1.0/wechat_jsapi_gateway/partners/{partner_code}_order_{order_id}

Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. It shall have already been created


Query Params

Field Type Description
redirect String Required, Redirect url (Redirect to this page Whether the user pays successfully or not need to Query Order Status in rediret page)
directpay Boolean whether open direct pay mode.
Default value: false
Allowed values: true , false
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Error Code

Name Description
ORDER_NOT_EXIST Order does not exist
ORDER_MISMATCH Order is not belong to this partner.
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description






Request Example


https://pay.alphapay.ca/api/v1.0/wechat_jsapi_gateway/partners/ZZZ6_order_ZZZ620200303133410?redirect=https://www.alphapay.com/success&directpay=true&time=1535759759798&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=d976fd4bfed4d28e96b6c8600507229f666943adc5122937a0f762d3e38b3a7f



JSAPI - Alipay JSAPI Payment Page


This page must be called after the payment order has been created. The actual URL shall be referencing to the pay_url param from order creation. When jumping to the redirect page, it is recommended to call the Order Query API to make sure the payment has succeeded.


GET  https://pay.alphapay.ca/api/v1.0/gateway/alipay/partners/{partner_code}/orders/{order_id}/app_pay


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. It shall have already been created


Query Params

Field Type Description
redirect String Required, Redirect url (Redirect to this page Whether the user pays successfully or not need to Query Order Status in rediret page)
directpay Boolean whether open direct pay mode.
Default value: false
Allowed values: true , false
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Error Code

Name Description
ORDER_NOT_EXIST Order does not exist
ORDER_MISMATCH Order is not belong to this partner.
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description








Request Example


https://pay.alphapay.ca/api/v1.0/gateway/alipay/partners/ZZZ6/orders/ZZZ620200303133410/app_pay?redirect=https://www.alphapay.com/success&directpay=true&time=1535759759798&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=d976fd4bfed4d28e96b6c8600507229f666943adc5122937a0f762d3e38b3a7f




JSAPI - Create Native JSAPI Payment Order


You need to complete the principal authentication and bind the appid through AlphaPay before you can use the Native JSAPI. JSAPI parameters that use to initiate JSAPI can be returned directly when you use Native JSAPI. When you create an order through the AlphaPay platform, you can directly initiate payment through the official JS SDK.


PUT
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/native_jsapi/{order_id}

Integration Process






If the currency is CNY, the equivalent CAD amount shall never less than 0.01 CAD, otherwise, the user will get Invalid Amount Error from WeChat when making the payment.


Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order.(Maximum length 50 characters)


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent CAD 1.00).
currency String Currency
Default value: CAD
Allowed values: CAD , CNY
operator String Note for the operator who created this order.
channel String Payment channel, case sensitive
Allowed values: Alipay , Wechat
appid String WeChat official account appid (leave empty for Alipay)
customer_id String Required, WeChat official account OpenId/ Alipay UserId
notify_url String AlphaPay System will post Json Package to notify url (if provided) when the payment succeeds. (Details on Payment Success Notification)


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
partner_order_id String Partner order id
full_name String Partner's full company name when registered
partner_name String Partner Name
channel String Payment channel
sdk_params object/object[] Parameters used for WeChat/Alipay/UnionPay to envoke the payment
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
order_id String Order id in AlphaPay
return_code String Execution result
pay_url String Payment page in AlphaPay


Error Code

Name Description
ORDER_MISMATCH Order is not belong to this partner.
ORDER_PAID Order has already been paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description


Make a payment

pay_url needs to add parameters, details on WeChat JSAPI Payment Page or Alipay JSAPI Payment Page











Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/native_jsapi/ZZZ620200303133415?time=1583281314142&nonce_str=123&sign=3ab9c318b4d97811d95e542c2cb694c02e738ea3b9ff62a380857c8b43e62cec




























































Request JSON


{
      "description": "DEVELOPER TEST",
      "price": 1,
      "currency": "CAD",
      "operator": "dev01",
      "channel": "Alipay",
      "customer_id": "2080000000000001",
      "notify_url": "www.alphapay.com/success.php"
}


























Response Example


{
      "partner_order_id": "ZZZ620200303133415",
      "full_name": "Hello Alpha Pay",
      "partner_name": "Hello Alpha Pay",
      "channel": "AlipayOnline",
      "sdk_params": 
        {
          "orderStr": "service=create_forex_trade_wap&partner=2088031415022202&product_code=NEW_WAP_OVERSEAS_SELLER&_input_charset=utf-8&sign_type=MD5¬ify_url=https://pay.alphapay.ca/api/v1.0/alipay/online_orders/ZZZ6-20200528081548975-ZJRAQNONZ/notify&return_url=https://pay.alphapay.ca/api/v1.0/alipay/partners/ZZZ6/orders/ZZZ6-20200528081548975-ZJRAQNONZ/result&subject=DEVELOPER TEST&body=DEVELOPER TEST&out_trade_no=ZZZ6-20200528081548975-ZJRAQNONZ¤cy=CAD&total_fee=0.01&order_create=1590682548975&timeout_rule=10m&secondary_merchant_id=ZZZ6&secondary_merchant_name=Hello Alpha Pay&secondary_merchant_industry=5065&app_pay=Y&sign=b5986ce5a9aa8353e0875b1257ce69d4"
        },
      "result_code": "SUCCESS",
      "partner_code": "ZZZ6",
      "order_id": "ZZZ6-20200303162209092-MO10OORNM",
      "return_code": "SUCCESS",
      "pay_url": "https://pay.alphapay.ca/api/v1.0/gateway/alipay/partners/ZZZ6/orders/ZZZ620200303133415/app_pay"
}


Alipay Envoke Payment Using TradeNO


<script src="https://gw.alipayobjects.com/as/g/h5-lib/alipayjsapi/3.1.1/alipayjsapi.inc.min.js"></script>

<button id="btn-pay" class="btn btn-default">Pay</button>
<script>
  var btn = document.querySelector('#btn-pay');
  btn.addEventListener('click', function(){
    ap.tradePay({
      orderStr: 'service=create_forex_trade_wap&partner=2088031415022202&product_code=NEW_WAP_OVERSEAS_SELLER&_input_charset=utf-8&sign_type=MD5¬ify_url=https://pay.alphapay.ca/api/v1.0/alipay/online_orders/ZZZ6-20200528081548975-ZJRAQNONZ/notify&return_url=https://pay.alphapay.ca/api/v1.0/alipay/partners/ZZZ6/orders/ZZZ6-20200528081548975-ZJRAQNONZ/result&subject=DEVELOPER TEST&body=DEVELOPER TEST&out_trade_no=ZZZ6-20200528081548975-ZJRAQNONZ¤cy=CAD&total_fee=0.01&order_create=1590682548975&timeout_rule=10m&secondary_merchant_id=ZZZ6&secondary_merchant_name=Hello Alpha Pay&secondary_merchant_industry=5065&app_pay=Y&sign=b5986ce5a9aa8353e0875b1257ce69d4'
    }, function(res){
      ap.alert(res.resultCode);
    });
  });
</script>




Mobile H5 - Create H5 Payment


Notice：WeChat H5 Payment requires application.
H5 Payment is used for Mobile App or Mobile browser. The browser would redirect to a webpage from UnionPay/Alipay and call UnionPay/Alipay App to finish the payment.


PUT
  https://pay.alphapay.ca/api/v1.0/h5_payment/partners/{partner_code}/orders/{order_id}


Integration Process




The return value contains a payment page. Partners shall guide users to redirect to this page. Sign params are required. If the currency is CNY, the equivalent CAD amount shall never less than 0.01CAD, otherwise, the user will get Invalid Amount Error from WeChat when making the payment.



Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order.(Maximum length 50 characters)


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent CAD 1.00).
currency String Currency
Default value: CAD
Allowed values: CAD , CNY
channel String Payment channel, case sensitive
Allowed values: Alipay , UnionPay
notify_url String AlphaPay System will post Json Package to notify url (if provided) when the payment succeeds. (Details on Payment Success Notification)
operator String Note for the operator who created this order.


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
partner_order_id String Partner order id
full_name String Partner's full company name when registered
partner_name String Partner Name
channel String Payment channel
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
order_id String Order id in AlphaPay
return_code String Execution result
pay_url String Payment page in AlphaPay


Error Code

Name Description
ORDER_MISMATCH Order is not belong to this partner.
ORDER_PAID Order has already been paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization
SECONDARY_MERCHANT_ID_INVALID Please contact AlphaPay for more details


ERROR

Name Description
return_code Error Code
return_msg Error Description


Make a Payment

pay_url needs to add parameters, details on H5 Payment Page.












Request Example


https://pay.alphapay.ca/api/v1.0/h5_payment/partners/ZZZ6/orders/ZZZ620200303170626?time=1583284025740&nonce_str=123&sign=b40baec1a61284c5cb5c2e680109931d4589d9a9e26b56ad4ab325a4cc3e9417






















































Request JSON


{
      "description": "DEVELOPER TEST",
      "price": 1,
      "currency": "CAD",
      "channel": "Alipay",
      "notify_url": "www.alphapay.com/success.php",
      "operator": "dev01"
}























Response Example


{
      "partner_order_id": "ZZZ620200303170626",
      "full_name": "Hello Alpha Pay",
      "partner_name": "Hello Alpha Pay",
      "channel": "Wechat",
      "result_code": "SUCCESS",
      "partner_code": "ZZZ6",
      "order_id": "ZZZ6-20200303170716961-3VEYBVEFN",
      "return_code": "SUCCESS",
      "pay_url": "https://pay.alphapay.ca/api/v1.0/h5_payment/partners/ZZZ6/orders/ZZZ620200303170626/pay"
}




Mobile H5 - H5 Payment Page


This page must be called after the payment order has been created. When jumping to the redirect page, it is recommended to call the Order Query API to make sure the payment has succeeded.


GET
  https://pay.alphapay.ca/api/v1.0/h5_payment/partners/{partner_code}/orders/{order_id}/pay


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. It shall have already been created


Query Params

Field Type Description
redirect String Required, Redirect url (Redirect to this page Whether the user pays successfully or not need to Query Order Status in rediret page)
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Error Code

Name Description
ORDER_NOT_EXIST Order does not exist
ORDER_MISMATCH Order is not belong to this partner.
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description








Request Example


https://pay.alphapay.ca/api/v1.0/h5_payment/partners/ZZZ6/orders/ZZZ620200303170626/pay?redirect=https://www.alphapay.com/success&time=1535759759798&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=d976fd4bfed4d28e96b6c8600507229f666943adc5122937a0f762d3e38b3a7f




SDK Payment - Create SDK Order


Used for mobile Apps calling WeChat/Alipay/UnionPay payment with WeChat/Alipay/UnionPay SDK. Call this API to create order and get a param string. Call SDK API with the param to start payment and get payment results from WeChat/Alipay/UnionPay app. It is recommended to call the Order Query API to make sure the payment has succeeded.


PUT
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/app_orders/{order_id}


Integration Process





Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order.(Maximum length 50 characters)


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent CAD 1.00).
currency String Currency
Default value: CAD
Allowed values: CAD , CNY
channel String Payment channel, case sensitive
Allowed values: Alipay , Wechat , UnionPay
notify_url String AlphaPay System will post Json Package to notify url (if provided) when the payment succeeds. (Details on Payment Success Notification)
operator String Note for the operator who created this order.
system String os type of client app
Allowed values: android , iphone , ipad
version String client app version
appid String WeChat appid, required for WeChat


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
partner_order_id String Partner order id
full_name String Partner's full company name when registered
partner_name String Partner Name
channel String Payment channel
sdk_params String param string for calling SDK
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
order_id String Order id in AlphaPay
return_code String Execution result


Error Code

Name Description
ORDER_MISMATCH Order is not belong to this partner.
ORDER_PAID Order has already been paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description


Make a Payment

After obtaining sdk_params, pass the parameters to the SDK to pull up WeChat/Alipay payment, and return the payment result directly by WeChat/Alipay. More information for integration with Alipay: Alipay SDK Document, Alipay Official Demo Code.

More information for integration with WeChat Pay: WeChat Pay SDK Document, WeChat Pay Official Demo Code.

Download UnionPay SDK, demo and user guide here: Android, IOS, pass the sdk_params as tn and use UPPayAssistEx.startPay (activity, null, null, tn, serverMode) to invoke the payment.











Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/app_orders/ZZZ620200304093950?time=1583344193469&nonce_str=123&sign=f36dd43876f0af89561f97d0faa2bffc813e580050345ace9a52c6de8fa2976a






















































Request JSON


{
      "description": "DEVELOPER TEST",
      "price": 1,
      "currency": "CAD",
      "channel": "Alipay",
      "notify_url": "www.alphapay.com/success.php",
      "operator": "dev01",
      "system": "android",
      "version": "1.0",
      "appid": "wx0000000000000001"
}





















Alipay Response Example


{
      "partner_order_id": "ZZZ620200304093950",
      "full_name": "Hello Alpha Pay",
      "partner_name": "Hello Alpha Pay",
      "channel": "AlipayOnline",
      "sdk_params": 
        {
          "service": "mobile.securitypay.pay",
          "partner": "0000000000000001",
          "_input_charset": "utf-8",
          "product_code": "NEW_WAP_OVERSEAS_SELLER",
          "notify_url": "https://pay.alphapay.ca/api/v1.0/alipay/online_orders/0468220191017154622994962/notify",
          "system": "android",
          "version": "1.0",
          "out_trade_no": "0468220191017154622994962",
          "subject": "AlipaySDKTest20191017164721",
          "payment_type": "1",
          "seller_id": "0000000000000001",
          "currency": "CAD",
          "total_fee": 0.01,
          "body": "AlipaySDKTest",
          "forex_biz": "FP",
          "it_b_pay": "2019-10-19 07:51:22",
          "secondary_merchant_id": "ZZZ6",
          "secondary_merchant_name": "AlphaPayTest",
          "secondary_merchant_industry": "0001",
          "sign": "JoErm4POMsuSLWZd5Dw%2FZmtfGzIlZX8E0w%2BPtgDJRZP3WVF5O2L5asGOkvYwb76zYhIvJgazbS0XxLGNFm%2Frrm7TPWhXrFYRSeKrFTsC%2B30Yqj0DSKVAkqwwUGZrHu9vS7QCoEQjLIqFrTzjy60eISKoFDxAVyO4bDS9czFyJlE%3D",
          "sign_type": "RSA"
        },
      "result_code": "SUCCESS",
      "partner_code": "ZZZ6",
      "order_id": "ZZZ6-20200303162209092-MO10OORNM",
      "return_code": "SUCCESS"
}


UnionPay Response Example


{
      "partner_order_id": "ZZZ620200304093950",
      "full_name": "Hello Alpha Pay",
      "partner_name": "Hello Alpha Pay",
      "channel": "UnionPayOnline",
      "sdk_params": "508581337784100197011",
      "result_code": "SUCCESS",
      "partner_code": "ZZZ6",
      "order_id": "ZZZ6-20200303162209092-MO10OORNM",
      "return_code": "SUCCESS"
}




Miniprogram Payment - Create Miniprogram Order


Use for WeChat or Alipay miniprogram payment. After creating order, get returned data and redirect param.


PUT
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/microapp_orders/{order_id}


Integration Process





Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order.(Maximum length 50 characters)


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent CAD 1.00).
currency String Currency
Default value: CAD
Allowed values: CAD , CNY
notify_url String AlphaPay System will post Json Package to notify url (if provided) when the payment succeeds. (Details on Payment Success Notification)
operator String Note for the operator who created this order.
channel String Payment channel. Alipay or Wechat. Case sensitive.
appid String Miniprogram appid
customer_id String Miniprogram openid


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
partner_order_id String Partner order id
full_name String Partner's full company name when registered
partner_name String Partner Name
channel String Payment channel
sdk_params String Required parameters for payment.(Json String)
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
order_id String Order id in AlphaPay
return_code String Execution result


Error Code

Name Description
ORDER_MISMATCH Order is not belong to this partner.
ORDER_PAID Order has already been paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description


Make a Payment

After obtaining sdk_params, use the parameters to complete WeChat Pay.











Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/microapp_orders/ZZZ620200304144418?time=1583361857409&nonce_str=123&sign=0963e3350a057e5933c651af79ab441c789b585b3f2f36aab31289540e5bd2ef























































Request JSON


{
      "description": "DEVELOPER TEST",
      "price": 1,
      "currency": "CAD",
      "notify_url": "www.alphapay.com/success.php",
      "operator": "dev01",
      "channel": "Wechat",
      "appid": "wx0000000000000001",
      "customer_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
























Response Example


{
      "partner_order_id": "ZZZ620200304144418",
      "full_name": "Hello Alpha Pay",
      "partner_name": "Hello Alpha Pay",
      "channel": "Wechat",
      "sdk_params": 
        {
          "timestamp": "1583361857409",
          "package": "prepay_id=wx0000000000000000000000000001",
          "paySign": "D8048A08613E526CB8E4026533666210",
          "appid": "wx0000000000000001",
          "signType": "MD5",
          "nonceStr": "0963e3350a057e5933c651af79ab441c789b585b3f2f36aab31289540e5bd2ef"
        },
      "result_code": "SUCCESS",
      "partner_code": "ZZZ6",
      "order_id": "ZZZ6-20200303162209092-MO10OORNM",
      "return_code": "SUCCESS"
}




Merchants Scan QR Code - Create Retail Passive Payment Order



Retail Passive Payment is used for cashier terminals that can scan Barcode or QR Code. The cashier inputs the payment amount and asks customers for their payment code, then the system sends price and payment code to the server and finishes the payment. Retail Passive Payment now supports Alipay, WeChat, and UnionPay.



PUT
  https://pay.alphapay.ca/api/v1.0/micropay/partners/{partner_code}/orders/{order_id}


Integration Process





Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order. (Maximum length 50 characters)


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent CAD 1.00).
currency String Currency
Default value: CAD
Allowed values: CAD , CNY
notify_url String AlphaPay System will post Json Package to notify url (if provided) when the payment succeeds. (Details on Payment Success Notification)
device_id String Required, ID of the device which sends the request. This ID only helps to record the device information.
auth_code String Required, The Payment QR Code scanned from customer's WeChat, Alipay or UnionPay Wallet.


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
partner_order_id String Partner order id
input_fee int Input amount. (exclude service charge)
create_time String Time when order is created(according to the latest order)(yyyy-MM-dd HH:mm:ss, UTC-8)
real_fee int Actual paid amount.(The same as total fee at the moment. After coupon feature is finished, this may be different.)
total_fee int Order amount, which uses the base unit of current currency
order_description String Description of order
channel String Channel. Alipay, Wechat, UnionPay
result_code String
  • PAYING: Waiting for payment
  • CREATE_FAIL: Fail to create order
  • CLOSED: Order closed
  • PAY_FAIL: Payment failed
  • PAY_SUCCESS: Payment succeeded
currency String Currency. Default value is CAD.
customer_id String ID of WeChat, Alipay or UnionPay user
return_code String Execution result
order_id String Order id in AlphaPay


Error Code

Name Description
ORDER_MISMATCH Order is not belong to this partner.
ORDER_PAID Order has already been paid
AUTHCODEEXPIRE QR Code expired
NOTENOUGH The customer does not have enough balance to complete the payment
NOTSUPORTCARD Card type is not supported
AUTH_CODE_ERROR Payment QR Code has been used more than once
AUTH_CODE_INVALID The submitted QR Code is not a WeChat\Alipay Payment QR Code
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description












Request Example


https://pay.alphapay.ca/api/v1.0/micropay/partners/ZZZ6/orders/ZZZ620200304151231?time=1583363550018&nonce_str=123&sign=cb03434d656c27a661ab29bbe6f35657038d938b91db3d66e0fc5a30fec267d5








































Request JSON


{
      "description": "DEVELOPER TEST",
      "price": 1,
      "currency": "CAD",
      "notify_url": "www.alphapay.com/success.php",
      "device_id": "00000000001",
      "auth_code": "000000000000000001",
}























Response Example


{
      "partner_order_id": "ZZZ620200304151231",
      "input_fee": 1,
      "create_time": "2020-03-04 15:14:46",
      "real_fee": 1,
      "total_fee": 1,
      "order_description": "DEVELOPER TEST-ZZZ620200304151231",
      "channel": "Wechat",
      "result_code": "PAYING",
      "currency": "CAD",
      "customer_id": null,
      "return_code": "SUCCESS",
      "order_id": "0240520200304151446961208"
}




Merchants Show QR Code - Create Retail Active Payment Order



Retail Active Payment is used for cashier terminals which cannot scan Barcode or QR Code. Get the code URL after creating the order, convert this URL to a QR Code and ask customers to use their app to scan this QR Code then finish the payment. Retail Active Payment now support Alipay, WeChat.



PUT
  https://pay.alphapay.ca/api/v1.0/retail_qrcode/partners/{partner_code}/orders/{order_id}


Integration Process





Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order.(Maximum length 50 characters)


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent CAD 1.00).
currency String Currency
Default value: CAD
Allowed values: CAD , CNY
notify_url String AlphaPay System will post Json Package to notify url (if provided) when the payment succeeds. (Details on Payment Success Notification)
device_id String Required, ID of the device which sends the request.
operator String Note for the operator who created this order.


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
partner_order_id String Partner order id
full_name String Partner's full company name when registered
code_url String QR Code string. Partners can create the payment QR Code according to this value.
partner_name String Partner Name
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
order_id String Order id in AlphaPay
return_code String Execution result
qrcode_img String QR Code image formatted in Base64. Can be used as the src attribute on img element


Error Code

Name Description
ORDER_MISMATCH Order is not belong to this partner.
ORDER_PAID Order has already been paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description











Request Example


https://pay.alphapay.ca/api/v1.0/retail_qrcode/partners/ZZZ6/orders/ZZZ620200304153159?time=1583364718677&nonce_str=123&sign=f458b8f9e3643794466c34decbd1cc4170651d7679aef4a73d3772dd3eab523e























































Request JSON


{
      "description": "DEVELOPER TEST",
      "price": 1,
      "currency": "CAD",
      "notify_url": "www.alphapay.com/success.php",
      "device_id": "00000000001",
      "operator": "dev01",
}


















Responce Example


{
      "partner_order_id": "ZZZ620200304153159",
      "full_name": "Hello Alpha Pay",
      "code_url": "https://pay.alphapay.ca/api/v1.0/payment/partners/ZZZ6/orders/0240520200304153243297379/retail_pay",
      "partner_name": "Hello Alpha Pay",
      "result_code": "SUCCESS",
      "partner_code": "ZZZ6",
      "order_id": "0240520200304153243297379",
      "return_code": "SUCCESS",
      "qrcode_img": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAACFElEQVR42u2aS27DMAxEmZWO4Zs68k11hC69EivOSPm4CdCtBhICw3VeF6VH5JCq+X/Wjy1sYQtb2MIUsGqx7l72uPrh5X5u7iWeJi0s7sueSmMyrn7azeOmqmHFEh8GfDu3FpMb4rMrYvHQthxXrCSLhbBD2yFyxEcSg8gRDRtfHd/2wtRY/7ZcPh/z29RYXz1ZITKph+JDzZoZq9i8ZttxIjKtJJ3t035sGUwK80jIAbMeIT9D5xEiKay95TqCkHtVQv09r4lLAGuqdjysyNU5ii/evkthjupjo+Du+BV7SdcyGINQaRep7R6N8i7y+TFDcsYbp7XApqbT0MK6sH244s3Z/kSU1DBKur1xGsX6zR5PjqGzey1GTecRiovIBTD2dNAzMrPTMaJnT1rY0DMlDV+BEKVrIzA91souDMYoRqF5uItL3BQwSLovJGdG5upDZseiTw9HEVk6s1UfLXxOUhjKLv981Fzs6BvGFFUMS8xdPkYTIOkb5TBHNGAtaBpRjP7shfkxNgKcqvVej2PhnOQwi/nhgw8DecZ7r2pYuCaMvmEdsaM5Gb67FMZFVY8a1G2kGFafvXk/y2A92pPnpIUBeLRyxzCQFRtcC8PxzRh6x8372F8NQxsbaTnmw9vjOFIS2+ko0BHAXF0MhgDGg6rRsLPZse34fJ41M2bPs4wX04juQAtb/+KysIUtbGH62C+l+/3an4SIyQAAAABJRU5ErkJggg=="
}




CommonApi - Get Current Exchange Rate


Get the current exchange rate from CAD to CNY provided by WeChat(CAD 1=CNY ?) and Alipay(CAD 1=CNY ?). This exchange rate shown is for reference only, please refer to the real-time exchange rate when processing the actual transaction.


GET
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/channel_exchange_rate


Header

Field Description
Accept application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
wechat_rate Double Exchange rate for WeChat
alipay_retail_rate Double Exchange rate for Alipay Retail Order
alipay_online_rate Double Exchange rate for Alipay Online Order
return_code String Execution result


Error Code

Name Description
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description









Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/channel_exchange_rate?time=1583365498458&nonce_str=123&sign=94cae1d62877b717f85bc68f6e4b493c592fec3cfb2ba2c81d615defc18bdf3e

































Response Example


{
      "wechat_rate": 5.2118990000,
      "alipay_retail_rate": 5.212000,
      "alipay_online_rate": 5.236220,
      "return_code": "SUCCESS"
}






CommonApi - Query Order Status


Including QR Code orders, JSAPI orders and Retail orders.

GET
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}


Header

Field Description
Accept application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
create_time String Time when order is created(according to the latest order)(yyyy-MM-dd HH:mm:ss, UTC-8)
real_fee int Actual paid amount.(The same as total fee at the moment. After coupon feature is finished, this may be different.)
order_description String Description of order
channel String Channel. Alipay, Wechat, UnionPay
channel_order_id String Order ID in payment channel (Alipay/Wechat/UnionPay)
pay_time String Time when order is paid(yyyy-MM-dd HH:mm:ss, UTC-8)
partner_order_id String Partner order id
input_fee int Input Amount, exclude service charge fee
rate Double Exchange Rate used while trading. 1CAD=?CNY
total_fee int Order amount, which uses the base unit of current currency
result_code String
  • PAYING: Waiting for payment
  • CREATE_FAIL: Fail to create order
  • CLOSED: Order closed
  • PAY_FAIL: Payment failed
  • PAY_SUCCESS: Payment succeeded
  • PARTIAL_REFUND: Partial refunded
  • FULL_REFUND: Full refunded
Use the same order id to call create order API can renew the order. PAYING, PAY_SUCCESS orders cannot be renewed.
currency String Currency. Default value is CAD.
customer_id String WeChat user id, Alipay user id, UnionPay user id
return_code String Execution result
order_id String AlphaPay Order ID


Error Code

Name Description
ORDER_NOT_EXIST Order does not exist
ORDER_MISMATCH Order is not belong to this partner.
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description









Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/ZZZ620200304151231?time=1583366028258&nonce_str=123&sign=969ab2c7486f7327fb2ed358b66a2e997e40263761c5c7aea2a689dec5ee681a




































Response Example


{
      "create_time": "2020-03-04 15:14:46",
      "real_fee": 1,
      "order_description": "DEVELOPER TEST-ZZZ620200304151231",
      "channel": "Wechat",
      "channel_order_id": "4200000491202003056383825269",
      "pay_time": "2020-03-04 15:14:47",
      "partner_order_id": "ZZZ620200304151231",
      "input_fee": 1,
      "rate": 5.17620320,
      "total_fee": 1,
      "result_code": "PAY_SUCCESS",
      "currency": "CAD",
      "customer_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "return_code": "SUCCESS",
      "order_id": "0240520200304151446961208"
}





CommonApi - Apply for Refund


One payment order can create more than one refund order. The total amount of all refund orders must be less than or equal to the actual paid amount, and the currency of the refund order is the same as the payment order.


PUT
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/refunds/{refund_id}


Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order. (Maximum length 50 characters)
refund_id String Required, Partner refund order id (if no refund_id, can be same as order_id)


JSON

Field Type Description
fee int Required, Refund amount. Use base unit of the currency. Total amount of all refund orders must be less than actual paid amount. (if customer paid service charge fee: check order status to get real_fee, service charge fee can also be refunded)
description String Description of this refund order
notify_url String Refund notification url, (Details on Refund Notification)


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
amount int Refund amount
channel_refund_id String Channel Refund id, it will show if it has
channel String Payment channel, Wechat, Alipay or UnionPay
currency String Refund currency
result_code String
  • WAITING: Order is being submitted
  • CREATE_FAILED: Fail to submit
  • SUCCESS: Submission succeeded
  • FAILED: Refund failed
  • FINISHED: Refund success(funds has already been returned to user's account)
  • CHANGE: Refund can not return to user's account. Manual operation is required
refund_id String AlphaPay Refund id
partner_refund_id String Partner Refund id
return_code String Execution result


Error Code

Name Description
ORDER_NOT_EXIST Order does not exist
ORDER_MISMATCH Order is not belong to this partner.
ORDER_NOT_PAID Payment order is not paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description










Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/ZZZ620200304151231/refunds/ZZZ620200304151231?time=1583368161186&nonce_str=123&sign=5c94900e1e379d2e19f92beeaf06e9ba7f6e62fa05daac24e2c84921a2237553



























Request JSON


{
      "fee": 1
      "description": "This is a refund order"
      "notify_url": "www.alphapay.com/refund.php"
}

















Response Example


{
      "amount": 1,
      "channel_refund_id": "50000503822020030515001953629",
      "channel": "Wechat",
      "currency": "CAD",
      "result_code": "SUCCESS",
      "refund_id": "ZZZ6R20200304163001069H5HILC9JBW",
      "partner_refund_id": "ZZZ620200304151231",
      "return_code": "SUCCESS"
}





CommonApi - Query Refund Order Status


GET
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/refunds/{refund_id}

Header

Field Description
Accept application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order. (Maximum length 50 characters)
refund_id String Required, Partner refund order id (if no refund_id, can be same as order_id)


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
amount int Refund Amount
channel_refund_id String Channel Refund id, it will show if it has
channel String Payment channel
currency String Refund currency
result_code String
  • WAITING: Order is being submitted
  • CREATE_FAILED: Fail to submit
  • SUCCESS: Submission succeeded
  • FAILED: Refund failed
  • FINISHED: Refund success (funds has already been returned to user's account)
  • CHANGE: Refund can not return to user's account. Manual operation is required
refund_id String AlphaPay Refund id
partner_refund_id String Partner Refund id
return_code String Execution result


Error Code

Name Description
ORDER_NOT_EXIST Order does not exist
ORDER_MISMATCH Order is not belong to this partner.
ORDER_NOT_PAID Payment order is not paid
REFUND_NOT_EXIST Refund order does not exist
REFUND_MISMATCH Refund order is not belong to this payment order
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description







Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/ZZZ620200304151231/refunds/ZZZ620200304151231?time=1583369179194&nonce_str=123&sign=9b3d71132eee75db0cbcf839092b82b744a9ddd01704b54d1b90d6d03c348236





































Response Example


{
      "amount": 1,
      "channel_refund_id": "50000503822020030515001953629",
      "channel": "Wechat",
      "currency": "CAD",
      "result_code": "FINISHED",
      "refund_id": "ZZZ6R20200304163001069H5HILC9JBW",
      "partner_refund_id": "ZZZ620200304151231",
      "return_code": "SUCCESS"
}





CommonApi - Check Orders


GET
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders

Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code


Query Params

Field Type Description
date String Payment order creation date,which is formatted in 'yyyyMMdd' ,UTC-8. Query all orders if not provided
status String Order status
  • ALL: All orders, including orders not paid and closed
  • PAID: Only paid orders. including orders which have refunds.
  • REFUNDED: Only orders which have refunds
    • Default value: ALL
    Allowed values: ALL , PAID , REFUNDED
page int Page number. start with 1
Default value: 1
limit int Rows per page
Default value: 10
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


ROOT

Field Type Description
pagination JSON Pagination information
data JSON[] Orders list
analysis JSON Payment analysis
return_code String Execution result


Pagination

Field Type Description
page int Page number,start with 1
limit int Rows per page
totalCount int Total rows
totalPages int Total pages


Data

Field Type Description
create_time String Payment order creation date,which is formatted in 'yyyyMMdd' ,UTC-8. Query all orders if not provided
real_fee int Actual paid amount
partner_name String Partner Name
channel String Channel. Alipay, Wechat, UnionPay
partner_order_id String Partner order id
pre_authorization Boolean "true" for pre-authorized orders and "false" for basic orders
total_fee Double Order amount
refund_fee Double Total refund amount of this order
tip_amount Double Tips of this order
currency String Currency
partner_code String Partner code
order_id String AlphaPay Order ID
order_body String Order description
pay_time String Time when order is created, which is formatted in 'yyyy-MM-dd HH:mm:ss', UTC-8
gateway String
  • Retail In-Store: Paid from official EFTPos or App
  • QRCODE: Paid from merchant static QR Code
  • Online API: Paid from QR Code API
  • WeChat HTML5: Paid from JSAPI
  • Retail API: Paid from Retail API
  • Mobile H5: Paid from H5 Api
  • APP: Paid from APP SDK Api
  • Miniprogram: Paid from Miniprogram Api
status String order status
  • SUBMITTING: Submitting
  • SUBMIT_FAIL: Fail to submit
  • WAITING_PAYMENT: Waiting for payment
  • CLOSED: Order closed
  • PAYMENT_FAIL: Payment failed
  • SUCCESS: Payment succeeded
  • PARTIAL_REFUND: Partial Refunded
  • FULL_REFUND: Full Refunded
channel_error_message String The reason of failure in creating order or making payment


Analysis

Field Type Description
order_count int Order count of successful payment (including orders which have refunds)
total_fee int Total amount
real_fee int Actual paid amount


Error Code

Name Description
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description






Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders?time=1583369635364&nonce_str=123&sign=c88e05a64d6f42d76111e7d96c3ae109f28c7bc15a8a434a7978a874532ad0f1



















































Response Example


{
      "pagination": {
        "endRow": 10,
        "firstPage": true,
        "hasNextPage": true,
        "hasPrePage": false,
        "lastPage": false,
        "limit": 10,
        "nextPage": 2,
        "offset": 0,
        "page": 1,
        "prePage": 1,
        "slider": [
          1,
          2,
          3,
          4,
          5,
          6,
          7
        ],
        "startRow": 1,
        "totalCount": 11864,
        "totalPages": 1187
      },
      "data": [
        {
          "create_time": "2017-11-24 12:31:25",
          "real_fee": 1.0000,
          "partner_name": "Hello Alpha Pay",
          "channel": "Wechat",
          "partner_order_id": "ZZZ62017-11-24 12:31:23",
          "pre_authorization": false,
          "ext_params": "NULL",
          "total_fee": 1.0000,
          "refund_fee": 0.0000,
          "tip_amount": 0.0000,
          "currency": "CAD",
          "partner_code": "ZZZ6",
          "order_id": "ZZZ6-20171124203125377-JTKF3IIBJ",
          "order_body": "test-ZZZ62017-11-24 12:31:23",
          "gateway": "Online API",
          "status": "CLOSED"
        }
      ],
      "analysis": {
        "cny_display_amount": 665.5100,
        "order_count": 1992,
        "pre_cny_display_amount": 0.0000,
        "pre_refund_fee": 0.0500,
        "refund_fee": -3196.8700,
        "paid_fee": 3288.3200,
        "customers": 177,
        "display_amount": 3157.2100,
        "pre_display_amount": 0.0500
      },
      "return_code": "SUCCESS"
}





CommonApi - Query Daily Transactions



This API will list all transactions for the current merchants in the day, containing all payment methods(include no gateway methods) and all payment channels such as payment, AlphaPay discount cashback, refunds, credit for failure refunds, system payback, cashback account income/outcome, etc. Settlement transactions will not be contained.
Notice: A payment order or refund order can contain several transaction records



GET
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/transactions

Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code


Query Params

Field Type Description
date String Required, Transaction date. Format as 'yyyyMMdd', UTC-8.
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


ROOT

Field Type Description
order_count int Payment order count
transaction_count int Transaction record count
result_code String Process result
transactions JSON[] Transaction list
refund_count int Refund order count
return_code String Execution result


Transactions

Field Type Description
exchange_rate Double Using exchange rate
customer_payment_amount int User actual paid amount, which uses the base unit of order currency
channel String Channel. Alipay, Wechat, UnionPay
remark String Remark
channel_order_id String Order ID in payment channel (Alipay/Wechat/UnionPay)
type String Trade Direction
  • Credit: Income
  • Debit: Outcome
refund_id String AlphaPay Refund ID (Only in refunds or refunds failure cashback)
total_surcharge int Total surcharge for this transaction
partner_order_id String Partner order id
input_amount int Order input amount, which uses the base unit of order currency
total_amount int Total payment amount, which uses the base unit of order currency
settle_amount int Settle amount, CAD cents
transaction_time String Trade time, format as yyyyMMddHHmmss, UTC-8
currency String currency
order_id String AlphaPay Order ID
partner_refund_id String Partner refund ID (Only in refunds or refunds failure cashback)
gateway String Payment method
  1. Offline Payment (Scan Payment Code displaying on customer's device)
  2. Offline Payment (Customer scan QR Code displaying on POS screen)
  3. Static Merchant QR Code
  4. QR Code Gateway
  5. JSAPI Gateway
  6. Offline Payment
  7. Offline Payment
  8. Static Merchant QR Code
  9. Mobile H5 Gateway
  10. Third-party Gateway
  11. APP SDK Gateway
  12. Share Code Gateway
  13. MiniProgram Gateway
  14. Native Payment Gateway
  15. Share Link Gateway
surcharge_rate Double Surcharge rate for this transaction


Error Code

Name Description
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description














Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/transactions?date=20200304&time=1583433703274&nonce_str=123&sign=3528e22beff8f85b5f1534c22664684db7e80672645dd5586945d40043165144




































Response Example


{
      "order_count": 1,
      "transaction_count": 2,
      "result_code": "SUCCESS",
      "transactions": [
        {
          "exchange_rate": 5.176203,
          "customer_payment_amount": 1,
          "channel": "Wechat",
          "remark": "MICROPAY:DEVELOPER TEST-ZZZ620200304151231",
          "channel_order_id": "4200000491202003056383825269",
          "type": "Credit",
          "refund_id": null,
          "total_surcharge": 0,
          "partner_order_id": "ZZZ620200304151231",
          "input_amount": 1,
          "total_amount": 1,
          "settle_amount": 1,
          "transaction_time": "20200304151447",
          "currency": "CAD",
          "order_id": "0240520200304151446961208",
          "partner_refund_id": null,
          "gateway": 5,
          "surcharge_rate": 0.0200
        },
        {
          "exchange_rate": 5.176203,
          "customer_payment_amount": 1,
          "channel": "Wechat",
          "remark": "GATEWAY - Refund For Order:DEVELOPER TEST-ZZZ620200304151231",
          "channel_order_id": "50000503822020030515001953629",
          "type": "Debit",
          "refund_id": "ZZZ6R20200304163001069H5HILC9JBW",
          "total_surcharge": 0,
          "partner_order_id": "ZZZ620200304151231",
          "input_amount": 1,
          "total_amount": 1,
          "settle_amount": 1,
          "transaction_time": "20200304163003",
          "currency": "CAD",
          "order_id": "0240520200304151446961208",
          "partner_refund_id": "ZZZ620200304151231",
          "gateway": 5,
          "surcharge_rate": 0.0200
        }
      ],
      "refund_count": 1,
      "return_code": "SUCCESS"
}





CommonApi - Query Settlement Details



This API will list all transactions for the current merchants for the pre-set date(not for today), containing all payment methods(include no gateway methods) and all payment channels such as payment, AlphaPay discount cashback, refunds, credit for failure refunds, system payback, cashback account income/outcome, etc. Settlement transactions will not be contained.
Notice: A payment order or refund order can contain several transaction records


GET
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/settlements

Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code


Query Params

Field Type Description
date String Required, Transaction date. Format as 'yyyyMMdd', UTC-8
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


ROOT

Field Type Description
order_count int Payment order count
total_credit int Total credit amount(CAD cent)
transaction_count int Transaction record count
total_transfer int Total amount sending to merchant's bank account(CAD cent)
total_debit int Total debit amount(CAD cent)
transactions JSON[] Transaction list
settle_days String Settle delay (T+n)
total_surcharge int Total surcharge amount(CAD cent)
settle_to String Transaction date to, yyyyMMdd
result_code String Process result
settle_from String Transaction date from, yyyyMMdd
refund_count int Refund order count
return_code String Execution result


Transactions

Field Type Description
surcharge int Surcharge amount, CAD cent
exchange_rate Double Using exchange rate
channel String Channel. Alipay, Wechat, UnionPay
remark String Remark
channel_order_id String Order ID in payment channel (Alipay/Wechat/UnionPay)
type String Trade Direction
  • Credit: Income
  • Debit: Outcome
refund_id String AlphaPay Refund ID (Only in refunds or refunds failure cashback)
partner_order_id String Partner order id
input_amount int Order input amount, which uses the base unit of order currency
total_amount int Total payment amount, which uses the base unit of order currency
transfer_amount int Amount send to merchant's bank account, CAD cent
settle_amount int Settle amount, CAD cents
transaction_time String Trade time, format as yyyyMMddHHmmss, UTC-8
currency String currency
order_id String AlphaPay Order ID
partner_refund_id String Partner Refund ID (Only in refunds or refunds failure cashback)
gateway String Payment method
  1. Offline Payment (Scan Payment Code displaying on customer's device)
  2. Offline Payment (Customer scan QR Code displaying on POS screen)
  3. Static Merchant QR Code
  4. QR Code Gateway
  5. JSAPI Gateway
  6. Offline Payment
  7. Offline Payment
  8. Static Merchant QR Code
  9. Mobile H5 Gateway
  10. Third-party Gateway
  11. APP SDK Gateway
  12. Share Code Gateway
  13. MiniProgram Gateway
  14. Native Payment Gateway
  15. Share Link Gateway
surcharge_rate String Rate of surcharge (x%)


Error Code

Name Description
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description














Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/settlements?date=20200303&time=1583443132970&nonce_str=123&sign=b53c903adc697b974b4eeb2c4523a90eb63689193a8b93283cf3486aee67b08d




































Responce Example


{
      "order_count": 1,
      "total_credit": 1,
      "transaction_count": 1,
      "total_transfer": 1,
      "total_debit": 0,
      "transactions": [
        {
          "surcharge": 1,
          "exchange_rate": 5.234527,
          "channel": "Wechat",
          "remark": "MICROPAY:AlphaPay Retail Order",
          "channel_order_id": "4200000491202002283776594113",
          "type": "Credit",
          "refund_id": null,
          "partner_order_id": null,
          "input_amount": 1,
          "total_amount": 1,
          "transfer_amount": 1,
          "settle_amount": 1,
          "transaction_time": "20200227165517",
          "currency": "CAD",
          "order_id": "0374020200227165515743559",
          "partner_refund_id": null,
          "gateway": 0,
          "surcharge_rate": "0.1%"
        }
      ],
      "settle_days": "T+2",
      "total_surcharge": 1,
      "settle_to": "20200301",
      "result_code": "SUCCESS",
      "settle_from": "20200227",
      "refund_count": 0,
      "return_code": "SUCCESS"
}





CommonApi - Suspend Settlement


Suspend settlement temporarily. For the merchants who do not want the money to be settled into their bank account after their customers paid the orders.


PUT
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/settle_lock


Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order. (Maximum length 50 characters)


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
result_code String
  • WAITING: Order is being submitted
  • CREATE_FAILED: Fail to submit
  • SUCCESS: Submission succeeded
  • FAILED: Suspend settlement failed
  • FINISHED: Suspend settlement success
  • CHANGE: Unablle to suspend settlement. Manual operation is required
return_code String Execution result


Error Code

Name Description
ORDER_NOT_EXIST Order does not exist
ORDER_MISMATCH Order is not belong to this partner.
ORDER_NOT_PAID Payment order is not paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description










Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/ZZZ620200304151231/settle_lock?time=1587855343247&nonce_str=123&sign=960e0cb7dfe16abfa821a198b3b0d005621340880f85d854887d6a7c023a4a15

















Response Example


{
      "result_code": "SUCCESS",
      "return_code": "SUCCESS"
}





CommonApi - Release Suspended Settlement


Release Suspended Settlement. For the merchants who want the money to be settled into their bank account again.


PUT
  https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_id}/release_settle_lock


Header

Field Description
Accept application/json
Content-Type application/json


Path Variable

Field Type Description
partner_code String Required, Partner Code
order_id String Required, Partner order id. Shall be unique for the same partner. If repeated, order will be recognized as an existing order. (Maximum length 50 characters)


Query Params

Field Type Description
time Long Required, UTC timestamp in milliseconds
nonce_str String Required, Random string and number
sign String Required, Sign (Each Request should generate new sign)


Success 200

Field Type Description
result_code String
  • WAITING: Order is being submitted
  • CREATE_FAILED: Fail to submit
  • SUCCESS: Submission succeeded
  • FAILED: Release suspension failed
  • FINISHED: Release suspension success
  • CHANGE: Released fund can not return to user's account. Manual operation is required
return_code String Execution result


Error Code

Name Description
ORDER_NOT_EXIST Order does not exist
ORDER_MISMATCH Order is not belong to this partner.
ORDER_NOT_PAID Payment order is not paid
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description










Request Example


https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/ZZZ620200304151231/release_settle_lock?time=1587856192854&nonce_str=123&sign=c5529fc2eb85c235f83a59553936e68b9fa5965ec25f7a145d4a87969d7b04cb

















Response Example


{
      "result_code": "SUCCESS",
      "return_code": "SUCCESS"
}