Contents

Alipay

 

The requests outlined in this document will need to be processed manually using our Webservices API.

 

PAYMENT ALIPAY
Alipay is a Chinese e-wallet that belongs to AntFinancial, an affiliate of the Alibaba group, the largest e-commerce company in the world. When selecting Alipay, customers will be redirected to their hosted pages, enter their personal details and agree to the payment, before being redirected back to your website. Once completed, you will receive confirmation via a URL notification.

 

Features

Supported customer countries AUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, KRW, NOK, NZD, SEK, SGD, THB, USD
Supported currencies
EUR, GBP, USD
Protect Plus Supported.
Refunds Full and partial refunds supported.
Chargebacks Payments are not subject to chargebacks.

 


 

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.

Info
This integration supports Alipay WAP Payments (Wireless Application Protocol)

Before you can begin processing WAP Payments, you will need to contact Alipay and request your account is enabled for WAP Payments.

 

Click here to learn more about WAP Payments >>>

 


 

Process overview

1

Initiate the customer

 

2

Redirect to Alipay

 

3

Payment completion

 

 


 

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 (E-commerce)

The example request below is for an e-commerce Alipay AUTH request:


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
    "returnurl": "https://www.example.com/return",
    "currencyiso3a": "EUR",
    "paymenttypedescription": "ALIPAY",
    "billinglastname": "Bloggs",
    "requesttypedescriptions": ["AUTH"],
    "sitereference": "test_site12345",
    "accounttypedescription": "ECOM",
    "billingcountryiso2a": "DE",
    "baseamount": "1050",
    "billingfirstname": "Joe",
    "orderreference": "My_Order_123"
}

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',
    'returnurl' => 'https://www.example.com/return',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'DE',
    'orderreference' => 'My_Order_123'
);

$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",
    "returnurl": "https://www.example.com/return",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "DE",
    "orderreference": "My_Order_123"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescriptions":["AUTH"],"accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"ALIPAY","returnurl":"https:\/\/www.example.com\/return","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"DE","orderreference":"My_Order_123"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>MyOrder123</orderreference>
      <returnurl>https://www.example.com/return</returnurl>
    </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>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

AUTH request (WAP Payments)

The example request below is for an Alipay AUTH request using the WAP Payments interface:


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
    "returnurl": "https://www.example.com/return",
    "currencyiso3a": "EUR",
    "paymenttypedescription": "ALIPAY",
    "billinglastname": "Bloggs",
    "requesttypedescriptions": ["AUTH"],
    "sitereference": "test_site12345",
    "accounttypedescription": "ECOM",
    "billingcountryiso2a": "DE",
    "baseamount": "1050",
    "billingfirstname": "Joe",
    "orderreference": "My_Order_123",
    "applicationtype": "WAP"
}

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',
    'returnurl' => 'https://www.example.com/return',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'DE',
    'orderreference' => 'My_Order_123',
    'applicationtype' => 'WAP'
);

$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",
    "returnurl": "https://www.example.com/return",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "DE",
    "orderreference": "My_Order_123",
    "applicationtype": "WAP"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescriptions":["AUTH"],"accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"ALIPAY","returnurl":"https:\/\/www.example.com\/return","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"DE","orderreference":"My_Order_123","applicationtype":"WAP"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>MyOrder123</orderreference>
      <returnurl>https://www.example.com/return</returnurl>
    </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>WAP</applicationtype>
    </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.
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 this field is omitted from your request, the standard Alipay e-commerce checkout page is displayed to the customer (default behaviour).
  • If “WAP” is submitted – The transaction is processed using the Alipay WAP Payments interface (Wireless Application Protocol), which is primarily designed for use by mobile devices.

Note: Before processing transactions using WAP (both through the sandbox environment and with live payments), you will need to contact Alipay and request for WAP 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”.
returnurl
XPath: /merchant/returnurl
URL (2048) The URL that the customer will be returned to after processing a payment with 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'2017-03-16 16:25:08',
    u'errormessage': u'Ok',
    u'settlestatus': u'10',
    u'accounttypedescription': u'ECOM',
    u'errorcode': u'0',
    u'redirecturl': u'https://example.com',
    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) "2017-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"
      ["redirecturl"] => string(107) "https://example.com"
      ["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":"2017-03-16 16:25:08","errormessage":"Ok","settlestatus":"10","accounttypedescription":"ECOM","errorcode":"0","redirecturl":"https:\/\/example.com","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>2017-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>
    <other>
      <redirecturl>https://example.com</redirecturl>
    </other>
    <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.

  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

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.

Click here for a full list of errorcode and message values.

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”.
redirecturl
XPath: /other/redirecturl
URL (255) Redirect the customer’s browser to this URL, to allow them to complete the payment on Alipay’s hosted pages.
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.

 

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:

Settle status 10
If the settlestatus is “10”, the payment is pending settlement.

  • The funds have not yet been settled into your bank account.
  • The next step is to redirect the customer’s browser to redirecturl to complete the payment.

Funds will not be settled into your account until the customer is redirected to Alipay’s pages, 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.
Settle status 3
If the settlestatus is “3”, the payment has been cancelled.

  • 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

After checking the AUTH response, if the request was successful, you will need to redirect the customer’s browser to the redirecturl returned in the response.

Your system will need to redirect the customer’s browser to the redirecturl, which is a page hosted by Alipay, in order to process the payment. At a later time, providing the customer has successfully completed the required steps on Alipay’s hosted pages, the customer’s browser will be redirected back to the returnurl provided in the AUTH request.

Info
When testing, you will be displayed the sandbox as provided by Alipay. To complete a test transaction, you will need to follow the instructions displayed on screen. Please contact your account manager for test credentials to enter while on the sandbox.

 


 

3. Payment completion

Once the customer returns from the Alipay hosted page to the returnurl hosted on your site, we recommend that you display a confirmation message stating the payment was successful.

 

If configured, our system will submit a URL notification to inform you of the authorisation. Following authorisation, funds will be settled at a later time, as determined by Alipay.

PAYMENT
The settlement process for Alipay differs from the standard process followed with card-based payment methods.
URL
The notification may not be sent immediately after processing the AUTH. For this reason, you should display a success or error message to the customer immediately after they return from Alipay’s hosted pages, and not wait for this notification.

 

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:

 

Configuring the authorisation notification

We recommend including at least the following fields in URL notifications sent on authorisation:

*Please choose your preferred format.

 

Configuring the settlement notification

We recommend including the following fields in URL notifications sent on settlement:

 

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:

 


 

Refunds

After processing a payment with Alipay, it is possible to pay the customer back by submitting a REFUND request.

Info
Refunds for Alipay are settled immediately (settlestatus “100”).

 

Requirements

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.

 

investors in people logo   pci - security standards council logo

TRUST Payments LTD, No.1 Royal Exchange, London, EC3V 3DG.
A company registered in England and Wales with Company Number 04591066. VAT Number 756265116