参考信息

2024-04-03 06:22

回调函数事件码

回调函数事件码在不同时机通过不同回调函数返回，主要包括以下三种：

状态码

在组件运行生命周期内，通过 onEventCallback 回调函数返回，可根据具体事件进行后续处理。

SDK_START_OF_LOADING：配置 showLoading 为 false 时，使用自定义动画，您可在这个时机渲染并展示自定义加载动画。
SDK_END_OF_LOADING：配置 showLoading 为 false 时，使用自定义动画，您可在这个时机结束自定义加载动画。
SDK_PAYMENT_CANCEL：表示用户取消支付，即用户未提交订单退出支付页面。可使用有效期内的 paymentSessionData 重新调用 SDK。如已过期，需要重新发起 支付会话创建 请求。
SDK_CALL_URL_SUCCESS：跳转支付方式/商户页面成功。
SDK_CALL_URL_ERROR：此事件码代表以下事件信息中的一种情况：

跳转商户页面失败。
跳转支付方式 App 或页面失败。
调用 支付会话创建 请求时 paymentRedirectUrl 参数未传入或未正确传入。

Web/WAP 场景下通常不会出现跳转异常，如果出现异常建议您校验重定向链接。

App 场景下如果经常出现跳转异常请联系 Alipay 技术支持，排查跳转或唤端问题。

SDK_DUPLICATE_SUBMISSION_BEHAVIOR：表单重复提交。您可以设置提示，避免用户重复点击提交。
SDK_FORM_VERIFICATION_FAILED：提交表单后校验不通过。SDK 会在要素收集页面展示表单错误码，用户可以重新提交支付。

错误码

在组件初始化阶段，通过 onEventCallback 或 onError 回调函数返回，可根据具体事件进行后续处理。

SDK_INTERNAL_ERROR：SDK 内部错误。请联系 Alipay 技术支持。
SDK_CREATEPAYMENT_PARAMETER_ERROR：createComponent 函数传入参数异常。请检查参数是否正确并重新初始化组件。
SDK_INIT_PARAMETER_ERROR：AMSCashierPayment 函数传入参数异常。请检查参数是否正确并重新实例化 SDK。
SDK_CREATECOMPONENT_ERROR：组件初始化异常。请联系 Alipay 技术支持。

支付结果码

在支付流程结束时，通过 onEventCallback 回调函数返回，可根据具体事件进行后续处理。

SDK_PAYMENT_SUCCESSFUL：表示支付成功。建议您重定向到支付结果页。
SDK_PAYMENT_FAIL：表示支付失败。建议您根据 paymentResultCode 错误码提示信息进行处理，并引导重新支付。
SDK_PAYMENT_PENDING：表示支付已经完成。请等待支付结果通知。
SDK_PAYMENT_PROCESSING：表示支付处理中。建议您的服务端查询支付状态或等待支付结果通知，同时可询问用户是否完成，如果用户未完成支付，可以引导重新支付。
SDK_PAYMENT_ERROR：表示支付状态异常。建议您的服务端查询支付状态或等待支付结果通知。

支付失败或异常说明

以下表格为支付失败或异常时的支付结果信息以及对应的处理建议，您可以根据收到的支付结果码作进一步处理。

支付结果码（paymentResultCode）

支付结果信息

（paymentResultMessage）

处理建议

ACCESS_DENIED

Access is denied.

无权限，请联系 Alipay 技术支持了解具体原因。

CURRENCY_NOT_SUPPORT

The currency is not supported.

币种不支持。请联系 Alipay 技术支持了解具体原因。

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.

风控拒绝。如下情况请联系 Alipay 技术支持：

您需要申诉。
买家两周内未收到退款。

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_EXPIRY_DATE_FORMAT

The format of expiryYear or expiryMonth is wrong.

卡有效期格式错误。建议检查卡有效期的填写格式。

ISSUER_REJECTS_TRANSACTION

The issuing bank rejects the transaction.

发卡行拒绝，建议换卡重试或联系发卡行。

INVALID_MERCHANT_STATUS

The merchant status is abnormal because restrictions exist.

