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

References

Callback event codes

Callback event codes are returned through different callback functions at different times, mainly including the following three types:

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_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 3D challenge 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. It is recommended that you verify the redirected link. In the app scenario, if this exception frequently occurs, contact Alipay technical support to troubleshoot redirection or calling issues.

  • SDK_CALL_URL_SUCCESS: The merchant page is successful.
  • 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 Ant Group technical support.
  • SDK_CREATEPAYMENT_PARAMETER_ERROR: mountComponent 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 Ant Group technical support.
  • SDK_SUBMIT_NETWORK_ERROR: Interface 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_PROCESSING: Payment is being processed. It is recommended that your server check the payment status or wait for the payment result notification.
  • SDK_Payment_FAIL: Payment failed. We suggest that you follow the paymentResultCode error code prompt and guide the user to pay it again.
  • SDK_PAYMENT_ERROR: The payment status is abnormal. It is recommended that your server check the payment status or wait for the payment result notification.

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 technical support for specific reasons.

CURRENCY_NOT_SUPPORT

The currency is not supported.

Currency is not supported. Contact 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 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.

Invalid card. Suggest changing the card and trying again.

INVALID_EXPIRY_DATE_FORMAT

The format of expiryYear or expiryMonth is wrong.

The card's expiration date is incorrect. Suggest checking the format of filling in the card validity period.

ISSUER_REJECTS_TRANSACTION

The issuing bank rejects the transaction.

The issuing bank refused. Suggest changing the card and trying again or contacting the issuing bank.

INVALID_MERCHANT_STATUS

The merchant status is abnormal because restrictions exist.

Merchant status is abnormal. Contact 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 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 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 Alipay 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 Alipay 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 technical support for specific reasons.

PROCESS_FAIL

A general business failure occurred.

Payment failed. This usually requires manual confirmation of the issue. We suggest that you contact Alipay 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 Alipay technical support.

SUSPECTED_CARD

The card is suspected of fraud. For example, the card is stolen or restricted.

Risk control refused. Suggest changing the card and trying again or contacting 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 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 Alipay 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 technical support for specific reasons.

USER_STATUS_ABNORMAL

The user status is abnormal on the payment method side.

The user status is abnormal. Contact 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 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. Suggest checking 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. Suggest changing the card and trying again. If there are still problems after trying again, contact technical support for the specific reason.

Code examples of integration key steps

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 interface yourself.

Integrate the SDK package using npm

copy
import { AMSCashierPayment } from "@alipay/ams-checkout";
// Step 1: Instantiate the SDK and handle the callback event.
const onEventCallback = function({ code, result }) {
  switch (code) {
    case code:
      'SDK_PAYMENT_SUCCESSFUL';
      // Payment was successful. Redirect users to the payment result page.
      break;
    case code:
      'SDK_PAYMENT_PROCESSING';
      console.log('Check the payment result data', result);
      // Payment was being processed. Guide users to retry the payment based on the provided information.
      break;
    case code:
      'SDK_PAYMENT_FAIL';
      console.log('Check the payment result data', result);
      // Payment failed. Guide users to retry the payment based on the provided information.
      break;
    case code:
      'SDK_PAYMENT_CANCEL';
      // Guide the user to retry the payment.
      break;
    case code:
      'SDK_PAYMENT_ERROR';
      console.log('Check the payment result data', result);
      // The payment status was abnormal. Guide users to retry the payment based on the provided information.
      break;
    case code:
      '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.
    },
  });
}

Integrate the SDK package CDN resources

copy
// Step 1: Instantiate the SDK and handle the callback event.
const onEventCallback = function({ code, result }) {
  switch (code) {
    case code:
      'SDK_PAYMENT_SUCCESSFUL';
      // Payment was successful. Redirect users to the payment result page.
      break;
    case code:
      'SDK_PAYMENT_PROCESSING';
      console.log('Check the payment result data', result);
      // Payment was being processed. Guide users to retry the payment based on the provided information.
      break;
    case code:
      'SDK_PAYMENT_FAIL';
      console.log('Check the payment result data', result);
      // Payment failed. Guide users to retry the payment based on the provided information.
      break;
    case code:
      'SDK_PAYMENT_CANCEL';
      // Guide the user to retry the payment.
      break;
    case code:
      'SDK_PAYMENT_ERROR';
      console.log('Check the payment result data', result);
      // The payment status was abnormal. Guide users to retry the payment based on the provided information.
      break;
    case code:
      '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.
    }, 
  });
}