APM 支付

2026-03-17 18:06

下架通知：

本指南内容已停止更新。
建议您采用 Payment Element 集成方式，以获得更优的集成体验。

Antom SDK 是一个预构建的用户界面组件，简化了集成 Antom 支付服务的过程。此组件提供了一种简单快捷的方式来集成 Antom 支持的所有支付方式，包括信用卡、电子钱包、银行转账、网上银行等。

SDK 组件可以自动适应买家的设备和位置，根据支付方式的特性执行信息收集、重定向、应用切换、展示二维码等任务。您可以在您的网站或应用上轻松提供全面的支付解决方案，节省构建每个支付界面和流程所需的时间和资源。

Web/WAP

iOS

Android

用户体验

以下图表展示了在购物网站或移动网页应用上支付的用户流程：

Web

WAP

支付流程

每种支付方式的支付流程包括以下步骤：

买家进入结账页面。
创建支付会话请求。
买家选择支付方式并提交订单后，您可以通过调用 createPaymentSession（单笔支付）接口获取支付会话。
调用客户端 SDK。
在客户端，通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码展示、验证等流程。随后，SDK 将通过
onEventCallback
回调支付结果，或者跳转到您的支付结果页面。
确认支付结果。
通过以下两种方法之一获取支付结果：

异步通知：在 createPaymentSession（单笔支付）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付成功或过期时，Antom 会使用 notifyPayment 向您发送异步通知。
同步查询：调用 inquiryPayment 接口来查询支付状态。

集成准备

在您开始集成前，请阅读集成指南及接口概述文档，了解服务端接口的集成步骤及调用接口的注意事项，并确保已完成以下预配置：

已获得 client ID。
已完成密钥配置。
已完成异步通知接收地址的配置。
集成 Antom 服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
参阅 Web/WAP 端集成 SDK 资源包文档来集成客户端 SDK 资源包。

集成步骤

请按照以下步骤开始集成：

创建支付会话
创建并调用 SDK
获取支付结果

步骤 1：创建支付会话
服务端

当买家选择 Antom 提供的支付方式时，您需要收集关键信息，如支付请求 ID、订单金额、支付方式、订单描述、支付重定向链接和支付结果通知链接，调用 createPaymentSession（单笔支付）接口来创建支付会话，并将支付会话返回给客户端。

创建支付会话包含以下参数：

以上参数是创建支付会话的基本参数，完整参数和特定支付方式的额外要求请参考 createPaymentSession（单笔支付）。

以下示例代码展示了如何调用 createPaymentSession（单笔支付）接口：

private static void createPaymentSession() {
  AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
  alipayPaymentSessionRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

  // 替换为您的 paymentRequestId 
  String paymentRequestId = UUID.randomUUID().toString();
  alipayPaymentSessionRequest.setPaymentRequestId(paymentRequestId);

  // 设置金额 
  Amount amount = Amount.builder().currency("SGD").value("4200").build();
  alipayPaymentSessionRequest.setPaymentAmount(amount);

  // 设置支付方式 
  PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("SHOPEEPAY_SG").build();
  alipayPaymentSessionRequest.setPaymentMethod(paymentMethod);

  // 替换为您的 orderId  
  String orderId = UUID.randomUUID().toString();

  // 设置买家信息
  Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

  // 设置订单信息
  Order order = Order.builder().referenceOrderId(orderId)
      .orderDescription("antom testing order").orderAmount(amount).buyer(buyer).build();
  alipayPaymentSessionRequest.setOrder(order);

  // 替换为您的通知地址
  alipayPaymentSessionRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");

  // 替换为您的跳转地址
  alipayPaymentSessionRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

  AlipayPaymentSessionResponse alipayPaymentSessionResponse = null;
  try {
      alipayPaymentSessionResponse = CLIENT.execute(alipayPaymentSessionRequest);
  } catch (AlipayApiException e) {
      String errorMsg = e.getMessage();
      // 处理错误情况
  }
}

以下代码展示了一个请求报文的示例：

{
"order": {
  "buyer": {
    "referenceBuyerId": "yourBuyerId"
  },
  "orderAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "orderDescription": "antom testing order",
  "referenceOrderId": "referenceOrderId01"
},
"paymentAmount": {
  "currency": "SGD",
  "value": "4200"
},
"paymentMethod": {
  "paymentMethodType": "SHOPEEPAY_SG"
},
"paymentNotifyUrl": "https://www.yourNotifyUrl.com",
"paymentRedirectUrl": "https://www.yourMerchantWeb.com",
"paymentRequestId": "paymentRequestId01",
"productCode": "CASHIER_PAYMENT"
}

以下代码展示了一个响应的示例，其中包含以下参数：

paymentSessionData：将返回给前端的支付会话数据。
paymentSessionExpiryTime：支付会话的过期时间。

{
"paymentSessionData": "gM5Y/Go6+IXMPSOZrYtukCdodtwxuSFsn1vRPSB8CzkDqlb1g2W7dDipOkoMRs/x2W7g7qVhjEM7RUGroIT8Cw==&&SG&&188&&eyJhY3Rpb24iOnsiYXBwIjp7fSwibmVlZFZlcmlmeUFuZFJlc3VtZSI6ZmFsc2UsInNraXBTZGtRdWVyeSI6ZmFsc2UsIndhcCI6e30sIndlYiI6e319LCJjbGllbnRJZCI6IlNBTkRCT1hfNVlCWjBMMlpIUjhSMDg5NzgiLCJleHRlbmRJbmZvIjoie1widmVyc2lvbk1hcFwiOntcIndlYlwiOntcIjEuMS4wXCI6e1widGFyZ2V0V2ViVmVyaXNvblwiOlwiMS4xLjBcIn0sXCIxLjIuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMi4wXCJ9fSxcImlPU1wiOntcIjEuMS4wXCI6e1widGFyZ2V0V2ViVmVyaXNvblwiOlwiMS4xLjBcIn0sXCIxLjIuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMi4wXCJ9fSxcIkFuZHJvaWRcIjp7XCIxLjEuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMS4wXCJ9LFwiMS4yLjBcIjp7XCJ0YXJnZXRXZWJWZXJpc29uXCI6XCIxLjIuMFwifX19fSIsInBheW1lbnRTZXNzaW9uQ29uZmlnIjp7InBheW1lbnRNZXRob2RDYXRlZ29yeVR5cGUiOiJBUE0iLCJwcm9kdWN0U2NlbmUiOiJDQVNISUVSX1BBWU1FTlQiLCJwcm9kdWN0U2NlbmVWZXJzaW9uIjoiMS4wIn19",
"paymentSessionExpiryTime": "2024-01-01T00:00:00+08:00",
"paymentSessionId": "gM5Y/Go6+IXMPSOZrYtukCdodtwxuSFsn1vRPSB8Czn6HfgqNzo2ogbIk1NUQS35",
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success.",
  "resultStatus": "S"
}
}

