Alpha Pay API Reference

Overview

Prepare

1. Before starting technology integration, merchants need to sign a contract with Alpha Pay for related products. For assistance, please contact Alpha Pay Business Team.
2. Merchants get the Partner Code and Credential Code for test.
3. Integrating APP and Miniprogram Payment should provide APPID to Alpha Pay.

Payment Scenarios


Different Channel

According to different Api used, Channel was distributed to Retail channel and Online channel. Each channels has 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 web page 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 jump to Alipay Official payment page. Customers can scan QR Code displayed in the page or sign in their account directly to finish payment. QR Code can provide a QR Code. Merchants can display this QR Code in their web page or jump to AlphaPay to display the QR Code. Customers can only scan the QR Code with their Alipay Client to finish payment.

Demo

demo.alphapay.ca

WordPress Demo - Try our WooCommerce Plugin

demo.alphapay.ca/wp

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 in a web page. Customers will scan the code via their WeChat and complete the payment in the linked web page. It is suitable for online shopping websites.
  • JSAPI Payment redirects customers to a web page in WeChat. This page can only be opened within WeChat app and it is suitable for payment from micro-shops on WeChat platform.
  • Retail passive payment(Scan Payment Code in customers’ WeChat Wallet) and active payment(Generate Payment QR Code for customers to scan) are used in retail environment such as payment terminals and pos machines.
  • Order ID is required when creating an order. The same order id can be sent again. The system will decide to renew an order or close the old order according to the order status. System will recognise the same order id to avoid duplicated payments from customers.
  • As orders can be resubmitted, Order ID returned by our server might not represent the last Order ID paid.
  • QR Code order creation will return QR Code and pay_url. Merchants may decide whether to display the QR code on their website or to redirect customer to the payment page available at pay_url.
  • JSAPI order creation will return pay_url. Merchants shall redirect customer to the payment page available at pay_url, and complete the payment.
  • When redirecting to pay_url, sign information 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 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 user open the payment page again.
  • Always redirect to AlphaPay’s payment page after calling the order creation method.
  • Same order id is allowed in both creating new payment order and creating 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.

Request And Parameters

Parameters Format

Request for payment or refund shall use PUT method. Request for querying order shall use 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.
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 shows the type of error that happened.
  • Response will also contain a return_msg field for detailed error message.

Multi-Language

System error message supports Simplified Chinese and English. The system by default will automatically choose the language according to the Accept-Language value in request header. Cookie "locale" value (zh-CN or en-US) will affect the result 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
    Parameters:
    • partner_code: Code for partner, including four uppercase letters or numbers.
    • time: UTC timestamp in milliseconds. Take current timestamp of UTC. 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()
  4. Include the time,nonce_str and sign into Query Param when calling api
  5. valid_string=TestPay&1468691301081&aaf2a94c8c2d56d5b43a1a3d9d811102&pQ5Jc9eoTcsxqPY5uQ3p2WmvSy0zEYeP
    sign=64712672795f94fa3bfb2e88ac09cb75d09bcf8a3c3dcaa529d8290dd6587060

Test Page:


Payment Success Notification - Asynchronous Notification

If notify_url is provided when order is created. System will post JSON package to this url when payment succeed. Different from Server APIs, sign parameters will be included in json entity. Merchant system shall valid them to prevent fake requests. System will retry the notification up to 3 times. Merchant system shall be able to handle the repeated requests.
Notice: Merchant domain should add SSL certificate in order to receive asynchronous notification.

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
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)

JSON Format Example


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

QR Code - Create QR Code Payment

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

Integration Process


Return value contains QR Code string, QR Ccode 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, equivalent CAD amount shall never less than 0.01CAD, otherwise user will get Invalid Amount Error from WeChat when making the payment.

put https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/orders/{order_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)

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 Alpha Pay 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
return_code String Execution result
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
channel String Payment channel
partner_code String Partner code
full_name String Partner's full company name when registered
partner_name String Partner's name
order_id String Order id in AlphaPay
partner_order_id String Partner order id
code_url String QR Code string. Partners can create the payment QR Code according to this value.
qrcode_img String QR Code image formatted in Base64. Can be used as the src attribute on img element
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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Request Example

