Alipay Cross-border

REST API

Alipay Cross-border is a type of Wallet.

Countries and Currencies

Countries

Worldwide

Currencies

AUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, KRW, NOK, NZD, SEK, SGD, THB, USD
Communication Formats

This table illustrates how Alipay Cross-border notifications are encoded and which languages and methods can be used for requests and responses.

Requests/Responses

Format

XML

Methods

POST, GET

IPN Encodement

Please follow the instructions given at Instant Payment Notification to set up IPN.
Transaction Types

For transaction type details which are not given here look at Transaction Types.

Transaction Type Description Link to the sample

debit

debit samples

Used with autoDebit, containing a <periodic>.

refund-debit

refundDebit samples

authorization-only

Used with auto-debit: Initiates the sign agreement between Alipay Cross-border and the consumer.

authorization-only (sign) samples

authorization-only (unsign) samples
Test Credentials

URL(s) Endpoints

For the transaction types authorization-only and debit.

https://api-test.wirecard.com/engine/rest/paymentmethods/

For the transaction types refund-debit and refund-request.

https://api-test.wirecard.com/engine/rest/payments/

Merchant Account ID (MAID)

47cd4edf-b13c-4298-9344-53119ab8b9df

Username

16390-testing

Password

3!3013=D3fD8X7
Additional test credentials on Alipay Cross-border’s environment
debit and refund-debit: For Merchants and Consumers

Merchant Account

Partner

2088101122136241

Key

760bdzec6y9goq7ctyx96ezkz78287de

Consumer Account

Account Name

alipaytest20091@gmail.com

Password

111111

Payment Password

111111

Captcha Code

8888
auto-debit: For Merchants and Consumers

Merchant Account

Partner

2088621880535422

Key

2l2o3ew9ke8d3ojobck40tvur6pmj00h

Consumer Account

Account Name

15145493455

Password

a111111

Payment Password

b111111
Workflow
debit Workflow
Figure 10. debit Workflow

  1. Consumers add items to shopping basket.

  2. Consumers select Payment Method Alipay Cross-border.

  3. Merchant initiates a debit transaction.

  4. Alipay Cross-border responds with a redirection URL to the merchant.

  5. Merchant redirects consumer to Alipay Cross-border.

  6. Consumers enter their account data and confirm the payment.

  7. Alipay Cross-border processes the transaction

  8. Wirecard Payment Gateway receives transaction status.

  9. Wirecard Payment Gateway sends transaction status to merchant and redirects the consumer to the merchant.

  10. Merchant receives the transaction’s status and displays the completion of the payment process to the consumer.

Fields

Most of the fields used for Alipay Cross-border requests, responses and notifications are the same as the REST API Fields. Please refer to: REST API Fields.

Additional Fields for Business Types

Alipay requires information on the business type of a payment transaction. Therefore, Wirecard Payment Gateway adds the business type as specified in your merchant configuration to each Alipay Cross-border request.

There are 5 business types:

  1. Hotel Industry

  2. Airlines

  3. Education Institutions

  4. Sales of Goods (retailers)

  5. Others: Includes all business types that do not fall into the above 4 categories (e.g. mobile data service recharge, airport pick up service, …​)

Each business type has additional mandatory fields to be sent with each request.

Business Type 1 - Hotel Industry

Each field is a child of hotel-industry and mandatory for this business type.

Field M/O Datatype Size Description

hotel-name

M

String

32

Hotel name.
Allowed characters:
0 - 9
a - z, A - Z
space
, . < > ( ) [ ] / \ - , .
If more than one hotel name exists, separate values with vertical bar (|).

check-in-date

M

Date

10

Check-in date.
Format: yyyy-MM-dd. Timezone: GMT +8.

check-out-date

M

Date

10

Check-out date.
Format: yyyy-MM-dd. Timezone: GMT +8.
Business Type 2 - Airlines

Each field is a child of airline-industry.itinerary.segment and mandatory for this business type.

Field M/O Datatype Size Description

flight-number

M

String

6

