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

Get started

Antom Shield detects and prevents risky transactions through interface data, so the way you integrate and the quality of your data will directly affect the effectiveness of risk assessment. This article will provide references for integration methods and standards for data quality.

Integration types

Antom Shield and Antom Shield Premium are automatically integrated in the Antom Card acquiring product, so you do not need to do any additional integration work. See Card payments (Web/WAP) for information on how to integrate card acquiring products.

When you need to apply Antom Shield and Antom Shield Premium products, the following are the integration methods and related recommendations for the Antom card acquiring product.

SDK integration

It is recommended that you prioritize using SDK to integrate the Antom card acquiring product, as this ensures the optimal effectiveness of the Antom Shield. When you use SDK to integrate Antom card acquiring products, there is no need to integrate the security SDK separately. Please refer to Card payments (Web/WAP) for the SDK integration steps for the card acquiring product.

API integration

When you use API to integrate the Antom card acquiring product, it is advised to separately integrate the security SDK to ensure effective identification of risk signals from the terminal devices. The API integration steps are as follows:

截屏2025-02-19 10.26.48.png

Please import the Security SDK package in advance following the steps below based on your terminal type:

Before integration

Provide the domain URL of the production environment to the risk control technical team, for examplehttps://www.alipay.com

Key steps

1. Introduce the security SDK  

copy
// Use CDN resources to introduce the SDK package:
<script src="https://sdk.marmot-cloud.com/package/antom-web-security/1.1.1/dist/umd/ams-security.min.js"></script>
copy
// Introduce the SDK package via npm:
npm install ams-security

import { AMSSecurity } from 'ams-security'

2. Initialize the security SDK  

copy
/**
 * Check if AMSSecuritySdk is ready
 * If ready, call the initAPSecurity method
 * If not ready, listen for the onAMSSecurityReady event, and when the event is triggered, call the initAPSecurity method again
 */
if(window.APSecuritySdk) {
  console.log('AMSSecuritySdk is ready');
  initAPSecurity();
} else {
  console.log('AMSSecuritySdk is not ready');
  window.onAPSecurityReady = function() {
    console.log('onAMSSecurityReady has been triggered');
    initAPSecurity();
  };
}

/**
 * Initialize AMSSecuritySdk
 * @param {string} scence - scence: CARD
 * @param {object} options - option
 * @param {string} options.region - region: SG/US/DE
 */
function initAPSecurity() {
  AMSSecurity.init("CARD", { region: "SG" })
}

3. Initialize device token

Generate deviceTokenId: Initialize the device token by invoking the device fingerprint generation method. The SDK will gather device information to create a device fingerprint. It is advisable to initialize the device fingerprint as early as possible when the application starts, allowing for direct use of getDeviceToken to obtain the token later.

copy
/**
 * Initialize AMSSecuritySdk
 * @param {string} scence - scence: CARD
 * @param {object} options - option
 * @param {string} options.region - region: SG/US/DE
 */
AMSSecurity.initToken("CARD", {}, (success: Boolean, tokenResult: any, msg: String) => {
    console.log("[Demo] initToken result success", success)
    console.log("[Demo] initToken result tokenResult", JSON.stringify(tokenResult))
    console.log("[Demo] initToken result msg", msg)
  });

4. Obtain the device token ID  

Query deviceTokenId: Retrieve the terminal device information token by querying deviceTokenId, and then provide this token to Antom in the pay (Checkout Payment) API.

copy
AMSSecurity.getTokenResult("CARD", (tokenResult: TokenResult) => {
    console.log("[Demo] getDeviceToken tokenResult", JSON.stringify(tokenResult))
  });

Data Quality

Antom Shield

When you need to use the list, rules, and risk scoring capabilities provided by Antom Shield, please check the integrity of the order.buyer.referenceBuyerId and env.clientIp fields during the transaction. In addition, please transmit the following key fields, as the related lists or rules involving variables will be invalid if any fields are missing or incorrect. Complete and accurate transaction data can effectively improve the accuracy of the risk scores.

Field Name

Description

Purpose

buyer.buyerPhoneNo

The mobile phone number of the buyer.

This is the unique identity marker for the buyer, used for configuring rule and list, as well as for calculating corresponding risk score.

buyer.buyerEmail

The email of the buyer.

env.deviceTokenId

The token identifier of the device.

When you use API to integrate the Antom card acquiring product, this data is used to identify the physical device used by the buyer to complete the transaction and the IP information of the device, which is utilized for setting rules and calculating risk scores.

order.shipping.shippingName

The name of the recipient. 

This is the name filled in by the buyer, used as an identifier for the buyer's purchasing behavior, for rule configuration and risk score calculations.
order.shipping.shippingName.firstNameThe first name of the recipient.
order.shipping.shippingName.middleNameThe middle name of the recipient. 
order.shipping.shippingName.lastNameThe last name of the recipient. 
order.shipping.shippingName.fullNameThe full name of the recipient. 
order.shipping.shippingAddress

Shipping address. 

This is the address of the recipient, used for identifying the buyer's purchasing behavior for relevant rule configuration and risk score calculations.

order.shipping.shippingAddress.region

The 2-letter country or region code that complies with ISO 3166 Country Codes standard

order.shipping.shippingAddress.state

The state, country, or province name.

order.shipping.shippingAddress.city

The city, district, suburb, town, or village name.

order.shipping.shippingAddress.address1

Address line 1, for example, the street address, PO box, and company name.

order.shipping.shippingAddress.address2

Address line 2, for example, the apartment, suite, unit, and building information.

order.shipping.shippingAddress.zipcode

ZIP or postal code.

order.shipping.shipToEmail

The email address where virtual goods are sent.

This serves as an identifier for the buyer's purchasing behavior, used for rule configuration and risk score caculation.

order.shipping.shippingPhoneNo

The phone number of a recipient (including extension).

When you use API to integrate the Antom card acquiring product and have integrated the security SDK, we will also use the information collected by the security SDK for Antom Shield rule configuration and risk assessments.

Antom Shield will collect certain device and transaction data for fraud identification, enhancing payment security and service quality. You can begin using Antom Shield after reading and agreeing to the terms related to the risk control services on the Antom Dashboard. If you want to cancel the services of Antom Shield or delete related data, please contact your account manager.

Antom Shield Premium

When enabling the Antom Shield Premium service, please ensure the accuracy of the fields marked as required for risk control in the transmission interface documentation, to guarantee the effectiveness of intelligent risk control decisions. The amount and quality of data you provide are directly related to the precision of risk control decisions; The higher the quality of the data, and the more data fields are provided, the more effective the intelligent risk control decisions will be. For more details, please refer to Expert decisions, and for field requirements, please refer to Antom APIs.

Note: Due to regulatory constraints, Antom Shield and Antom Shield Premium may not be available for merchants who activated specific regional cards. Contact your Antom account manager for more information.