alipay.acquire.overseas.spot.pay

Environment

HTTPS request URL

Production environment

Priority: https://globalmapi.alipay.com/gateway.do

Backup: https://intlmapi.alipay.com/gateway.do

Test environment

https://mapi.alipaydev.com/gateway.do

service

String Required

Interface name 

Example:alipay.acquire.overseas.spot.pay

sign

String Required

Sign value 

Example:c8il4epm90wyn768fijgqhy8tay37gqa

sign_type

String Required

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

Example:MD5

partner

String Required

The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088.

Example:2088*********662

_input_charset

String

The charset with which the request data are encoded. UTF-8, GBK, and GB2312 are supported.

Example:UTF-8

notify_url

URL (200) Required

The URL for receiving asynchronous notifications after the payment is completed.

Note: To make sure that the payment result can be fetched immediately, use the QUERY interface to query the payment result if asynchronous notification is not received.

Example:http://notify.msp.hk/notify.htm

alipay_seller_id

String Required

Alipay seller ID, with the same value of partner ID.

Example:2088102012343978

quantity

Number

The quantity of goods

Example:1

trans_name

String(256) Required

The name of the transaction, which is to be shown in the transaction record list.

Example:iPhone

partner_trans_id

String(64) Required

The unique transaction ID assigned by the partner in the partner system, can be a sale order ID or a payment order ID.

Example:2010121000000002

trans_currency

String(8)

The pricing currency used for labelling the price of the transaction. Using this parameter, merchants can specify their transaction currency.

Note: Currently, the parameter's values are MOP, TWD, and CNY. Please contact your BD for the usage of this parameter.

Example:MOP

currency

String(8) Required

The settlement currency that Alipay settles to the partner. When the trans_currency parameter is not specified, the pricing currency and settlement currency would be the same. Use upper case. For more information about supported currencies, see Supported Currencies.

Example:USD

trans_amount

Number(11,2) Required

The transaction amount in the pricing currency. The value is in the range of 0.01 - 100000000.00 and with two decimal places.

Example:39.25

buyer_identity_code

String(32) Required

A dynamic code with 16 - 24 digits, used to identify Alipay users. This code starts with 25, 26, 27, 28, 29, or 30, and must be read from Alipay wallet of the user in real time.

Example:283323458639276347

identity_code_type

String(16) Required

Identity code type. The value is barcode.

Example:barcode

trans_create_time

String(30)

The time that the partner system creates the transaction, which is in a format of yyyyMMddHHmmss.SSS±timezone.

Example:20131120153059.782+08:30

memo

String(256)

Transaction notes 

Example:Iphone with special promotion discount

biz_product

String(256) Required

Product name, with a value of OVERSEAS_MBARCODE_PAY

Example:OVERSEAS_MBARCODE_PAY

extend_info

String(512) Required

Extended information, which contains extended parameters and merchant business information. For more details, see extend_info.

Example:{"secondary_merchant_name":"Lotte","secondary_merchant_id":"123","secondary_merchant_industry":"5812","store_id":"A101","store_name":"McDonald in 966 3rd Ave, New York","terminal_id":"212133131" }

trade_information

String(6000)

Information about the trade industry. See trade_information for details.

Example:{"business_type":"1","hotel_name":"zlidu, sluhg-987, 889utng","check_in_time":"2018-10-20","check_out_time":"2018-10-22"}

secondary_merchant_id

String(64) Required

The unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores.

Example:A80001

secondary_merchant_name

String(128) Required

Registration legal name of the secondary merchant, shown in the Alipay Wallet and the reconciliation file to identify a secondary merchant.

Example:Muku

secondary_merchant_industry

String(4) Required

Industry classification identifier of the secondary merchant, which is assigned by Alipay. For more information about the MCC code, see MCC list.

Example:7011

store_name

String Required

Store name. Can be null only when the store information is verified.

Example:Muku in the Dreieichstrabe

store_id

String(64) Required

The unique ID that is assigned by the partner to identify the store of a merchant, which can contain letters, numbers, and underscores.

Example:BJ_ZZ_001

terminal_id

String

Terminal ID

Example:T80001

sys_service_provider_id

String(32)

System service provider ID, which is used to identify the payment system provider.

Example:R00998889911

terminal_create_time

String (30)

The time when the transaction is created on terminal. Format: yyyyMMddHHmmss.SSS±timezone

Example:20131120153059.782+08:30

last_payment_info

String

Information about the previous one payment. The information includes alipay_trans_id and the time when the merchant receives the response from Alipay, which are separated by a vertical bar (|).