Flight number.
If flight transfer exists, separate flight numbers with vertical bar (|).

departure-date

M

String

Departure time.
Format: yyyy-MM-dd HH:mm. Timezone: GMT +8.
If flight transfer exists, separate time values with vertical bar (|).
Business Type 3 - Education Institutions

Attribute of custom-fields.custom-field.

Field M/O Datatype Size Description

@admission_notice_url

M

String

256

URL of the admission notice for overseas study consulting.
Mandatory for business type "Education Institutions".
Wirecard Payment Gateway does not validate this field but rather forwards it to Alipay.
Business Type 4 - Sales of Goods

Each field is a child of order-items.order-item and mandatory for this business type.

Field M/O Datatype Size Description

name

M

String

256

Name of the item in the shopping basket.

quantity

M

Numeric

Total number of this item in the shopping basket.

amount

M

Numeric

18.3

Item’s price per unit.

Business Type 5 - Other

The business type description of your business is stored in the MCC code of your merchant configutation. For other business types than the ones described above, Wirecard Payment Gateway adds this MCC code description to your request.
You do not need to add mandatory fields to your request.
For MCC code setup, contact merchant support.

Additional Fields for auto-debit

Only the auto-debit fields listed below have different properties.

The following elements are mandatory (M) or optional (O) for a request/response/notification.

Field M/O Datatype Size Description

periodic/periodic-type

M

String

15

Periodic type value can only be recurring.

periodic/sequence-type

M

String

15

Sequence type value can be first, recurring or final, depending on transaction type.
Features
Mobile Payment Service

The merchant can use the parameter entry mode to route the process directly to the mobile endpoint.

When using REST API the provision of the mobile endpoint has to be indicated in the paramenter entry mode with each request.

When using HPP/EPP Wirecard Payment Gateway detects the device in use automatically and displays the corresponding payment page.

Merchants using HPP/EPP can overwrite the auto detect function. They must send the paramenter entry mode in each request.

Customizing

Use the Provider Parameter connector.wap.autodetect to customize the activation of the layout type. The layout can either be mobile or desktop.

When the parameter is set to true, it depends on the value of the entry mode, set by the merchant.

When the parameter is set to false, all payment processes will activate the desktop layout.

Overview

When Provider Parameter connector.wap.autodetect is set to true.

Attribute REST API HPP/EPP

Name

Attribute Sent?

Value

entry-mode (ReST API)
entry_mode (HPP/EPP)

no

Activates desktop layout.

Detects device type automatically

yes

mcommerce

Activates layout for mobile payment.

Activates layout for mobile payment.

yes

For further questions, please contact your sales manager.

auto-debit

The auto-debit service is used for enabling consumers using Alipay Cross-border to make recurring purchases (subject to Alipay Cross-border confirmation of authorization). Merchants initiate a request for collecting payments from consumers in accordance with Alipay Cross-border’s auto-debit Service Agreement.

Workflow
Alipay Cross-border auto-debit_Workflow
Figure 11. auto-debit Workflow

  1. The consumer selects the payment method Alipay Cross-border.

  2. The merchant requests the consumer to sign in to Alipay Cross-border.

  3. WPG requests a redirect URL from Alipay Cross-border.

  4. Alipay Cross-border generates a redirect URL and sends it to WPG.

  5. WPG forwards the redirect URL to the merchant.

  6. The merchant redirects the consumer to Alipay Cross-border.

  7. The consumer enters his access key and the password.

  8. Alipay Cross-border confirms the consumer’s access credentials.

  9. WPG forwards the confirmation to the merchant and redirects the consumer to the merchant’s shop.

  10. The merchant displays the confirmation page to the consumer.

  11. If the merchant offers recurring payments, the merchant initiates an auto-debit request to WPG.

  12. WPG forwards this request to Alipay Cross-border.

  13. Alipay Cross-border processes the payment and sends a payment notification to the consumer.

Samples

Alipay Cross-border returns coded payment method URLs in the response!

