Antom, leading provider of tailored payment solutions

SDK references

Note: This page has been deprecated and is no longer maintained or updated. Visit https://docs.antom.com/ for the latest content.

Callback data

Callback function can return various types of data or values, such as event codes and payment-related information. This part will introduce you event codes, card payment information, and risk control details returned through callback functions.

Event codes

Event codes are returned through different callback functions at different times, mainly including the following three types:
  • Status codes
  • Error codes
  • Payment result codes

Status codes

Returned through the onEventCallback method during the component's runtime lifecycle, and subsequent processing can be done based on the specific event.
  • SDK_START_OF_LOADING: The loading animation starts to be shown when the component is created. When configured to hide loading and use a custom animation, the custom animation can be rendered at this time.
  • SDK_END_OF_LOADING: The loading animation ends when the component is created. When configured to hide loading and use custom animation, the animation can be hidden at this time.
  • SDK_PAYMENT_CANCEL: Indicates that the user canceled the payment (the user exited the payment page without submitting the order). You can re-invoke the SDK using the paymentSessionData within its validity period. If it has expired, you need to initiate a new createPaymentSession request.
  • SDK_CALL_URL_ERROR: This event code represents one of the following situations in the event information:
    • Failed to redirect to merchant page.
    • Failed to redirect to the payment method app or page.
    • The paymentRedirectUrl parameter is not specified or is not correctly specified when calling the createPaymentSession request.
In the Web or WAP scenario, redirecting links is usually not abnormal. If an exception does occur, it is recommended that you verify the redirected link. In the app scenario, if the exception frequently occurs, contact Antom Technical Support to troubleshoot redirection or calling issues.
  • SDK_CALL_URL_SUCCESS: Successfully redirected to the payment method/merchant page.
  • SDK_DUPLICATE_SUBMISSION_BEHAVIOR: The form is submitted repeatedly. The merchant can prompt the user through a toast without the need to click submit repeatedly.
  • SDK_FORM_VERIFICATION_FAILED: The form verification failed after submitting the form. The SDK will display the form error code on the element collection page, allowing users to resubmit payments.
  • SDK_PAYMENT_AUTHORIZATION_SUCCESSFUL: The payment process is completed. If the method of not redirecting after payment is configured, it is recommended to continue listening for the corresponding payment event code to handle the subsequent process. This event code, otherwise,  can be ignored and redirected to your payment results page.
  • SDK_PAYMENT_CHALLENGE: Triggering a 3D challenge, and the issuing bank needs further interaction with shoppers before payment can be verified. No need to process, the SDK will redirect to the challenge page.

Error codes

Returned through the onEventCallback or onError method during the component initialization phase, and subsequent processing can be done based on the specific event.
  • SDK_INTERNAL_ERROR: SDK internal error. Contact Antom Technical Support.
  • SDK_CREATEPAYMENT_PARAMETER_ERROR: createComponent method specified parameter abnormally. Check if the parameters are correct and reinitialize the component.
  • SDK_INIT_PARAMETER_ERROR: AMSCashierPayment method specified parameter abnormally. Check if the parameters are correct and re-instantiate the SDK.
  • SDK_CREATECOMPONENT_ERROR: Component initialization exception. Contact Antom Technical Support.
  • SDK_SUBMIT_NETWORK_ERROR: API call failed due to network reasons. It may occur in submit method submission. Try to submit it again.

Payment result codes

Returned through the onEventCallback method at the end of the payment process and subsequent processing can be done based on the specific event.
  • SDK_PAYMENT_SUCCESSFUL: Payment is successful. The buyer needs to cancel the SDK for the first-time payment, and the SDK will close in the card token payment mode. Suggest redirecting to the payment result page.
  • SDK_PAYMENT_FAIL: Payment failed. We suggest that you follow the paymentResultCode error code prompt and guide the user to pay again.
  • SDK_PAYMENT_PROCESSING: Payment is being processed. It is recommended to check the payment status on your server or wait for the payment result notification.
  • SDK_PAYMENT_ERROR: The payment status is abnormal. It is recommended to check the payment status on your server or wait for the payment result notification.
  • SDK_PAYMENT_RETRY: Retry after payment failure. When you enable the option to retry after payment failure, guide the buyer to modify the information and pay again.