Example: 202001010101050909|2019-06-01T12:01:01.379+08:30

business_type

String

Business type. 5 types are supported:

1: Hotel

2: AIR

3: Overseas study consulting

4: Sales of goods

5: Others, including all the other business types that do not fall into the above 4 categories. For example, mobile data service recharge, airport pick up service, etc.

If more than one type is involved, separate type values with vertical bar (|).

Example:1|2|3|4|5 or 1

hotel_name

String

Hotel name that consists of numbers, letters, spaces, and special characters including ,.<>()[]/\-,. If more than one hotel name exists, separate values with vertical bar (|). Specify this field only when business_type is 1 (Hotel).

Example:zlidu, sluhg-987, 889utng

check_in_time

Date

Check-in time. Format: yyyy-MM-dd. Timezone: GMT +8. Specify this field only when business_type is 1 (Hotel).

Example:2018-10-20

check_out_time

Date

Check-out time. Format: yyyy-MM-dd. Timezone: GMT +8. Specify this field only when business_type is 1 (Hotel).

Example:2018-10-22

flight_number

String

Flight number. If flight transfer exists, separate flight numbers with vertical bar (|). Specify this field only when business_type is 2 (AIR).

Example:NWS 996|TWF 8854

departure_time

Date

Departure time. Format: yyyy-MM-dd HH:mm Timezone: GMT +8. If flight transfer exists, separate time values with vertical bar (|). Specify this field only when business_type is 2 (AIR).

Example:2018-10-22 20:49

admission_notice_url

String

If business_type is 3 (Overseas study consulting), the URL of admission notice (image) must be specified.

Example:https://www.iconfont.cn/search/index?test

goods_info

String

Goods information that includes SKU names and corresponding quantities, in the format of SKU_name^quantity. If more than one goods exists, separate values with vertical bar (|). Specify this field only when business_type is 4 (Sales of goods).

Example:pencil^2|eraser^5|iPhone XS 256G^1

total_quantity

Number

Total quantities of all goods in one order. Specify this field only when business_type is 4 (Sales of goods).

Example:8

other_business_type

String

If business_type is 5 (Others), specify the business type in details.

Example:Airport pick up service

is_success

String(1) Required

Status of the API call, used to indicate whether the request is accepted by Alipay gateway.

T: accepted

F: rejected

Example:T

sign_type

String Required

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

Note:This field is not returned if the error code is ILLEGAL_SIGN. 

Example:MD5

sign

String(32) Required

Sign value.

Note: This field is not returned if the error code is ILLEGAL_SIGN.

Example:59c7275cf3c82f038b7c0076f9888926

result_code

String(32) Required

Processing result of the request, with a value of SUCCESS, FAILED, or UNKNOW.

SUCCESS: The payment succeeds.

FAILED: The payment is failed. When the value is FAIL, merchants can show the corresponding failure result to the cashier.

UNKNOW: The payment result is unknown. For transactions in the offline mode, merchants must cancel the transaction immediately. For transactions in the offline to online mode, the partner system is suggested to query the transaction status with a certain frequency until a clear status is returned, or the merchant can cancel the transaction after a certain time.

Example:SUCCESS

error

String(48)

Error code that is returned when the request is unsuccessful. This field is returned only when the result_code is FAILED or UNKNOW. For more information, see the Error Code section in this document.

Example:BEYOND_PAY_RESTRICTION

alipay_buyer_login_id

String（64）

Alipay login ID of the buyer, which can be an email address or mobile number. The ID is partially masked for privacy.

Example:caoxxx@126.com or 186xxx22156

alipay_buyer_user_id

String(16) Required

The unique ID for each Alipay account, which starts with 2088. 

Example:2088102130896433

partner_trans_id

String(64) Required

Equal to the partner_trans_id given in the request

Example:2010121000000002

alipay_trans_id

String(64)

The transaction ID assigned by Alipay for the partner's payment request, which follows a mapping relation with the partner field plus the partner_trans_id field.

Example:201311221703338463

alipay_pay_time

String(16)

The time that the transaction was paid, which is in a format of yyyyMMddHHmmss. 

Example:201311212323

trans_currency

String(8)

The pricing currency used for labelling the price of the transaction

Example:MOP

currency

String(8) Required

The settlement currency that Alipay settles to the partner

Example:USD

trans_amount

Number(11,2) Required

The transaction amount in the pricing currency. The value of this parameter is in the range of 0.01 - 100000000.00 and with two decimal places. 

Example:39.25

