× CAD 中文
Overview

Request And Parameters

Sign Algorithm

Payment Success Notification

QR Code Payment
Create QR Code Payment     - QR Payment in AlpayPay
Alipay Online Payment
Create Alipay Online Order
JSAPI
Create JSAPI Order     - WeChatPay JSAPI     - Alipay JSAPI
Mobile H5
Create Alipay H5 Payment     - Alipay H5 rediret
APP - SDK
Create SDK Order
Mini Program
Create Mini Program Order
Retail Payment
Retail Passive Payment Retail Active Payment
Common API
Get Current Exchange Rate Query Order Status Apply For Refund Query Refund Order Status Check Orders Query Daily Transactions Query Settlement Details

Overview



Prepare


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


Payment Scenarios









Different Channel


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


Currency Codes


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


Business Roles


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




















API Endpoint


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

Request And Parameters



Parameters Format


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

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

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


Multi-Language


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






Sign Algorithm



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


Sign Process:

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

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





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.



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, 1USD=?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)


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














JSON Format Example








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 the QR Code generated when creating order and finish the payment.


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


Integration Process






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



Header

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


Path Variable

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


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent USD 1.00).
currency String Currency
Default value: USD
Allowed values: USD, 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'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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description


Two ways to display the QR code for payment


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













































Requeset Example


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




















































Response Example








QR Code - QR Code Payment Page in AlphaPay


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

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


Path Variable

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


Query Params

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


Error Code

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


ERROR

Name Description
return_code Error Code
return_msg Error Description


















Request Example


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



Alipay Online Payment - Create Alipay Online Order


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


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


Integration Process







Header

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


Path Variable

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


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent USD 1.00).
currency String Currency
Default value: USD
Allowed values: USD , 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


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













































Response Example









Example Redirect to Alipay Payment Page

pay_url should add time, nonce_str, sign Parameters

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




JSAPI - Create JSAPI Payment Order


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


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

Integration Process






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


Header

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


Path Variable

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


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent USD 1.00).
currency String Currency
Default value: USD
Allowed values: USD , 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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description


Make a payment

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
















































Request Example


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

















































Response Example




JSAPI - WeChat JSAPI Payment Page


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


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

Path Variable

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


Query Params

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


Error Code

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


ERROR

Name Description
return_code Error Code
return_msg Error Description















Request Example


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



JSAPI - Alipay JSAPI Payment Page


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


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


Path Variable

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


Query Params

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


Error Code

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


ERROR

Name Description
return_code Error Code
return_msg Error Description


















Request Example


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




MobileH5 - Create H5 Payment


Warning:WeChat Pay does not support 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.


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


Integration Process




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



Header

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


Path Variable

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


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent USD 1.00).
currency String Currency
Default value: USD
Allowed values: USD , 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 capitalization
SECONDARY_MERCHANT_ID_INVALID Please contact AlphaPay for more details


ERROR

Name Description
return_code Error Code
return_msg Error Description


Make a Payment

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













































Request Example


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















































Response Example







MobileH5 - H5 Payment Page


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


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


Path Variable

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


Query Params

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


Error Code

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


ERROR

Name Description
return_code Error Code
return_msg Error Description


















Request Example


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




SDK Payment - Create SDK Order


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


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


Integration Process





Header

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


Path Variable

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


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent USD 1.00).
currency String Currency
Default value: USD
Allowed values: USD , 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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description


Make a Payment

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







































Request Example


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





Miniprogram Payment - Create Miniprogram Order


Use for WeChat Payment in miniprogram. After creating the order, get returned data and redirect param. WeChat Channel Only.


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


Integration Process





Header

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


Path Variable

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


JSON

Field Type Description
description String Required, Description of an order. (Maximum length 128 characters)
price int Required, Price of the order. Use the base unit of the currency (E.g use 100 to represent USD 1.00).
currency String Currency
Default value: USD
Allowed values: USD , 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 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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description


Make a Payment

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













































