AlphaPay Gateway Payment API

AlphaPay Gateway Payment API for Third-Party Developers

QRCode

QRCode - Create QR Code Payment

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

Return value contains QR Code string, QR Ccode image and payment page address. Partners can decide how to finish the payment. 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.

JSON keys

Field Type Description
description String

Required, Description of an order.

price int

Required, Price of the order. Use the base unit of the currency.

currency String

Currency

Default value: CAD

Allowed values: CAD, CNY

channel String

Payment channel, case sensitive

Allowed values: Alipay, Wechat

notify_url String

System will call the notify url if provided when the payment succeeds

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

sign String

Required, 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, which is also WeChat order id. The final order id which is paid may be different from this one.

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

QRCode - QR Code Payment Page in AlphaPay

This page must be called after payment order has been created. When jumping back to redirection URL, 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. Contain sign parameters for validation.

time Long

Required, UTC timestamp in milliseconds

nonce_str String

Required, Random string

sign String

Required, 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

JSApi

JSApi - Create JSAPI Payment Order

JSAPI 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.

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/wechat_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

JSON keys

Field Type Description
description String

Required, Order description

price int

Required, Price of the order. Use the base unit of the currency.

currency String

currency

Default value: CAD

Allowed values: CAD, CNY

channel String

Payment channel, case sensitive

Allowed values: Alipay, Wechat

notify_url String

System will call the notify url if provided when the payment succeeds

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

sign String

Required, 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

channel String

Payment Channel

full_name String

Partner's full company name when registered

partner_name String

Partner's name

order_id String

Order id in AlphaPay, which is also WeChat order id. The final order id which is paid may be different from this one

partner_order_id String

Partner order id

pay_url String

Payment page in AlphaPay. Can only be accessed through WeChat

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

JSApi - Wechat JSAPI Payment Page in AlphaPay

This page must be called after Payment Order has been created. Actural url shall be according to pay_url param from order creation

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. Must have already been created

Query Params

Field Type Description
redirect String

Required, Redirect url when the payment succeeded

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

sign String

Required, 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

JSApi - Alipay JSAPI Payment Page in AlphaPay

This page must be called after Payment Order has been created. Actural url shall be according to pay_url param from order creation

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. Must have already been created

Query Params

Field Type Description
redirect String

Required, Redirect url when the payment succeeded

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

sign String

Required, 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

MobileH5

MobileH5 - Create H5 Payment

Warning:Wechat H5 Payment socket requires application separately and requires agreement from Tencent. Merchants who needs this socket please contact AlphaPay first. Alipay has no limit at the moment.
H5 Payment is used for payment in Webpage or App on mobile outside WeChat App. The browser would redirect to a webpage from WeChat or Alipay and call WeChat App to finish the payment.
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

JSON keys

Field Type Description
description String

Required, Order description

price int

Required, Price of the order. Use the base unit of the currency.

currency String

currency

Default value: CAD

Allowed values: CAD, CNY

channel String

Payment channel, case sensitive

Allowed values: Alipay, Wechat

notify_url String

System will call the notify url if provided when the payment succeeds

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

sign String

Required, 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

channel String

Payment channel

full_name String

Partner's full company name when registered

partner_name String

Partner's name

order_id String

Order id in AlphaPay, which is also WeChat order id.

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

MobileH5 - H5 Payment Page

This page must be called after payment order has been created. When jumping back to redirection URL, 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 when payment succeeded. Contain sign parameters for validation.

time Long

Required, UTC timestamp in milliseconds

nonce_str String

Required, Random string

sign String

Required, 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

RetailPay

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

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

JSON keys

Field Type Description
description String

Required, Order description

price int

Required, Price of the order. Use the base unit of the currency.

currency String

currency

Default value: CAD

Allowed values: CAD, CNY

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 Wallet.

notify_url String

System will call the notify url if provided when the payment succeeds.

Query Params

Field Type Description
time Long

Required, UTC timestamp in milliseconds

nonce_str String

Required, Random string

sign String

Required, Sign

Success 200

Field Type Description
return_code String

Execution result

result_code String

Order status

  • 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, which is also WeChat order id.

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

pay_time String

Time when order is paid(yyyy-MM-dd HH:mm:ss, UTC-8 (UTC-7 Summer Time))

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

Error Code

Name Description
ORDER_MISMATCH

Order ID does not belongs to current 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 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.

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/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 existed order.

JSON keys

Field Type Description
description String

Required, Description of order.

price int

Required, Price of the order. Use the base unit of the currency.

currency String

Currency

Default value: CAD

Allowed values: CAD, CNY

device_id String

Required, ID of the device which sends the request.

notify_url String

