decide
Use this API to request Ant's real-time risk management decision of whether to accept or reject a transaction when a buyer pays on your client. This API can be used both before and after the card payment authorization.
Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：
Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
- If the data type of a field is Integer and its value is 20, set it as "20".
- If the data type of a field is Boolean and its value is true, set it as "true".
Request parameters
referenceTransactionId String REQUIRED
The unique ID assigned by the merchant that directly provides services or goods to users, to identify a transaction.
More information:
- Maximum length: 64 characters
authorizationPhase String REQUIRED
Indicates the time when the API is called. Valid values are:
PRE_AUTHORIZATION: indicates that you initiate the decide request before the card payment authorization.- POST_AUTHORIZATION : indicates that you initiate the decide request after the card payment authorization.
More information:
- Maximum length: 16 characters
orders Array<Order> REQUIRED
The order information, such as merchant, goods, amount, and shipping information.
More information:
- Maximum size: 10 elements
buyer Buyer REQUIRED
Buyer information, including the ID, name, phone number, and email of the buyer.
actualPaymentAmount Amount REQUIRED
Indicates the actual amount the buyer needs to pay after deducting the discount.
paymentDetails Array<PaymentDetail> REQUIRED
Indicates the details of the payment method, including the payment method type and card information.
More information:
- Maximum size: 5 elements
discountAmount Amount
The discounted amount of this transaction.
Providing this information helps to increase the accuracy of fraud detection and improve payment success rates.
env Env REQUIRED
Information about the environment where the order is placed, such as the device information.
Response parameters
decision string REQUIRED
Risk management decision from Ant. Valid values are:
ACCEPT: Indicates that Ant advises to accept the payment.REJECT: Indicates that Ant advises to reject the payment.
More information:
- Maximum length: 16 characters
authenticationDecision String
The authentication method recommended by Ant. Valid values are:
3D: 3D authentication is recommended for this transaction.NON_3D: Non-3D authentication is recommended for this transaction.
This parameter is returned when the value of decide is ACCEPT.
More information:
- Maximum length: 16 characters
result Result REQUIRED
The result of the API call.
Request
Response
Result/Error codes
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success | The API is called successfully, no further action is needed. |
| ACCESS_DENIED | F | Access is denied. | Contact Alipay Technical Support for detailed reasons. |
| INVALID_API | F | The called API is invalid or not active. | Contact Alipay Technical Support to resolve the issue. |
| INVALID_CONTRACT | F | The parameter values in the contract do not match those in the current transaction. | Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Alipay Technical Support to troubleshoot the issue. |
| KEY_NOT_FOUND | F | The private key or public key of Alipay or the merchant is not found. | Check whether the private key or public key exists. If not, upload the private key in Alipay Developer Center. |
| MERCHANT_KYB_NOT_QUALIFIED | F | The payment failed because of the merchant's KYB status. The merchant is either not KYB compliant, or the KYB status is not qualified for this transaction. | Contact Alipay Technical Support for detailed reasons. |
| MERCHANT_NOT_REGISTERED | F | The merchant is not registered. | Please register the merchant by using the registration interface. Contact Alipay Technical Support if failed to call the registration interface. |
| NO_INTERFACE_DEF | F | API is not defined. | Check whether the URL is correct. Please refer to the endpoint in the API documentation. |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support. |
| PARAM_ILLEGAL | F | The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong. | Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid. |
| SYSTEM_ERROR | F | A system error occurred. | Do not retry, and contact Alipay Technical Support for more details. |
| UNKNOWN_EXCEPTION | U | An API call has failed, which is caused by unknown reasons. | Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support. |