put https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/20180101122549?time=1535753255985&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=a7a706541544bb3552a7dab8dd67d16574bbd1eafb0f7672cdb739710311ef14

Response Example


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. 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 Alpha Pay Payment Page (need to add parameters, details on QR Code Payment Page in AlphaPay

QR Code - QR Code Payment Page in AlphaPay

This page must be called after 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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Link Example

get https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/2018010112254915/pay?redirect=%22https://www.alphapay.ca/success%22&time=1535759759798&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=d976fd4bfed4d28e96b6c8600507229f666943adc5122937a0f762d3e38b3a7f

Alipay Online Payment - Create Alipay Online Order

Use for Alipay Payment in PC Website. After create order, jump to the pay_url returned and attach sign params and redirect param. Then enter Alipay page to finish payment. Alipay Channel Only.

Integration Process


put https://pay.alphapay.ca/api/v1.0/alipay/partners/{partner_code}/orders/{order_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)

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.

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
return_code String Execution result
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
full_name String Partner's full company name when registered
partner_name String Parter Name
order_id String Order id in AlphaPay
partner_order_id String Partner order id
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

put https://pay.alphapay.ca/api/v1.0/alipay/partners/ZZZ6/orders/2018010112258455?time=1535760771439&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=dba59bffd4dba6040ec6cbb80bb34bf0311931b0e0574a0eae78570777868f5e

Response Example


Redirect to Alipay Payment Page

pay_url should add time, nonce_str, sign Parameters
get https://pay.alphapay.ca/api/v1.0/alipay/partners/ZZZ6/orders/2018010112258455/web_pay?time=1535761172065&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=124d2ba7eca94c8adedad84aa3dd892f3558d1aa310bf702945700ecbfe54dfb

JSAPI - Create JSAPI Payment Order

SAPI Payment is used to pay in 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.

Integration Process


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

put https://pay.alphapay.ca/api/v1.0/jsapi_gateway/partners/{partner_code}/orders/{order_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)

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
return_code String Execution result
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
channel String Payment channel
partner_code String Partner code
full_name String Partner's full company name when registered
partner_name String Partner Name
order_id String Order id in AlphaPay
partner_order_id String Partner order id
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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Request Example

put https://pay.alphapay.ca/api/v1.0/jsapi_gateway/partners/ZZZ6/orders/20180101122549?time=1535753255985&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=a7a706541544bb3552a7dab8dd67d16574bbd1eafb0f7672cdb739710311ef14

Response Example


Make a payment

pay_url need to add parameters,Details onWechat JSAPI Payment Page或者Alipay JSAPI Payment Page


JSAPI - Wechat JSAPI Payment Page

This page must be called after Payment Order has been created. Actural url shall be according to pay_url param from order creation. 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/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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Link Example

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

JSAPI - Alipay JSAPI Payment Page

This page must be called after Payment Order has been created. Actural url shall be according to pay_url param from order creation. 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/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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Link Example

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

MobileH5 - Create H5 Payment

Warning:Wechat Pay is not support for H5 Payment.
H5 Payment is used for Mobile App or Mobile browser. The browser would redirect to a webpage from Alipay and call Alipay App to finish the payment.

Integration Process


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

put https://pay.alphapay.ca/api/v1.0/h5_payment/partners/{partner_code}/orders/{order_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)

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
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
return_code String Execution result
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
channel String Payment channel
partner_code String Partner code
full_name String Partner's full company name when registered
partner_name String Partner Name
order_id String Order id in AlphaPay
partner_order_id String Partner order id
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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Request Example

put https://pay.alphapay.ca/api/v1.0/h5_payment/partners/ZZZ6/orders/20180905112525?time=1536177012365&nonce_str=d4e11lnh9u13gyapjkfieq9l46ak4r&sign=b180ed81ef2e84f0ed94710d23e47539f8a1af84ed4d8da1961b92abec1be384

Response Example


Make a Payment

pay_url need to add parameters,details on H5 Payment Page


MobileH5 - H5 Payment Page

This page must be called after 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/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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Link Example

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

SDKPayment - Create SDK Order

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

Integration Process


put https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/app_orders/{order_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)

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.
system String os type of client app
Allowed values: android , iphoneipad
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
return_code String Execution result
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
full_name String Partner's full company name when registered
partner_name String Partner Name
order_id String Order id in AlphaPay
partner_order_id String Partner order id
sdk_params String param string for calling SDK

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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Request Example

put https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/app_orders/201801011225855451?time=1536086256103&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=836c14b1d1eb6e9ea67c68064e78152cff354e47f5b6907107321d8dde72c65b

Response Example



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 DocumentWechat Pay Official Demo Code


Miniprogram_Payment - Create Miniprogram Order

Use for wechat Payment in miniprogram. After create order, returned and redirect param. wechat Channel Only. MiniProgram integration document

Integration Process


put https://pay.alphapay.ca/api/v1.0/gateway/partners/{partner_code}/microapp_orders/{order_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)

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.
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
return_code String Execution result
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
full_name String Partner's full company name when registered
partner_name String Partner Name
order_id String Order id in AlphaPay
partner_order_id String Partner order id
sdk_params String he required parameters for payment.(Json String)

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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Request Example

put https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/microapp_orders/201801011225855451?time=1536086256103&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=836c14b1d1eb6e9ea67c68064e78152cff354e47f5b6907107321d8dde72c65b

Response Example


Make a Payment

After obtaining Sdk_params, use the parameters to complete WechatPay.Details on MiniProgram integration document




RetailPay - Create Retail Passive Payment Order

Retail Passive Payment is used for cashier terminals which can scan BarCode or QRCode. Shop staff input the payment amount and ask customers for their payment code, then system send price and payment code to server and finish the payment. Retail Passive Payment now support both Alipay and WeChat

Integration Process


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

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
auth_code String Required, The Payment QR Code scanned from customer's WeChat/Alipay 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
return_code String Execution result
result_code String
  • PAYING: Waiting for payment
  • CREATE_FAIL: Fail to create order
  • CLOSED: Order closed
  • PAY_FAIL: Payment failed
  • PAY_SUCCESS: Payment succeeded
order_id String Order id in AlphaPay
partner_order_id String Partner order id
total_fee int Order amount, which uses the base unit of current currency
real_fee int Actual paid amount.(The same as total fee at the moment. After coupon feature is finished, this may be different.)
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)
currency String Currency. Default value is CAD.
channel String Channel. Alipay,Wechat
order_description String description of order
customer_id String ID of Wechat/Alipay user

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 finish the payment
NOTSUPORTCARD Card type is not supported
AUTH_CODE_ERROR Payment QR Code has been used twice
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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