常见问题

问：请求参数的值可以使用中文字符吗？

答：为了避免特定支付方式的兼容性问题，请求中的字段请勿使用中文字符。

问：如何设置接收支付通知的地址？

答：在 createPaymentSession（单笔支付）接口中指定 paymentNotifyUrl 字段，以接收支付结果的异步通知（notifyPayment），或者在 Antom Dashboard 中配置接收地址。如果请求和 Antom Dashboard 中都指定了地址，请求中的值优先。

步骤 2：创建并调用 SDK
客户端

Antom SDK 是用于处理支付流程的组件。为了收集信息、在应用间切换以及根据 createPaymentSession（单笔支付）接口中指定的支付方式展示二维码，您需要通过创建支付会话来启动 SDK。

买家在页面上选择支付方式后，您需要创建并使用支付会话初始化 SDK。

1.（可选）预加载 SDK

在创建支付会话前，强烈建议您预加载 SDK，以提升收银台页面的渲染速度，减少买家在支付过程中的等待时间。按照以下代码示例执行预加载操作：

// import { AMSCashierPayment } from '@alipay/ams-checkout';

AMSCashierPayment.preload();

2. 初始化 SDK

通过使用

AMSCashierPayment

并指定基础配置来创建 SDK 实例。配置对象包括以下参数：

以下示例代码展示了如何实例化 SDK：

// import { AMSCashierPayment } from '@alipay/ams-checkout'

const checkoutApp = new window.AMSCashierPayment({
environment: "sandbox",
locale: "en_US",
onLog: ({code, message}) => {},
onEventCallback: ({code, message}) => {},
});

// 请求服务器以获取 paymentSessionData

注意：每个实例只能处理一个支付会话。建议在每次调用

createComponent

之前先创建实例。

3. 调用 SDK

使用实例对象中的

createComponent

函数来创建支付组件：

以下示例代码展示了如何调用

createComponent

：

async function create(sessionData) {
await checkoutApp.createComponent({ 
  sessionData: sessionData,
});
}

在以下情况下调用

unmount

方法以释放 SDK 组件资源：

当买家切换视图离开支付页面时，释放 createPaymentSession（单笔支付）中创建的组件资源。
当买家发起多次支付时，释放之前 createPaymentSession（单笔支付）中创建的组件资源。
当买家完成支付并设置 notRedirectAfterComplete 为
true
时，获取特定支付结果代码释放组件资源。

// 释放 SDK 组件资源
checkoutApp.unmount();

常见问题

问：遇到 SDK_CREATEPAYMENT_PARAMETER_ERROR 时该怎么办？

答：收到此事件码时，请检查传递的 sessionData 是否正确且完整。

问：遇到 SDK_PAYMENT_ERROR 或渲染视图错误时该怎么办？

答：检查接口初始化时的网络请求是否出现异常，如网络超时。确保创建支付会话请求的环境与 SDK 实例化时的环境一致。检查 createPaymentSession（单笔支付）接口中的参数传递是否正确。如果接口异常持续存在，请联系我们进行进一步的故障排除。

4. 展示支付结果

您可以使用支付组件处理需要重定向的支付方式（异步支付）和不需要的重定向的支付方式（同步支付）。

重定向支付

某些支付方式的支付过程需要离开原网页，跳转到机构页面完成支付，例如网银支付。在这种情况下，买家在完成支付后会被重定向到您在 createPaymentSession（单笔支付）接口中提供的 paymentRedirectUrl。您可以通过主动查询获取支付结果，并在该 URL 中将结果展示给买家。

非重定向支付

对于无需重定向的支付，支付结果将通过

onEventCallback

函数给出。这里的支付结果仅用于前端展示，最终订单状态以服务器端为准。您需要通过

onEventCallback

返回的数据自定义每个支付结果的处理流程。

以下是可能由

onEventCallback

返回的支付结果的事件码。

以下示例代码展示了如何处理

onEventCallback

：

function onEventCallback({ code, result }) {
switch (code) {
  case 'SDK_PAYMENT_SUCCESSFUL':
    // 支付成功，建议将买家重定向到支付结果页面，随后与服务器确认支付结果。
    break;
  case 'SDK_PAYMENT_PROCESSING':
    console.log('Check the payment result data', result);
    // 支付正在处理中，建议与服务器确认支付结果。如果支付成功，将买家重定向到支付结果页面；如果支付失败，引导买家重新尝试支付。
    break;
  case 'SDK_PAYMENT_FAIL':
    console.log('Check the payment result data', result);
    // 支付失败，建议您检查在 onEventCallback 结果数据中 result.paymentResultCode 的值以获取详细信息。根据获得的信息，引导买家重新尝试支付。
    break;
  case 'SDK_PAYMENT_CANCEL':
    // 支付被取消。建议使用在有效期内的 paymentSessionData 重新调用 SDK；如果已过期，则需要重新请求 paymentSessionData。
    break;
  case 'SDK_PAYMENT_ERROR':
    console.log('Check the payment result data', result);
    // 支付状态异常，建议与服务器确认支付结果。如果确认支付失败，引导买家重新尝试支付。
    break;
  default:
    break;
}
}

步骤 3：获取支付结果
服务端

在买家完成支付或支付超时后，Antom 会通过服务器交互将相应的支付结果发送给您，您可以通过以下方法之一获取支付结果：

接收异步通知
查询结果

接收异步通知

当支付成功或失败时，Antom 会向您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定的地址发送异步通知（notifyPayment）。收到 Antom 的通知后，您需要按照返回收到确认信息的格式返回响应。

Antom 允许您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定链接。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。

以下代码展示了通知请求的示例：

{
"notifyType": "PAYMENT_RESULT",
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "success"
},
"paymentRequestId": "paymentRequestId01",
"paymentId": "20240101123456789XXXX",
"paymentAmount": {
  "value": "4200",
  "currency": "SGD"
},
"paymentCreateTime": "2024-01-01T00:00:00+08:00",
"paymentTime": "2024-01-01T00:01:00+08:00"
}

如何验证通知的签名并做出响应，请参阅签名和验签。

常见问题

问：何时会发送通知？

答：这取决于支付是否完成：

如果支付成功完成，Antom 通常会在 3 到 5 秒内发送异步通知。对于某些支付方式，如现金支付，通知可能会稍有延迟。
如果支付未完成，Antom 需要先关闭订单，然后发送异步通知。不同支付方式关闭订单所需的时间会有所不同，通常默认为 14 分钟。

问：异步通知会被重新发送吗？

答：是的，对于以下情况，异步通知会在 24 小时内自动重新发送：