exchange_rate

Number(8,6)

The exchange rate between the currency given in the request to CNY. The exchange occurs when the Alipay trade order is created. 

Example:6.09390000

trans_amount_cny

Number(9,2)

The transaction amount in CNY. It is the exact amount that the buyer has paid. 

Example:239.19

m_discount_forex_amount

Number(9,2)

If coupons or vouchers are used in the transaction, the discount amount redeemed in the settlement currency will be returned. Otherwise, no return.

Example:2.19

is_success

String(1) Required

Status of the API call, used to Indicate whether the request is accepted by Alipay gateway.

T: accepted

F: rejected

Example:F

sign_type

String Required

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

Example:MD5

sign

String(32) Required

Sign value 

Example:59c7275cf3c82f038b7c0076f9888926

error

String(48)

Error code that is returned when the request is unsuccessful, to describe the request failure reason. For more information, see the Error Code section in this document.

Example:BEYOND_PAY_RESTRICTION

notify_time

Timestamp Required

The time when the notification is sent. The time format is yyyy-MM-dd HH:mm:ss 

Example:2013-11-27 15:45:58

notify_type

String Required

Notification type 

Example:trade_status_sync

notify_id

String Required

Notification ID, used by the partner system to verify the notification 

Example:ac05099524730693a8b330c5ecf72da978

sign_type

String Required

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

Example:MD5

sign

String Required

Sign value 

Example:601510b7970e52cc63db0f44997cf70e

notify_action_type

String

Notification action type. The value can be one of the following items:

• createDirectPayTradeByBuyerAction: Create a transaction
• payByAccountAction: Make the payment
• refundFPAction: Make the refund
• reverseAction: Cancel the transaction
• closeTradeAction: Close the transaction
• finishFPAction: Complete the transaction

Example:payByAccountAction

out_trade_no

String

Unique order ID in the order system in the corresponding merchant's website other than Alipay trade number. Uniqueness of this parameter in merchant's website shall be guaranteed. This is a parameter transmitted upon corresponding request, which shall be returned in its original shape.

Example:990xxxxxxx8989

subject

String(256)

Brief description of the transaction.This parameter is in the first column of Alipay trade details and is important for account checking. This parameter is transmitted by the corresponding request and needs to be returned with its original value. 

Example:kids clothing

trade_no

String(64)

The serial number assigned by Alipay to identify a trade in the Alipay system, with a length in the range 16 - 64 bits.

Example:2013112711001004940000394507

trade_status

String

Transaction status. See Trade status for details.

Example:WAIT_BUYER_PAY

gmt_create

Date

The time when the trade transaction is created. Format: yyyy-MM-dd HH:mm:ss. Use GMT+8. 

Example:2013-11-27 15:45:57

gmt_payment

Date

The time when the payment is completed. Format: yyyy-MM-dd HH:mm:ss. Use GMT+8. 

Example:2013-11-27 15:45:57

buyer_email

String

Buyer's Alipay ID, which can be an email address or phone number. 

Example:6xxxxx@qq.com

seller_id

String

Seller's unique Alipay user ID, consists of 16 digits and begins with 2088.

Example:208xxxxxxxxx8155

buyer_id

String

Buyer's unique Alipay user ID, consists of 16 digits and begins with 2088.

Example:208xxxxxxxxx1127

price

Number

Goods price in RMB. This parameter is transmitted by the corresponding request and needs to be returned with its original value. It is the corresponding parameter upon request, and will be returned back as it is if the currency is RMB. For a foreign currency, corresponding RMB amount will be calculated based on the exchange rate.

Example:1.00

quantity

Number

The quantity of goods. This parameter is transmitted by the corresponding request and needs to be returned with its original value. 

Example:10

total_fee

Number(11,2)

Total amount of a transaction in RMB. It is the corresponding parameter upon request, and will be returned back as it is if the currency is RMB.

For a foreign currency, corresponding RMB amount will be calculated based on the exchange rate.

Example:10.00

body

String

Detailed description about the goods. This parameter is transmitted by the corresponding request and needs to be returned with its original value. 

Example:Glitter leggings

refund_fee

Number

The refund amount. The unit is Yuan. 

Example:1.00

paytools_pay_amount

String

Payment amount information of all successful payments in various channels. 

Example:[{"MCARD":"7.94"},{"TMPOINT":"1.69"},{"BANKCARD":"5.55"}]

m_discount_forex_amount

Number

If coupons/vouchers are used in the transaction, the discount amount redeemed in the settlement currency will be returned. Otherwise, no return. 