When you perform a test transaction, the <payment-method-url> that is returned in the XML response is encoded and cannot be used directly. You must decode the URL first to link to the correct page. You can use any tool that decodes URLs. Maybe you want to try Coder’s Toolbox, available at: https://coderstoolbox.net/string/#!encoding=xml&action=decode&charset=us_ascii.

General
debit
debit Request (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
      <payment-methods>
          <payment-method name="alipay-xborder" />
      </payment-methods>
      <merchant-account-id>47cd4edf-b13c-4298-9344-53119ab8b9df</merchant-account-id>
      <request-id>31b5bee8-cea9-4037-b604-4401a063dab1</request-id>
      <transaction-type>debit</transaction-type>
      <requested-amount currency="USD">2.22</requested-amount>
      <order-number>180528105918955</order-number>
      <order-detail>Test product 001</order-detail>
      <ip-address>127.0.0.1</ip-address>
      <locale>en</locale>
      <account-holder>
          <first-name>Max</first-name>
          <last-name>Cavalera</last-name>
          <email>max.cavalera@wirecard.com</email>
      </account-holder>
   <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
   <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
   <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
</payment>
debit Response (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
   <merchant-account-id>47cd4edf-b13c-4298-9344-53119ab8b9df</merchant-account-id>
   <transaction-id>2cc70f39-4d50-4c1a-9566-b8a5422e00ed</transaction-id>
   <request-id>31b5bee8-cea9-4037-b604-4401a063dab1</request-id>
   <transaction-type>debit</transaction-type>
   <transaction-state>success</transaction-state>
   <completion-time-stamp>2018-05-28T08:59:19.000Z</completion-time-stamp>
   <statuses>
      <status code="201.0000" description="The resource was successfully created." severity="information" />
   </statuses>
   <requested-amount currency="USD">2.22</requested-amount>
   <account-holder>
      <first-name>Max</first-name>
      <last-name>Cavalera</last-name>
      <email>max.cavalera@wirecard.com</email>
   </account-holder>
   <ip-address>127.0.0.1</ip-address>
   <order-number>180528105918955</order-number>
   <order-detail>Test product 001</order-detail>
   <payment-methods>
      <payment-method url="https://openapi.alipaydev.com/gateway.do?sign_type=MD5&amp;partner=2088101122136241&amp;service=create_forex_trade&amp;notify_url=https%3A%2F%2Fapi-test.wirecard.com%3A443%2Fengine%2Fnotification%2Falipay-xborder%2F&amp;return_url=https%3A%2F%2Fapi-test.wirecard.com%3A443%2Fengine%2Fnotification%2Falipay-xborder%2Fredirect%2F2cc70f39-4d50-4c1a-9566-b8a5422e00ed%2F&amp;out_trade_no=2cc70f39-4d50-4c1a-9566-b8a5422e00ed&amp;subject=180528105918955&amp;total_fee=2.22&amp;currency=USD&amp;secondary_merchant_id=0000003173B0F907&amp;secondary_merchant_name=testing-merchant&amp;secondary_merchant_industry=4555&amp;order_gmt_create=2018-05-28+16%3A59%3A19&amp;order_valid_time=21600&amp;timeout_rule=12h&amp;body=Test+product+001&amp;sign=2a95b723ee0c59eb4d6e320dd4abc558" name="alipay-xborder" />
   </payment-methods>
   <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
   <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
   <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
   <locale>en</locale>
</payment>
refund-debit
refund-debit Request (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>47cd4edf-b13c-4298-9344-53119ab8b9df</merchant-account-id>
    <request-id>88bba544-5d77-4f52-9b43-531642b2543f</request-id>
    <transaction-type>refund-debit</transaction-type>
    <parent-transaction-id>${former debit transaction}</parent-transaction-id>
    <ip-address>127.0.0.1</ip-address>
    <payment-methods>
        <payment-method name="alipay-xborder" />
    </payment-methods>
</payment>
refund-debit Response (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction" self="https://api-test.wirecard.com:443/engine/rest/merchants/47cd4edf-b13c-4298-9344-53119ab8b9df/payments/66382a82-e48d-4c7c-a644-2ce3f91eeb5e">
   <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/47cd4edf-b13c-4298-9344-53119ab8b9df">47cd4edf-b13c-4298-9344-53119ab8b9df</merchant-account-id>
   <transaction-id>66382a82-e48d-4c7c-a644-2ce3f91eeb5e</transaction-id>
   <request-id>5ae58f7c-7922-4486-baf8-33276120fd29</request-id>
   <transaction-type>refund-debit</transaction-type>
   <transaction-state>success</transaction-state>
   <completion-time-stamp>2018-05-28T09:14:57.000Z</completion-time-stamp>
   <statuses>
      <status code="201.0000" description="alipay-xborder:The resource was successfully created." severity="information" />
   </statuses>
   <requested-amount currency="USD">1.23</requested-amount>
   <parent-transaction-id>a9bbf42e-ed7a-4b0a-8111-511747d3b762</parent-transaction-id>
   <account-holder>
      <first-name>Max</first-name>
      <last-name>Cavalera</last-name>
      <email>max.cavalera@wirecard.com</email>
   </account-holder>
   <ip-address>127.0.0.1</ip-address>
   <order-number>180528105415146</order-number>
   <order-detail>Test product 001</order-detail>
   <payment-methods>
      <payment-method name="alipay-xborder" />
   </payment-methods>
   <parent-transaction-amount currency="USD">1.230000</parent-transaction-amount>
   <api-id>elastic-api</api-id>
   <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
   <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
   <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
   <locale>en</locale>
</payment>
auto-debit
authorization-only (Sign Agreement)
authorization-only (Sign) Request (Successful)
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <merchant-account-id>09383431-11cf-4eab-9905-a0a84f3c89e0</merchant-account-id>
   <request-id>2003495d-5d8b-4afc-9787-860e6713b8f8</request-id>
   <transaction-type>authorization-only</transaction-type>
   <requested-amount currency="USD">0.00</requested-amount>
   <order-detail>XBOX</order-detail>
   <periodic>
      <periodic-type>recurring</periodic-type>
      <sequence-type>first</sequence-type>
   </periodic>
   <ip-address>127.0.0.1</ip-address>
   <payment-methods>
   <payment-method name="alipay-xborder"/>
   </payment-methods>
</payment>
_get-url (Sign) Response (Successful)
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
   <merchant-account-id>09383431-11cf-4eab-9905-a0a84f3c89e0</merchant-account-id>
   <transaction-id>417c2896-c33d-46c4-99a0-2c6e4bf07873</transaction-id>
   <request-id>2003495d-5d8b-4afc-9787-860e6713b8f8-get-url</request-id>
   <transaction-type>get-url</transaction-type>
   <transaction-state>success</transaction-state>
   <completion-time-stamp>2018-09-05T19:12:39.000Z</completion-time-stamp>
   <statuses>
      <status code="201.0000" description="The resource was successfully created." severity="information"/>
   </statuses>
   <requested-amount currency="USD">0.00</requested-amount>
   <ip-address>127.0.0.1</ip-address>
   <order-detail>XBOX</order-detail>
   <payment-methods>
      <payment-method url="https://openapi.alipaydev.com/gateway.do?_input_charset=utf-8&amp;access_info=%7B%22channel%22%3A%22PC%22%7D&amp;external_sign_no=417c2896-c33d-46c4-99a0-2c6e4bf07873&amp;notify_url=https%3A%2F%2Fdev.thesolution.com%2Fengine%2Fnotification%2Falipay-xborder%2F&amp;partner=2088621880535422&amp;product_code=GENERAL_WITHHOLDING_P&amp;return_url=https%3A%2F%2Fdev.thesolution.com%2Fengine%2Fnotification%2Falipay-xborder%2Fredirect%2F417c2896-c33d-46c4-99a0-2c6e4bf07873%2F&amp;sales_product_code=FOREX_GENERAL_WITHHOLDING&amp;scene=INDUSTRY%7CMEDICAL&amp;service=alipay.dut.customer.agreement.page.sign&amp;sign=7a5b3a8efc97e007b190adbfe4c806c3&amp;sign_type=MD5&amp;third_party_type=PARTNER" name="alipay-xborder"/>
   </payment-methods>
   <periodic>
      <periodic-type>recurring</periodic-type>
      <sequence-type>first</sequence-type>
   </periodic>
</payment>
debit (with <periodic>)
debit Request (Successful)
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <merchant-account-id>83716d0c-9663-4329-81f6-898ac57776fa</merchant-account-id>
   <request-id>f626c59f-afd6-4926-8f31-dbd26d07a757</request-id>
   <transaction-type>debit</transaction-type>
   <parent-transaction-id>649cb805-5aa0-4ee7-b00e-75a6332a85aa</parent-transaction-id>
   <requested-amount currency="USD">2.01</requested-amount>
   <payment-methods>
      <payment-method name="alipay-xborder"/>
   </payment-methods>
   <order-detail>XBOX</order-detail>
   <periodic>
      <periodic-type>recurring</periodic-type>
      <sequence-type>recurring</sequence-type>
   </periodic>
   <sub-merchant-info>
      <store-id>BJ_ZZ_001</store-id>
      <store-name>Muku in the Dreieichstrabe</store-name>
   </sub-merchant-info>
   <ip-address>127.0.0.1</ip-address>
</payment>
get-url Response (Successful)
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
   <merchant-account-id>83716d0c-9663-4329-81f6-898ac57776fa</merchant-account-id>
   <transaction-id>2b9afc33-c8b8-4c0f-8755-730a2abbbfef</transaction-id>
   <request-id>f626c59f-afd6-4926-8f31-dbd26d07a757-get-url</request-id>
   <transaction-type>get-url</transaction-type>
   <transaction-state>success</transaction-state>
   <completion-time-stamp>2018-09-05T15:11:16.000Z</completion-time-stamp>
   <statuses>
      <status code="201.0000" description="The resource was successfully created." severity="information" provider-transaction-id="2018090521001004890500277853"/>
   </statuses>
   <requested-amount currency="USD">2.01</requested-amount>
   <parent-transaction-id>649cb805-5aa0-4ee7-b00e-75a6332a85aa</parent-transaction-id>
   <account-holder>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <email>john.doe@wirecard.com</email>
      <phone>1 555 555 5555</phone>
      <address>
         <street1>123 test</street1>
         <city>Toronto</city>
         <state>ON</state>
         <country>CA</country>
         <postal-code>M4P1E8</postal-code>
      </address>
   </account-holder>
   <ip-address>127.0.0.1</ip-address>
   <order-number>123456</order-number>
   <order-detail>XBOX</order-detail>
   <payment-methods>
      <payment-method name="alipay-xborder"/>
   </payment-methods>
   <api-id>elastic-payment-page-nvp</api-id>
   <processing-redirect-url>http://10.0.0.114:8080/shop/complete.jsp?state=processing&amp;</processing-redirect-url>
   <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
   <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
   <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
   <locale>en</locale>
   <periodic>
      <periodic-type>recurring</periodic-type>
      <sequence-type>recurring</sequence-type>
   </periodic>
   <sub-merchant-info>
      <store-id>BJ_ZZ_001</store-id>
      <store-name>Muku in the Dreieichstrabe</store-name>
   </sub-merchant-info>
</payment>
authorization-only (Unsign Agreement)
authorization-only (Unsign) Request (Successful)
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <merchant-account-id>09383431-11cf-4eab-9905-a0a84f3c89e0</merchant-account-id>
   <request-id>1219a275-6032-4854-ba10-ee44ccf9c802</request-id>
   <transaction-type>authorization-only</transaction-type>
   <requested-amount currency="USD">0.00</requested-amount>
   <parent-transaction-id>f704f0a9-8a9c-4639-bb98-28f97744dd60</parent-transaction-id>
   <order-detail>XBOX</order-detail>
   <periodic>
      <periodic-type>recurring</periodic-type>
      <sequence-type>final</sequence-type>
   </periodic>
   <ip-address>127.0.0.1</ip-address>
   <payment-methods>
      <payment-method name="alipay-xborder"/>
   </payment-methods>
</payment>
authorization-only (Unsign) Response (Successful)
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
   <merchant-account-id>09383431-11cf-4eab-9905-a0a84f3c89e0</merchant-account-id>
   <transaction-id>9af5964e-5d8c-467a-8299-1f3204a56e0b</transaction-id>
   <request-id>1219a275-6032-4854-ba10-ee44ccf9c802</request-id>
   <transaction-type>authorization-only</transaction-type>
   <transaction-state>success</transaction-state>
   <completion-time-stamp>2018-09-05T19:12:48.000Z</completion-time-stamp>
   <statuses>
      <status code="201.0000" description="The resource was successfully created." severity="information" provider-transaction-id=""/>
   </statuses>
   <requested-amount currency="USD">0.00</requested-amount>
   <parent-transaction-id>f704f0a9-8a9c-4639-bb98-28f97744dd60</parent-transaction-id>
   <ip-address>127.0.0.1</ip-address>
   <order-detail>XBOX</order-detail>
   <payment-methods>
      <payment-method name="alipay-xborder"/>
   </payment-methods>
   <consumer-id>2088622907141895</consumer-id>
   <api-id>---</api-id>
   <periodic>
      <periodic-type>recurring</periodic-type>
      <sequence-type>final</sequence-type>
   </periodic>
</payment>

Wirecard Payment Page v2

Wirecard Payment Page v1 LEGACY is no longer supported. We recommend using Wirecard Payment Page v2 integration instead. If you have questions about your existing Wirecard Payment Page v1 integration, consult our REST API integration guide.

General Information

This is a reference page for Alipay Cross-border. Here you find all the information necessary for integrating this payment method into your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page v2 (WPP v2)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

All WPP v2 integrations share a common process flow for creating payments.

Below, you find example requests for the available transaction type debit, including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information.

For production, you need to use production credentials. For details contact merchant support.

All given requests return successful responses.

For more details on the redirect-url, see the Configuring Redirects and IPNs for WPP v2 section.

For response verification examples, see the WPP v2 Security section.

About Alipay Cross-border

Alipay is China’s leading online payment service provider. It offers a wallet system similar to PayPal and WeChat Pay.

Alipay Cross-border makes international online shopping easy for Chinese consumers: they can pay using Renminbi (RMB). Alipay Cross-border will then remit the sum to the foreign merchant in their currency.

Currently, Alipay Cross-border supports transactions with the following currencies: AUD, CAD, CHF, CNY, DKK, EUR, GBP, HKD, JPY, NOK, NZD, SEK, SGD, THB, USD.

Test Credentials

Merchant Credentials for Transaction Type debit

URI Endpoint

https://wpp-test.wirecard.com/api/payment/register

Merchant Account ID (MAID)

47cd4edf-b13c-4298-9344-53119ab8b9df

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key (used for response verification)

94fe4f40-16c5-4019-9c6c-bc33ec858b1d
Additional Test Credentials for the Alipay Cross-border Environment

Merchant Test Account

User ID

2088101122136241

Key

760bdzec6y9goq7ctyx96ezkz78287de

Consumer Test Account

Account Name

alipaytest20091@gmail.com

Password

111111

Payment Password

111111
Alipay Cross-border login form
Transaction Type debit

A debit transaction charges the specified amount from the account holder’s bank account and marks it for immediate transfer.

For a successful debit transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

  3. Highly recommended: Parse and process the payment response.

We provide ready-made JSON examples for each step of this process. You find them below.

Endpoint for Alipay Cross-border transactions.

Initial Request

The initial request creates the payment session. If it is successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic MTYzOTAtdGVzdGluZzozITMwMTM9RDNmRDhYNw==

Content-Type

application/json
Optional fields

For a full list of optional fields you can use, see the REST API Alipay Cross-border specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "47cd4edf-b13c-4298-9344-53119ab8b9df"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "debit",
    "requested-amount": {
      "currency": "USD",
      "value": "2.22"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "alipay-xborder"
        }
      ]
    },
    "order-number": "180528105918955",
    "order-detail": "Test product 001",
    "ip-address": "127.0.0.1",
    "locale": "en",
    "account-holder": {
      "first-name": "Wing",
      "last-name": "Wu",
      "email": "wiwu@example.com"
    },
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel"
  }
}
Field (JSON) Data Type Description

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Wirecard).

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later. {{$guid}} serves as a placeholder for a random request-id.