如果由于网络原因未收到异步通知。
如果您收到来自 Antom 的异步通知，但您没有按照处理通知的示例代码格式对通知做出响应。

通知最多可以重发 8 次，或者直到收到正确的响应以终止发送。发送间隔如下：0 分钟，2 分钟，10 分钟，10 分钟，1 小时，2 小时，6 小时，15 小时。

问：在响应异步通知时，我需要添加数字签名吗？

答：如果您收到来自 Antom 的异步通知，您需要按照处理通知的示例代码格式返回响应，但不需要对响应进行签名。

问：我在通知中需要使用哪些关键参数？

答：请注意以下关键参数：

result：表示订单的支付结果。
paymentRequestId：用于咨询、取消和对账的支付请求 ID。
paymentId：表示由 Antom 生成的支付订单 ID，用于退款和对账。
paymentAmount：表示支付金额。

查询结果

您可以调用 inquiryPayment 接口来发起对订单结果的查询。

完整的参数集，请参考 inquiryPayment 接口文档，获取全部参数及特定支付方式的额外要求。

以下示例代码展示了如何调用 inquiryPayment 接口：

public static void inquiryPayment() {
  AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();

  // 替换为您的 paymentRequestId
  alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");

  AlipayPayQueryResponse alipayPayQueryResponse = null;
  try {
      alipayPayQueryResponse = CLIENT.execute(alipayPayQueryRequest);
  } catch (AlipayApiException e) {
      String errorMsg = e.getMessage();
      // 处理错误情况
  }
}

以下代码展示了请求报文的示例：

{
"paymentRequestId": "paymentRequestId01"
}

以下代码展示了响应报文的示例：

{
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "Success"
},
"paymentStatus": "SUCCESS",
"paymentRequestId": "paymentRequestId01",
"paymentId": "20240101123456789XXXX",
"paymentAmount": {
  "value": "4200",
  "currency": "SGD"
},
"paymentCreateTime": "2024-01-01T00:00:00+08:00",
"paymentTime": "2024-01-01T00:01:00+08:00",
"paymentMethodType": "SHOPEEPAY_SG"
}

常见问题

问：我应该多久调用一次 inquiryPayment 接口？

答：以 2 秒的间隔持续调用 inquiryPayment 接口，直到获取最终的支付结果或收到异步支付结果通知为止。

问：我在通知中需要使用哪些关键参数？

答：请注意以下关键参数：

result：表示此 inquiryPayment 接口调用的结果，需要根据 paymentStatus 来判断订单状态：

SUCCESS
和
FAIL
表示最终结果。
PROCESSING
表示处理中。

paymentAmount：表示支付的金额。

示例代码

前端完整示例代码：

import { AMSCashierPayment } from '@alipay/ams-checkout'

//（可选）预加载 SDK。在创建支付会话前预加载 SDK，以提升收银台页面的渲染速度，减少买家在支付过程中的等待时间。
AMSCashierPayment.preload();

// 监听收银台提交事件。
document
.querySelector("button#submit")
.addEventListener("click", handleSubmit);

async function handleSubmit() {

// 步骤一：从您的服务端获取支付会话。
const paymentSessionData = await getPaymentSessionData();


// 步骤二：创建并调用 SDK。
// 创建一个 AMSCashierPayment 实例。
const checkoutApp = new window.AMSCashierPayment({
  environment: "sandbox",
  locale: "en_US",
  onLog: ({code, message}) => {},
  onEventCallback: onEventCallback,
});


// 通过调用 createComponent 方法来展示结账界面。
await checkoutApp.createComponent({ 
  sessionData: paymentSessionData,
});
}

// 处理支付结果。
const onEventCallback = function({ code, result }) {
switch (code) {
  case 'SDK_PAYMENT_SUCCESSFUL':
     // 支付成功，建议将买家重定向到支付结果页面，随后与服务器确认支付结果。
    break;
  case 'SDK_PAYMENT_PROCESSING':
    console.log('Check the payment result data', result);
    // 支付正在处理中，建议与服务器确认支付结果。如果支付成功，将买家重定向到支付结果页面；如果支付失败，引导买家重新尝试支付。
    break;
  case 'SDK_PAYMENT_FAIL':
    console.log('Check the payment result data', result);
    // 支付失败，建议您检查在 onEventCallback 结果数据中 result.paymentResultCode 的值以获取详细信息。根据获得的信息，引导买家重新尝试支付。
    break;
  case 'SDK_PAYMENT_CANCEL':
    // 支付被取消。建议使用在有效期内的 paymentSessionData 重新调用SDK；如果已过期，则需要重新请求 paymentSessionData。
    break;
  case 'SDK_PAYMENT_ERROR':
    console.log('Check the payment result data', result);
    // 支付状态异常，建议与服务器确认支付结果。如果确认支付失败，引导买家重新尝试支付。
    break;
  case 'SDK_FORM_VERIFICATION_FAILED':
    // 表单提交后，验证失败。建议引导买家确认输入并重新尝试支付。
    break;
  default:
    break;
}
}

事件码

状态码：在组件运行生命周期内，通过

onEventCallback

回调函数返回。

用户体验

以下图表展示了在购物网站或移动网页应用上支付的用户流程：

支付流程

每种支付方式的支付流程包括以下步骤：

买家进入结账页面。
创建支付会话请求。
买家选择支付方式并提交订单后，您可以通过调用 createPaymentSession（单笔支付）接口获取支付会话。
调用客户端 SDK。
在客户端，通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码展示、验证等流程。随后，SDK 将通过
onEventCallback
回调支付结果，或者跳转到您的支付结果页面。
确认支付结果。
通过以下两种方法之一获取支付结果：

异步通知：在 createPaymentSession（单笔支付）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付成功或过期时，Antom 会使用 notifyPayment 向您发送异步通知。
同步查询：调用 inquiryPayment 接口来查询支付状态。

集成准备

在您开始集成前，请阅读集成指南及接口概述文档，了解服务端接口的集成步骤及调用接口的注意事项，并确保已完成以下预配置：

已获得 client ID。
已完成密钥配置。
已完成异步通知接收地址的配置。
集成 Antom 服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
参阅 iOS 端集成 SDK 资源包文档来集成客户端 SDK 资源包。

注意：暂不支持 ‌Flutter 和 React Native（RN）开发框架。

集成步骤

请按照以下步骤开始集成：

创建支付会话
创建并调用 SDK
获取支付结果

步骤 1：创建支付会话
服务端

创建支付会话包含以下参数：

以上参数是创建支付会话的基本参数，完整参数和特定支付方式的额外要求请参考 createPaymentSession（单笔支付）。

以下示例代码展示了如何调用 createPaymentSession（单笔支付）接口：

