AlipayHKAlipayHKDOCS

System flow

1. State diagram of a cashless voucher template

image

The diagram shows the different states of a cashless voucher template record. A template could be in a DRAFT, AUDIT, ACTIVATING, FAILED, ACTIVATED, PAUSED, or CLOSED state. Each state represents how a cashless voucher responds to various events by changing from one state to another. 

2. Create a cashless voucher template

image

  1. The merchant creates a cashless voucher template to create a new template in the merchant/ISV server.
  2. The merchant/ISV server will verify and save the input template details. If no problem is found, a template creation request is sent to the AlipayHK server via alipay.intl.merchantcenter.cashlessvoucher.template.create API with ClientID and RequestID. ClientID is a unique ID generated by the AlipayHK platform to identify the merchant's application, and RequestID is a unique ID generated by the merchant/ISV server to identify the voucher template record.
  3. AlipayHK server will respond to the template creation result. If successful, the merchant/ISV server will update the records with TemplateID and mark the record status to DRAFT by using RequestID. Otherwise, the API responses fail, the template record will be updated to FAILED in record status by using RequestID.
  4. After the template record is created, the merchant/ISV server can set up a periodic task to check the approval result of the template in the Alipay promotion platform. The task will call alipay.intl.merchantcenter.cashlessvoucher.template.detail API with ClientID, TemplateID. The API will respond to the template record details. If the template record status is ACTIVATED, FAILED, or CLOSED, the task check will be terminated and the merchant/ISV server will update its template record status accordingly.

3. Manage a cashless voucher template

image

  1. The merchant can manage their cashless voucher templates in the merchant/ISV server. The server will send a query request to AlipayHK via alipay.intl.merchantcenter.cashlessvoucher.template.list API with ClientID.
  2. The merchant server will receive the requested template list from AlipayHK and then display it to the merchant.
  3. The merchant can select a voucher template to browse the details. The merchant/ISV server will send an API call to alipay.intl.merchantcenter.cashlessvoucher.template.detail with ClientID and TemplateID. After the response is returned, the merchant/ISV server will display the voucher template details.
  4. If the status of voucher template is DRAFT, PAUSED, or ACTIVATED, the merchant can close the voucher promotion. The merchant/ISV server will send a request of the alipay.intl.merchantcenter.cashlessvoucher.tempalte.switchStatus API by using ClientID, TemplateID, CLOSED status to the AlipayHK server. After the response is returned, the merchant/ISV server will update its record status accordingly.
  5. If the status of the voucher template is ACTIVATED, the merchant can pause the voucher promotion. The merchant/ISV server will send a request of the alipay.intl.merchantcenter.cashlessvoucher.tempalte.switchStatus API by using ClientID, TemplateID, PAUSE status to the AlipayHK server. After the response is returned, the merchant/ISV server will update its record status accordingly.
  6. If the status of the voucher template is PAUSED, the merchant can reactivate the voucher promotion. The merchant/ISV server will send a request of the alipay.intl.merchantcenter.cashlessvoucher.tempalte.switchStatus API by using ClientID, TemplateID, ACTIVATED status to the AlipayHK server. After the response is returned, the merchant/ISV server will update its record status accordingly.

4. Issue a cashless voucher

image

If a cashless voucher template is activated (the record status is ACTIVATED) in the AlipayHK promotion platform, the voucher will be displayed on the merchant promotion page in the AlipayHK app during the promotion period (between startDate and endDate in the template record).

AlipayHK users can collect merchant vouchers on the merchant promotion page. AlipayHK app will send an issue voucher request with UID, TemplateID to the AlipayHK backend server when users click Collect in a merchant voucher. If the voucher issue is fulfilled, the voucher will be added to the users' coupon wallets.

5. Redeem a cashless voucher

The vouchers will be redeemed automatically if redemption conditions are matched. The actual amount that the user has to pay will be equal to the order amount minus the face value of the coupon. For Example, if the user has a $10 HKD cash coupon issued by the merchant when a $ 100 HKD payment order is placed, the coupon will be redeemed automatically and the user will have to pay $90 HKD for the order. This transaction will settle $90 HKD to the merchant, assume that no fee is deducted from the transaction.

image

6. Download cashless voucher usage report

Reconciliation files below are available for the merchant to download via SFTP:

  1. Cashless voucher issue status file
  2. Cashless voucher redemption status file

To obtain your reconciliation files through SFTP, complete the following steps:

  1. Contact Alipay to get your public IP address added to white list. Contact Global Merchant Technical Support (overseas_support@service.alibaba.com) to submit your PID and public IP address with which you visit the SFTP server. If you are using sandbox environment, submit your test PID and public IP address. 
  2. After receiving your request in step 1, Alipay will send you the SFTP login credentials within 3 working days.
  3. Connect to SFTP server to download files. For example, you can select a frequently used tool according to your specific requirements to connect to SFTP. Use the following settings to log in and obtain files:
  • Port: 22
  • Host name: sftp.alipay.com 
  • Username and password

Notes:

  • SFTP accounts that are not used for 90 days are closed.
  • Files older than 7 days on the SFTP server might be removed. It is suggested to download the files within 3 days. If the file you need is deleted, contact Global Technical Support (overseas_support@service.alibaba.com) for help.