Allowed characters: [a-z0-9-_]

transaction-type

String

The requested transaction type. For Alipay Cross-border payments, transaction-type must be set to debit.

requested-amount

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

To test Alipay Cross-border, enter a small sum (double digit amount at most).

currency

String

The currency of the requested/contested transaction amount. For Alipay Cross-border payments, the currency must be one of the following: AUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, KRW, NOK, NZD, SEK, SGD, THB, USD. Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

The name of the payment method used. Set this value to alipay-xborder.

order-number

String

The order number provided by the merchant.

order-detail

String

Merchant-provided string to store the order details for the transaction.

ip-address

String

The internet protocol address of the consumer.

locale

String

A set of parameters defining language and country in the user interface.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

email

String

The email address of the account holder.

success-redirect-url

String

The URL to which the consumer is redirected after a successful payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/success

fail-redirect-url

String

The URL to which the consumer is redirected after an unsuccessful payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/error

cancel-redirect-url

String

The URL to which the consumer is redirected after having cancelled a payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/cancel
2. Redirect the Consumer to the Payment Page (Initial Debit Response)
{
  "payment-redirect-url": "https://wpp-test.wirecard.com/processing?wPaymentToken=qbGUDHkDzUGJ6lMePOZCGMIrM-19k61AXlUAEOaqccU"
}
Field (JSON) Data Type Description

