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: POP automatically captures funds immediately after a successful authorization when one of the following conditions is met:

• You set the value of paymentFactor.captureMode in the pay API to AUTOMATIC.
• You leave the value of paymentFactor.captureMode in the pay API empty or you do not pass in this parameter.

• Manual capture: You initiate fund capture by calling the capture API after a successful authorization. You must set the value of paymentFactor.captureMode in the pay API to MANUAL.
  

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:

1. 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.
2. Call the pay API to request an authorization payment.
3. 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.
4. 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:

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 POP 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.
• U and PAYMENT_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"
    }
}

{
    "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": "ACCESS_DENIED",
        "resultMessage": "Access is denied.",
        "resultStatus": "F"
    }
}

{
  "result": {
    "resultStatus": "U",
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultMessage": "payment in process"
  },
  "normalUrl": "https://pgw-ui.2c2p.com/payment/4.1/ant/#/token/kSAops9Zwhos8hSTSeLTUchuUa9%2bFg0EHv0XtS%2bTyCt8%2f1qy%2fDZCW88dV9FH3Yh8pEobKvOj%2fsh6nbH95mDRORzWy%2bsBbFh541I7QzVolYBEzeYnLiTC6lP2hjCAwadc",
  "paymentId": "20221111194010890100111650285726898",
  "paymentRequestId": "amsdmpay_cangxi_lj_20221111_104718_672",
  "redirectActionForm": {
    "redirectUrl": "https://pgw-ui.2c2p.com/payment/4.1/ant/#/token/kSAops9Zwhos8hSTSeLTUchuUa9%2bFg0EHv0XtS%2bTyCt8%2f1qy%2fDZCW88dV9FH3Yh8pEobKvOj%2fsh6nbH95mDRORzWy%2bsBbFh541I7QzVolYBEzeYnLiTC6lP2hjCAwadc",
    "method": "GET"
  },
  "paymentAmount": {
    "currency": "HKD",
    "value": "100"
  },
  "paymentCreateTime": "2022-11-10T18:47:20-08:00"
}

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:

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"
        }
    }
}

{
    "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"
    }
}

{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "Success"
    },
    "paymentStatus": "SUCCESS",
    "paymentRequestId": "pay_1089760038715669_10277574507XXXX",
    "paymentId": "2019060811401080010018882020035XXXX",
    "paymentAmount": {
        "value": "500",
        "currency": "USD"
    },
    "paymentCreateTime": "2019-06-01T12:01:01+08:30",
    "paymentTime": "2019-06-01T12:01:01+08:30",
    "paymentResultInfo": {
        "avsResultRaw": "A",
        "cvvResultRaw": "Y",
        "networkTransactionId": "sampleNetworkTransactionId123456",
        "threeDSResult": {
            "eci": "02",
            "threeDSVersion": "2.2.0",
            "caav": "cavvSample",
            "dsTransactionId": "sample_dsTranasctionId"
        }
    }
}

{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "Success"
    },
    "paymentStatus": "SUCCESS",
    "paymentRequestId": "pay_1089760038715669_10277574507XXXX",
    "paymentId": "2019060811401080010018882020035XXXX",
    "paymentAmount": {
        "value": "500",
        "currency": "USD"
    },
    "paymentCreateTime": "2019-06-01T12:01:01+08:30",
    "paymentTime": "2019-06-01T12:01:01+08:30",
    "paymentResultInfo": {
        "avsResultRaw": "A",
        "cvvResultRaw": "Y",
        "networkTransactionId": "sampleNetworkTransactionId123456"
    }
}