RetailPay - Create Retail Active Payment Order

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

Integration Process


put https://pay.alphapay.ca/api/v1.0/retail_qrcode/partners/{partner_code}/orders/{order_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)

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
return_code String Execution result
result_code String SUCCESS means order created successfully, EXISTS means order has already existed.
partner_code String Partner code
full_name String Partner's full company name when registered
partner_name String Partner Name
order_id String Order id in AlphaPay
partner_order_id String Partner order id
code_url String QR Code string. Partners can create the payment QR Code according to this value.

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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

CommonApi - Get Current Exchange Rate

Get 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
return_code String Execution result
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

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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Request Example

get https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/channel_exchange_rate?time=1536093518031&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=b307328d9b7d72b3341cf6430441125e944e4813e0a3536b2a9a128bf21ed436

Response Example



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
return_code String Execution result
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.
order_id String AlphaPay Order ID
partner_order_id String Partner order id
input_fee int Input Amount, exclude service charge fee
total_fee int Order amount, which uses the base unit of current currency
real_fee int Actual paid amount.(The same as total fee at the moment. After coupon feature is finished, this may be different.)
rate Double Exchange Rate used while trading. 1CAD=?CNY
pay_time String Time when order is paid(yyyy-MM-dd HH:mm:ss, UTC-8)
create_time String Time when order is created(according to the latest order)(yyyy-MM-dd HH:mm:ss, UTC-8)
currency String Currency. Default value is CAD.
channel String Channel. Alipay,Wechat
customer_id String Wechat user id、Alipay user 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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Request Example