商户状态异常，请联系 Alipay 技术支持了解具体原因。

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.

商户 KYB 异常，请联系 Alipay 技术支持了解具体原因。

NO_PAY_OPTIONS

The currency is not supported for the transaction.

币种不支持。检查支付方式是否支持该币种，或支付方式和币种是否与合同中所签约一致。如有问题，联系技术支持了解具体原因。

ORDER_IS_CLOSED

The request you initiated has the same paymentRequestId as that of the existed transaction, which is closed.

订单关闭。请重新发起请求。

PAYMENT_AMOUNT_EXCEED_LIMIT

The payment amount is greater than the maximum amount allowed by the contract or payment method.

超过限制金额。检查支付金额是否超过限额或使用较低的金额重试。联系支付宝技术支持了解具体支付限额。

PAYMENT_COUNT_EXCEED_LIMIT

The maximum number of payments exceeds the limit that is specified by the payment method.

超过限制使用次数。联系支付宝技术支持了解具体支付限额。

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.

商户无权限。联系技术支持了解具体原因。

PROCESS_FAIL

A general business failure occurred.

支付失败。请联系 Alipay 技术支持。

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.

风控拒绝。如果买家两周内未收到退款，请联系 Alipay 技术支持。

SUSPECTED_CARD

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

风控拒绝。建议换卡重试或联系发卡行。

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.

风控拒绝。如下情况下请联系技术支持：

您需要申诉。
买家两周内未收到退款。

USER_AMOUNT_EXCEED_LIMIT

The payment amount exceeds the user payment limit.

金额超限。使用小于或等于账户可用余额的金额重新发起支付，或联系 Alipay 技术支持。

USER_BALANCE_NOT_ENOUGH

The payment cannot be completed because the user balance in the corresponding payment method is not enough.

用户余额不足。请充值或选择其它支付方式。

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).

用户 KYC 验证异常，先完成 KYC 认证。

USER_PAYMENT_VERIFICATION_FAILED

The user is restricted from payment on the payment method side.

用户验证失败。请联系 Alipay 技术支持了解具体原因。

USER_STATUS_ABNORMAL

The user status is abnormal on the payment method side.

用户状态异常。请联系 Alipay 技术支持了解具体原因。

PAYMENT_IN_PROCESS

The payment is being processed.

支付处理中。

UNKNOWN_EXCEPTION

An API call has failed, which is caused by unknown reasons.

未知异常。请联系 Alipay 技术支持了解具体原因。

CARD_NOT_SUPPORTED

The card used for the transaction is not supported.

卡不支持。请换卡重试。

INVALID_EXPIRATION_DATE

The value of paymentMethod.paymentMethodMetaData.expiryYear or paymentMethod.paymentMethodMetaData.expiryDate is invalid.

卡的有效期不正确。建议检查卡有效期是否填写及是否填写正确。

INVALID_CARD_NUMBER

The number of the card used for the transaction is invalid.

卡号不正确。建议换卡重试。如重试后还有问题，请联系 Alipay 技术支持了解具体原因。

集成关键步骤代码示例

以下代码示例展示了集成过程中的关键步骤。代码中不包括调用 支付会话创建 接口的步骤示例，需要您自行处理服务端接口的调用。

npm 引包方式代码示例