payment-redirect-url

String

The URL which redirects to the payment form. Sent as a response to the initial request.

At this point, you need to redirect your consumer to payment-redirect-url (or render it in an iframe depending on your integration method).

Consumers are redirected to the payment form. There they enter their data and submit the form to confirm the payment. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (transaction-state: failed).

The transaction result is the value of transaction-state in the payment response. More details (including the status code) can also be found in the payment response in the statuses object. Canceled payments are returned as failed, but the status description indicates it was canceled.

In any case (unless the consumer cancels the transaction on a 3rd party provider page), a base64-encoded response containing payment information is sent to the configured redirection URL. See Configuring Redirects and IPNs for WPP v2 for more details on redirection targets after payment and transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "payment": {
    "locale": "en",
    "ip-address": "127.0.0.1",
    "transaction-id": "93b086ec-3183-494a-83e0-fcf6f85f4273",
    "completion-time-stamp": "2019-03-12T07:24:06",
    "requested-amount": {
      "currency": "USD",
      "value": 2.22
    },
    "parent-transaction-id": "f30f82ff-86e1-47b2-aa1a-d741e9eee8cf",
    "request-id": "47987754-5852-419d-9d44-0236ea6a8780",
    "merchant-account-id": {
      "value": "47cd4edf-b13c-4298-9344-53119ab8b9df"
    },
    "transaction-state": "success",
    "transaction-type": "debit",
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel",
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
    "statuses": {
      "status": [
        {
          "description": "The resource was successfully created.",
          "severity": "information",
          "code": "201.0000"
        }
      ]
    },
    "account-holder": {
      "first-name": "Wing",
      "last-name": "Wu",
      "email": "wiwu@example.com"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "alipay-xborder"
        }
      ]
    },
    "order-number": "180528105918955",
    "order-detail": "Test product 001",
    "api-id": "{api-id]"
  }
}
Field (JSON) Data Type Description