private static void createPaymentSession() {
  AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
  alipayPaymentSessionRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

  // 替换为您的 paymentRequestId 
  String paymentRequestId = UUID.randomUUID().toString();
  alipayPaymentSessionRequest.setPaymentRequestId(paymentRequestId);

  // 设置金额 
  Amount amount = Amount.builder().currency("SGD").value("4200").build();
  alipayPaymentSessionRequest.setPaymentAmount(amount);

  // 设置支付方式 
  PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("SHOPEEPAY_SG").build();
  alipayPaymentSessionRequest.setPaymentMethod(paymentMethod);

  // 替换为您的 orderId  
  String orderId = UUID.randomUUID().toString();

  // 设置买家信息
  Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

  // 设置订单信息
  Order order = Order.builder().referenceOrderId(orderId)
      .orderDescription("antom testing order").orderAmount(amount).buyer(buyer).build();
  alipayPaymentSessionRequest.setOrder(order);

  // 替换为您的通知地址
  alipayPaymentSessionRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");

  // 替换为您的跳转地址
  alipayPaymentSessionRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

  AlipayPaymentSessionResponse alipayPaymentSessionResponse = null;
  try {
      alipayPaymentSessionResponse = CLIENT.execute(alipayPaymentSessionRequest);
  } catch (AlipayApiException e) {
      String errorMsg = e.getMessage();
      // 处理错误情况
  }
}

以下代码展示了一个请求报文的示例：

{
"order": {
  "buyer": {
    "referenceBuyerId": "yourBuyerId"
  },
  "orderAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "orderDescription": "antom testing order",
  "referenceOrderId": "referenceOrderId01"
},
"paymentAmount": {
  "currency": "SGD",
  "value": "4200"
},
"paymentMethod": {
  "paymentMethodType": "SHOPEEPAY_SG"
},
"paymentNotifyUrl": "https://www.yourNotifyUrl.com",
"paymentRedirectUrl": "https://www.yourMerchantWeb.com",
"paymentRequestId": "paymentRequestId01",
"productCode": "CASHIER_PAYMENT"
}

以下代码展示了一个响应的示例，其中包含以下参数：

paymentSessionData：将返回给前端的支付会话数据。
paymentSessionExpiryTime：支付会话的过期时间。

{
"paymentSessionData": "gM5Y/Go6+IXMPSOZrYtukCdodtwxuSFsn1vRPSB8CzkDqlb1g2W7dDipOkoMRs/x2W7g7qVhjEM7RUGroIT8Cw==&&SG&&188&&eyJhY3Rpb24iOnsiYXBwIjp7fSwibmVlZFZlcmlmeUFuZFJlc3VtZSI6ZmFsc2UsInNraXBTZGtRdWVyeSI6ZmFsc2UsIndhcCI6e30sIndlYiI6e319LCJjbGllbnRJZCI6IlNBTkRCT1hfNVlCWjBMMlpIUjhSMDg5NzgiLCJleHRlbmRJbmZvIjoie1widmVyc2lvbk1hcFwiOntcIndlYlwiOntcIjEuMS4wXCI6e1widGFyZ2V0V2ViVmVyaXNvblwiOlwiMS4xLjBcIn0sXCIxLjIuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMi4wXCJ9fSxcImlPU1wiOntcIjEuMS4wXCI6e1widGFyZ2V0V2ViVmVyaXNvblwiOlwiMS4xLjBcIn0sXCIxLjIuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMi4wXCJ9fSxcIkFuZHJvaWRcIjp7XCIxLjEuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMS4wXCJ9LFwiMS4yLjBcIjp7XCJ0YXJnZXRXZWJWZXJpc29uXCI6XCIxLjIuMFwifX19fSIsInBheW1lbnRTZXNzaW9uQ29uZmlnIjp7InBheW1lbnRNZXRob2RDYXRlZ29yeVR5cGUiOiJBUE0iLCJwcm9kdWN0U2NlbmUiOiJDQVNISUVSX1BBWU1FTlQiLCJwcm9kdWN0U2NlbmVWZXJzaW9uIjoiMS4wIn19",
"paymentSessionExpiryTime": "2024-01-01T00:00:00+08:00",
"paymentSessionId": "gM5Y/Go6+IXMPSOZrYtukCdodtwxuSFsn1vRPSB8Czn6HfgqNzo2ogbIk1NUQS35",
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success.",
  "resultStatus": "S"
}
}

常见问题

问：请求参数的值可以使用中文字符吗？

答：为了避免特定支付方式的兼容性问题，请求中的字段请勿使用中文字符。

问：如何设置接收支付通知的地址？

步骤 2：创建并调用 SDK
客户端

买家在页面上选择支付方式后，您需要创建并使用支付会话初始化 SDK。

1.（可选）预加载 SDK

在创建支付会话前，强烈建议您预加载 SDK，以提升收银台页面的渲染速度，减少买家在支付过程中的等待时间。按照以下代码示例执行预加载操作：

[[AMSCashierPayment shared] preload];

2. 初始化 SDK

通过使用

AMSCashierPayment

并指定基本配置来创建 SDK 实例。创建一个

AMSCashierPaymentConfiguration

对象包括以下参数：

实现

AMSPaymentProtocol

，用于处理后续流程中的相应事件。它包含以下方法：

注意：每个实例只能处理一个支付会话。建议在每次调用

createComponent

之前先创建实例。

以下示例代码展示了如何实例化 SDK：

#import <AMSComponent/AMSComponent-Swift.h>

AMSCashierPaymentConfiguration *componentConfig = [AMSCashierPaymentConfiguration new];
componentConfig.locale = @"en_US";

// 设置沙箱环境。如果将其置空，则默认使用线上正式环境。
NSDictionary *options = @{@"sandbox": @"true"};
componentConfig.options = options;

[[AMSCashierPayment shared] initConfiguration:componentConfig];

// 设置回调来监听收银台页面的支付事件。
[AMSCashierPayment shared].paymentDelegate = self;

// 服务端调用 createPaymentSession 接口以获取 paymentSessionData。

3. 调用 SDK

调用

createComponent

方法：

在以下情况调用

onDestroy

方法释放 SDK 组件资源：

当买家离开结账页面时，释放 createPaymentSession（单笔支付）中创建的组件资源。
当买家发起多次支付时，释放之前 createPaymentSession（单笔支付）中创建的组件资源。

以下示例代码展示了如何调用 SDK：

[[AMSCashierPayment shared] createComponent:sessionData];

// 释放 SDK 组件资源
[[AMSCashierPayment shared] onDestroy];

4. 展示支付结果

您可以使用支付组件处理需要重定向的支付方式（异步支付）和不需要的重定向的支付方式（同步支付）。

