Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

More features

When initiating an authorized payment, you can choose whether to use more features based on your service needs. This topic explains more features and how to use them.

Set 3D verification

You can choose whether to subject a payment to 3D verification by specifying the is3DSAuthentication parameter through pay API.

  • Leave is3DSAuthentication empty: The result is the same as that of specifying the parameter as false. 3D verification is disabled for the payment. If Antom determines this payment as high-risk, this payment is rejected.
  • Specify is3DSAuthentication as false: 3D verification is disabled for the payment. If Antom determines this payment as high-risk, this payment is rejected.
  • Specify is3DSAuthentication as true: 3D verification is enabled for the payment. If Antom determines this payment as high-risk, this payment is rejected.

Intelligent transaction salvage

The transaction salvage feature allows transactions where the card scheme requires 3D verification to automatically initiate the 3D verification process. This enables you to salvage transactions regardless of whether you previously chose 3D verification for them.

You can enable the transaction salvage feature for a transaction by specifying enableAuthenticationUpgrade as true. If you do not enable this feature and 3D verification for a transaction where the card scheme requires 3D verification, the card scheme determines this transaction as risky and rejects the payment.

Note: This feature is unavailable for payments initiated using certain cards under the corresponding local card scheme. These cards include South Korean cards, Singaporean cards, and Hong Kong cards.

Setting 3D verification and automatic transaction salvage will jointly determine the risk control verification process of transactions. The following table shows how the settings of the two features affect the risk control results:

Set 3D verification:

is3DSAuthentication

Set automatic transaction salvage:

enableAuthenticationUpgrade

Risk control result

false/leave it empty

true/leave it empty

After a payment without 3D verification failed, this payment automatically triggers 3D verification, and Antom returns the URL for rendering a 3D verification page.

false/leave it empty

false

If a payment without 3D verification failed, Antom returns the result of a failed payment.

true

true/false/leave it empty

This payment is to undergo 3D verification, and Antom returns the URL for rendering a 3D verification page.

Table 1. Risk control result affected by the settings of the two features

For API integration, after Antom returns the URL for rendering a 3D verification page, you need to display the verification page and guide buyers to finish the verification process. The following code sample shows how the URL is returned through the response in the pay API:

copy
{
  "result": {
    "resultStatus": "U",
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultMessage": "payment in process"
  },
  "normalUrl": "https://centinelapi.cardinalcommerce.com/V1/Cruise/Collect/...",
  "paymentId": "20221111194010890100111650285726898",
  "paymentRequestId": "amsdmpay_cangxi_lj_20221111_104718_672",
  "redirectActionForm": {
    "redirectUrl": "https://centinelapi.cardinalcommerce.com/V1/Cruise/Collect/...",
    "method": "GET"
  },
  "paymentAmount": {
    "currency": "HKD",
    "value": "100"
  },
  "paymentCreateTime": "2022-11-10T18:47:20-08:00"
}

Value-added risk control service

If you need an upgraded risk control service for payments, you can purchase the value-added risk control service provided by Antom. This service provides intelligent risk control policies based on the risk levels of payments.

Setting 3D Verification, Automatic Transaction Salvage, and this feature will jointly determine the risk control verification process of transactions. The following table shows how the settings of the three features affects the risk control results:

Value-added risk control service

Set 3D verification:

is3DSAuthentication

Set automatic transaction salvage:

enableAuthenticationUpgrade

Risk control result

Enabled

false/leave it empty

false

The risk control service determines whether to execute 3D verification.

Enabled

false/leave it empty

true/leave it empty

The risk control service determines whether to execute 3D verification. If the service determines not to execute 3D verification and a card scheme requires 3D verification, Antom returns the URL for rendering a 3D verification page.

Enabled

true

true/false/leave it empty

Even if the risk control service determines not to execute 3D verification, Antom returns the URL for rendering a 3D verification page.

Table 2. Risk control result affected by settings of the three features

Notes：

  • If you have purchased the value-added risk control service, you do not need to specify the is3DSAuthentication parameter. The risk control service provides you with risk control policies.
  • This feature is unavailable for payments initiated using certain cards under the supervision of the corresponding local card scheme. These cards include South Korean cards, Singaporean cards, and Hong Kong cards.

AVS check