System will call the notify url if provided when the payment succeeds

Query Params

Field Type Description
time Long

Required, UTC timestamp in milliseconds

nonce_str String

Required, Random string

sign String

Required, 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's name

order_id String

Order id in AlphaPay, which is also WeChat order id. The final order id which is paid may be different from this one

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

Alipay Online Payment

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.

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

JSON keys

Field Type Description
description String

Required, Order description

price int

Required, Price of the order. Use the base unit of the currency.

currency String

Currency

Default value: CAD

Allowed values: CAD, CNY

notify_url String

System will call the notify url if provided when the payment succeeds

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

sign String

Required, 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's name

order_id String

Order id in AlphaPay, which is also WeChat order id. The final order id which is paid may be different from this one

partner_order_id String

Partner order id

pay_url String

Payment page in AlphaPay. Can only be accessed through WeChat

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

SDKPayment

SDKPayment - Create Alipay SDK Order

Used for mobile Apps calling Alipay payment with 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 Alipay app It is strongly advised to request AlphaPay order query Api to confirm that the order has been paid in order to cancelling order by system at the same time.

More information for integration with Alipay: Alipay SDK Document

https://pay.alphapay.ca/api/v1.0/alipay/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

JSON keys

Field Type Description
description String

Required, Order description

price int

Required, Price of the order. Use the base unit of the currency.

currency String

Currency

Default value: CAD

Allowed values: CAD, CNY

notify_url String

System will call the notify url if provided when the payment succeeds

operator String

Note for the operator who created this order.

system String

os type of client app, optional

Allowed values: android, iphone, ipad

version String

client app version, optional

Query Params

Field Type Description
time Long

Required, UTC timestamp in milliseconds

nonce_str String

Required, Random string

sign String

Required, 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's name

order_id String

Order id in AlphaPay, which is also WeChat order id. The final order id which is paid may be different from this one

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

CommonApi

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}/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

sign String

Required, 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 Trade

alipay_online_rate Double

Exchange rate for Alipay Online Trade

ERROR

Name Description
return_code

Error Code

return_msg

Error Description

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

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

sign String

Required, 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
Use the same order id to call create order API can renew the order. PAYING, PAY_SUCCESS orders cannot be renewed.
order_id String

Order id in AlphaPay, which is also WeChat order id. The final order id which is paid may be different from this one

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.(Equal to total fee at the moment. After coupon feature is finished, this value 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 (UTC-7 Summer Time))

create_time String

Time when order is created(according to the latest order)(yyyy-MM-dd HH:mm:ss, UTC-8 (UTC-7 Summer Time))

currency String

Currency. Default value is CAD.

channel String

Channel. Alipay,Wechat.

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

ERROR

Name Description
return_code

Error Code

return_msg

Error Description

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 payment order id

refund_id String

Required, Partner refund order id

JSON keys

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.

Query Params

Field Type Description
time Long

Required, UTC timestamp in milliseconds

nonce_str String

Required, Random string

sign String

Required, Sign

Success 200

Field Type Description
return_code String

Execution result

result_code String
  • WAITING: Order is being submitted to WeChat
  • CREATE_FAILED: Fail to submit to WeChat
  • 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

Payment order does not exist

ORDER_MISMATCH

Payment 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

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

Content-Type

application/json

Path Variable

Field Type Description
partner_code String

Required, Partner code

order_id String

Required, Partner payment order id

refund_id String

Required, Partner refund order id

Query Params

Field Type Description
time Long

Required, UTC timestamp in milliseconds

nonce_str String

Required, Random string

sign String

Required, Sign

Success 200

Field Type Description
return_code String

Execution result