重定向支付

非重定向支付

对于无需重定向的支付，支付结果将通过

onEventCallback

函数给出。这里的支付结果仅用于前端展示，最终订单状态以服务器端为准。您需要通过

onEventCallback

返回的数据自定义每个支付结果的处理流程。

以下是可能由

onEventCallback

返回的支付结果的事件码。

以下示例代码展示了如何处理

onEventCallback

：

#import <AMSComponent/AMSComponent-Swift.h>


#pragma AMSPaymentProtocol
- (void)onEventCallback:(NSString *)eventCode eventResult:(AMSEventResult *)eventResult
{
  if ([eventCode isEqualToString:@"SDK_PAYMENT_SUCCESSFUL"]) {
      // 支付成功，建议将买家重定向到支付结果页面，随后与服务器确认支付结果。
  } else if ([eventCode isEqualToString:@"SDK_PAYMENT_PROCESSING"]) {
      // 支付正在处理中，建议与服务器确认支付结果。如果支付成功，将买家重定向到支付结果页面；如果支付失败，引导买家重新尝试支付。

  } else if ([eventCode isEqualToString:@"SDK_PAYMENT_FAIL"]) {
      // 支付失败，建议您检查在 onEventCallback 结果数据中 result.paymentResultCode 的值以获取详细信息。根据获得的信息，引导买家重新尝试支付。

  } else if ([eventCode isEqualToString:@"SDK_PAYMENT_CANCEL"]) {
     // 支付被取消。建议使用在有效期内的 paymentSessionData 重新调用 SDK；如果已过期，则需要重新请求 paymentSessionData。

  } else if ([eventCode isEqualToString:@"SDK_PAYMENT_ERROR"]) {
     // 支付状态异常，建议与服务器确认支付结果。如果确认支付失败，引导买家重新尝试支付。
  }
  NSLog(@"eventCode%@ eventResult%@", eventCode, eventResult);
}

步骤 3：获取支付结果
服务端

在买家完成支付或支付超时后，Antom 会通过服务器交互将相应的支付结果发送给您，您可以通过以下方法之一获取支付结果：

接收异步通知
查询结果

接收异步通知

Antom 允许您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定链接。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。

以下代码展示了通知请求的示例：

{
"notifyType": "PAYMENT_RESULT",
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "success"
},
"paymentRequestId": "paymentRequestId01",
"paymentId": "20240101123456789XXXX",
"paymentAmount": {
  "value": "4200",
  "currency": "SGD"
},
"paymentCreateTime": "2024-01-01T00:00:00+08:00",
"paymentTime": "2024-01-01T00:01:00+08:00"
}

如何验证通知的签名并做出响应，请参阅签名和验签。

常见问题

问：何时会发送通知？

答：这取决于支付是否完成：

如果支付成功完成，Antom 通常会在 3 到 5 秒内发送异步通知。对于某些支付方式，如现金支付，通知可能会稍有延迟。
如果支付未完成，Antom 需要先关闭订单，然后发送异步通知。不同支付方式关闭订单所需的时间会有所不同，通常默认为 14 分钟。

问：异步通知会被重新发送吗？

答：是的，对于以下情况，异步通知会在 24 小时内自动重新发送：

如果由于网络原因未收到异步通知。
如果您收到来自 Antom 的异步通知，但您没有按照处理通知的示例代码格式对通知做出响应。

通知最多可以重发 8 次，或者直到收到正确的响应以终止发送。发送间隔如下：0 分钟，2 分钟，10 分钟，10 分钟，1 小时，2 小时，6 小时，15 小时。

问：在响应异步通知时，我需要添加数字签名吗？

答：如果您收到来自 Antom 的异步通知，您需要按照处理通知的示例代码格式返回响应，但不需要对响应进行签名。

问：我在通知中需要使用哪些关键参数？

答：请注意以下关键参数：

result：表示订单的支付结果。
paymentRequestId：用于咨询、取消和对账的支付请求 ID。
paymentId：表示由 Antom 生成的支付订单 ID，用于退款和对账。
paymentAmount：表示支付金额。

查询结果

您可以调用 inquiryPayment 接口来发起对订单结果的查询。

完整的参数集，请参考 inquiryPayment 接口文档，获取全部参数及特定支付方式的额外要求。

以下示例代码展示了如何调用 inquiryPayment 接口：

public static void inquiryPayment() {
  AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();

  // 替换为您的 paymentRequestId
  alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");

  AlipayPayQueryResponse alipayPayQueryResponse = null;
  try {
      alipayPayQueryResponse = CLIENT.execute(alipayPayQueryRequest);
  } catch (AlipayApiException e) {
      String errorMsg = e.getMessage();
      // 处理错误情况
  }
}

以下代码展示了请求报文的示例：

{
"paymentRequestId": "paymentRequestId01"
}

以下代码展示了响应报文的示例：

{
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "Success"
},
"paymentStatus": "SUCCESS",
"paymentRequestId": "paymentRequestId01",
"paymentId": "20240101123456789XXXX",
"paymentAmount": {
  "value": "4200",
  "currency": "SGD"
},
"paymentCreateTime": "2024-01-01T00:00:00+08:00",
"paymentTime": "2024-01-01T00:01:00+08:00",
"paymentMethodType": "SHOPEEPAY_SG"
}

常见问题

问：我应该多久调用一次 inquiryPayment 接口？

答：以 2 秒的间隔持续调用 inquiryPayment 接口，直到获取最终的支付结果或收到异步支付结果通知为止。

问：我在通知中需要使用哪些关键参数？

答：请注意以下关键参数：

result：表示此 inquiryPayment 接口调用的结果，需要根据 paymentStatus 来判断订单状态：

SUCCESS
和
FAIL
表示最终结果。
PROCESSING
表示处理中。

paymentAmount：表示支付的金额。

示例代码

前端完整示例代码：

#import <AMSComponent/AMSComponent-Swift.h>

//（可选）预加载 SDK。在创建支付会话前预加载 SDK，以提升收银台页面的渲染速度，减少买家在支付过程中的等待时间。
[[AMSCashierPayment shared] preload];

// 步骤一: 从您的服务端获取 Antom PaymentSessionData。
NSString *paymentSessionData = "YOUR_PAYMENT_SESSIONDATA";

// 步骤二: 创建一个 AMSConfiguration 对象。
AMSCashierPaymentConfiguration *componentConfig = [AMSCashierPaymentConfiguration new];
componentConfig.locale = @"en_US";

// 设置沙箱环境。如果将其置空，则默认使用线上正式环境。
NSDictionary *options = @{@"sandbox": @"true"};
componentConfig.options = options;
[[AMSCashierPayment shared] initConfiguration:componentConfig];