locale

String

A set of parameters defining language and country in the user interface.

ip-address

String

The internet protocol address of the consumer.

transaction-id

String

A unique identifier assigned for every transaction. This information is returned in the response only.

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount. For Alipay Cross-border payments, the currency must be one of the following: AUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, KRW, NOK, NZD, SEK, SGD, THB, USD.

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

transaction-state

String

The current transaction state.

Possible values:

  • in-progress

  • success

  • failed

Typically, a transaction starts with state in-progress and finishes with state either success or failed. This information is returned in the response only.

transaction-type

String

The requested transaction type. For Alipay Cross-border payments, transaction-type must be set to debit.

cancel-redirect-url

String

The URL to which the consumer is redirected after having cancelled a payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/cancel

success-redirect-url

String

The URL to which the consumer is redirected after a successful payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/success

fail-redirect-url

String

The URL to which the consumer is redirected after an unsuccessful payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/error

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

account-holder

first-name

String

The first name of the consumer.

last-name

String

The last name of the consumer.

email

String

The email address of the consumer.

payment-method

name

String

The name of the payment method used. Set this value to alipay-xborder.

order-number

String

This is the order number of the merchant.

order-detail

String

Merchant-provided string to store the order details for the transaction.

api-id

String

Identifier of the currently used API.
Post-Processing Operations

