Authorization payment

2024-04-03 02:01

The API integration introduces how to initiate an authorized payment via APIs.

Request for an authorization payment

After the buyer clicks the button to pay, you need to call the pay API 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 can collect card information and initiate an authorization payment in the following two ways:

Server-to-server mode: This mode requires that you are PCI qualified.
Hosted payment page mode: This mode does not require that you are PCI qualified.

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: Antom 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.

Server-to-server mode

Server-to-server payment mode allows you to process transactions by sending requests from your server to the Antom server. With this integration mode, you need to provide all user information, including card payment information.

Prerequisites for integration

The server-to-server integration mode requires that you are PCI qualified. Provide the following materials to complete verification according to business requirements:

If your annual card transaction volume is expected to exceed 6 million, complete and submit the PCI Attestation of Compliance (AoC) file for verification.
If your annual card transaction volume is expected to be below 6 million, complete and submit the PCI DSS Self-Assessment Questionnaires (SAQs) file for verification.

For more information about PCI DSS compliance requirements, see PCI DSS standard.

Integration steps

In the server-to-serve 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.

6@3x.png

Figure 1. The interaction process of authorization payment (Server-to-server mode)

User experience

First payment (Web)

First payment (App)

Saved card payment (Web)

Saved card payment (App)

API call

When sending a request for the pay API, 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 1. Card information to be collected

When sending a request for the pay API, you can also choose to use the following 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.
Salvage transaction intelligently: Automatically initiate a 3D Secure authentication for a non-3D Secure transaction if required by the card issuer to salvage a failed transaction. Specify the enableAuthenticationUpgrate parameter in the pay API to enable this feature.
Value-added risk control services: Antom provides upgraded risk control services at a transaction level, and intelligently decides risk control strategies based on the risk level of a transaction.
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.
Specify card brand: For dual-branded card payments, specify the brand or region of the card used for authorization.
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.
Installment payments: When making a payment, buyers can choose the installment payment method and make regular payments for each installment period. After the buyer completes the payment for the initial installment period, Antom settles the full order amount based on the settlement period specified in the contract.

For more information about how to use more features, see More features.

The request sample of the pay API:

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

Hosted payment page mode

The hosted payment page mode protects you from PCI-DSS restrictions because sensitive data (such as card no. and password) is not transmitted through your server, so PCI qualification is not required. In this mode, Antom provides the payment information collection page and collects payment information. The payment information is then stored as a card token (cardToken) for subsequent payments.

Antom provides issuer-authentication and non-authentication card payment types for Korean cards products. The majority of card payment products and non-authentication payments of Korean cards follow the general card payment process. However, issuer-authentication payments of Korean cards scenario involve additional processes. Choose the appropriate integration process based on the card type you want to integrate.

Integration steps

General card payment scenario

Issuer-authentication of Korean cards scenario

In the hosted payment page mode, follow the steps to complete an authorization payment:

The buyer selects the card payment method and goes to pay.
Call the pay API to submit the authorization payment request. The card information is not included in the API request.
After Antom receives the API call request, a card information collection page is returned for the buyer to enter the card information.
Open an intermediate page on the front end to display the card information collection page for the buyer.
After the buyer enters complete payment information, Antom verifies the payment information. When the verification is successful, Antom processes the API call with the payment information stored as a token (cardToken) and submits the authorization payment request to the card issuer.
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 result of the authorization payment to the buyer.

7@3x.png

.SENDPAYREQUEST,EXCLUDINGCARDINFORMATION

DISPLAYTHECARDINFORMATIONCOLLECTIONPAGE

MERCHANTCLIENT

1.BUYERSELECTSACARDANDGOESTOPAY

MERCHANTSERVER

5.BUYERENTERSTHECARDINFORMATION

INFORMATIONCOLLECTIONPAGE

7.DISPLAYTHEPAYMENTRESULT

6RETURNTHEPAYMENTRESULT

3.RETURNTHEURLOFTHECARD

ALIPAY

旦

Figure 2. The interaction process of authorization payment (General card payment scenario)

User experience

The following is the user experience process in the general card payment scenario.

First payment (Web)

First payment (App)

Saved card payment (Web)

Saved card payment (App)

For user experience in the issuer-authentication of Korean cards scenario, refer to Issuer-authentication payment.

API call

General card payment scenario

Issuer-authentication of Korean cards scenario

When sending a request for the pay API , you need to provide the following information:

Env info: used to improve the payment success rate

Order info: used to reduce payment rejection and card theft rates

terminalType

goods

shipping

buyer

Table 2. Information to be collected

When sending a request for the pay API, you can also choose to use the following 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.
Salvage transaction intelligently: Automatically initiate a 3D Secure authentication for a non-3D Secure transaction if required by the card issuer to salvage a failed transaction. Specify the enableAuthenticationUpgrate parameter in the pay API to enable this feature.
Value-added risk control services: Antom provides upgraded risk control services at a transaction level, and intelligently decides risk control strategies based on the risk level of a transaction.
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.
Installment payments: When making a payment, buyers can choose the installment payment method and make regular payments for each installment period. After the buyer completes the payment for the initial installment period, Antom settles the full order amount based on the settlement period specified in the contract.

For more information about how to use more features, see More features.

The request sample of the pay API:

copy
{
    "env": {
        "terminalType": "APP",
        "clientIp": "112.80.248.78",
        "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMOzAKe",
        "osType": "IOS",
        "deviceLanguage": "zh_CN"
    },
    "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"
    },
    "settlementStrategy": {
        "settlementCurrency": "EUR"
    },
    "paymentNotifyUrl": "https://www.alipay.com/notify",
    "paymentRedirectUrl": "https://www.alipay.com",
    "paymentRequestId": "PAY_20221114141714891",
    "productCode": "CASHIER_PAYMENT",
    "paymentFactor": {
        "isAuthorization": true
    }
}

In subsequent payments after the buyer saved a card in the first card payment, you need to pass in the obtained cardToken information through the paymentMethod.paymentMethodId parameter in the pay API. The value of cardToken can be obtained in the following ways:

Receive asynchronous notification (notifyPayment): cardToken is in the cardInfo object in the notification.
Call the inquiryPayment API: cardToken is in the cardInfo object returned by the inquiryPayment API.

Obtain authorization result

After calling the pay API, the value of the resultStatus parameter in the response returned by Antom indicates the authorization payment result of a transaction.

8@3x.png

Figure 3. Descriptions of resultStatus in response

S (resultStatus): indicates that the authorization payment is successful.
F (resultStatus): indicates that the authorization payment is failed. You can change the paymentRequestID and call the payment request again.
U (resultStatus) 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.
No response: You can change the paymentRequestID or retry the payment request with the original request ID.

Notes:
In the general card payment scenario, the value of the resultStatus parameter returned by the pay API can only be F or U.
In the issuer-authentication of Korean cards scenario, the value of the resultStatus parameter returned by the pay API can only be F or U or no response.

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:

Authorization payment successful

Authorization payment failed

Authorization in the process

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

When the payment is completed, Antom will send you an asynchronous notification, and you can also obtain the authorization payment results through the inquiryPayment API.

Receive an asynchronous notification

You can obtain the authorization result by receiving an asynchronous notification sent by Antom. 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), Antom sends you the asynchronous notification through notifyPayment. When you receive the notification, you must return a response as instructed in Requirements. Otherwise, Antom 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 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)

Figure 3. Key information about the authorization result

Note: In the issuer-authentication and non-authentication payments of Korean cards scenarios, the responses obtained from asynchronous notifications and active queries do not contain 3D authentication info.

The following code samples show the result returned by noitfyPayment and inquiryPayment in the general card payment scenario:

notifyPayment (3D)

notifyPayment (non-3D)

inquiryPayment (3D)

inquiryPayment (non-3D)

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

The following code samples show the result returned by noitfyPayment and inquiryPayment in the issuer-authentication of Korean cards scenario:

notifyPayment

inquiryPayment

copy
{
  "actualPaymentAmount": {
    "currency": "KRW",
    "value": "120"
  },
  "cardInfo": {
    "avsResultRaw": "",
    "cvvResultRaw": "",
    "paymentMethodRegion": "KR",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "notifyType": "PAYMENT_RESULT",
  "paymentAmount": {
    "currency": "KRW",
    "value": "120"
  },
  "paymentCreateTime": "2024-03-18T19:35:39-07:00",
  "paymentId": "2020010123456789XXXX",
  "paymentRequestId": "2020010123456789XXXX",
  "paymentResultInfo": {
    "avsResultRaw": "",
    "cvvResultRaw": "",
    "paymentMethodRegion": "KR",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentTime": "2024-03-18T19:36:54-07:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}