Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

APIs calling process

According to whether you have PCI qualifications and whether you are willing to collect the card information, the API calling process is different.

If you have PCI qualifications and can independently collect the card information, the API calling process is as follows:

  1. Before card payment authorization: Call the decide API to obtain advice on whether to authorize the transaction and whether to perform 3D verification on the transaction.
  2. After obtaining the authorization result: Call the sendPaymentResult API to notify Ant Group of the card payment authorization result for training Ant Group's risk control model.
  3. After a refund occurs: Call the sendRefundResult API to notify Ant Group of the refund result for training Ant Group's risk control model.
  4. After a risk occurs: Call the reportRisk API to notify Ant Group of a risk for training Ant Group's risk control model.

The following figures show the API integration for implementing Card Payment Protection in the previously-mentioned two cases.

APIs calling process

Note: Card Payment Protection can provide risk control for the acquiring services provided by any payment service provider. To improve the accuracy of identifying risky transactions, we recommend that you always notify Ant Group of the transaction results by calling the sendPaymentResult or sendRefundResult API after the transaction or refund reaches the final state.

Step 1: Request a risk control decision

How you request a risk control decision depends on whether you collect the card information:

Send a request

When you call the decide API to request a risk control decision from Ant Group, pass in the following card information to paymentDetails.paymentMethod. You must provide a card information filling page to collect buyers' card information.

Child parameter

Description

paymentMethodType

Required. The value is CARD.

paymentMethodId

Not required.

paymentMethodMetaData.cardNo

Pass in the card number.

paymentMethodMetaData.cardBin

Pass in the Card Bank Identification Number.

paymentMethodMetaData.expiryYear

Pass in the year the card expires.

paymentMethodMetaData.expiryMonth

Pass in the month the card expires.

paymentMethodMetaData.cardholderName

Pass in the cardholder's name.

paymentMethodMetaData.billingAddress

Pass in the cardholder's billing address. Specify the parameter when you use the card payment service in Hong Kong and Singapore.

paymentMethodMetaData.cpf

Pass in the CPF number. Specify the parameter for Brazilian cards.

paymentMethodMetaData.is3DSAuthentication

Specify the value to indicate whether to use 3D secure verification. Alipay determines the verification type based on the assigned value, risk control policies, and payment method capabilities (whether a payment method supports 3D secure verification).

  • is3DSAuthentication=true: indicates that you want to use 3D secure verification. However, the verification type also depends on Alipay's risk control policies.
  • is3DSAuthentication=false: indicates that you want to use non-3D non-3D secure verification. However, the verification type also depends on Alipay's risk control policies.
  • is3DSAuthentication is not specified: The acquirer determines the verification type.

Table 1. Description of child parameters of paymentMethod

Apart from the card information, you must also pass in the following payment information:

Parameter

Description

referenceTransactionId

The unique ID to identify a transaction, which is assigned by the merchant.

authorizationPhase

Pass in the value PRE_AUTHORIZATION, which indicates that the request is initiated before the card payment authorization.

actualPaymentAmount.value

The order amount.

env.terminalType

For desktop website payment, specify it as WEB. For mobile website payment, specify it as WAP. For mobile application payment, specify it as APP.

referenceOrderId

referenceOrderId generally refers to an order ID, and paymentRequestId generally refers to a transaction ID. Alipay allows one order ID corresponding to multiple transaction IDs. You can also establish a one-to-one correspondence between them.

Table 2. Key request parameters in the pay API

In addition to the parameters listed above, we recommend that you provide as much transaction environment, logistics information, merchant information, and buyer information as possible in your request. This will help Ant Group accurately identify risky transactions and improve your transaction success rate. For details about the request parameters, see the decide API.

Obtain risk control advice

After you call the decide API successfully, Ant Group returns the request processing result. The response contains the following parameters to provide you with risk control advice.

Parameter

Description

decision

Ant Group's risk control advice. Valid values are:

  • ACCEPT: indicates that Ant Group suggests authorizing the payment.
  • REJECT: indicates that Ant Group suggests not authorizing the payment.