get https://pay.alphapay.ca/api/v1.0/gateway/partners/ZZZ6/orders/20180101122585566?time=1536093994255&nonce_str=apcp0dumiamxhxlolv22bke2587dp8&sign=07be0e9f9cb017111beb17f93e215ed5a97f5578b8578f1f6c9975bcd0454dac

Response Example



CommonApi - Apply for Refund

One payment order can create more than one refund orders. Total amount of all refund orders must be less than or equal to the actual paid amount and the currency of 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)

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
return_code String Execution result
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
amount int Refund amount
currency String Refund currency

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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

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
return_code String Execution result
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
amount int refund Amount
currency String Refund currency

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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

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
return_code String Execution result
data JSON[] Orders list
pagination JSON Pagination information
analysis JSON Payment analysis

data

Field Type Description
order_id String AlphaPay Order ID
partner_order_id String Partner order id
total_fee int Order amount
real_fee int Actual paid amount
channel String Channel. Alipay,Wechat
currency String Currency
create_time String Payment order creation date,which is formatted in 'yyyyMMdd' ,UTC-8. Query all orders if not provided
pay_time String Time when order is created, which is formatted in 'yyyy-MM-dd HH:mm:ss', UTC-8
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
order_body String Order description
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
partner_code String Partner code
partner_name String Partner Name
refund_fee String Total refund amount of this order

pagination

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

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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

CommonApi - Query Daily Transactions

This Api will list all transactions for current merchant 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 pay back, cashback account income/outcome, etc. Settlement transactions will not be contained.
Notice: A payment order or refund order can contains 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
return_code String Execution result
result_code String Process result
transaction_count int transaction record count
order_count int payment order count
refund_count int refund order count
transactions JSON[] transaction list

transactions

Field Type Description
transaction_time String Trade time, format as yyyyMMddHHmmss, UTC-8
order_id String AlphaPay Order ID
partner_order_id String Partner order id
channel_order_id String Order ID in payment channel (Alipay/Wechat)
refund_id String AlphaPay Refund ID (Only in refunds or refunds failure cashback)
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. QRCode 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
channel String Channel. Alipay,Wechat
type String Trade Direction
  • Credit: Income
  • Debit: Outcome
currency String currency
total_amount int Total payment amount, which uses the base unit of order currency
input_amount int Order input amount, which uses the base unit of order currency
customer_payment_amount int User actual paid amount, which uses the base unit of order currency
settle_amount int Settle amount, CAD cents
exchange_rate Double Using exchange rate
remark String Remark

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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

CommonApi - Query Settlement Details

This Api will list all transactions for current merchant 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 pay back, cashback account income/outcome, etc. Settlement transactions will not be contained.
Notice: A payment order or refund order can contains 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
return_code String Execution result
result_code String Process result
settle_from String Transaction date from,yyyyMMdd
settle_to String Transaction date to, yyyyMMdd
settle_days String Settle delay(T+n)
transaction_count int transaction record count
order_count int payment order count
refund_count int refund order count
total_credit int Total credit amount(CAD cent)
total_debit int Total debit amount(CAD cent)
total_surcharge int Total surcharge amount(CAD cent)
total_transfer int Total amount sending to merchant's bank account(CAD cent)
transactions JSON[] transaction list

transactions

Field Type Description
transaction_time String Trade time, format as yyyyMMddHHmmss, UTC-8
order_id String AlphaPay Order ID
partner_order_id String Partner order id
channel_order_id String Order ID in payment channel (Alipay/Wechat)
refund_id String AlphaPay Refund ID (Only in refunds or refunds failure cashback)
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. QRCode 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
channel String Channel. Alipay,Wechat
type String Trade Direction
  • Credit: Income
  • Debit: Outcome
currency String currency
total_amount int Total payment amount, which uses the base unit of order currency
input_amount int Order input amount, which uses the base unit of order currency
customer_payment_amount int User actual paid amount, which uses the base unit of order currency
settle_amount int Settle amount, CAD cents
surcharge_rate String Rate of surcharge (x%)
surchargee int Surcharge amount, CAD cent
transfer_amount int Amount send to merchant's bank account, CAD cent
exchange_rate Double Using exchange rate
remark String Remark

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 Capitalize

ERROR

Name Description
return_code Error Code
return_msg Error Description

Resource Download