Description of payment failure or abnormal payment status

The following table provides payment result code and corresponding handling suggestions for payment failure or abnormal payment status. You can take further action based on the received payment result code.
paymentResultcode
paymentResultMessage
Suggestion
ACCESS_DENIED
Access is denied.
Insufficient permissions. Contact Antom Technical Support for specific reasons.
CURRENCY_NOT_SUPPORT
The currency is not supported.
Currency is not supported. Contact Antom Technical Support for specific reasons.
FRAUD_REJECT
The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.
Fraud denied. Contact Antom Technical Support if:
  • You need to appeal.
  • The buyer did not receive a refund within two weeks.
INVALID_CARD
The card is invalid. Maybe the credit card number cannot be identified, the card has no corresponding issuing bank, or the card number is in the wrong format.
Change the card and try again.
INVALID_EXPIRY_DATE_FORMAT
The format of expiryYear or expiryMonth is wrong.
The card's expiration date is incorrect. Check the format of filling in the card validity period.
ISSUER_REJECTS_TRANSACTION
The issuing bank rejects the transaction.
The issuing bank refused. Change the card and try again or contact the issuing bank.
INVALID_MERCHANT_STATUS
The merchant status is abnormal because restrictions exist.
Merchant status is abnormal. Contact Antom Technical Support for specific reasons.
MERCHANT_KYB_NOT_QUALIFIED
The payment failed because of the merchant's KYB status. The merchant is either not KYB compliant, or the KYB status is not qualified for this transaction.
Contact Antom Technical Support for specific reasons.
NO_PAY_OPTIONS
The currency is not supported for the transaction.
Currency is not supported. Check if the payment method supports the currency or if the payment method and currency are consistent with the contract. If there are any issues, contact Antom Technical Support for specific reasons.
ORDER_IS_CLOSED
The request you initiated has the same paymentRequestId as that of the existing transaction, which is closed.
The order has been closed. Initiate a new request and retry.
PAYMENT_AMOUNT_EXCEED_LIMIT
The payment amount is greater than the maximum amount allowed by the contract or payment method.
Limit amount exceeded. Check whether the payment amount exceeds the limit or try again with a lower amount. Contact Antom Technical Support for specific payment limits.
PAYMENT_COUNT_EXCEED_LIMIT
The maximum number of payments exceeds the limit that is specified by the payment method.
Use limit exceeded. Contact Antom Technical Support for specific payment limits.
PAYMENT_NOT_QUALIFIED
The merchant is not qualified to pay because the merchant is not registered, does not have a contract for Auto Debit payment, or is forbidden to make a payment.
The merchant does not have permission. Contact Antom Technical Support for specific reasons.
PROCESS_FAIL
A general business failure occurred.
Payment failed. This usually requires manual confirmation of the issue. Contact Antom Technical Support to resolve the issue.
RISK_REJECT
The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.
Risk control refused. If the buyer does not receive a refund within two weeks, contact Antom Technical Support.
SUSPECTED_CARD
The card is suspected of fraud. For example, the card is stolen or restricted.
Risk control refused. Change the card and try again or contact the issuing bank.
SUSPECTED_RISK
The transaction cannot be further processed because of suspected security issues. You can retry the transaction after one working day. If the transaction is not secure and the user has already paid, the transaction will be refunded.
Risk control refused. Contact Antom Technical Support if:
  • You need to appeal.
  • The buyer did not receive a refund within two weeks.
