Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications in this section to integrate with Alipay.

API Version

Minimum required API version: 1.2.0



    If you price your products in CNY, then you can pass CNY in your transaction requests. In this case, PaymentsOS will pass the settlement currency (instead of CNY) to Alipay. PaymentsOS does not convert the amount to the settlement currency (the original amount is passed 'as is').

  • Domestic merchants: CNY


The following table lists all supported requests for ewallet-based transactions.

Use the bodybuilder to create a sample request body for each request type.

Charge Both partial and multiple are supportedAsynchronous and SynchronousInstallments are not supported.
Refund Both partial and multiple are supportedSynchronousThe refund must be initiated within a certain time period after the payment, which is specified in your contract with Alipay. Usually, a 365-day period is specified.

Setup Procedures

The following table lists the setup procedures that are specific to this provider.

In the PaymentsOS Control Center, configure the following credentials:
  • partner_id: The merchant UID/PID.
  • md5_key: The MD5 private key. This is a 32-byte string, composed of letters and numbers.
  • settlement_currency: Default settlement currency code. This must be one of the currency codes configured in your Alipay account. Format: a three character ISO-4217 currency code. See Currencies for a list of supported currencies.
In the PaymentsOS Control Center, configure a timeout_rule value. This is the timeout period from the moment the customer logs into the Alipay site (for completing the transaction) to completing the payment. Possible values: 5m 10m 15m 30m 1h 2h 3h 5h 10h 12h. Default: 12h. Important note: To pass a timeout value, you must contact Alipay support to specify the timeout value in your Alipay account as wellOptional
In the PaymentsOS Control Center, set 'international_integration' to 'False' if you are a domestic Chinese merchant. Set 'international_integration' to 'True' if you have an entity outside of China. Default is 'True' (international).Optional

Integration Procedures

The following sections list the integration procedures that are specific to this provider.

Implementing the Payment Flow

As part of the payment flow, you must redirect customers to the Alipay page on which they can complete the transaction.

The steps in the flow are as follows:

  1. Create a Payment.

  2. Implement a redirection flow. This involves invoking the Create Charge API, and redirecting customers to the Alipay page on which they can complete the transaction (we provide you with the Alipay site URL in the Redirection object of the charge response data.)

  3. After completing the flow, users will be redirected to your merchant_site_url on which you can display a payment completed message.


You can use the credentials below for testing.

International merchants:

  • PARTNER_ID: ‘2088621925033412’,
  • MD5_KEY: ‘tfhwk6rj0ac02ym0olvdibv7fumfjl2u’

Domestic Chinese merchants:

  • PARTNER_ID: ‘2088102180483272’,
  • MD5_KEY: ‘knyzygllasbtlktnhvuc6a7g822ipunr’

End user credentials:

Last modified November 9, 2022