alipay.fund.auth.order.voucher.create

Environment

HTTPS request URL

Production environment

https://globalopenapi.alipay.com/gateway.do

Test environment

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

Parameter

Type

Basic parameter

app_id

String (32) Required

The unique ID that is assigned by Alipay to identify an application.

Example: 2014072300007148

method

String (128) Required

Interface name

Example: alipay.fund.auth.order.freeze

format

String (40)

Only JSON is supported.

Example: JSON

charset

String (10) Required

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

Example: UTF-8

sign_type

String (10) Required

Signature type. RSA and RSA2 are supported. Use uppercase.

Example: RSA2

sign

String (344) Required

Signature value

timestamp

String (19) Required

The time when the merchant server sends the request. The format is yyyy-MM-dd HH:mm:ss.

Example: 2020-07-24 03:07:50

version

String (3) Required

The API version. The value is fixed as 1.0.

Example: 1.0

notify_url

String (256)

The URL for receiving asynchronous notifications after the pre-auth is completed.

Example: http://api.test.alipay.net/atinterface/receive_notify.htm

app_auth_token

String (40)

To query authorization information. 

Example: 201510BBaabdb44d8fd04607abf8d5931ec75D84

Note: After a merchant authorizes an ISV to use certain APIs, Alipay will assign an app_auth_token to the ISV. The ISV can use this interface to query the authorization information such as the authorizer and authorized APIs corresponding to the app_auth_token. For more details, see Overview of the app authorization (in Mandarin).

biz_content

String Required

Collection of request parameters. The maximum length is not limited. Except for common parameters, all other request parameters must be passed in to this parameter.

Business parameter

out_order_no

String (64) Required

The transaction number of funds pre-auth assigned by merchant. The number must be unique on the merchant end.

Example: 8077735255938023

out_request_no

String (64) Required

The serial number of a merchant's funds pre-auth request. The number must be unique on the merchant end.

Example: ABC8077735255938032

product_code

String (32) Required

The product code of the Alipay product that you use. The value for this field is OVERSEAS_INSTORE_AUTH.

Example: OVERSEAS_INSTORE_AUTH

order_title

String(100) Required

Transaction title

Example: Pre-auth transaction

amount

Price (11) Required

Frozen amount

Example: 150.00

pay_timeout

String (5)

The period before the customer confirms the authorization. The value of this field is 15m by default. The value of this field ranges from 1m to 15d.

Note:

The following abbreviations are used to present units of time:

• m: minute
• h: hour
• d: day
• 1c: current day

Example: 1d

payee_logon_id

String (100)

The payee's Alipay login ID, email, or phone number are supported.

Note:

If both payee_logon_id and payee_user_id are passed, use payee_user_id. If the merchant selects credit pay as pay method, then payee_logon_id and payee_user_id cannot both be null.

Example: 159****5620

payee_user_id

String (32)

The payee's unique Alipay user ID. The user ID is composed of 16 digits and begins with 2088.

Note: If payee_user_id is not null, the system will check if the payee of the transaction matches with payee_user_id. If the merchant selects credit pay as pay method, then payee_logon_id and payee_user_id cannot both be null.

Example: 2088102000275795

trans_currency

String (8)

The pricing currency. Use uppercase. Refer to Supported Currencies for more information.

Example: USD

settle_currency

String (8)

Merchant settlement currency. Use uppercase.

Example: USD

Parameter

Description

secondaryMerchantId

String Required

The unique ID assigned by the partner to identify a secondary merchant.

Example: merchantxidongsx

category

String Required

The type of in-store funds pre-auth.

Example: HOTEL

outStoreCode

String Required

Merchant store number

Example: Storesx01

outStoreAlias

String

Alias of a merchant's store.

Parameter

Description

Basic parameter

code

String (16) Required

The gateway return code, which indicates whether the request is accepted by Alipay gateway.

Example:  10000

msg

String (32) Required

Description of the gateway return code

Example: Business Failed

sub_code

String (16)

Processing result of the request

Example: isv.invalid-signature

sub_msg

String (64)

Description of the processing result of the request

sign

String (344) Required

The sign value. See Signature for details.

Business parameter

out_order_no

String (64) Required

The transaction number of funds pre-auth assigned by merchant.

Example: 4977164666634053

out_request_no

String (64) Required

The serial number of funds operation request assigned by merchant.

Example: 487735255938023

code_type 

String(20) Required

The code type, including barCode and qrCode. Only qrCode is supported now.

Example: qrCode

code_value

String(200) Required

The QR code string generated for the request creation. The merchant can use the QR code generator with the string to create the QR code.

Example: https://qr.alipay.com/aax017928umnzqo0uswmzd3

code_url

String(200) Required

The URL address of the generated QR code with Alipay's logo is http://mobilecodec.alipay.com/show.htm?code=aeparsv2dknkqf3018556a

The merchant may add picSize at the end to assign the picture's size. For example, a 1280p picture's URL is http://mobilecodec.alipay.com/show.htm?code=aeparsv2dknkqf3018556a&picSize=1280

Supported resolutions include: 256, 227, 270, 344, 430, 512, 570, 860, 1280, and 1546.

Example: http://mobilecodec.alipay.com/show.htm?code=aeparsv2dknkqf3018556a

Parameter

Description

auth_no

String (64) Required

The transaction number of funds pre-auth assigned by Alipay, which is composed of 28 digits.