// 设置回调来监听收银台页面的支付事件。
[AMSCashierPayment shared].paymentDelegate = self;

// 创建并渲染组件。
[[AMSCashierPayment shared] createComponent:paymentSessionData];

#pragma AMSPaymentProtocol
- (void)onEventCallback:(NSString *)eventCode eventResult:(AMSEventResult *)eventResult
{
  if ([eventCode isEqualToString:@"SDK_PAYMENT_SUCCESSFUL"]) {
      // 支付成功。建议将买家重定向到支付结果页面，随后与服务器确认支付结果。
  } else if ([eventCode isEqualToString:@"SDK_PAYMENT_PROCESSING"]) {
      // 支付正在处理中。建议与服务器确认支付结果。如果支付成功，将买家重定向到支付结果页面；如果支付失败，引导买家重新尝试支付。
  } else if ([eventCode isEqualToString:@"SDK_PAYMENT_FAIL"]) {
      // 支付失败。建议您检查在 onEventCallback 结果数据中 result.paymentResultCode 的值以获取详细信息。根据获得的信息，引导买家重新尝试支付。
  } else if ([eventCode isEqualToString:@"SDK_PAYMENT_CANCEL"]) {
      // 支付被取消。建议使用在有效期内的 paymentSessionData 重新调用SDK；如果已过期，则需要重新请求 paymentSessionData。
  } else if ([eventCode isEqualToString:@"SDK_PAYMENT_ERROR"]) {
      // 支付状态异常。建议与服务器确认支付结果。如果确认支付失败，引导买家重新尝试支付。
  } else if ([eventCode isEqualToString:@"SDK_FORM_VERIFICATION_FAILED"]) {
     // 表单提交后，验证失败。建议引导买家确认输入并重新尝试支付。
  }
  NSLog(@"eventCode%@ eventResult%@", eventCode, eventResult);
}

// 请在支付完成后或者界面销毁时，清理支付组件资源。
[[AMSCashierPayment shared] onDestroy];

事件码

状态码：在组件运行生命周期内，通过

onEventCallback

回调函数返回。

用户体验

以下图表展示了在应用程序中支付的用户流程：

支付流程

每种支付方式的支付流程包括以下步骤：

买家进入结账页面。
创建支付会话请求。
买家选择支付方式并提交订单后，您可以通过调用 createPaymentSession（单笔支付）接口获取支付会话。
调用客户端 SDK。
在客户端，通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码展示、验证等流程。随后，SDK 将通过
OnCheckoutListener
回调支付结果，或者跳转到您的支付结果页面。
确认支付结果。
通过以下两种方法之一获取支付结果：

异步通知：在 createPaymentSession（单笔支付）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付成功或过期时，Antom 会使用 notifyPayment 向您发送异步通知。
同步查询：调用 inquiryPayment 接口来查询支付状态。

集成准备

在您开始集成前，请阅读集成指南及接口概述文档，了解服务端接口的集成步骤及调用接口的注意事项，并确保已完成以下预配置：

已获得 client ID。
已完成密钥配置。
已完成异步通知接收地址的配置。
集成 Antom 服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
参阅 Android 端集成 SDK 资源包文档来集成客户端 SDK 资源包。

注意：暂不支持 ‌Flutter 和 React Native（RN）开发框架。

集成步骤

请按照以下步骤开始集成：

创建支付会话
创建并调用 SDK
获取支付结果

步骤 1：创建支付会话
服务端

创建支付会话包含以下参数：

以上参数是创建支付会话的基本参数，完整参数和特定支付方式的额外要求请参考 createPaymentSession（单笔支付）。

以下示例代码展示了如何调用 createPaymentSession（单笔支付）接口：

private static void createPaymentSession() {
  AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
  alipayPaymentSessionRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

  // 替换为您的 paymentRequestId 
  String paymentRequestId = UUID.randomUUID().toString();
  alipayPaymentSessionRequest.setPaymentRequestId(paymentRequestId);

  // 设置金额 
  Amount amount = Amount.builder().currency("SGD").value("4200").build();
  alipayPaymentSessionRequest.setPaymentAmount(amount);

  // 设置支付方式 
  PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("SHOPEEPAY_SG").build();
  alipayPaymentSessionRequest.setPaymentMethod(paymentMethod);

  // 替换为您的 orderId  
  String orderId = UUID.randomUUID().toString();

  // 设置买家信息
  Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

  // 设置订单信息
  Order order = Order.builder().referenceOrderId(orderId)
      .orderDescription("antom testing order").orderAmount(amount).buyer(buyer).build();
  alipayPaymentSessionRequest.setOrder(order);

  // 替换为您的通知地址
  alipayPaymentSessionRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");

  // 替换为您的跳转地址
  alipayPaymentSessionRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

  AlipayPaymentSessionResponse alipayPaymentSessionResponse = null;
  try {
      alipayPaymentSessionResponse = CLIENT.execute(alipayPaymentSessionRequest);
  } catch (AlipayApiException e) {
      String errorMsg = e.getMessage();
      // 处理错误情况
  }
}

以下代码展示了一个请求报文的示例：

{
"order": {
  "buyer": {
    "referenceBuyerId": "yourBuyerId"
  },
  "orderAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "orderDescription": "antom testing order",
  "referenceOrderId": "referenceOrderId01"
},
"paymentAmount": {
  "currency": "SGD",
  "value": "4200"
},
"paymentMethod": {
  "paymentMethodType": "SHOPEEPAY_SG"
},
"paymentNotifyUrl": "https://www.yourNotifyUrl.com",
"paymentRedirectUrl": "https://www.yourMerchantWeb.com",
"paymentRequestId": "paymentRequestId01",
"productCode": "CASHIER_PAYMENT"
}

以下代码展示了一个响应的示例，其中包含以下参数：

paymentSessionData：将返回给前端的支付会话数据。
paymentSessionExpiryTime：支付会话的过期时间。

