API integration
The API integration introduces how to initiate an authorized payment via APIs. This solution is suitable for merchants who have higher requirements for customization of the payment process.
Request for an authorization payment
After the buyer clicks the button to pay, you need to call the pay API (POST/v1/payments/pay) to initiate an authorization for a card payment. Perform this step according to the following instructions:
- After the buyer clicks to pay, disable the payment button until you receive the API result in case of repeated operations triggered by the user.
- You need to collect buyer card information during the authorized payment process. Please refer to the Integration steps for more details.
- You can also choose to use More features according to your business needs when initiating an authorization payment.
- You can designate the capture mode as either automatic capture or manual capture when initiating an authorization payment. The capture mode is automatic capture by default.
- Automatic capture: APO automatically captures funds immediately after a successful authorization when one of the following conditions is met:
Integration steps
The non-independent card binding mode means that you have not used the independent card binding ability before initiating authorized payment. With this mode integration, you need to provide all buyer information, including card payment information.
In the non-independent card binding mode, follow the steps to complete an authorization payment:
- After the buyer chooses the car payment method, display the card information collection page for the buyer (this page is developed by you). During this process, you need to collect the user's card information, environment information, and order information.
- Call the pay API to request an authorization payment.
- Process the response of the pay API. The response may contain the result of the authorization payment. For more information about how to handle the response, see Obtain authorization result.
- Display the authorization payment result to the buyer.
Figure 2. The interaction process of authorization payment
API call
When sending a request for the pay API (POST/v1/payments/pay), you need to provide the following information:
Card info | Env info: used to improve the payment success rate | Order info: used to reduce payment rejection and card theft rates |
cardNo cvv expiryYear expiryMonth cardholderName billingAddress ... | browserInfo clientIp terminalType | goods shipping buyer |
Table 2. Card information to be collected
When sending a request for the pay API, you can also choose to use More features according to your business needs.
- Enable 3D authentication: Specify the value of is3DSAuthentication in the pay API to set whether the transaction is authenticated by using 3D Secure.
- Address Verification System (AVS) service: This service verifies whether the provided billing address matches the cardholder's address on record at the issuing bank. AVS helps to prevent fraudulent transactions.
- Store card info: Obtain the buyer's agreement to store card information at the first payment, so that the card information does not need to be entered again for the next payment.
- Merchant-initiated transactions (MIT): Initiate scheduled or unscheduled transactions without user involvement.
- Merchant Plug-In (MPI): If the buyer completes 3D Secure authentication through a third-party authentication agency before the payment, pass in the 3D Secure authentication result when calling the pay API. The MPI feature is only available if you collect the buyer's card information.
The request sample of the pay API:
{
"env": {
"browserInfo": {
"acceptHeader": "*/*",
"javaEnabled": true,
"javaScriptEnabled": true,
"language": "zh_CN",
"userAgent": "Chrome/100"
},
"terminalType": "APP",
"clientIp": "112.80.248.78",
"deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMOzAKe",
"osType": "IOS",
"deviceLanguage": "zh_CN",
"colorDepth": 48,
"screenHeight": 768,
"screenWidth": 1024,
"timeZoneOffset": 1
},
"order": {
"orderAmount": {
"currency": "EUR",
"value": "30000"
},
"orderDescription": "Cappuccino #grande (Mika's coffee shop)",
"referenceOrderId": "ORDER_20221114141714891",
"goods": [
{
"referenceGoodsId": "383382011_SGAMZ-904520356",
"goodsName": "[3 Boxes] Starbucks Cappuccino Milk Coffee Pods / Coffee Capsules by Nescafe Dolce Gusto",
"goodsUrl": "https://www.lazada.sg/products/3-boxes-starbucks-cappuccino-milk-coffee-pods-coffee-capsules-by-nescafe-dolce-gusto-i383382011-s904520356.html?clickTrackInfo=undefined&search=1&source=search&spm=a2o42.searchlist.list.3",
"goodsCategory": "Digital Goods/Digital Vouchers/Food and Beverages",
"goodsUnitAmount": {
"currency": "EUR",
"value": "30000"
},
"goodsQuantity": "10"
}
],
"shipping": {
"shippingName": {
"firstName": "Dehua",
"lastName": "Liu",
"fullName": "Dehua Skr Liu",
"middleName": "Skr"
},
"shippingAddress": {
"zipCode": "310000",
"address2": "Xihu",
"city": "Hangzhou",
"address1": "Wuchang road",
"state": "Zhejiang",
"region": "CN"
},
"shippingCarrier": "FedEx",
"shippingPhoneNo": "12345678912",
"shipToEmail": "test@gmail.com"
},
"buyer": {
"referenceBuyerId": "test12345678",
"buyerPhoneNo": "12345678912",
"buyerEmail": "alipay@alipay.com",
"buyerName": {
"firstName": "Dehua",
"lastName": "Liu",
"fullName": "Dehua Skr Liu",
"middleName": "Skr"
}
}
},
"paymentAmount": {
"currency": "EUR",
"value": "30000"
},
"paymentMethod": {
"paymentMethodType": "CARD",
"paymentMethodMetaData": {
"isCardOnFile": false,
"enableAuthenticationUpgrade": true,
"is3DSAuthentication": false,
"cvv": "850",
"cardholderName": {
"firstName": "Tom",
"lastName": "Jay"
},
"expiryMonth": "12",
"billingAddress": {
"zipCode": "310000",
"address2": "Xihu",
"city": "Hangzhou",
"address1": "Wuchang road",
"state": "Zhejiang",
"region": "CN"
},
"expiryYear": "29",
"cardNo": "4117347806156383"
}
},
"settlementStrategy": {
"settlementCurrency": "EUR"
},
"paymentNotifyUrl": "https://www.alipay.com/notify",
"paymentRedirectUrl": "https://www.alipay.com",
"paymentRequestId": "PAY_20221114141714891",
"productCode": "CASHIER_PAYMENT",
"paymentFactor": {
"isAuthorization": true
}
}User experience
Obtain authorization result
After calling the pay API, the value of the resultStatus parameter in the response returned by APO indicates the authorization payment result of a transaction.
Figure 3. Descriptions of resultStatus in response
S: indicates that the authorization payment is successful.F: indicates that the authorization payment is failed.UandPAYMENT_IN_PROCESS(resultCode): indicates that the authorization payment is in progress and your buyer needs to be redirected to the URL specified in the normalUrl parameter to complete the authorization payment. You can obtain the result of the authorization payment through asynchronous notifications or inquire through inquiryPayment.
The following code samples show the response you may receive after calling the pay API. The response may include information on successful authorization payments, failed authorization payments, or redirect URLs for authorization payments in the process:
{
"paymentAmount": {
"currency": "EUR",
"value": "1314"
},
"paymentCreateTime": "2021-11-12T01:27:50-08:00",
"paymentId": "20211112194010800100188570271832381",
"paymentRequestId": "PAY_20211112172747856",
"paymentResultInfo": {
"avsResultRaw": "A",
"cvvResultRaw": "Y",
"networkTransactionId": "sampleNetworkTransactionId123456"
},
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
}
}Receive an asynchronous notification
You can obtain the authorization result by receiving an asynchronous notification sent by APO. You must set a notification address before you can receive the asynchronous notification. When a final authorization status is achieved (that is, when the authorization is successful or failed), APO sends you the asynchronous notification through notifyPayment. When you receive the notification, you must return a response as instructed in Requirements. Otherwise, APO resends the notification until a correct response is received.
Inquire about the authorization result
Due to network issues, asynchronous notifications may not be delivered or may be delayed. Therefore, we recommend that you proactively query the transaction status through the inquiryPayment (POST/v1/payments/inquiryPayment) API. You can set up active queries in the following scenarios:
- Before the payment result page is invoked: When the payment is initiated on the payment method page, you can automatically trigger calling the inquiryPayment API for subsequent redirection.
- When the user inquires about the payment result: When the user clicks or taps I have paid or a button with the same meaning on your page, you can call the inquiryPayment API to check the payment status.
- When the payment expires: When the payment reaches the expiry time, you can call the inquiryPayment API to check the payment status.
The response obtained from asynchronous notifications and inquiryPayment contains the authorization payment result as well as other key information such as:
API | Authorization result | AVS info | CVV info | 3DS authentication info |
notifyPayment | resultStatus | avsResultRaw | cvvResultRaw | threeDSResult (only available for the 3DS authentication authorization) |
inquiryPayment | paymentStatus | avsResultRaw | cvvResultRaw | threeDSResult (only available for the 3DS authentication authorization) |
Table 3. Key information about the authorization result
The following code samples show the result returned by noitfyPayment and inquiryPayment:
{
"notifyType": "PAYMENT_RESULT",
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"paymentRequestId": "2020010123456789XXXX",
"paymentId": "2020010123456789XXXX",
"paymentAmount": {
"value": "8000",
"currency": "EUR"
},
"paymentCreateTime": "2020-01-01T12:01:00+08:30",
"paymentTime": "2020-01-01T12:01:01+08:30",
"paymentResultInfo": {
"avsResultRaw": "A",
"cvvResultRaw": "Y",
"networkTransactionId": "sampleNetworkTransactionId123456",
"threeDSResult": {
"eci": "02",
"threeDSVersion": "2.2.0",
"caav": "cavvSample",
"dsTransactionId": "sample_dsTranasctionId"
}
}
}