USER_AMOUNT_EXCEED_LIMIT
The payment amount exceeds the user payment limit.
The amount exceeds the limit. Reinitiate the payment with an amount less than or equal to the available balance in your account, or contact Antom Technical Support.
USER_BALANCE_NOT_ENOUGH
The payment cannot be completed because the user balance in the corresponding payment method is not enough.
Insufficient user balance. Recharge or choose another payment method.
USER_KYC_NOT_QUALIFIED
The payment failed because of the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified for this transaction (for example, limitations on the payment amount or product information).
The user completes KYC authentication first.
USER_PAYMENT_VERIFICATION_FAILED
The user is restricted from payment on the payment method side.
The user did not complete verification. Contact Antom Technical Support for specific reasons.
USER_STATUS_ABNORMAL
The user status is abnormal on the payment method side.
The user status is abnormal. Contact Antom Technical Support for specific reasons.
PAYMENT_IN_PROCESS
The payment is being processed.
Payment is being processed.
UNKNOWN_EXCEPTION
An API call has failed, which is caused by unknown reasons.
Unknown exception. Contact Antom Technical Support for specific reasons.
CARD_NOT_SUPPORTED
The card used for the transaction is not supported.
The card is not supported. Change the card and try again.
INVALID_EXPIRATION_DATE
The value of paymentMethod.paymentMethodMetaData.expiryYear or paymentMethod.paymentMethodMetaData.expiryDate is invalid.
The validity period of the card is incorrect. Check if the validity period of the card is filled out correctly.
INVALID_CARD_NUMBER
The number of the card used for the transaction is invalid.
The card number is incorrect. Change the card and try again. If there are still problems after trying again, contact Antom Technical Support for specific reasons.

Card payment information

In the case of card payment, once the payment processing reaches a final state of success or failure, you will receive the cardPaymentResultInfo parameter in the response after invoking the onEventCallback function. See the table below to explore child parameters of cardPaymentResultInfo:
Note: If the payment flow completes and the user is redirected to the redirection URL, you will not receive the cardPaymentResultInfo parameter.
Parameter name
Required
Description
cardNo
Optional
String (32)
The masked card number, which just shows part of the card number and can be used to display to the user.
This parameter is returned when the value of paymentMethodType in the pay API is CARD and the merchant does not have the PCI qualification.
cardBrand
Optional
String (256)
The card brand, which can be used to display to the user.
This parameter is returned when the value of paymentMethodType in the pay API is CARD .
cardBin
Optional
String (32)
The first six digits of the card number.
lastFour
Optional
String (4)
The last four digits of the card number.
issuerName
Optional
String (256)
The issuing bank of the card.
issuingCountry
Optional
String (2)
The issuing country of the card. The value of this parameter is a 2-letter country code that follows ISO 3166 Country Codes standard.
This parameter is returned when the value of paymentMethodType in the pay API is CARD.
funding
Optional
String (32)
The funding type of the card. Valid values are:
  • CREDIT: indicates a credit card.
  • DEBIT: indicates a debit card.
  • PREPAID: indicates a prepaid card.
  • CHARGE: indicates a charge card.
  • DEFERRED_DEBIT: indicates a deferred debit card.​
This parameter is returned when all the following conditions are met:
  • The value of paymentMethodType is CARD.
  • The value of cardNo is valid.
  • The information is available in the Antom card database.
avsResultRaw
Optional
String (128)
The raw AVS result. See AVS result codes to check the valid values.
This parameter is returned when the issuing bank passes this information to Antom.
cvvResultRaw
Optional
String (128)
The raw Card Verification Value (CVV), Card Security Code (CSC), or Card Verification Code (CVC) result. See CVV result codes to check the valid values.
This parameter is returned when the issuing bank passes this information to Antom.
holdName
Optional
String (32)
The card holder name.
fingerprint
Optional
String (256)
The unique identifier for this specific card number. You can use this parameter to check if two registered customers are using the same card number.
expiryMonth
Optional
String (2)
The month the card expires. Pass in two digits representing the month. For example, if the expiry month is February, the value of this parameter is 02.
This parameter is returned when all the following conditions are met:
  • You have the PCI qualification.
  • The value of paymentMethodType is CARD.
  • The information is available in the Antom card database.