Request Example


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





RetailPay - Create Retail Passive Payment Order



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



Integration Process





PUT
 https://pay.alphapay.com/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 USD 1.00).
currency String Currency
Default value: USD
Allowed values: USD , CNY
notify_url String AlphaPay System will post Json Package to notify url (if provided) when the payment succeeds. (Details on Payment Success Notification)
device_id String Required, ID of the device which sends the request. This ID only helps to record the device information.
auth_code String Required, The Payment QR Code scanned from customer's WeChat/Alipay 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 USD.
channel String Channel. Alipay, Wechat
order_description String Description of order
customer_id String ID of WeChat or 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 complete the payment
NOTSUPORTCARD Card type is not supported
AUTH_CODE_ERROR Payment QR Code has been used more than once
AUTH_CODE_INVALID The submitted QR Code is not a WeChat\Alipay Payment QR Code
SYSTEMERROR Exception inside system
INVALID_SHORT_ID Partner code is invalid or there is no partner associated with this code
SIGN_TIMEOUT Sign expired, the difference between time and the server time is more than 5 minutes
INVALID_SIGN Invalid sign
PARAM_INVALID Parameters are invalid. See return_msg for more details.
NOT_PERMITTED Gateway payment permission has not been enabled for this partner
INVALID_CHANNEL Channel name is not available, check the capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description













































Request Example






































Response Example






RetailPay - Create Retail Active Payment Order



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



Integration Process





PUT
 https://pay.alphapay.com/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 USD 1.00).
currency String Currency
Default value: USD
Allowed values: USD , 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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description













































Request Example


















































Response Example






CommonApi - Get Current Exchange Rate


Get the current exchange rate from USD to CNY provided by WeChat(USD 1=CNY ?) and Alipay(USD 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.com/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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description

















Request Example


https://pay.alphapay.com/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.com/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. 1USD=?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 USD.
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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description

















Request Example


https://pay.alphapay.com/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 order. The total amount of all refund orders must be less than or equal to the actual paid amount, and the currency of the refund order is the same as the payment order.


PUT
 https://pay.alphapay.com/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
channel String Payment channel, "Wechat" or "Alipay"
channel_refund_id String Channel Refund id, it will show if it has
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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description








































































Response Example







CommonApi - Query Refund Order Status


GET
 https://pay.alphapay.com/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
channel_refund_id String Channel Refund id, it will show if it has
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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description


















































Response Example








CommonApi - Check Orders


GET
 https://pay.alphapay.com/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
channel_error_message String The reason of failure in creating order or making payment


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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description






CommonApi - Query Daily Transactions



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



GET
 https://pay.alphapay.com/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. QR Code Gateway
  5. JSAPI Gateway
  6. Offline Payment
  7. Offline Payment
  8. Static Merchant QR Code
  9. Mobile H5 Gateway
  10. Third-party Gateway
  11. APP SDK Gateway
  12. Share Code Gateway
  13. MiniProgram Gateway
  14. Native Payment Gateway
  15. Share Link Gateway
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, USD 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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description

















































Response Example








CommonApi - Query Settlement Details



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


GET
 https://pay.alphapay.com/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 (USD cent)
total_debit int Total debit amount (USD cent)
total_surcharge int Total surcharge amount (USD cent)
total_transfer int Total amount sending to merchant's bank account (USD 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. QR Code Gateway
  5. JSAPI Gateway
  6. Offline Payment
  7. Offline Payment
  8. Static Merchant QR Code
  9. Mobile H5 Gateway
  10. Third-party Gateway
  11. APP SDK Gateway
  12. Share Code Gateway
  13. MiniProgram Gateway
  14. Native Payment Gateway
  15. Share Link Gateway
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, USD cents
surcharge_rate String Rate of surcharge (x%)
surchargee int Surcharge amount, USD cent
transfer_amount int Amount send to merchant's bank account, USD 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 capitalization


ERROR

Name Description
return_code Error Code
return_msg Error Description