An address verification system (AVS) check compares the billing address used in the transaction with the issuing bank's address information on file for that cardholder in order to detect fraud. By enabling the AVS check, the system automatically compares the billing address and email address entered by a buyer with the issuer's stored information. If there is a mismatch between this information, it may lead to a payment rejection or extra identity verification.

After you enable the AVS check service, you can initiate an AVS check based on your integration mode:

  • If you use server-to-server communication, pass in the billingAddress parameter through the pay API.
  • If you use the form hosting service, Antom provides the payment information collection page for buyers to enter their billing address, requiring no extra effort on your part.

Notes:

  • You can obtain the result of the AVS check through the avsResultRaw parameter in the response of the notifyPayment or inquiryPayment API.
  • This feature is only available for payments initiated using American cards under the supervision of American card schemes.

Card information storage

You can allow buyers to add their cards. That is, users can choose to save their card information during the first-time payment so that they do not need to re-enter the information for subsequent payments. The following figure shows the checkout page for a subsequent payment after a user saved their card information during the first-time payment.

11.png

Figure 1. Checkout page for subsequent payment with previously saved card information

How to add users' cards varies by integration mode. For server-to-server mode and form-hosting mode, perform these steps accordingly:

In server-to-server mode, after collecting the buyer's card information, you can choose to store the card information yourself or let Antom store it for you.

Antom stores card information (Recommended)

When a buyer stores card information on your page, pass in the card information to Antom through the pay API and specify the tokenize field as true. Antom generates a corresponding cardToken for the card information. After the payment is authorized successfully, obtain the cardToken and the masked cardNo by receiving an asynchronous notification or calling the inquiryPayment API. To process subsequent payments, you must store and associate the obtained card token, masked card number, and other information concerning the buyer.

The following code sample shows the pay API call request when Antom stores card information after you collect the card information:

copy
{
    "settlementStrategy": {
        "settlementCurrency": "EUR"
    },
    "productCode": "CASHIER_PAYMENT",
    "paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_GROUP&paymentMethodType=CARD",
    "paymentRequestId": "2023070458941025622196",
    "paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=2023070458941025622196",
    "paymentFactor": {
        "isAuthorization": true
    },
    "paymentMethod": {
        "paymentMethodMetaData": {
            "recurringType": "",
            "cvv": "123",
            "is3DSAuthentication": false,
            "isCardOnFile": false,
            "expiryMonth": "05",
            "tokenize": true,
            "expiryYear": "26",
            "billingAddress": {
                "zipCode": "310000",
                "address2": "gongzhuan Road",
                "city": "hangzhou",
                "state": "zhejiang",
                "region": "CN"
            },
            "cardNo": "411227747859****"
        },
        "paymentMethodType": "CARD"
    },
    "paymentExpiryTime": "2025-11-27T12:00:01+08:30",
    "paymentAmount": {
        "currency": "EUR",
        "value": "8204"
    },
    "merchantRegion": "",
    "order": {
        "orderAmount": {
            "currency": "EUR",
            "value": "8204"
        },
        "referenceOrderId": "202307049082433354****",
        "shipping": {
            "shippingName": {
                "firstName": "Li",
                "lastName": "Kyle",
                "fullName": "Kyle Li"
            },
            "shippingCarrier": "DHL",
            "shippingPhoneNo": "+8611012****",
            "shipToEmail": "email@163.com",
            "shippingAddress": {
                "zipCode": "310000",
                "address2": "gongzhuan Road",
                "city": "hangzhou",
                "state": "zhejiang",
                "region": "CN"
            }
        },
        "goods": [
        {
            "referenceGoodsId": "202305152647604043****",
            "goodsUrl": "qinghailipipeng",
            "goodsCategory": "chemical",
            "goodsUnitAmount": {
                "currency": "EUR",
                "value": "8204"
            },
            "goodsQuantity": "1",
            "goodsName": "boom",
            "goodsSkuName": "boom boom room",
            "goodsBrand": "antom boom"
        }
        ],
        "env": {
            "clientIp": "1.1.1.1",
            "osType": "IOS",
            "terminalType": "WAP"
        },
        "orderDescription": "ANTOM_ZZ",
        "buyer": {
            "referenceBuyerId": "Kyle Li8438027539****",
            "buyerName": {
                "firstName": "Li",
                "lastName": "Kyle",
                "fullName": "Kyle Li"
            }
        }
    }
}