WPP is best used to deal with one-off payments (e.g. regular, independent debit transactions) or the initial transaction in a chain of them (e.g. a first authorization in a chain of recurring transactions). However, when it comes to referencing a transaction for any kind of post-processing operation - such as a refund of one of your debit transactions - use our REST API directly.

Check the REST API Alipay Cross-border specification for details on Alipay Cross-border specific post-processing operations.
JSON/NVP Field Reference

NVP equivalents for JSON fields (for migrating merchants).

Here you can:

  • find the NVP equivalents for JSON fields (for migrating merchants),

  • see the structure of a full request (optional fields included).

JSON Structure for Alipay Cross-Border debit Requests
{
  "payment": {
    "merchant-account-id": {
      "value": "string"
    },
    "request-id": "string",
    "transaction-type": "string",
    "requested-amount": {
      "currency": "string",
      "value": "numeric"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "alipay-xborder"
        }
      ]
    },
    "order-number": "string",
    "order-detail": "string",
    "ip-address": "string",
    "locale": "string",
    "account-holder": {
      "first-name": "string",
      "last-name": "string",
      "email": "string"
    },
    "success-redirect-url": "string",
    "fail-redirect-url": "string",
    "cancel-redirect-url": "string"
  }
}
Request-Only Fields
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request_id