{
"paymentSessionData": "gM5Y/Go6+IXMPSOZrYtukCdodtwxuSFsn1vRPSB8CzkDqlb1g2W7dDipOkoMRs/x2W7g7qVhjEM7RUGroIT8Cw==&&SG&&188&&eyJhY3Rpb24iOnsiYXBwIjp7fSwibmVlZFZlcmlmeUFuZFJlc3VtZSI6ZmFsc2UsInNraXBTZGtRdWVyeSI6ZmFsc2UsIndhcCI6e30sIndlYiI6e319LCJjbGllbnRJZCI6IlNBTkRCT1hfNVlCWjBMMlpIUjhSMDg5NzgiLCJleHRlbmRJbmZvIjoie1widmVyc2lvbk1hcFwiOntcIndlYlwiOntcIjEuMS4wXCI6e1widGFyZ2V0V2ViVmVyaXNvblwiOlwiMS4xLjBcIn0sXCIxLjIuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMi4wXCJ9fSxcImlPU1wiOntcIjEuMS4wXCI6e1widGFyZ2V0V2ViVmVyaXNvblwiOlwiMS4xLjBcIn0sXCIxLjIuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMi4wXCJ9fSxcIkFuZHJvaWRcIjp7XCIxLjEuMFwiOntcInRhcmdldFdlYlZlcmlzb25cIjpcIjEuMS4wXCJ9LFwiMS4yLjBcIjp7XCJ0YXJnZXRXZWJWZXJpc29uXCI6XCIxLjIuMFwifX19fSIsInBheW1lbnRTZXNzaW9uQ29uZmlnIjp7InBheW1lbnRNZXRob2RDYXRlZ29yeVR5cGUiOiJBUE0iLCJwcm9kdWN0U2NlbmUiOiJDQVNISUVSX1BBWU1FTlQiLCJwcm9kdWN0U2NlbmVWZXJzaW9uIjoiMS4wIn19",
"paymentSessionExpiryTime": "2024-01-01T00:00:00+08:00",
"paymentSessionId": "gM5Y/Go6+IXMPSOZrYtukCdodtwxuSFsn1vRPSB8Czn6HfgqNzo2ogbIk1NUQS35",
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success.",
  "resultStatus": "S"
}
}

常见问题

问：请求参数的值可以使用中文字符吗？

答：为了避免特定支付方式的兼容性问题，请求中的字段请勿使用中文字符。

问：如何设置接收支付通知的地址？

步骤 2：创建并调用 SDK
客户端

买家在页面上选择支付方式后，您需要创建并使用支付会话初始化 SDK。

1.（可选）预加载 SDK

在创建支付会话前，强烈建议您预加载 SDK，以提升收银台页面的渲染速度，减少买家在支付过程中的等待时间。

调用

preload

方法：

按照以下代码示例执行预加载操作：

AMSCashierPayment.preload(context.getApplicationContext());

2. 初始化 SDK

使用

AMSCashierPayment

创建 SDK 实例并指定基本配置。创建配置对象包括以下方法：

注意：每个实例只能处理一个支付会话。建议在每次调用

createComponent

之前先创建实例。

以下示例代码展示了如何实例化 SDK：

AMSCashierPaymentConfiguration configuration = new AMSCashierPaymentConfiguration();
configuration.setLocale(new Locale("en", "US"));
// 设置沙箱环境。如果将其置空，则默认使用线上正式环境。
configuration.setOption("sandbox", "true");
// 设置回调来监听收银台页面的支付事件。
configuration.setOnCheckoutListener(new OnCheckoutListener() {
  @Override
  public void onEventCallback(String eventCode, AMSEventResult eventResult) {
      Log.e(TAG, "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString());
  }
});
// 实例化 AMSCashierPayment。
AMSCashierPayment checkout = new AMSCashierPayment.Builder(activity, configuration).build();

3. 调用 SDK

调用

createComponent

方法：

在以下情况调用

onDestroy

方法释放 SDK 组件资源：

当买家离开支付页面时，释放 createPaymentSession（单笔支付）中创建的组件资源。
当买家发起多次支付时，释放之前 createPaymentSession（单笔支付）中创建的组件资源。

以下示例代码展示了如何调用 SDK：

checkout.createComponent(activity, sessionData);

// 释放 SDK 组件资源
checkout.onDestroy();

4. 展示支付结果

您可以使用支付组件处理需要重定向的支付方式（异步支付）和不需要的重定向的支付方式（同步支付）。

重定向支付

非重定向支付

对于无需重定向的支付，支付结果将通过

onEventCallback

函数给出。这里的支付结果仅用于前端展示，最终订单状态以服务器端为准。您需要通过

onEventCallback

返回的数据自定义每个支付结果的处理流程。

以下是可能由

onEventCallback

返回的支付结果的事件码。

以下示例代码展示了如何处理回调事件

onEventCallback

：

@Override
public void onEventCallback(String eventCode, AMSEventResult eventResult) {
  AlipayLog.e(TAG, "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString());

  if (!TextUtils.isEmpty(eventCode)) {
      if ("SDK_PAYMENT_SUCCESSFUL".equals(eventCode)) {
          // 支付成功，建议将买家重定向到支付结果页面，随后与服务器确认支付结果。
      } else if ("SDK_PAYMENT_PROCESSING".equals(eventCode)) {
          // 支付正在处理中，建议与服务器确认支付结果。如果支付成功，将买家重定向到支付结果页面；如果支付失败，引导买家重新尝试支付。
      } else if ("SDK_PAYMENT_FAIL".equals(eventCode)) {
          // 支付失败，建议您检查在 onEventCallback 结果数据中 result.paymentResultCode 的值以获取详细信息。根据获得的信息，引导买家重新尝试支付。
      } else if ("SDK_PAYMENT_CANCEL".equals(eventCode)) {
          // 支付被取消。建议使用在有效期内的 paymentSessionData 重新调用 SDK；如果已过期，则需要重新请求 paymentSessionData。
      } else if ("SDK_PAYMENT_ERROR".equals(eventCode)) {
          // 支付状态异常，建议与服务器确认支付结果。如果确认支付失败，引导买家重新尝试支付。
      }
  }
}

步骤 3：获取支付结果
服务端

在买家完成支付或支付超时后，Antom 会通过服务器交互将相应的支付结果发送给您，您可以通过以下方法之一获取支付结果：

接收异步通知
查询结果

接收异步通知

Antom 允许您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定链接。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。

以下代码展示了通知请求的示例：

{
"notifyType": "PAYMENT_RESULT",
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "success"
},
"paymentRequestId": "paymentRequestId01",
"paymentId": "20240101123456789XXXX",
"paymentAmount": {
  "value": "4200",
  "currency": "SGD"
},
"paymentCreateTime": "2024-01-01T00:00:00+08:00",
"paymentTime": "2024-01-01T00:01:00+08:00"
}

如何验证通知的签名并做出响应，请参阅签名和验签。

常见问题

问：何时会发送通知？

答：这取决于支付是否完成：

如果支付成功完成，Antom 通常会在 3 到 5 秒内发送异步通知。对于某些支付方式，如现金支付，通知可能会稍有延迟。
如果支付未完成，Antom 需要先关闭订单，然后发送异步通知。不同支付方式关闭订单所需的时间会有所不同，通常默认为 14 分钟。

问：异步通知会被重新发送吗？

答：是的，对于以下情况，异步通知会在 24 小时内自动重新发送：

如果由于网络原因未收到异步通知。
如果您收到来自 Antom 的异步通知，但您没有按照处理通知的示例代码格式对通知做出响应。

通知最多可以重发 8 次，或者直到收到正确的响应以终止发送。发送间隔如下：0 分钟，2 分钟，10 分钟，10 分钟，1 小时，2 小时，6 小时，15 小时。

问：在响应异步通知时，我需要添加数字签名吗？

答：如果您收到来自 Antom 的异步通知，您需要按照处理通知的示例代码格式返回响应，但不需要对响应进行签名。

问：我在通知中需要使用哪些关键参数？

答：请注意以下关键参数：

result：表示订单的支付结果。
paymentRequestId：用于咨询、取消和对账的支付请求 ID。
paymentId：表示由 Antom 生成的支付订单 ID，用于退款和对账。
paymentAmount：表示支付金额。

查询结果

您可以调用 inquiryPayment 接口来发起对订单结果的查询。

完整的参数集，请参考 inquiryPayment 接口文档，获取全部参数及特定支付方式的额外要求。

以下示例代码展示了如何调用 inquiryPayment 接口：

public static void inquiryPayment() {
  AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();

  // 替换为您的 paymentRequestId
  alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");

  AlipayPayQueryResponse alipayPayQueryResponse = null;
  try {
      alipayPayQueryResponse = CLIENT.execute(alipayPayQueryRequest);
  } catch (AlipayApiException e) {
      String errorMsg = e.getMessage();
      // 处理错误情况
  }
}

以下代码展示了请求报文的示例：

{
"paymentRequestId": "paymentRequestId01"
}

以下代码展示了响应报文的示例：

{
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "Success"
},
"paymentStatus": "SUCCESS",
"paymentRequestId": "paymentRequestId01",
"paymentId": "20240101123456789XXXX",
"paymentAmount": {
  "value": "4200",
  "currency": "SGD"
},
"paymentCreateTime": "2024-01-01T00:00:00+08:00",
"paymentTime": "2024-01-01T00:01:00+08:00",
"paymentMethodType": "SHOPEEPAY_SG"
}