When a buyer makes a payment using a saved card, complete the following:

  1. Display the masked card information for the buyer on the checkout page.
  2. Pass in the following parameters through the pay API:
  1. paymentMethodId: The value is the same as that of the cardToken parameter (obtained from paymentResultInfo of notifyPayment and inquiryPayment).
  2. Extra verification parameters (such as the cpf parameter for Brazilian cards).
  3. isCardOnFile: Set the value to true. This parameter is used to identify a subsequent payment using a saved card.

The following code sample shows the pay API call request using a card token when a buyer uses a saved card to pay:

copy
{
  "settlementStrategy": {
    "settlementCurrency": "EUR"
  },
  "productCode": "CASHIER_PAYMENT",
  "paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_GROUP&paymentMethodType=CARD",
  "paymentRequestId": "202307047191356537****",
  "paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=2023070471913565376977",
  "paymentFactor": {
    "isAuthorization": true
  },
  "paymentMethod": {
    "paymentMethodId": "ALIPAYXUDrmVyZKWqfGTZelkD1O+967zi3JmCeo9vUonsnMT9bcKcly88bvcRE4C+wRjazecG+d5jFylCRsGrtK8j0****",
    "paymentMethodMetaData": {
      "recurringType": "SCHEDULED",
      "is3DSAuthentication": false,
      "isCardOnFile": true,
      "networkTransactionId": "20423687633****"
    },
    "paymentMethodType": "CARD"
  },
  "paymentExpiryTime": "2025-11-27T12:00:01+08:30",
  "paymentAmount": {
    "currency": "EUR",
    "value": "3063"
  },
  "merchantRegion": "",
  "order": {
    "orderAmount": {
      "currency": "EUR",
      "value": "3063"
    },
    "referenceOrderId": "202307045940797909****",
    "shipping": {
      "shippingName": {
        "firstName": "Li",
        "lastName": "Kyle",
        "fullName": "Kyle Li"
      },
      "shippingCarrier": "DHL",
      "shippingPhoneNo": "+8611012****",
      "shipToEmail": "xihuanchishi@163.com",
      "shippingAddress": {
        "zipCode": "310000",
        "address2": "gongzhuan Road",
        "city": "hangzhou",
        "state": "zhejiang",
        "region": "CN"
      }
    },
    "goods": [
      {
        "referenceGoodsId": "202305151728950723****",
        "goodsUrl": "qinghailipipeng",
        "goodsCategory": "chemical",
        "goodsUnitAmount": {
          "currency": "EUR",
          "value": "3063"
        },
        "goodsQuantity": "1",
        "goodsName": "boom",
        "goodsSkuName": "boom boom room",
        "goodsBrand": "antom boom"
      }
    ],
    "env": {
      "clientIp": "1.1.1.1",
      "osType": "IOS",
      "terminalType": "WAP"
    },
    "orderDescription": "ANTOM_ZZ",
    "buyer": {
      "referenceBuyerId": "Kyle Li8415922738****",
      "buyerName": {
        "firstName": "Li",
        "lastName": "Kyle",
        "fullName": "Kyle Li"
      }
    }
  }
}

Store card information by yourself

When the buyer saves card information on your page, you need to store and associate the buyer's information and the corresponding card information on your server. When the buyer initiates a payment again, you need to pass in the card information through the pay API and specify the value of isCardOnFile as true. isCardOnFile is used to identify the subsequent payment using a saved card. Specifying this parameter improves the payment success rate.

The following code sample shows the pay API call request when a buyer uses a saved card to pay:

copy
{
    "env": {
        "terminalType": "APP",
        "clientIp": "112.80.248.78",
        "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMO****",
        "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_2022111414171****",
        "goods": [
            {
                "referenceGoodsId": "38338

MIT

Merchant-initiated Transaction (MIT) refers to a type of pre-authorized transactions for card payments, that is, regular or irregular transactions without the buyer's participation.

Note:

MIT is a type of transactions without 3D verification.

  • Before you initiate an MIT, you must obtain a buyer's authorization, which requires the buyer to complete 3D verification for the first-time authorization of the payment.
  • This feature is unavailable for payments initiated using certain cards under the corresponding local card scheme. These cards include South Korean cards, Singaporean cards, and Hong Kong cards.

For API integration, specify the following parameters in the pay API to initiate an MIT.

  • isCardOnFile: The value is true, which is used to label the payment as a subsequent payment using a saved card.
  • recurringType: The value is SCHEDULED or UNSCHEDULED, which is used to specify this payment as a regular or irregular payment.
  • networkTransactionId: Antom needs to confirm that you have obtained the buyer authorization to complete the MIT. Therefore, you must pass in a unique identifier to this parameter. The identifier is assigned by a card scheme to identify an authorized payment for the first-time authorization. When the buyer completes the payment with the first-time authorization, you can obtain the identifier through the response in the notifyPayment API or inquiryPayment API.

Specify a card brand

When a buyer chooses a dual-scheme card (a card issued under two card schemes) for an authorized payment, you can specify the card brand and region by specifying thepaymentMethodRegion and selectedCardBrands parameters. The following table shows how the settings of the two parameters determines the card brand for the payment:

PaymentMethodRegion

selectCardBrands

Card brand for the payment

GLOBAL

None

A global card brand

FR, BR..

None

A local card brand

None

VISA, CB

A specific card brand

None

None

A card brand determined by Antom considering the costs and success rates

Table 3. Card brand determined by the settings of the two parameters

Notes:

  • For the card brand and region of a specific card, see Payment methods。
  • This feature is unavailable for payments initiated using Brazilian cards under any Brazilian card scheme.

MPI

If you let your buyer complete 3D Secure authentication through a third party before you initiate the authorized payment, pass in the 3D Secure authentication result through mpiData and specify this payment as non-3D Secure authentication when calling the pay API.

Field

Description

mpiData.threeDSVersion

The 3D Secure protocol version returned by the third-party authentication agency.

mpiData.caav

The cardholder authentication value returned by the third-party authentication agency.

mpiData.dsTransactionId

The unique transaction identifier returned by the third-party authentication agency.

mpiData.eci

Electronic Commerce Indicator (ECI) returned by the third-party authentication agency.

is3DSAuthentication

Set to false. The buyer completes 3D Secure authentication. Specify the transaction as non-3D authentication.

enableAuthenticationUpgrade

Set to false. The buyer completes 3D Secure authentication. No need to upgrade the transaction to 3D Secure authentication.

Figure 4. MPI information

The following code sample shows the request for calling the pay API with mpiData:

copy
{
    "env": {
        "browserInfo": {
            "acceptHeader": "*/*",
            "javaEnabled": true,
            "javaScriptEnabled": true,
            "language": "zh_CN",
            "userAgent": "Chrome/100"
        },
        "terminalType": "APP",
        "clientIp": "112.80.248.78",
        "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMO****",
        "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_2022111414171****",
        "goods": [
        {
            "referenceGoodsId": "383382011_SGAMZ-90452****",
            "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": "1234567****",
            "shipToEmail": "test@gmail.com"
        },
        "buyer": {
            "referenceBuyerId": "test1234****",
            "buyerPhoneNo": "1234567****",
            "buyerEmail": "example@alipay.com",
            "buyerName": {
                "firstName": "D****",
                "lastName": "L****",
                "fullName": "Dehua Skr****",
                "middleName": "S****"
            }
        }
    },
    "paymentAmount": {
        "currency": "EUR",
        "value": "30000"
    },
    "paymentMethod": {
        "paymentMethodType": "CARD",
        "paymentMethodMetaData": {
            "isCardOnFile": false,
            "enableAuthenticationUpgrade": false,
            "is3DSAuthentication": false,
            "mpiData": {
                "eci": "02",
                "threeDSVersion": "2.2.0",
                "caav": "cavvSample",
                "dsTransactionId": "sample_dsTranascti****"
            },
            "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": "411734780615****"
        }
    },
    "settlementStrategy": {
        "settlementCurrency": "EUR"
    },
    "paymentNotifyUrl": "https://www.alipay.com/notify",
    "paymentRedirectUrl": "https://www.alipay.com",
    "paymentRequestId": "PAY_2022111414171****",
    "productCode": "CASHIER_PAYMENT",
    "paymentFactor": {
        "isAuthorization": true
    }
}

Note: The MPI feature is unavailable for payments initiated using South Korean cards under any South Korean card scheme.