Example:2.19

Error code

Description

SYSTEM_ERROR

Alipay system is currently not available.

Action: Call the alipay.acquire.overseas.query API to query the status of this payment. For more details, see Case 2.

ILLEGAL_SIGN

Illegal signature

Action: Use a correct signature and try again.

INVALID_PARAMETER

Parameter error

Action: Check the standard of each request parameter according to the API specification. You can log in to iSandbox and use iDiagnose to pinpoint the error.

ILLEGAL_ARGUMENT

Parameter error

Action: Check each request parameter according to the API specification. Contact Alipay technical support if this error persists.

ILLEGAL_PARTNER

Incorrect partner ID

Action: Ensure that the value of partner parameter matches the partner value provided by Alipay. Contact Alipay technical support if this error persists.

ILLEGAL_EXTERFACE

Interface configure error

Action: Ensure that the service parameters have same values with the one in API specification. Contact Alipay technical support if this error persists.

ILLEGAL_PARTNER_EXTERFACE

The partner ID does not have access privilege

Action: Ensure that your agreement with Alipay has been finalized. Contact Alipay technical support if needed.

ILLEGAL_SIGN_TYPE

Illegal sign type

Action: Ensure that the value of sign_type is among MD5, RSA and RSA2. Contact Alipay technical support if this error persists.

HAS_NO_PRIVILEGE

Has no privilege

Action: Contact Alipay technical support for more information.

TRADE_BUYER_NOT_MATCH

The buyer doesn't match.

Action: The merchant can ask the user to show or scan the last barcode that is used for the previous payment. Or the merchant can refresh the partner_trans_id to generate a new payment. If this error persists, contact Alipay technical support for help.

TRADE_HAS_CLOSE

Corresponding trade is closed, and is not allowed for the current operation.

Action: The merchant can send a new payment request.

TRADE_STATUS_ERROR

Corresponding trade status is not allowed for the current operation.

Action: The partner system needs to generate a new partner_trans_id request to Alipay. If a same error code is returned, use other payment method such as cash or the credit card.

EXIST_FORBIDDEN_WORD

Entered forbidden words according to China law.

Action: Partners need to check the content of the trans_name parameter.

SELLER_NOT_EXIST

The entered value for the alipay_seller_id parameter is not correct. No corresponding account can be found.

Action: Check whether the seller ID is correct

BUYER_NOT_EXIST

The entered value for buyer_identity_code is not correct. No corresponding account can be found.

Action: Ask the user to use other payment methods such as cash or the credit card

BUYER_ENABLE_STATUS_FORBID

The entered buyer account is disabled due to security issues.

Action: The user needs to complete the real-name validation accordingly. Users can contact Alipay CS hotline for help. Besides, Hong Kong and Macau residents or foreign residents are not supported.

BUYER_SELLER_EQUAL

The entered buyer account is equal to the seller account.

Action: Change user's Alipay account.

CLIENT_VERSION_NOT_MATCH

Client version doesn't match.

Action: Update the Alipay wallet to the latest version.

SOUNDWAVE_PARSER_FAIL

Incorrect barcode

Action: Ensure that users are using correct Alipay barcode or QR code. Besides, ask the cashier to check whether the scanner is handled correctly and make sure the cashier doesn't scan the user's barcode repeatedly.

CONTEXT_INCONSISTENT

The trade information is inconsistent.

Action: The merchant needs to check whether the request data are consistent with the previous one.

PRODUCT_AMOUNT_LIMIT_ERROR

Product quota exceeds.

Action: Contact Alipay technical support.

BUYER_BALANCE_NOT_ENOUGH

Alipay account of the buyer does not have enough balance for current operation.

Action: Cashier can ask the user to top-up the balance or bind a new bank card with sufficient fund.

TOTAL_FEE_EXCEED

Trade amount exceeds the limitation.

Action: The user needs to use the other payment method, such as cash or the credit card.

BUYER_PAYMENT_AMOUNT_DAY_LIMIT_ERROR

Total trade amount of the buyer exceeds the maximum amount allowed for a buyer in one day.

Action: The user needs to use the other payment method such as cash or the credit card.

BUYER_PAYMENT_AMOUNT_MONTH_LIMIT_ERROR

Total trade amount of the buyer exceeds the maximum amount allowed for a buyer in one month.

Action: The user needs to use the other payment method such as cash or the credit card.

ERROR_BUYER_CERTIFY_LEVEL_LIMIT