request-id

payment ({ })

transaction_type

transaction-type

payment ({ })

requested_amount

value

requested-amount ({ })

requested_amount_currency

currency

requested-amount ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

order_number

order-number

payment ({ })

order_detail

order-detail

payment ({ })

ip_address

ip-address

payment ({ })

locale

locale

payment ({ })

first_name

first-name

account-holder ({ })

last_name

last-name

account-holder ({ })

email

email

account-holder ({ })

success_redirect_url

success-redirect-url

payment ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

cancel_redirect_url

cancel-redirect-url

payment ({ })
JSON Structure for Alipay Cross-border debit Responses
{
  "payment": {
    "transaction-id": "string",
    "completion-time-stamp": "2019-03-12T07:24:06",
    "parent-transaction-id": "string",
    "transaction-state": "success",
    "statuses": {
      "status": [
        {
          "description": "string",
          "severity": "string",
          "code": "string"
        }
      ]
    },
    "api-id": "{api-id]"
  }
}
Response-Only Fields
Field (NVP) Field (JSON) JSON Parent

transaction_id

transaction-id

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

parent_transaction_id

parent-transaction-id

payment ({ })

transaction_state

transaction-state

payment ({ })

status_description_n

status ([ {} ])/ description

statuses ({ })

status_severity_n

status ([ {} ])/ severity

statuses ({ })

status_code_n

status ([ {} ])/ code

statuses ({ })

api_id

api-id

payment ({ })

← Credit Card | Alipay Domestic →