result_code String
  • WAITING: Order is being submitted to WeChat
  • CREATE_FAILED: Fail to submit to WeChat
  • SUCCESS: Submission succeeded
  • FAILED: Refund failed
  • FINISHED: Refund succeeded(funds have 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

Payment order does not exist

ORDER_MISMATCH

Payment 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

ERROR

Name Description
return_code

Error Code

return_msg

Error Description

CommonApi - Check Orders

Get a list of orders. This api may change in the future.

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 (UTC-7 Summer Time). 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

sign String

Required, 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

currency String

Currency

create_time String

Time when order is created, which is formatted in 'yyyy-MM-dd HH:mm:ss', UTC-8 (UTC-7 Summer Time)

pay_time String

Time when order is paid, which is formatted in 'yyyy-MM-dd HH:mm:ss', UTC-8 (UTC-7 Summer Time). will be null if not paid

status String

order status

  • SUBMITTING: Submitting to wechat
  • SUBMIT_FAIL: Submission failed
  • WAITING_PAYMENT: Submission succeeded and wait for payment
  • CLOSED: Order closed
  • PAYMENT_FAIL: Payment failed
  • SUCCESS: Payment succeeded
order_body String

Order description

gateway String
  • QR Code: QR Code payment. User use WeChat client to scan the QR Code provided to finish the payment
  • JSAPI: JSAPI payment. User use WeChat client to open the payment page and finish the payment in page
  • OFFLINE: Offline payment. Partner uses equipments to scan user's payment QR Code or BarCode provided by WeChat Wallet
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

Name Description
return_code

Error Code

return_msg

Error Description

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

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

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 (UTC-7 Summer time)

time Long

Required, UTC timestamp in milliseconds

nonce_str String

Required, Random string

sign String

Required, Sign

ROOT

Field Type Description
return_code String

Execution result,SUCCESS

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 (UTC-7 Summer time)

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

  • 0: AlphaPay EftPOS Payment Code (Scan Payment Code displaying in customer's device)
  • 1: AlphaPay EftPOS Order Code (Customer scan QR Code displaying on POS screen)
  • 2: AlphaPay Static Merchant QRCode
  • 3: QRCode Gateway
  • 4: JSAPI Gateway
  • 5: Gateway for third-party EftPOS Payment Code
  • 6: Gateway for third-party EftPOS Order Code
  • 7: AlphaPay Static Merchant QRCode(deprecated)
  • 8: H5 Payment Gateway
channel String

Payment Channel (Alipay, Wechat)

type String

Trade Direction

  • Credit: Income
  • Debit: Outcome
currency String

currency(CAD/CNY)

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

settle_amount int

Settle amount, CAD cents

exchange_rate double

Using exchange rate

remark String

Remark

ERROR

Name Description
return_code

Error Code

return_msg

Error Description

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

CommonApi - Query Settlement Details

This Api will list all transactions with the settlement this 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.
Notice: A payment order or refund order can contains several transaction records

https://mpay.AlphaPay.com.au/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 (UTC-7 Summer Time)

time Long

Required, UTC timestamp in milliseconds

nonce_str String

Required, Random string

sign String

Required, Sign

ROOT

Field Type Description
return_code String

Execution result,SUCCESS

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 (UTC-7 Summer Time)

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

  • 0: AlphaPay EftPOS Payment Code (Scan Payment Code displaying in customer's device)
  • 1: AlphaPay EftPOS Order Code (Customer scan QR Code displaying on POS screen)
  • 2: AlphaPay Static Merchant QRCode
  • 3: QRCode Gateway
  • 4: JSAPI Gateway
  • 5: Gateway for third-party EftPOS Payment Code
  • 6: Gateway for third-party EftPOS Order Code
  • 7: AlphaPay Static Merchant QRCode(deprecated)
  • 8: H5 Payment Gateway
channel String

Payment Channel (Alipay, Wechat)

type String

Trade Direction

  • Credit: Income
  • Debit: Outcome
currency String

currency(CAD/CNY)

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

settle_amount int

Amount to make settlement, CAD cents

surcharge_rate String

Rate of surcharge (x%)

surcharge int

Surcharge amount, CAD cents

transfer_amount int

Amount send to merchant's bank account, CAD cents

exchange_rate double

Using exchange rate

remark String

Remark

ERROR

Name Description
return_code

Error Code

return_msg

Error Description

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

API

API List

API - Payment Success Notice

If notify_url is provided when order is created. System will post request to this url when the payment succeeds. Request method is POST. Different from Server APIs, sign parameters will be included in json entity. Partner system shall valid them to prevent fake requests. Partner system shall response with correct parameters. If AlphaPay did not receive valid response, system will regard as receiving failed and retry the notification. System will retry up to3 times. Partner system shall be able to handle the repeated requests.

post
https://pay.alphapay.ca/notify_url

Header

Field Description
Accept

application/json

Content-Type

application/json

JSON keys

Field Type Description
time long

UTC timestamp in millis

nonce_str String

Random string

sign String

Sign

partner_order_id String

Partner order id

order_id String

AlphaPay order id

total_fee int

Order amount

real_fee int

Actual paid amount

rate Double

Exchange Rate used while trading. 1CAD=?CNY

currency String

Currency,CAD

channel String

Payment Channel Alipay、Wechat

create_time String

Time when order is created, which is formatted in 'yyyy-MM-dd HH:mm:ss', UTC-8 (UTC-7 Summer Time)

pay_time String

Time when order is paid, which is formatted in 'yyyy-MM-dd HH:mm:ss', UTC-8 (UTC-7 Summer Time).

Success 200

Field Type Description
return_code String

SUCCESS