Example: 201808077735255938

operation_id

String (64) Required

The serial number of funds operation assigned by Alipay.

Example: 2014070800032850551

out_order_no

String (64) Required

The transaction number of funds pre-auth assigned by merchant.

Example: 4977164666634053

out_request_no

String (64) Required

The serial number of funds operation request assigned by merchant.

Example: 2014070700166653

operation_type

String (20) Required

Funds operation type. Possible values include:

• FREEZE
• UNFREEZE
• PAY

Example: FREEZE

amount

Price (11) Required

The total amount of funds frozen in the transaction currency, rounded to 2 decimal places.

Example: 100.00

status

String (20) Required

Status of the funds pre-auth. Possible values are:

• INIT
• SUCCESS
• CLOSED

Example: SUCCESS

payer_user_id

String (32) Required

Payer's Alipay user ID

Example: 2088102000275885

payer_logon_id

String (100) Required

The payer's Alipay login ID, email, or phone number are supported.

Example: email@example.com

payee_user_id

String (32) Required

Payee's unique Alipay user ID

Example: 2088102000275111

payee_logon_id

String (100) Required

Payee's Alipay login ID, email, or phone number are supported.

Example: email@example.com

gmt_trans

Date Required

The time when the funds pre-auth changed. The format is yyyy-mm-dd hh:mm:ss. Use GMT+8.

Example: 2020-09-15 11:23:04

gmt_create

Date Required

The time when the funds pre-auth succeed. The format is yyyy-mm-dd hh:mm:ss.

Example: 2020-09-15 11:23:04

pre_auth_type

String (32) Required

The pre-auth type. Only CREDIT_AUTH (credit pre-auth) is supported now. International pre-auth does not need this parameter. 

With this parameter, merchants can determine the type of pre-auth. Return value being CREDIT_AUTH means that the funds are credit pre-authed and no funds are actually frozen. Return value being null or anything other than CREDIT_AUTH means that the funds are pre-authed normally and user's funds are frozen.

Example: CREDIT_AUTH

total_freeze_amount

String (11) Required

The total frozen amount. The unit is the transaction currency used when the funds were frozen.

Example: 100.00

total_unfreeze_amount

String (11) Required

The total unfrozen amount. The unit is the transaction currency used when the funds were frozen.

Example: 20.00

total_pay_amount

String (11) Required

The total paid amount. The unit is the transaction currency used when the funds were frozen.

Example: 80.00

rest_amount

String (11) Required

The total paid amount. The unit is the transaction currency used when the funds were frozen.

Example: 20.00

credit_amount

String (11) Required

The credit amount. The currency is RMB.

Example: 10.00

fund_amount

String (11) Required

The balance amount. The currency is RMB.

Example: 10.00

total_freeze_credit_amount

String (11) Required

The total frozen credit amount. The currency is RMB.

Example: 10.00


Total_freeze_fund_amount

String (11) Required

The total frozen balance amount. The currency is RMB.

Example: 10.00

total_unfreeze_credit_amount

String (11) Required

The total unfrozen credit amount. The currency is RMB.

Example: 10.00


total_unfreeze_fund_amount

String (11) Required

The total unfrozen balance amount. The currency is RMB.

Example: 10.00

total_pay_credit_amount

String (11) Required

The total paid credit amount. The currency is RMB.

Example:10.00

total_pay_fund_amount

String (11) Required

The total paid balance amount. The currency is RMB.

Example: 10.00

rest_credit_amount

String (11) Required

The rest credit amount. The currency is RMB.

Example: 10.00

rest_fund_amount

String (11) Required

The rest balance amount. The currency is RMB.

Example: 10.00

trans_currency

String (8) Required

The pricing currency. Use uppercase.

Example: USD

Trigger condition name

Description

Note

fund_auth_freeze

Pre-auth fund is frozen successfully

true (triggers notification)

fund_auth_freeze.closed

Pre-auth freeze order closed

false (does not trigger notification)

fund_auth_freeze.init

Pre-auth freeze order created

false (does not trigger notification)

Error Code

Description

ILLEGAL_ARGUMENT

The parameter is incorrect. Check each request parameter according to the API specification.

For cashier, get the customer to refresh the payment code and try the pre-auth again.

UNIQUE_VIOLATION

Repeated order number. Get the cashier to cancel the order and retry.

EXIST_FORBIDDEN_WORD

Prohibited words are included in the transaction request.

ACCESS_FORBIDDEN

You have no permission to use the product. Check your agreement with Alipay. 

PAYEE_NOT_EXIST

The payee account does not exist.

PAYEE_USER_STATUS_LIMIT

Abnormal payee account

PAYER_USER_STATUS_LIMIT

Abnormal customer account

ORDER_ALREADY_FINISH

Order completed

ORDER_ALREADY_CLOSED

Order closed

FREEZE_ALREADY_SUCCESS

Repeat operation

ERROR_BALANCE_PAYMENT_DISABLE

Balance payment disabled

SYSTEM_ERROR

System error

MONEY_NOT_ENOUGH

Insufficient balance

NO_PAYMENT_INSTRUMENTS_AVAILABLE

Payment channel unavailable

PAYER_PAYEE_EQUAL

The payer and payee cannot be the same.

CURRENCY_VERIFICATION_FAIL

Incorrect currency

SECONDARY_MERCHANT_STATUS_ERROR