expiryYear
Optional
String (2)
The year the card expires. Pass in the last two digits of the year number. For example, if the expiry year is 2025, the value of this parameter is 25.
This parameter is returned when all the following conditions are met:
  • You have the PCI qualification.
  • The value of paymentMethodType is CARD.
  • The information is available in the Antom card database.
The sample code of returned card information:
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "paymentStatus": "SUCCESS",
  "paymentResultCode": "SUCCESS",
  "paymentResultMessage": "success",
  "cardPaymentResultInfo": {
    "avsResultRaw": "4",
    "cardBin": "409280",
    "cardBrand": "VISA",
    "cardNo": "************8888",
    "cvvResultRaw": "1",
    "expiryMonth": "02",
    "expiryYear": "27",
    "fingerprint": "",
    "funding": "DEBIT",
    "holdName": "Tom Jay",
    "issuerName": "BANCO ITAUCARD, S.A.",
    "issuingCountry": "BR",
    "lastFour": "0000"
  }
}

Risk control

In the case of card payment, once the payment processing reaches a final state of success or failure and you have signed the risk control service with Antom, you will receive the popRiskDecisionResultInfo parameter in the response after invoking the onEventCallback function. See the table below to explore child parameters of popRiskDecisionResultInfo:
Note: If the payment flow completes and the user is redirected to the redirection URL, you will not receive the popRiskDecisionResultInfo parameter.
Parameter name
Required
Description
riskDecision
Optional
String (16)
Risk management decision from Antom. Valid values are:
  • ACCEPT: Indicates that Antom advises to accept the payment.
  • REJECT: Indicates that Antom advises to reject the payment.
This parameter is returned when you signed risk control service with Antom.
riskAuthDecision
Optional
String (16)
The authentication method recommended by Antom. Valid values are:
  • 3D: 3D authentication is recommended for this transaction.
  • NON_3D: Non-3D authentication is recommended for this transaction.
This parameter is returned when you signed risk control service with Antom.
The sample code of returned risk control information:
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "paymentStatus": "SUCCESS",
  "paymentResultCode": "SUCCESS",
  "paymentResultMessage": "success",
  "popRiskDecisionResultInfo": {
    "riskDecision": "ACCEPT",
    "riskAuthDecision": "NON_3D"
  }
}

Complete sample code for using the client SDK

The following code example illustrates the key steps in the integration process. The code does not include an example of calling the createPaymentSession API. You need to handle the calling of the server-side API yourself.
Web/WAP
The integration solution to support accepting payments from a desktop browser or mobile browser. Here are sample codes for two integration methods:
  • Integrate the SDK package using npm
  • Integrate the SDK package CDN resources
npm
import { AMSCashierPayment } from "@alipay/ams-checkout";
// Step 1: Instantiate the SDK and handle the callback event.
const onEventCallback = function ({ code, result }) {
  switch (code) {
    case "SDK_PAYMENT_SUCCESSFUL":
      // Payment was successful. Redirect users to the payment result page.
      break;
    case "SDK_PAYMENT_PROCESSING":
      console.log("Check the payment result data", result);
      // Payment is being processed. Query the payment status through the server or wait for the payment result notification. At the same time, you can check whether the user has completed the payment. If the payment is not completed, guide the user to pay again.
      break;
    case "SDK_PAYMENT_FAIL":
      console.log("Check the payment result data", result);
      // Payment failed. Please refer to the processing suggestions in the Event codes and guide the user to pay again.
      break;
    case "SDK_PAYMENT_CANCEL":
      // The user exits the payment page without submitting the order. You can re-invoke the SDK with paymentSessionData that is still valid. If it has expired, you need to re-request paymentSessionData.
      break;
    case "SDK_PAYMENT_ERROR":
      console.log("Check the payment result data", result);
      // The payment status is abnormal. Query the payment status through the server or wait for the payment result notification, or guide the user to pay again.
      break;
    case "SDK_END_OF_LOADING":
      // End the custom loading animation.
      break;
    default:
      break;
  }
};
const checkoutApp = new AMSCashierPayment({
  environment: "sandbox",
  locale: "en_US",
  onLog: ({ code, message }) => {},
  onEventCallback: onEventCallback,
});
// Handle payment button events.
document.querySelector("#your form id").addEventListener("submit", handleSubmit);