常见问题

问：我应该多久调用一次 inquiryPayment 接口？

答：以 2 秒的间隔持续调用 inquiryPayment 接口，直到获取最终的支付结果或收到异步支付结果通知为止。

问：我在通知中需要使用哪些关键参数？

答：请注意以下关键参数：

result：表示此 inquiryPayment 接口调用的结果，需要根据 paymentStatus 来判断订单状态：

SUCCESS
和
FAIL
表示最终结果。
PROCESSING
表示处理中。

paymentAmount：表示支付的金额。

示例代码

前端完整示例代码：

//（可选）预加载 SDK。在创建支付会话前预加载 SDK，以提升收银台页面的渲染速度，减少买家在支付过程中的等待时间。
AMSCashierPayment.preload(context);

// 步骤一: 从您的服务端获取 Antom PaymentSessionData。
String paymentSessionData = "YOUR_PAYMENT_SESSIONDATA";

AMSCashierPaymentConfiguration configuration = new AMSCashierPaymentConfiguration();
configuration.setLocale(new Locale("en", "US"));
// 设置沙箱环境。如果将其置空，则默认使用线上正式环境。
configuration.setOption("sandbox", "true");
// 设置回调来监听收银台页面的支付事件。
configuration.setOnCheckoutListener(new OnCheckoutListener() {
  @Override
  public void onEventCallback(String eventCode, AMSEventResult eventResult) {
      AlipayLog.e(TAG, "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString());

      if (!TextUtils.isEmpty(eventCode)) {
          if ("SDK_PAYMENT_SUCCESSFUL".equals(eventCode)) {
              // 支付成功。建议将买家重定向到支付结果页面，随后与服务器确认支付结果。
          } else if ("SDK_PAYMENT_PROCESSING".equals(eventCode)) {
              // 支付正在处理中。建议与服务器确认支付结果。如果支付成功，将买家重定向到支付结果页面；如果支付失败，引导买家重新尝试支付。
          } else if ("SDK_PAYMENT_FAIL".equals(eventCode)) {
              // 支付失败。建议您检查在 onEventCallback 结果数据中 result.paymentResultCode 的值以获取详细信息。根据获得的信息，引导买家重新尝试支付。
          }else if ("SDK_PAYMENT_CANCEL".equals(eventCode)) {
              // 支付被取消。建议使用在有效期内的 paymentSessionData 重新调用SDK；如果已过期，则需要重新请求 paymentSessionData。
          } else if ("SDK_PAYMENT_ERROR".equals(eventCode)) {
              // 支付状态异常。建议与服务器确认支付结果。如果确认支付失败，引导买家重新尝试支付。
          } else if ("SDK_FORM_VERIFICATION_FAILED".equals(eventCode)) {
              // 表单提交后，验证失败。建议引导买家确认输入并重新尝试支付。
          }
      }
  }
});
// 实例化 AMSCashierPayment。
AMSCashierPayment checkout = new AMSCashierPayment.Builder(activity, configuration).build();

// 创建并渲染组件。
checkout.createComponent(activity, sessionData);

// 请在支付完成后或者界面销毁时，清理支付组件资源。
checkout.onDestroy();

事件码

状态码：在组件运行生命周期内，通过

onEventCallback

回调函数返回。

APM 支付

用户体验

支付流程

集成准备

集成步骤

步骤 1：创建支付会话 服务端

步骤 2：创建并调用 SDK 客户端

1.（可选）预加载 SDK

2. 初始化 SDK

3. 调用 SDK

4. 展示支付结果

重定向支付

非重定向支付

步骤 3：获取支付结果 服务端

接收异步通知

查询结果

示例代码

事件码

用户体验

支付流程

集成准备

集成步骤

步骤 1：创建支付会话 服务端

步骤 2：创建并调用 SDK 客户端

1.（可选）预加载 SDK

2. 初始化 SDK

3. 调用 SDK

4. 展示支付结果

重定向支付

非重定向支付

步骤 3：获取支付结果 服务端

接收异步通知

查询结果

示例代码

事件码

用户体验

支付流程

集成准备

集成步骤

步骤 1：创建支付会话 服务端

步骤 2：创建并调用 SDK 客户端

1.（可选）预加载 SDK

2. 初始化 SDK

3. 调用 SDK

4. 展示支付结果

重定向支付

非重定向支付

步骤 3：获取支付结果 服务端

接收异步通知

查询结果

示例代码

事件码

步骤 1：创建支付会话
服务端

步骤 2：创建并调用 SDK
客户端

步骤 3：获取支付结果
服务端

步骤 1：创建支付会话
服务端

步骤 2：创建并调用 SDK
客户端

步骤 3：获取支付结果
服务端

步骤 1：创建支付会话
服务端

步骤 2：创建并调用 SDK
客户端

步骤 3：获取支付结果
服务端