authenticationDecision

The recommended verification method when Ant Group suggests you authorize the payment. Valid values are:

  • 3D: indicates that Ant Group recommends 3D verification.
  • NON_3D: indicates that Ant Group recommends non-3D verification.

Table 3. Response parameters in the decide API

Step 2: Notify a transaction result

How you notify a transaction result depends on whether you collect the card information:

After obtaining Ant Group's risk control advice in Step 1, you can choose whether to authorize the transaction according to your own needs. If you have chosen Ant Group's acquiring service and authorized the transaction, after placing an order using the pay API, you can obtain the card payment authorization result through three methods:

  • Receive a synchronous return result.
  • Receive an asynchronous notification.
  • Inquire about the authorization result.

Receive a synchronous return result

In the response parameters of the pay API, if the value of resultStatus is S or F, the authorization is successful or failed respectively. If the value of resultStatus is U, you need to receive an asynchronous notification or inquire about the authorization result.

Receive an asynchronous notification

You can obtain the authorization result by receiving an asynchronous notification sent by Alipay.

You must set a notification address by specifying paymentNotifyUrl in the pay API before you can receive the asynchronous notification. When a final authorization status is achieved (that is, when the authorization is successful or failed), Alipay sends you the asynchronous notification through the notifyPayment notification. In the notification, if the value of resultStatus is S or F, the authorization is successful or failed respectively. When you receive the notification, you must return a response as instructed in Requirements.

Inquire about the authorization status

The asynchronous notification and the synchronous redirection can both fail to be received or implemented. We recommend that you inquire about the payment status by calling the inquiryPayment API. In the response returned through the inquiryPayment API, if the value of paymentStatus is SUCCESS or FAIL, the authorization is successful or failed respectively.

After obtaining the authorization result, you need to call the sendPaymentResult API to notify Ant Group of the authorization result. Pass in the following key parameters in your request：

ParameterDescription

referenceTransactionId

The unique ID to identify a transaction, which is assigned by the merchant.

paymentStatus

Pass in the authorization result. The valid values are SUCCESS and FAIL.

cardVerificationResult.authenticationType

If you have authorized the payment, pass in the verification type used for payment. Valid values are:

3D: indicates that 3D verification is used for the payment.

NON_3D: indicates that non-3D verification is used for the payment.

Table 5. Key request parameters in the sendPaymentResult API

Step 3: Notify a refund result

If a transaction is successfully refunded, call the sendRefundResult API to notify the refund result. Pass in the following parameters in your request:

Parameter

Description

referenceTransactionId

The unique ID to identify a transaction, which is assigned by the merchant.

referenceRefundId

The unique ID to identify a refund, which is assigned by the merchant.

actualRefundAmount

The total refunded amount of this transaction.

refundRecords

The refund details of each good of this transaction.

Table 6. Key request parameters in the sendRefundResult API

Step 4: Notify a risk

If a transaction is suspected of fraud, or a card fraud or chargeback occurs, you need to call the reportRisk API to notify Ant Group of the risk. Pass in the following parameters in your request:

Parameter

Description

referenceTransactionId

The unique ID to identify a transaction, which is assigned by the merchant.

reportReason

The reason why you report the risk.

riskType

The type of the reported risk. Valid values are:

  • SUSPICIOUS: indicates that the transaction is deemed risky by the merchant, such as when the buyer hits the merchant's blocklist.
  • CHARGEBACK: indicates a chargeback issued by the buyer.
  • FRAUD: indicates EMV (Europay, Mastercard, and Visa) counterfeit fraud.

riskOccurrenceTime

Indicates the time when the risk case occurs, which is defined in the following ways:

  • If the value of riskType is SUSPICIOUS, the value is the time when you identify the transaction as risky.
  • If the value of riskType is CHARGEBACK, the value is the time that is specified in the notification sent by the specific payment method provider.
  • If the value of riskType is FRAUD, the value is the time that is specified in the notification sent by the specific payment method provider.

Table 7. Key request parameters in the reportRisk API