async function handleSubmit() {
  // Step 2: The server calls createPaymentSession API to obtain paymentSessionData.
  async function getPaymentSessionData() {
    const url = "Fill in the server address";
    const config = {
      // Fill in the request configuration.
    };
    const response = await fetch(url, config);
    // Obtain the value of the paymentSessionData parameter in the response.
    const { paymentSessionData } = await response.json();
    return paymentSessionData;
  }
  const paymentSessionData = await getPaymentSessionData();

  // Step 3: Create rendering components.
  // Best practice
  await checkoutApp.createComponent({
    sessionData: paymentSessionData,
    appearance: {
      showLoading: true, // Set as true by default to enable the default loading pattern.
    },
  });
}
CDN
// Step 1: Instantiate the SDK and handle the callback event.
const onEventCallback = function ({ code, result }) {
  switch (code) {
    case "SDK_PAYMENT_SUCCESSFUL":
      // Payment was successful. Redirect users to the payment result page.
      break;
    case "SDK_PAYMENT_PROCESSING":
      console.log("Check the payment result data", result);
      // Payment is being processed. Query the payment status through the server or wait for the payment result notification. At the same time, you can check whether the user has completed the payment. If the payment is not completed, guide the user to pay again.
      break;
    case "SDK_PAYMENT_FAIL":
      console.log("Check the payment result data", result);
      // Payment failed. Please refer to the processing suggestions in the Event codes and guide the user to pay again.
      break;
    case "SDK_PAYMENT_CANCEL":
      // The user exits the payment page without submitting the order. You can re-invoke the SDK with paymentSessionData that is still valid. If it has expired, you need to re-request paymentSessionData.
      break;
    case "SDK_PAYMENT_ERROR":
      console.log("Check the payment result data", result);
      // The payment status is abnormal. Query the payment status through the server or wait for the payment result notification, or guide the user to pay again.
      break;
    case "SDK_END_OF_LOADING":
      // End the custom loading animation.
      break;
    default:
      break;
  }
};
const checkoutApp = new window.AMSCashierPayment({
  environment: "sandbox",
  locale: "en_US",
  onLog: ({ code, message }) => {},
  onEventCallback: onEventCallback,
});
// Handle payment button events.
document.querySelector("#your form id").addEventListener("submit", handleSubmit);