copy
13:57import { AMSCashierPayment } from "@alipay/ams-checkout";
// 步骤一：实例化SDK，并处理好事件回调
const onEventCallback = function({ code, result }) {
  switch (code) {
    case 'SDK_PAYMENT_SUCCESSFUL':
      // 支付成功。建议您重定向到支付结果页。
      break;
    case 'SDK_PAYMENT_PROCESSING':
      console.log('可检查支付结果数据', result);
      // 支付处理中。建议您通过服务端查询支付状态或等待支付结果通知，同时可询问用户是否完成，如果未完成，可以引导用户重新支付。
      break;
    case 'SDK_PAYMENT_FAIL':
      console.log('可检查支付结果数据', result);
      // 支付失败。建议您查阅文末参考信息服务端事件码表格中的处理建议，并引导用户重新支付。
      break;
    case 'SDK_PAYMENT_CANCEL':
      // 用户在未提交订单状态下退出支付页面。可以用在有效期内的 paymentSessionData 重新调用SDK。如已过期，需要重新请求 paymentSessionData。
      break;
    case 'SDK_PAYMENT_ERROR':
      console.log('可检查支付结果数据', result);
      // 支付状态异常。建议您通过服务端查询支付状态或等待支付结果通知，或引导用户重新支付。
      break;
    case 'SDK_END_OF_LOADING':
      // 建议您结束自定义加载动画
      break;
    default:
      break;
  }
}
const checkoutApp = new AMSCashierPayment({
  environment: "sandbox",
  locale: "en_US",
  onLog: ({code, message}) => {},
  onEventCallback: onEventCallback,
});
// 处理卡支付按钮事件
document
  .querySelector("#你的表单id")
  .addEventListener("submit", handleSubmit);

async function handleSubmit() {
  // 步骤二：服务端调用支付会话创建接口，获取paymentSessionData
  async function getPaymentSessionData() {
    const url = "填写服务端地址";
    const config = {
      // 填写请求配置
    };
    const response = await fetch(url, config);
    // 获取响应中的paymentSessionData参数值
    const { paymentSessionData } = await response.json();
    return paymentSessionData;
  }
  const paymentSessionData = await getPaymentSessionData();

  // 步骤三：创建渲染卡组件
  // 最佳实践
  await checkoutApp.createComponent({ 
    sessionData: paymentSessionData, 
    appearance:{
      showLoading: true, // 默认为true，表示展示初始化加载动画
    },
  });
}

CDN 引包方式代码示例

copy
// 步骤一：实例化SDK，并处理好事件回调
const onEventCallback = function({ code, result }) {
    switch (code) {
      case 'SDK_PAYMENT_SUCCESSFUL':
        // 支付成功。建议您重定向到支付结果页。
        break;
      case 'SDK_PAYMENT_PROCESSING':
        console.log('可检查支付结果数据', result);
        // 支付处理中。建议您通过服务端查询支付状态或等待支付结果通知，同时可询问用户是否完成，如果未完成，可以引导用户重新支付。
        break;
      case 'SDK_PAYMENT_FAIL':
        console.log('可检查支付结果数据', result);
        // 支付失败。建议您查阅文末参考信息服务端事件码表格中的处理建议，并引导用户重新支付。
        break;
      case 'SDK_PAYMENT_CANCEL':
        // 用户在未提交订单状态下退出支付页面。可以用在有效期内的 paymentSessionData 重新调用SDK。如已过期，需要重新请求 paymentSessionData。
        break;
      case 'SDK_PAYMENT_ERROR':
        console.log('可检查支付结果数据', result);
        // 支付状态异常。建议您通过服务端查询支付状态或等待支付结果通知，或引导用户重新支付。
        break;
      case 'SDK_END_OF_LOADING':
        // 建议您结束自定义加载动画
        break;
      default:
        break;
    }
  }
  const checkoutApp = new window.AMSCashierPayment({
    environment: "sandbox",
    locale: "en_US",
    onLog: ({code, message}) => {},
    onEventCallback: onEventCallback,
  });
  // 处理卡支付按钮事件
  document
    .querySelector("#你的表单id")
    .addEventListener("submit", handleSubmit);
  
  async function handleSubmit() {
    // 步骤二：服务端调用支付会话创建接口，获取paymentSessionData
    async function getPaymentSessionData() {
      const url = "填写服务端地址";
      const config = {
        // 填写请求配置
      };
      const response = await fetch(url, config);
      // 获取响应中的paymentSessionData参数值
      const { paymentSessionData } = await response.json();
      return paymentSessionData;
    }
    const paymentSessionData = await getPaymentSessionData();
  
    // 步骤三：创建渲染卡组件
    // 最佳实践
    await checkoutApp.createComponent({ 
      sessionData: paymentSessionData, 
      appearance:{
        showLoading: true, // 默认为true，表示展示默认加载动画
      }, 
    });
  }