Alipay In-App Payments
The requests outlined in this document will need to be processed manually using our Webservices API.

Features
![]() |
![]() |
![]() |
![]() |
Protect Plus![]() |
Supported.![]() |
![]() |
![]() |
![]() |
![]() |
Configuration
To enable Alipay on your account, please get in touch with your account manager.
A test sandbox account will be provided, which you will need when testing your implementation.

Process overview
1. Initiate the customer
When the customer chooses to pay with Alipay, your system will need to perform an AUTH request and, if successful, redirect the customer’s browser to the URL returned in the response.
AUTH request (In-App Payments)
The example request below is for an Alipay AUTH request using the In-App Payments interface:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth = { "currencyiso3a": "EUR", "paymenttypedescription": "ALIPAY", "billinglastname": "Bloggs", "requesttypedescriptions": ["AUTH"], "sitereference": "test_site12345", "accounttypedescription": "ECOM", "billingcountryiso2a": "DE", "baseamount": "1050", "billingfirstname": "Joe", "orderreference": "My_Order_123", "applicationtype": "APP", "applicationsystem": "ios" } strequest = securetrading.Request() strequest.update(auth) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) { throw new Exception('Composer autoloader file could not be found.'); } require_once($autoload); $configData = array( 'username' => '[email protected]', 'password' => 'Password1^' ); $requestData = array( 'currencyiso3a' => 'EUR', 'requesttypedescriptions' => array('AUTH'), 'accounttypedescription' => 'ECOM', 'sitereference' => 'test_site12345', 'baseamount' => '1050', 'paymenttypedescription' => 'ALIPAY', 'billingfirstname' => 'Joe', 'billinglastname' => 'Bloggs', 'billingcountryiso2a' => 'DE', 'orderreference' => 'My_Order_123', 'applicationtype' => 'APP', 'applicationsystem' => 'ios', ); $api = \Securetrading\api($configData); $response = $api->process($requestData); var_dump($response->toArray()); ?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{ "alias": "[email protected]", "version": "1.00", "request": [{ "currencyiso3a": "EUR", "requesttypedescriptions": ["AUTH"], "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "ALIPAY", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "DE", "orderreference": "My_Order_123", "applicationtype": "APP", "applicationsystem": "ios" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescriptions":["AUTH"],"accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"ALIPAY","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"DE","orderreference":"My_Order_123","applicationtype":"APP","applicationsystem":"ios"}]}
<?xml version='1.0' encoding='utf-8'?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="AUTH"> <merchant> <orderreference>MyOrder123</orderreference> </merchant> <billing> <name> <first>Joe</first> <last>Bloggs</last> </name> <amount currencycode="EUR">1050</amount> <payment type="ALIPAY"/> </billing> <operation> <sitereference>test_site12345</sitereference> <accounttypedescription>ECOM</accounttypedescription> <applicationtype>APP</applicationtype> <applicationsystem>ios</applicationsystem> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | Only “ECOM” (e-commerce) is supported. |
![]() |
applicationsystem XPath: /operation/applicationsystem |
Alpha (7) | Required if applicationtype is “APP”. Defines the platform on which the app is being run. Supported values are “android” and “ios”. |
![]() |
applicationtype XPath: /operation/applicationtype |
Alpha (3) | Determines the payment interface displayed to the customer after they have been redirected to the checkout hosted by Alipay:
If “APP” is submitted – The transaction is processed using the Alipay In-App Payments interface, which is primarily designed for use from within mobile apps. Note: Before processing transactions using In-App Payments (both through the sandbox environment and with live payments), you will need to contact Alipay and request for the functionality to be enabled on your Alipay account. |
![]() |
baseamount XPath: /billing/amount |
Numeric (13) | The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000. This value must be greater than zero.
Max length may vary depending on your acquiring bank. Contact your bank for further info. |
![]() |
billingprefixname XPath: /billing/name/prefix |
Alphanumeric including symbols (25) |
The prefix of the customer’s billing name (e.g. Mr, Miss, Dr). |
![]() |
billingfirstname XPath: /billing/name/first |
Alphanumeric including symbols (127) |
The customer’s billing first name. |
![]() |
billingmiddlename XPath: /billing/name/middle |
Alphanumeric including symbols (127) |
The customer’s billing middle name(s). |
![]() |
billinglastname XPath: /billing/name/last |
Alphanumeric including symbols (127) |
The customer’s billing last name. |
![]() |
billingsuffixname XPath: /billing/name/suffix |
Alphanumeric including symbols (25) |
The suffix of the customer’s billing name (e.g. Bsc). |
![]() |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency that the transaction will be processed in (in iso3a format).
For a list of currency codes supported by Alipay, refer to the list found at the top of this page. |
![]() |
orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (255) |
Your unique order reference that can be stored on Trust Payments and Alipay’s systems. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value must be submitted as “ALIPAY”. |
![]() |
requesttypedescription XPath: /@type |
Alpha (20) | The value in the request must be “AUTH”. |
![]() |
sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team. |
AUTH response
{ u'requestreference': u'An3ug1kap', u'version': u'1.00', u'response': [{ u'transactionreference': u'23-86-113', u'merchantname': u'Test Merchant', u'paymenttypedescription': u'ALIPAY', u'orderreference': u'My_Order_123', u'settleduedate': u'2017-03-16', u'baseamount': u'1050', u'transactionstartedtimestamp': u'2020-03-16 16:25:08', u'errormessage': u'Ok', u'settlestatus': u'10', u'accounttypedescription': u'ECOM', u'errorcode': u'0', u'requesttypedescription': u'AUTH', u'operatorname': u'[email protected]', u'livestatus': u'0', u'currencyiso3a': u'EUR', u'partner id': u'2088611221573217' }] }
array(3) { ["requestreference"] => string(9) "A0345jmuw" ["version"] => string(4) "1.00" ["response"] => array(1) { [0]=> array(17) { ["transactionreference"] => string(9) "23-86-113" ["merchantname"] => string(4) "Test Merchant" ["paymenttypedescription"] => string(6) "ALIPAY" ["orderreference"] => string(12) "My_Order_123" ["transactionstartedtimestamp"] => string(19) "2020-03-16 16:25:08" ["errormessage"] => string(2) "Ok" ["accounttypedescription"] => string(4) "ECOM" ["errorcode"] => string(1) "0" ["settleduedate"] => string(10) "2017-03-16" ["currencyiso3a"] => string(3) "EUR" ["baseamount"] => string(4) "1050" ["requesttypedescription"] => string(4) "AUTH" ["operatorname"] => string(11) "[email protected]" ["livestatus"] => string(1) "0" ["settlestatus"] => string(2) "10" ["partner id"] => string(16) "2088611221573217" } } }
{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionreference":"23-86-113","merchantname":"Test Merchant","paymenttypedescription":"ALIPAY","orderreference":"My_Order_123","settleduedate":"2017-03-16","baseamount":"1050","transactionstartedtimestamp":"2020-03-16 16:25:08","errormessage":"Ok","settlestatus":"10","accounttypedescription":"ECOM","errorcode":"0","requesttypedescription":"AUTH","operatorname":"[email protected]","livestatus":"0","currencyiso3a":"EUR","partner id":"2088611221573217"}],"secrand":"zO9"}
<?xml version='1.0' encoding='utf-8'?> <responseblock version="3.67"> <requestreference>Xd4nk260v</requestreference> <response type="AUTH"> <merchant> <merchantname>Test Merchant</merchantname> <orderreference>MyOrder123</orderreference> <operatorname>[email protected]</operatorname> <partnerid>2088101122136241</partnerid> </merchant> <transactionreference>44-86-102</transactionreference> <timestamp>2020-03-16 17:34:16</timestamp> <operation> <accounttypedescription>ECOM</accounttypedescription> </operation> <settlement> <settleduedate>2017-03-16</settleduedate> <settlestatus>10</settlestatus> </settlement> <billing> <amount currencycode="EUR">1050</amount> <payment type="ALIPAY"/> </billing> <live>0</live> <error> <message>Ok</message> <code>0</code> </error> </response> <secrand>Z1W</secrand> </responseblock>
Field specification
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | The value returned is “ECOM”. |
![]() |
baseamount XPath: /billing/amount |
Numeric (13) | The amount of the transaction in base units, with no commas or decimal points, so £10 is returned as 1000. |
![]() |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency that the transaction was processed in (in iso3a format). |
![]() |
errorcode XPath: /error/code |
Numeric (1-5) | The error code should be used to determine if the request was successful or not.
|
![]() |
errordata XPath: /error/data |
Alphanumeric (255) | Additional information to help troubleshoot the error. |
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (255) |
The unique order reference stored on Trust Payments and Alipay’s system. |
![]() |
partnerid XPath: /merchant/partnerid |
Numeric (16) | A unique identifier for Alipay partners. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “ALIPAY”. |
![]() |
requesttypedescription XPath: /@type |
Alpha (20) | The value returned is “AUTH”. |
![]() |
settlestatus XPath: /settlement/settlestatus |
Numeric (3) | This allows you to determine the status of the payment. Refer to the Handling the response section below for information on how to best interpret this field. |
![]() |
signeddata XPath: /other/signeddata |
Returned from Alipay. Must be submitted using the SDK when customer is being redirected to the Alipay app. |
Handling the response
When handling the AUTH response for Alipay payments, the recommendations outlined in our Best practices still need to be followed, with exception to the handling of the settlestatus field, which is subject to different conditions that are detailed below:
The settlestatus returned in the AUTH response is used to determine the status of the Alipay payment:

- The funds have not yet been settled into your bank account.
- The next step is to redirect the customer’s device to the Alipay app using their SDK to continue with the payment.
Funds will not be settled into your account until the customer is redirected to Alipay’s app, in order to complete the payment. Read on for further information.
- When there is an update to the settle status of the AUTH, you will receive a URL notification to inform you that the settlestatus has been updated to either “3” or “100”.
- Further information on the notifications can be found below.

- The payment has been declined, or has encountered an error.
- To learn more about why the payment was unsuccessful, you will need to look at the errorcode. e.g. “70000” indicates that the payment was declined. Click here for a full list of error codes.
- In rare cases, the settlestatus can be updated from “3” to “100” (indicating payment has successfully settled). If this occurs, you will receive another URL notification to inform you. e.g. This can be due to the customer contacting Alipay directly to resolve an issue on their account that was preventing the payment from being processed successfully.
2. Redirect to Alipay app
After checking the AUTH response, if the request was successful, you will need to redirect the customer’s device to the Alipay app using their SDK, including the signeddata returned in the AUTH response.

Once on the app, the customer will be prompted to enter additional information in order to complete the payment. At a later time, providing the customer has successfully completed the required steps on the Alipay app, the customer’s device will be redirected back to your app.

3. Verify Auth Response
To verify that the payment was processed successfully while the customer was using the Alipay app, you will need to submit a VERIFYAUTHRESPONSE request to Trust Payments:
VERIFYAUTHRESPONSE request
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) verifyAuthResponse = { "requesttypedescriptions": ["VERIFYAUTHRESPONSE"], "parenttransactionreference": "44-86-102", "sitereference": "test_site12345", "verifystring": "ALIPAY SYNC RESPONSE STRING" } strequest = securetrading.Request() strequest.update(verifyAuthResponse) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) { throw new Exception('Composer autoloader file could not be found.'); } require_once($autoload); $configData = array( 'username' => '[email protected]', 'password' => 'Password1^' ); $requestData = array( 'requesttypedescriptions' => array('VERIFYAUTHRESPONSE'), 'parenttransactionreference' => '44-86-102', 'sitereference' => 'test_site12345', 'verifystring' => 'ALIPAY SYNC RESPONSE STRING' ); $api = \Securetrading\api($configData); $response = $api->process($requestData); var_dump($response->toArray()); ?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{ "alias": "[email protected]", "version": "1.00", "request": [{ "requesttypedescriptions": ["VERIFYAUTHRESPONSE"], "parenttransactionreference": "44-86-102", "sitereference": "test_site12345", "verifystring": "ALIPAY SYNC RESPONSE STRING" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["VERIFYAUTHRESPONSE"],"parenttransactionreference":"44-86-102","sitereference":"test_site12345","verifystring":"ALIPAY SYNC RESPONSE STRING"}]}
<?xml version='1.0' encoding='utf-8'?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="VERIFYAUTHRESPONSE"> <operation> <parenttransactionreference>44-86-102</parenttransactionreference> <sitereference>test_site12345</sitereference> <verifystring>ALIPAY SYNC RESPONSE STRING</verifystring> </operation> </request> </requestblock>
Field specification
Field | Format | Description | |
![]() |
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
The transactionreference returned in the AUTH response. |
![]() |
requesttypedescriptions XPath: /@type |
Alpha (20) | You must submit “VERIFYAUTHRESPONSE”, as shown in the request example. |
![]() |
sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
Identifies your site on the Trust Payments system.
If you do not know your site reference, please contact our Support Team. |
![]() |
verifystring XPath: /operation/verifystring |
Returned when customer is redirected back from the Alipay app. |
VERIFYAUTHRESPONSE response
The information returned in the VERIFYAUTHRESPONSE response should be used to determine the message displayed to the customer following their payment attempt.
{ u'requestreference': u'An3ug1kap', u'version': u'1.00', u'response': [{ u'transactionstartedtimestamp': u'2020-03-16 16:25:08', u'errormessage': u'Ok', u'errorcode': u'0', u'requesttypedescription': u'VERIFYAUTHRESPONSE', }] }
array(3) { ["requestreference"] => string(9) "A0345jmuw" ["version"] => string(4) "1.00" ["response"] => array(1) { [0]=> array(4) { ["transactionstartedtimestamp"] => string(19) "2020-03-16 16:25:08" ["errormessage"] => string(2) "Ok" ["errorcode"] => string(1) "0" ["requesttypedescription"] => string(18) "VERIFYAUTHRESPONSE" } } }
{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionstartedtimestamp":"2020-03-16 16:25:08","errormessage":"Ok","errorcode":"0","requesttypedescription":"VERIFYAUTHRESPONSE"}],"secrand":"zO9"}
<?xml version='1.0' encoding='utf-8'?> <responseblock version="3.67"> <requestreference>Xd4nk260v</requestreference> <response type="VERIFYAUTHRESPONSE"> <timestamp>2020-03-16 17:34:16</timestamp> <error> <message>Ok</message> <code>0</code> </error> </response> <secrand>Z1W</secrand> </responseblock>
Field specification
Field | Format | Description | |
![]() |
errorcode XPath: /error/code |
Numeric (1-5) | The error code should be used to determine if the request was successful or not.
|
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
requesttypedescription XPath: /@type |
Alpha (20) | The value returned is “VERIFYAUTHRESPONSE”. |
![]() |
transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss | The time the request was processed. |
4. Payment completion
After receiving the VERIFYAUTHRESPONSE response, you will need to use the data returned in order to display the appropriate response message stating the outcome of the payment (e.g. success / error).
If configured, our system will submit a URL notification to inform you of the authorisation outcome. Following authorisation, funds will be settled at a later time, as determined by Alipay.


In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled into your account.
Configuring the authorisation notification
We recommend including at least the following fields in URL notifications sent on authorisation:
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in URL notifications sent on settlement:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled into your account. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.
Refunds
After processing a payment with Alipay, it is possible to pay the customer back by submitting a REFUND request.

Requirements
- You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
- You cannot refund a greater amount than was originally settled.
The REFUND request and response for Alipay payments follow the same field specification as outlined in our standard REFUND documentation. Click here for further information.
BancontactAlipay