async function handleSubmit() {
  // Step 2: The server calls createPaymentSession API to obtain paymentSessionData.
  async function getPaymentSessionData() {
    const url = "Fill in the server address";
    const config = {
      // Fill in the request configuration.
    };
    const response = await fetch(url, config);
    // Obtain the value of the paymentSessionData parameter in the response.
    const { paymentSessionData } = await response.json();
    return paymentSessionData;
  }
  const paymentSessionData = await getPaymentSessionData();

  // Step 3: Create rendering components.
  // Best practice
  await checkoutApp.createComponent({
    sessionData: paymentSessionData,
    appearance: {
      showLoading: true, // Set as true by default to enable the default loading pattern.
    },
  });
}
Android
The following sample code shows how to Integrate the client SDK on an Android device.
AMSCashierPaymentConfiguration configuration = new AMSCashierPaymentConfiguration();
configuration.setLocale(new Locale("en", "US"));
// When the showLoading parameter is set to true (default value), use the internal loading page. When false, the merchant can customize the loading animation through the event in onPaymentEventCallback.
configuration.setOption("showLoading", "true");
// Set the sandbox environment instead of the online production environment.
configuration.setOption("sandbox", "true");
// Configure whether the payment button is rendered by the SDK component.
configuration.setOption("showSubmitButton", "true");
// Set up checkout callback monitoring.
configuration.setOnCheckoutListener(
  new OnCheckoutListener() {
    @Override
    public void onEventCallback(String eventCode, AMSEventResult eventResult) {
      Log.e(
        TAG,
        "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString()
      );

      if (!TextUtils.isEmpty(eventCode)) {
        if ("SDK_PAYMENT_SUCCESSFUL".equals(eventCode)) {
          // Payment was successful. Suggest redirecting to the payment result page.
        } else if ("SDK_PAYMENT_PROCESSING".equals(eventCode)) {
          // Payment is being processed. We suggest that your server check the payment status or wait for the payment result notification.
        } else if ("SDK_PAYMENT_FAIL".equals(eventCode)) {
          // Payment failed. We suggest that you follow the paymentResultCode error code prompt and guide the user to pay it again.
        } else if ("SDK_PAYMENT_CANCEL".equals(eventCode)) {
          // The buyer did not click to pay and closed the payment window. The SDK can be re-called with paymentSessionData within the validity period. If it has expired, paymentSessionData needs to be requested again.
        } else if ("SDK_PAYMENT_ERROR".equals(eventCode)) {
          // The payment status was abnormal. We suggest that your server check the payment status or wait for the payment result notification.
        }
      }
    }
  }
);
// Create the AMSCashierPayment instantiation.
AMSCashierPayment checkout = new AMSCashierPayment.Builder(activity, configuration).build();

checkout.mountComponent(activity, sessionData);

checkout.onDestroy();
iOS
The following sample code shows how to Integrate the client SDK on an iOS device.
#import <AMSComponent/AMSComponent-Swift.h>

AMSCashierPaymentConfiguration *componentConfig = [AMSCashierPaymentConfiguration new];
componentConfig.locale = @"en_US";
// Set sandbox environment instead of online production environment
NSDictionary *options = @{@"showLoading": @"true", @"sandbox": @"true"};
componentConfig.options = options;

[[AMSCashierPayment shared] initConfiguration:componentConfig];

[AMSCashierPayment shared].paymentDelegate = self;
[AMSCashierPayment shared].loggerDelegate = self;
[[AMSCashierPayment shared] createComponent:paymentSessionData];

NSString *dataString = @"{"billingAddress":{"zipCode":"310000","region":"CN"}}";
[[AMSCashierPayment shared] submit: dataString];

#pragma AMSPaymentProtocol
- (void)onEventCallback:(NSString *)eventCode eventResult:(AMSEventResult *)eventResult
{
    if ([eventCode isEqualToString:@"SDK_PAYMENT_SUCCESSFUL"]) {
        // Payment was successful. Suggest redirecting to the payment result page.
    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_PROCESSING"]) {
        // Payment is being processed. It is recommended that your server check the payment status or wait for the payment result notification.

    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_FAIL"]) {
        // Payment failed. We suggest that you follow the paymentResultCode error code prompt and guide the user to pay it again.

    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_CANCEL"]) {
        // The buyer did not click to pay and closed the payment window. The SDK can be re-called with paymentSessionData within the validity period. If it has expired, paymentSessionData needs to be requested again.

    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_ERROR"]) {
        // The payment status was abnormal. It is recommended that your server check the payment status or wait for the payment result notification.
    }
    NSLog(@"eventCode%@ eventResult%@", eventCode, eventResult);
}

#pragma AMSLogProtocol
- (void)logWithName:(NSString *)name parameter:(NSDictionary<NSString *,id> *)parameter
{
   NSLog(@"name%@ parameter%@", name, parameter);
}