Buyers failed to pass the PBOC (People's Bank of China) validation.

Action: The user needs to complete the real-name validation.

ERROR_SELLER_CERTIFY_LEVEL_LIMIT

The seller failed to pass the PBOC (People's Bank of China) validation.

Action: Merchants need to supplement the business license and some other materials (low possibilities for overseas partners).

PAYMENT_REQUEST_HAS_RISK

Current trade contains a risk detected by Alipay.

Action: Users can contact Alipay CS window for help or use other payment method such as cash or the credit card.

NO_PAYMENT_INSTRUMENTS_AVAILABLE

No available payment tool can be used for the current operation.

Action: Ask the user to pay again. If the issue persists, ask the user to contact Alipay technical support for help.

BUYER_BANKCARD_BALANCE_NOT_ENOUGH

Bank account of the buyer does not have enough balance for current operation.

Action: Ask the user to top up his/her Alipay account or use another bank card to pay for the order again.

PAYMENT_FAIL

The transaction is failed.

Action: The partner can retry the payment with the same partner_trans_id.

MOBILE_PAYMENT_SWITCH_OFF

The buyer switches off the mobile pay function, therefore, the operation cannot be performed.

Action: Users need to access to www.alipay.com, go to [账户管理] - [支付宝钱包设置], and enable [支付宝钱包支付].

USER_FACE_PAYMENT_SWITCH_OFF

The buyer switches off the face-to-face payment function, therefore, the operation cannot be performed.

Action: Ask the user to disable [付款码] at top right corner in his/her Alipay wallet, then switch it on again.

ERROR_BALANCE_PAYMENT_DISABLE

The buyer switches off the balance payment function, therefore, the operation cannot be performed.

Action: Users need to access to www.alipay.com, go to [账户管理] - [付款方式和额度], then switch on [账户支付功能].

EXCHANGE_AMOUNT_OR_CURRENCY_ERROR

The exchange amount or currency is not allowed for the current operation.

Action: Merchants need to check whether the amount and the currency parameter are correct.

ILLEGAL_SECURITY_PROFILE

Incorrect key profile.

Action: Make sure you upload your public keys before calling APIs.

ILLEGAL_EXTERFACE_FOR_CA_VERIFY

The interface is not allowed to use Certificate Verification Service.

Action: Contact Alipay technical support for help.

PULL_MOBILE_CASHIER_FAIL

Failed to call the mobile cashier.

Action: Contact Alipay technical support for help.

BEYOND_PAY_RESTRICTION

The payment limitation is exceeded.

Action: Users need to use the other payment method such as cash or the credit card.

NOT_SUPPORT_PAYMENT_INST

The Alipay Wallet version used by the buyer is not supported.

Action: Contact Alipay technical support for help.

INVALID_RECEIVE_ACCOUNT

The seller is not in the payee list.

Action: Contact Alipay technical support for help.

FORBIDDEN_MERCHANT_INDUSTRY

This transaction type is not allowed.

Action: Check the value of secondary_merchant_industry and contact Alipay technical support if needed.

ILLEGAL_MERCHANT_INDUSTRY

Illegal MCC format.

Action: Make sure the value of secondary_merchant_industry is defined in the MCC list.

CURRENCY_NOT_SUPPORT

The currency is not supported.

Action: Check your agreement with Alipay.

TRADE_TOTAL_FEE_ERROR

The total transaction fee is incorrect.

Action: Check the values of amount related parameters.

RESTRICTED_MERCHANT_INDUSTRY

The payment cannot exceed the certain amount in the industry.

Action: Check your agreement with Alipay.

ACCESS_FORBIDDEN

The merchant has no permission to use the product.

Action: Check your agreement with Alipay.

SECONDARY_MERCHANT_ID_BLANK

The secondary merchant ID is not provided to Alipay.

Action: Send the secondary merchant ID to Alipay.

SECONDARY_MERCHANT_ID_INVALID

The secondary merchant is not registered with Alipay.

Action: Check whether the provided secondary merchant ID is correct and whether the secondary merchant is registered with Alipay. If the secondary merchant is not registered with Alipay, register the secondary merchant with Alipay immediately.

STORE_NOT_MATCH

The secondary merchant is not registered with Alipay.

Action: Check whether the provided store ID is correct and whether the secondary merchant is registered with Alipay. If the secondary merchant is not registered with Alipay, register the secondary merchant with Alipay immediately.

SECONDARY_MERCHANT_STATUS_ERROR

The status of secondary merchant is abnormal in the Alipay system.

Action: Contact Alipay Business Support by sending an email to global.service@alipay.com.