Antom, leading provider of tailored payment solutions

银行卡支付

下架通知:
本指南内容已停止更新。
建议您采用 Payment Element 集成方式,以获得更优的集成体验。
Antom SDK 是一个预构建的用户界面组件,用于收集银行卡信息并为您处理 3D 验证流程。集成此组件不需要您具有 PCI 认证,非常适合那些希望委托 Antom 来收集银行卡信息的用户。
Web/WAP

用户体验

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

支付流程

以下流程说明了如何通过 Antom SDK 集成单笔支付:
  1. 买家进入结账页面。
  2. 创建支付会话请求。
    买家选择支付方式并提交订单后,您可以通过调用 createPaymentSession(单笔支付)接口获取支付会话。
  3. 调用客户端 SDK。
    在客户端,通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码展示、验证等流程。随后,SDK 将通过 onEventCallback 回调支付结果。
  4. 确认支付结果。
    通过以下两种方法之一获取支付结果:
  5. 获取请款结果。
    对于银行卡支付,通过以下两种方法之一获取请款结果:

集成准备

在您开始集成前,请阅读集成指南及接口概述文档,了解服务端接口的集成步骤及调用接口的注意事项,并确保已完成以下预配置:
  • 已获得 client ID。
  • 已完成密钥配置。
  • 已完成异步通知接收地址的配置。
  • 集成 Antom 服务端 SDK 资源包,并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
  • 参阅 Web/WAP 端集成 SDK 资源包文档来集成客户端 SDK 资源包。

集成步骤

请按照以下步骤开始集成:
  1. 创建支付会话
  2. 创建并调用 SDK
  3. 获取支付结果
  4. 获取请款结果

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

当买家选择 Antom 提供的支付方式时,您需要收集关键信息,如支付请求 ID、订单金额、支付方式、订单描述、支付重定向链接和支付结果通知链接,调用 createPaymentSession(单笔支付)接口来创建支付会话,并将支付会话返回给客户端。
创建支付会话包含以下参数:
参数名称
是否必需
描述
productCode
是
表示合同中规定的所使用的支付产品。对于单笔支付,此值设置为 CASHIER_PAYMENT。
paymentRequestId
是
商户为识别支付请求而分配的专属 ID。
paymentAmount
是
商户请求以订单币种收取的支付金额。
paymentMethod
是
商户或收单机构用于收款的支付方式。
paymentRedirectUrl
是
支付完成后,买家被重定向到的商户页面链接。
order
是
包括买家、商户、商品、金额、配送信息和购买环境的订单信息。
paymentNotifyUrl
否
支付结果通知地址,可通过接口传递,也可通过 Antom Dashboard 设置为固定值。
settlementStrategy
否
支付请求的结算策略。
paymentFactor.isAuthorization
否
表示支付场景是否为授权场景。当 paymentMethodType 的值为 CARD 时,请将此参数的值设为 true,表示支付场景需要授权。
注意:当此参数的值为 true 时,支付资金在支付方式端被保全并冻结,您可以使用 capture(单笔支付)接口扣除支付资金。
以上参数是创建支付会话的基本参数,完整参数和特定支付方式的额外要求请参考 createPaymentSession(单笔支付)。
以下示例代码展示了如何调用 createPaymentSession(单笔支付)接口:
java
public static void createCardPaymentSession() {
  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("CARD").build();
  alipayPaymentSessionRequest.setPaymentMethod(paymentMethod);

  // 设置授权请款支付模式
  PaymentFactor paymentFactor = PaymentFactor.builder().isAuthorization(true).build();
  alipayPaymentSessionRequest.setPaymentFactor(paymentFactor);

  // 替换为您的 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();
    // 处理错误情况
  }
}
以下代码展示了一个请求报文的示例:
json
{
  "order": {
    "buyer": {
      "referenceBuyerId": "yourBuyerId"
    },
    "orderAmount": {
      "currency": "SGD",
      "value": "4200"
    },
    "orderDescription": "antom testing order",
    "referenceOrderId": "referenceOrderId01"
  },
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentFactor": {
    "isAuthorization": true
  },
  "paymentMethod": {
    "paymentMethodType": "CARD"
  },
  "paymentNotifyUrl": "https://www.yourNotifyUrl.com",
  "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
  "paymentRequestId": "paymentRequestId01",
  "productCode": "CASHIER_PAYMENT"
}
以下代码展示了一个响应的示例,其中包含以下参数:
  • paymentSessionData:需要返回给前端的支付会话数据。
  • paymentSessionExpiryTime:支付会话的过期时间。
json
{
  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
  "paymentSessionExpiryTime": "2024-01-01T00:00:00+08:00",
  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
常见问题
问:请求参数的值可以使用中文字符吗?
答:为了避免特定支付方式的兼容性问题,请求中的字段请勿使用中文字符。

问:如何设置接收支付通知的地址?
答:在 createPaymentSession(单笔支付)接口中指定 paymentNotifyUrl 字段,以接收支付结果的异步通知(notifyPayment),或者在 Antom Dashboard 中配置接收地址。如果请求和 Antom Dashboard 中都指定了地址,请求中的值优先。

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

Antom SDK 是用于处理支付流程的组件,被会话唤起的组件根据 createPaymentSession(单笔支付)接口中指定的支付方式,进行信息收集、唤端、展示二维码等流程。

1.(可选)预加载 SDK

在创建支付会话前,强烈建议您预加载 SDK,以提升收银台页面的渲染速度,减少买家在支付过程中的等待时间。按照以下代码示例执行预加载操作:
javascript
// import { AMSCashierPayment } from '@alipay/ams-checkout';

AMSCashierPayment.preload();

2. 初始化 SDK

通过使用 AMSCashierPayment 来创建 SDK 实例。配置对象包括以下参数:
参数名称
是否必需
描述
environment
是
用于传递环境信息。有效值包括:
  • sandbox:沙箱环境
  • prod:生产环境
locale
否
用于传递语言信息。有效值如下所示。您可以根据支付方式的地区选择要传递的值。如果传入其他值,默认使用英语:
  • en_US:英语
  • es_ES:西班牙语
  • fr_FR:法语
  • nl_NL:荷兰语
  • it_IT:意大利语
  • de_DE:德语
  • zh_CN:简体中文
  • zh_HK:繁体中文
  • pt_PT:葡萄牙语(葡萄牙)
  • ro:罗马尼亚语
  • pl_PL:波兰语
analytics
否
用于配置和分析数据。包含以下值:
  • enabled:选传,Boolean 类型。默认值为 true,表示允许 SDK 上传和分析操作数据以提供更好的服务。如果不允许上传和分析数据,将其设置为 false。
onLog
否
这是一个回调方法,用于生成 SDK 执行期间的日志错误信息和接口异常。
onEventCallback
否
一个回调函数,在 SDK 运行期间,当发生支付事件(如支付结果或表单提交错误)时,返回特定的事件代码。更多信息请参阅事件码。
以下示例代码展示了如何实例化 SDK:
javascript
// 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

当买家在页面上选择支付方式后,您需要创建 SDK 并使用支付会话进行初始化。
使用实例对象中的 createComponent 或 mountComponent 函数来创建支付组件:
参数名称
是否必需
描述
sessionData
是
使用 sessionData 参数创建配置对象:将通过 createPaymentSession(单笔支付)接口在响应中获取的完整 paymentSessionData 参数传递给 sessionData 参数。
appearance
否
自定义外观主题配置,包含以下子参数:
  • showSubmitButton:选传,Boolean 类型。默认值为 false,表示不启用由 SDK 组件渲染支付按钮。true 表示由 SDK 组件渲染支付按钮。若设定该值为 false,则需要调用实例对象中 submit() 函数触发提交支付流程。该参数仅适用于嵌入式体验。
notRedirectAfterComplete
否
默认值为 false,表示支付完成后会跳转回您的页面。值为空时也适用。true 表示支付完成后不会跳转。您需要使用客户事件代码来控制银行绑卡以完成后续流程。请注意,客户端返回的支付结果码仅用作客户端页面跳转操作的参考。对于交易状态的更新,请参考服务器端 notifyPayment 或 inquiryPayment 接口返回的结果。
merchantAppointParam
否
Object 类型,用于自定义功能的设置,包含以下参数:
  • storedCard:选传,Object 类型,用于在已存卡情况下设置自定义功能,包含以下参数:
  • needCVV:选传,Boolean 类型,默认值为 false,表示在支付过程中无需用户输入 CVV 校验,当值为空时同理。若设定该值为 true ,则表示在支付过程中需要用户输入 CVV 校验。

弹窗体验与嵌入式体验

您可以通过弹窗或嵌入页面的方式在页面上展示 SDK。
弹窗体验
弹窗体验的优势在于对页面样式影响较小,流程相对独立。
当买家在页面上选择支付方式并点击提交后,您需要调用 SDK 并弹出窗口。
javascript
async function create(sessionData) {
  await checkoutApp.createComponent({
    sessionData: sessionData,
    notRedirectAfterComplete: true,
  });
}
嵌入式体验
嵌入式体验将支付元素嵌入到指定视图中,您需关注支付列表的样式调整。嵌入内容的宽度会自动适应父容器,而高度会随着视图变化动态更新。
javascript
async function create(sessionData) {
  await checkoutApp.mountComponent(
    {
      sessionData: sessionData,
      appearance: {
        showSubmitButton: false, // 配置支付按钮是否由 SDK 组件呈现。
      },
      notRedirectAfterComplete: true,
    },
    "#ContainerNodeId",
  );
}
嵌入式提交支付
如果您需要传入提前收集好的 billing address 信息用于 AVS 验证,您可配置如下参数通过 submit 函数传入。
  • billingAddress:选传,Object 类型。用来识别付款人身份和位置的账单地址信息。包含如下参数:
  • region:必传,String (2)。遵循 ISO 3166 标准的二位字母的国家或地区代码。
  • address1:选传,String (256)。地址行 1,例如街道地址、邮政信箱和公司名称。
  • address2:选传,String (256)。地址行 2,例如公寓、套房、单元和建筑物信息。
  • city:选传,String (32)。城市、地区、郊区、城镇或村庄名称。
  • state:选传,String (8)。州、国家或省名称。
  • zipCode:选传,String (32)。邮政编码。
javascript
// 用户输入地址信息并存储在 billingAddress 对象中,用于后续提交。
const billingAddress = {
  region: "",
  address1: "",
  address2: "",
  city: "",
  state: "",
  zipCode: "",
};

// 当用户完成表单填写,点击提交按钮时执行。
checkoutApp.submit({ billingAddress }).then(({ code, message }) => {});
销毁组件
在以下情况下,调用 unmount 方法来释放 SDK 组件资源:
javascript
// 释放 SDK 组件资源。
checkoutApp.unmount();
常见问题
问:遇到 SDK_CREATEPAYMENT_PARAMETER_ERROR 时该怎么办?
答:收到此事件代码时,请检查传递的 sessionData 是否正确且完整。
​
问:遇到 SDK_PAYMENT_ERROR 或渲染视图错误时该怎么办?
答:检查接口初始化时的网络请求是否出现异常,如网络超时。确保创建支付会话请求的环境与 SDK 实例化时的环境一致。检查 createPaymentSession(单笔支付)接口中的参数传递是否正确。如果接口异常持续存在,请联系我们进行进一步的故障排除。
​
问:遇到 SDK_FORM_VERIFICATION_FAILED 时该怎么办?
答:可能是因为买家没有填写所有必填项。提交时,可能会返回表示表单验证失败的错误代码。建议引导买家完善表单内容。

4. 展示支付结果

如果设置 notRedirectAfterComplete 为 false,买家在完成支付后将被重定向到您在 createPaymentSession(单笔支付)接口中提供的 paymentRedirectUrl。您可以在该链接中主动查询支付结果并展示给买家。
如果 notRedirectAfterComplete 为 true,支付结果将通过 onEventCallback 函数返回。这里的支付结果仅用于前端展示,最终订单状态以服务器端为准。
您需要通过 onEventCallback 返回的数据自定义每个支付结果的处理流程。
以下是 onEventCallback 的支付结果可能返回的事件码:
事件码
信息
解决方案
SDK_PAYMENT_SUCCESSFUL
支付成功。
建议将买家重定向到支付结果页面,随后与服务器确认支付结果。
SDK_PAYMENT_PROCESSING
支付正在处理中。
建议与服务器确认支付结果。如果支付成功,将买家重定向到支付结果页面;如果支付失败,引导买家重新尝试支付。
SDK_PAYMENT_FAIL
支付失败。
建议您检查在 onEventCallback 结果数据中 result.paymentResultCode 的值以获取详细信息。根据获得的信息,引导买家重新尝试支付。
注意:请参阅支付失败或异常说明,以获取 result.paymentResultCode 的含义。
SDK_PAYMENT_CANCEL
支付被取消。
建议使用在有效期内的 paymentSessionData 重新调用 SDK;如果已过期,则需要重新请求 paymentSessionData。
SDK_PAYMENT_ERROR
支付状态异常。
建议与服务器确认支付结果。如果确认支付失败,引导买家重新尝试支付。
以下示例代码展示了如何处理回调函数 onEventCallback:
javascript
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 中配置该地址。
以下代码展示了通知请求的示例:
json
{
  "actualPaymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "cardInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "XXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "notifyType": "PAYMENT_RESULT",
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentCreateTime": "2024-01-01T00:00:00+08:00",
  "paymentId": "20240101123456789XXXX",
  "paymentRequestId": "paymentRequestId01",
  "paymentResultInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "XXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentTime": "2024-01-01T00:01:00+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
如何验证通知的签名并做出响应,请参阅签名和验签。
常见问题
问:何时会发送通知?
答:这取决于支付是否完成:
  • 如果支付成功完成,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 接口来发起对订单结果的查询。
参数名称
是否必需
描述
paymentRequestId
否
由商户生成的支付请求 ID。
完整的参数集,请参考 inquiryPayment 接口文档,获取全部参数及特定支付方式的额外要求。
以下示例代码展示了如何调用 inquiryPayment 接口:
java
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();
    // 处理错误情况
  }
}
以下代码展示了请求报文的示例:
json
{
  "paymentRequestId": "paymentRequestId01"
}
以下代码展示了响应报文的示例:
json
{
  "authExpiryTime": "2024-01-08T00:01:00+08:00",
  "cardInfo": {
    "cardBrand": "MASTERCARD",
    "funding": "DEBIT",
    "issuingCountry": "US"
  },
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentId": "20240101123456789XXXX",
  "paymentMethodType": "CARD",
  "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
  "paymentRequestId": "paymentRequestId01",
  "paymentResultCode": "SUCCESS",
  "paymentResultInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "networkTransIdXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentResultMessage": "success",
  "paymentStatus": "SUCCESS",
  "paymentTime": "2024-01-01T00:01:00+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
常见问题
问:我应该多久调用一次 inquiryPayment 接口?
答:以 2 秒的间隔持续调用 inquiryPayment 接口,直到获取最终的支付结果或收到异步支付结果通知为止。

问:我在通知中需要使用哪些关键参数?
答:请注意以下关键参数:
  • result:表示此 inquiryPayment 接口调用的结果,需要根据 paymentStatus 来判断订单状态:
  • SUCCESS 和 FAIL 表示最终结果。
  • PROCESSING 表示处理中。
  • paymentAmount:表示支付的金额。

步骤 4:获取请款结果
服务端

在商户完成请款或请款超时后,Antom 会通过服务器交互将相应的请款结果发送给您,您可以通过以下方法之一获取请款结果:
  • 接收异步通知
  • 查询结果

接收异步通知

请款成功或失败时,Antom 会向您在 createPaymentSession(单笔支付)接口的 paymentNotifyUrl 参数中指定的地址发送异步通知(notifyPayment)。收到 Antom 的通知后,您需要按照返回收到确认信息返回响应。
Antom允许您在 createPaymentSession(单笔支付)接口的 paymentNotifyUrl 参数中指定链接。如果每个支付的地址相同,您也可以在 Antom Dashboard 中配置该地址。
以下代码展示了请款成功的示例:
json
{
  "captureAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "notifyType": "CAPTURE_RESULT",
  "captureId": "20240101987654321XXXX",
  "captureRequestId": "captureRequestId01",
  "captureTime": "2024-01-01T00:00:02+08:00",
  "paymentId": "20240101123456789XXXX",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
以下代码展示了请款失败的示例:
json
{
  "captureAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "notifyType": "CAPTURE_RESULT",
  "captureId": "20240101123456789XXXX",
  "captureRequestId": "captureRequestId01",
  "captureTime": "2024-01-01T00:00:02+08:00",
  "paymentId": "20240101123456789XXXX",
  "result": {
    "resultCode": "PROCESS_FAIL",
    "resultMessage": "fail.",
    "resultStatus": "F"
  }
}
如何验证通知的签名并做出响应,请参阅签名与验签。
常见问题
问:异步通知会被重新发送吗?
答:是的,对于以下情况,异步通知将在 24 小时内自动重新发送:
  • 如果您因网络原因未收到异步通知。
  • 如果您收到来自 Antom 的异步通知,但您没有按照处理通知的示例代码格式进行响应。
通知最多可以重发 8 次,或者直到收到正确的响应以终止发送。发送间隔为:0 分钟,2 分钟,10 分钟,10 分钟,1 小时,2 小时,6 小时和 15 小时。
​
问:在响应异步通知时,我需要添加数字签名吗?
答:如果您收到来自 Antom 的异步通知,您需要按照处理通知的示例代码格式返回响应,但不需要对响应进行签名。
​
问:我需要使用通知中的哪些关键参数?
答:请注意以下关键参数:
  • result:表示订单的请款结果。
  • notifyType:通知类型为 CAPTURE_RESULT。
  • paymentRequestId:您生成的支付请求 ID,用于查询、取消和对账。
  • paymentId:Antom 生成的支付订单 ID,用于退款和对账。
  • acquirerReferenceNo:集成新加坡和香港内银行卡支付服务的商户将在通知中收到特定的收单机构 ID。

查询结果

您可以调用 inquiryPayment 接口来发起对订单结果的查询。
参数名称
是否必需
描述
paymentRequestId
否
由商户生成的支付请求 ID。
有关完整参数集,请参阅 inquiryPayment 接口,获取完整的参数列表以及某些支付方式的额外要求。
以下示例代码展示了如何调用 inquiryPayment 接口:
java
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();
    // 处理错误情况
  }
}
以下是请求报文的示例:
json
{
  "paymentRequestId": "paymentRequestId01"
}

请款状态的值

接口响应中的 transactions 字段值表示请款状态:
参数名称
描述
transactions.transactionType
值为 CAPTURE,表示请款状态。
transactions.transactionResult
请款状态。
以下代码展示了请款成功的示例:
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success"
      }
    }
  ]
}
以下代码展示了请款失败的示例:
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "F",
        "resultCode": "PROCESS_FAIL",
        "resultMessage": "General business failure. No retry."
      }
    }
  ]
}
以下代码展示了请款处理中的示例:
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "U",
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "payment in process"
      }
    }
  ]
}
常见问题
问:我应该多久调用一次 inquiryPayment 接口?
答:以 2 秒的间隔持续调用 inquiryPayment 接口,直到获取最终的支付结果或收到异步支付结果通知。

示例代码

前端完整示例代码:
javascript
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,
    // 设置付款完成后不跳转,由您控制后续流程。
    notRedirectAfterComplete: true,
    merchantAppointParam: {
      storedCard: {
        needCVV: true, // 默认为 false,表示不需要用户输入 CVV 校验。
      },
    },
  });
}

// 处理支付结果。
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 回调函数返回。
类型
代码
描述
后续操作
状态码
SDK_FORM_VERIFICATION_FAILED
表单提交后,验证失败。
引导买家确认输入并重新尝试支付。
iOS

用户体验

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

支付流程

对于每种支付方式,支付流程包括以下步骤:
  1. 买家进入结账页面。
  2. 创建支付会话请求。
    买家选择支付方式并提交订单后,您可以通过调用 createPaymentSession(单笔支付)接口获取支付会话。
  3. 调用客户端 SDK。
    在客户端,通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码展示、验证等流程。随后,SDK 将通过 onEventCallback 回调支付结果。
  4. 确认支付结果。
    通过以下两种方法之一获取支付结果:
  5. 获取请款结果。
    对于银行卡支付,通过以下两种方法之一获取请款结果:

集成准备

在您开始集成前,请阅读集成指南及接口概述文档,了解服务端接口的集成步骤及调用接口的注意事项,并确保已完成以下预配置:
  • 已获得 client ID。
  • 已完成密钥配置。
  • 已完成异步通知接收地址的配置。
  • 集成 Antom 服务端 SDK 资源包,并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
  • 参阅 iOS 端集成 SDK 资源包文档来集成客户端 SDK 资源包。
注意:暂不支持 ‌Flutter 和 React Native(RN)开发框架。

集成步骤

请按照以下步骤开始集成:
  1. 创建支付会话
  2. 创建并调用 SDK
  3. 获取支付结果
  4. 获取请款结果

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

当买家选择 Antom 提供的支付方式时,您需要收集关键信息,如支付请求 ID、订单金额、支付方式、订单描述、支付重定向链接和支付结果通知链接,调用 createPaymentSession(单笔支付)接口来创建支付会话,并将支付会话返回给客户端。
创建支付会话包含以下参数:
参数名称
是否必需
描述
productCode
是
表示合同中规定的所使用的支付产品。对于单笔支付,此值设置为 CASHIER_PAYMENT。
paymentRequestId
是
商户为识别支付请求而分配的专属 ID。
paymentAmount
是
商户请求以订单币种收取的支付金额。
paymentMethod
是
商户或收单机构用于收款的支付方式。
paymentRedirectUrl
是
支付完成后,买家被重定向到的商户页面链接。
order
是
包括买家、商户、商品、金额、配送信息和购买环境的订单信息。
paymentNotifyUrl
否
支付结果通知地址,可通过接口传递,也可通过 Antom Dashboard 设置为固定值。
settlementStrategy
否
支付请求的结算策略。
paymentFactor.isAuthorization
否
表示支付场景是否为授权场景。当 paymentMethodType 的值为 CARD 时,请将此参数的值设为 true,表示支付场景需要授权。
注意:当此参数的值为 true 时,支付资金在支付方式端被保全并冻结,您可以使用 capture(单笔支付)接口扣除支付资金。
以上参数是创建支付会话的基本参数,完整参数和特定支付方式的额外要求请参考 createPaymentSession(单笔支付)。
以下示例代码展示了如何调用 createPaymentSession(单笔支付)接口:
java
public static void createCardPaymentSession() {
  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("CARD").build();
  alipayPaymentSessionRequest.setPaymentMethod(paymentMethod);

  // 设置授权请款支付模式
  PaymentFactor paymentFactor = PaymentFactor.builder().isAuthorization(true).build();
  alipayPaymentSessionRequest.setPaymentFactor(paymentFactor);

  // 替换为您的 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();
    // 处理错误情况
  }
}
以下代码展示了一个请求报文的示例:
json
{
  "order": {
    "buyer": {
      "referenceBuyerId": "yourBuyerId"
    },
    "orderAmount": {
      "currency": "SGD",
      "value": "4200"
    },
    "orderDescription": "antom testing order",
    "referenceOrderId": "referenceOrderId01"
  },
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentFactor": {
    "isAuthorization": true
  },
  "paymentMethod": {
    "paymentMethodType": "CARD"
  },
  "paymentNotifyUrl": "https://www.yourNotifyUrl.com",
  "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
  "paymentRequestId": "paymentRequestId01",
  "productCode": "CASHIER_PAYMENT"
}
以下代码展示了一个响应的示例,其中包含以下参数:
  • paymentSessionData:需要返回给前端的支付会话数据。
  • paymentSessionExpiryTime:支付会话的过期时间。
json
{
  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
  "paymentSessionExpiryTime": "2024-01-01T00:00:00+08:00",
  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
常见问题
问:请求参数的值可以使用中文字符吗?
答:为了避免特定支付方式的兼容性问题,请求中的字段请勿使用中文字符。

问:如何设置接收支付通知的地址?
答:在 createPaymentSession(单笔支付)接口中指定 paymentNotifyUrl 字段,以接收支付结果的异步通知(notifyPayment),或者在 Antom Dashboard 中配置接收地址。如果请求和 Antom Dashboard 中都指定了地址,请求中的值优先。

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

Antom SDK 是用于处理支付流程的组件,被会话唤起的组件根据 createPaymentSession(单笔支付)接口中指定的支付方式,进行信息收集、唤端、展示二维码等流程。
当买家在页面上选择支付方式后,您需要创建并使用支付会话初始化 SDK。

1.(可选)预加载 SDK

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

2. 初始化 SDK

使用 AMSCashierPayment 创建 SDK 实例并指定基本配置。创建 AMSCashierPaymentConfiguration 对象时,包括以下参数:
参数名称
是否必需
描述
locale
否
用于传递语言信息。有效值如下所示。您可以根据支付方式的地区选择要传递的值。如果传入其他值,默认使用英语:
  • en_US:英语
  • es_ES:西班牙语
  • fr_FR:法语
  • nl_NL:荷兰语
  • it_IT:意大利语
  • de_DE:德语
  • zh_CN:简体中文
  • zh_HK:繁体中文
  • pt_PT:葡萄牙语(葡萄牙)
  • ro:罗马尼亚语
  • pl_PL:波兰语
options
否
用于自定义外观主题和功能以及是否使用沙箱环境。有效值包括:
  • "showSubmitButton":选传,Boolean 类型。默认值为 false,表示不启用由 SDK 组件渲染支付按钮。true 表示由 SDK 组件渲染支付按钮。若设定该值为 false,则需要调用实例对象中 submit() 函数触发提交支付流程。该参数仅适用于嵌入式体验。
  • "sandbox", "true":沙箱环境。
  • "sandbox", "false":生产环境。
  • "notRedirectAfterComplete", "true":选传,Boolean 类型。默认值为 false,表示支付完成后跳回您的页面,当值为空时同理。值为 true 表示支付完成后不跳转,您需要通过客户事件码自行控制绑卡完成后续流程。请注意,客户端返回的支付结果事件码仅用于客户端页面的跳转操作参考,交易状态的更新请以服务端 notifyPayment 或 inquiryPayment 接口返回结果为准。
  • "merchantAppointParam":选传,JSONString 类型。用于自定义功能设置,包含以下参数:
  • storedCard:选传,Object 类型。用于已存卡情况下的自定义功能设置,包含以下参数:
  • needCVV:选传,Boolean 类型。默认值为false,表示在支付过程中无需买家输入 CVV 校验,当值为空时同理。若设定该值为true,则表示在支付过程中需要买家输入 CVV 校验。
实现 AMSPaymentProtocol,用于处理后续流程中的相应事件。它包含以下方法:
方法
是否必需
描述
onEventCallback
否
一个回调函数,用于监控结账页面上的支付事件,返回 eventCode 和 eventResult。
注意:每个实例只能处理一个支付会话。建议在每次调用 createComponent 之前先创建实例。
以下示例代码展示了如何实例化 SDK:
objectivec
#import <AMSComponent/AMSComponent-Swift.h>

AMSCashierPaymentConfiguration *componentConfig = [AMSCashierPaymentConfiguration new];
componentConfig.locale = @"en_US";
// 卡支付场景需要进行 CVV 校验。
NSString *merchantAppointParam = @"{ \"storedCard\": { \"needCVV\": true } }"; 

NSDictionary *options = @{
    @"showSubmitButton": @"false", // 仅嵌入式体验生效,配置支付按钮是否由 SDK 组件呈现,默认值为 false。
    @"sandbox": @"true", // 设置沙箱环境。如果将其置空,则默认使用线上正式环境。
    @"merchantAppointParam": merchantAppointParam,
    @"notRedirectAfterComplete": @"true"  // 设置付款完成后不跳转,由您控制后续流程。
    };
componentConfig.options = options;

[[AMSCashierPayment shared] initConfiguration:componentConfig];

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

3. 调用 SDK

调用 createComponent 方法:
参数名称
是否必需
描述
sessionData
是
使用 sessionData 参数创建配置对象:将通过 createPaymentSession(单笔支付)接口在响应中获取的完整 paymentSessionData 参数传递给 sessionData 。
在以下情况下调用 onDestroy 方法释放 SDK 组件资源:
以下示例代码展示了如何调用 SDK:
objectivec
[[AMSCashierPayment shared] createComponent:sessionData];

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

弹窗体验与嵌入式体验

您可以通过弹窗或嵌入页面的方式在页面上展示 SDK。
弹窗体验
弹窗体验的优势在于对页面样式影响较小,流程相对独立。
当买家在页面上选择支付方式并点击提交后,您需要调用 SDK 并弹出窗口。
javascript
[[AMSCashierPayment shared] createComponent:sessionData];
嵌入式体验
嵌入式体验将支付元素嵌入到指定视图中,您需关注支付列表的样式调整。嵌入内容的宽度会自动适应父容器,而高度会随着视图变化动态更新。
javascript
self.checkoutView = [[AMSCashierPayment shared] mountComponent:paymentSessionData];
嵌入式提交支付
调用实例对象中的 submit() 函数:
  • 调用该函数,可触发支付提交流程,返回特定事件码。这些事件码也会通过 onError 或 onEventCallback 等函数返回。
  • 如果您需要传入提前收集好的 billing address 信息用于 AVS 验证,您可配置如下参数通过 submit 函数传入。
  • billingAddress:选传,Object 类型。用来识别付款人身份和位置的账单地址信息。包含如下参数:
  • region:必传,String (2)。遵循 ISO 3166 标准的二位字母的国家或地区代码。
  • address1:选传,String (256)。地址行 1,例如街道地址、邮政信箱和公司名称。
  • address2:选传,String (256)。地址行 2,例如公寓、套房、单元和建筑物信息。
  • city:选传,String (32)。城市、地区、郊区、城镇或村庄名称。
  • state:选传,String (8)。州、国家或省名称。
  • zipCode:选传,String (32)。邮政编码。
objectivec
// 用户输入完成支付
NSString *dataString = @"{"billingAddress":{"zipCode":"310000","region":"CN"}}";

[[AMSCashierPayment shared] submit: dataString];

4. 展示支付结果

支付结果将通过 onEventCallback 函数返回。这里的支付结果仅用于前端展示,最终订单状态以服务器端为准。您需要通过 onEventCallback 返回的数据自定义每个支付结果的处理流程。
以下是 onEventCallback 的支付结果可能返回的事件码:
事件码
信息
解决方案
SDK_PAYMENT_SUCCESSFUL
支付成功。
建议将买家重定向到支付结果页面,随后与服务器确认支付结果。
SDK_PAYMENT_PROCESSING
支付正在处理中。
建议与服务器确认支付结果。如果支付成功,将买家重定向到支付结果页面;如果支付失败,引导买家重新尝试支付。
SDK_PAYMENT_FAIL
支付失败。
建议您检查在 onEventCallback 结果数据中 result.paymentResultCode 的值以获取详细信息。根据获得的信息,引导买家重新尝试支付。
注意:请参阅支付失败或异常说明,以获取 result.paymentResultCode 的含义。
SDK_PAYMENT_CANCEL
支付被取消。
建议使用在有效期内的 paymentSessionData 重新调用 SDK;如果已过期,则需要重新请求 paymentSessionData。
SDK_PAYMENT_ERROR
支付状态异常。
建议与服务器确认支付结果。如果确认支付失败,引导买家重新尝试支付。
以下示例代码展示了如何处理回调函数 onEventCallback:
objectivec
#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 参数中指定的地址发送异步通知(notifyPayment)。收到 Antom 的通知后,您需要按照返回收到确认信息的格式返回响应。
Antom 允许您在 createPaymentSession(单笔支付)接口的 paymentNotifyUrl 参数中指定地址。如果每个支付的地址相同,您也可以在 Antom Dashboard 中配置该地址。
以下代码展示了通知请求的示例:
json
{
  "actualPaymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "cardInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "XXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "notifyType": "PAYMENT_RESULT",
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentCreateTime": "2024-01-01T00:00:00+08:00",
  "paymentId": "20240101123456789XXXX",
  "paymentRequestId": "paymentRequestId01",
  "paymentResultInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "XXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentTime": "2024-01-01T00:01:00+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
如何验证通知的签名并做出响应,请参阅签名和验签。
常见问题
问:何时会发送通知?
答:这取决于支付是否完成:
  • 如果支付成功完成,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 接口来发起对订单结果的查询。
参数名称
是否必需
描述
paymentRequestId
否
由商户生成的支付请求 ID。
完整的参数集,请参考 inquiryPayment 接口文档,获取全部参数及特定支付方式的额外要求。
以下示例代码展示了如何调用 inquiryPayment 接口:
java
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();
    // 处理错误情况
  }
}
以下代码展示了请求报文的示例:
json
{
  "paymentRequestId": "paymentRequestId01"
}
以下代码展示了响应报文的示例:
json
{
  "authExpiryTime": "2024-01-08T00:01:00+08:00",
  "cardInfo": {
    "cardBrand": "MASTERCARD",
    "funding": "DEBIT",
    "issuingCountry": "US"
  },
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentId": "20240101123456789XXXX",
  "paymentMethodType": "CARD",
  "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
  "paymentRequestId": "paymentRequestId01",
  "paymentResultCode": "SUCCESS",
  "paymentResultInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "networkTransIdXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentResultMessage": "success",
  "paymentStatus": "SUCCESS",
  "paymentTime": "2024-01-01T00:01:00+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
常见问题
问:我应该多久调用一次 inquiryPayment 接口?
答:以 2 秒的间隔持续调用 inquiryPayment 接口,直到获取最终的支付结果或收到异步支付结果通知为止。

问:我在通知中需要使用哪些关键参数?
答:请注意以下关键参数:
  • result:表示此 inquiryPayment 接口调用的结果,需要根据 paymentStatus 来判断订单状态:
  • SUCCESS 和 FAIL 表示最终结果。
  • PROCESSING 表示处理中。
  • paymentAmount:表示支付的金额。

步骤 4:获取请款结果
服务端

在商户完成请款或请款超时后,Antom 会通过服务器交互将相应的请款结果发送给您,您可以通过以下方法之一获取请款结果:
  • 接收异步通知
  • 查询结果

接收异步通知

请款成功或失败时,Antom 会向您在 createPaymentSession(单笔支付)接口的 paymentNotifyUrl 参数中指定的地址发送异步通知(notifyPayment)。收到 Antom 的通知后,您需要按照返回收到确认信息返回响应。
Antom允许您在 createPaymentSession(单笔支付)接口的 paymentNotifyUrl 参数中指定地址。如果每个支付的地址相同,您也可以在 Antom Dashboard 中配置该地址。
以下代码展示了请款成功的示例:
json
{
  "captureAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "notifyType": "CAPTURE_RESULT",
  "captureId": "20240101987654321XXXX",
  "captureRequestId": "captureRequestId01",
  "captureTime": "2024-01-01T00:00:02+08:00",
  "paymentId": "20240101123456789XXXX",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
以下代码展示了请款失败的示例:
json
{
  "captureAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "notifyType": "CAPTURE_RESULT",
  "captureId": "20240101123456789XXXX",
  "captureRequestId": "captureRequestId01",
  "captureTime": "2024-01-01T00:00:02+08:00",
  "paymentId": "20240101123456789XXXX",
  "result": {
    "resultCode": "PROCESS_FAIL",
    "resultMessage": "fail.",
    "resultStatus": "F"
  }
}
如何验证通知的签名并做出响应,请参阅签名与验签。
常见问题
问:异步通知会被重新发送吗?
答:是的,对于以下情况,异步通知将在 24 小时内自动重新发送:
  • 如果您因网络原因未收到异步通知。
  • 如果您收到来自 Antom 的异步通知,但您没有按照处理通知的示例代码格式进行响应。
通知最多可以重发 8 次,或者直到收到正确的响应以终止发送。发送间隔为:0 分钟,2 分钟,10 分钟,10 分钟,1 小时,2 小时,6 小时和 15 小时。
​
问:在响应异步通知时,我需要添加数字签名吗?
答:如果您收到来自 Antom 的异步通知,您需要按照处理通知的示例代码格式返回响应,但不需要对响应进行签名。
​
问:我需要使用通知中的哪些关键参数?
答:请注意以下关键参数:
  • result:表示订单的请款结果。
  • notifyType:通知类型为 CAPTURE_RESULT。
  • paymentRequestId:您生成的支付请求 ID,用于查询、取消和对账。
  • paymentId:Antom 生成的支付订单 ID,用于退款和对账。
  • acquirerReferenceNo:集成新加坡和香港内银行卡支付服务的商户将在通知中收到特定的收单机构 ID。

查询结果

您可以调用 inquiryPayment 接口来发起对订单结果的查询。
参数名称
是否必需
描述
paymentRequestId
否
由商户生成的支付请求 ID。
有关完整参数集,请参阅 inquiryPayment 接口,获取完整的参数列表以及某些支付方式的额外要求。
以下示例代码展示了如何调用 inquiryPayment 接口:
java
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();
    // 处理错误情况
  }
}
以下是请求报文的示例:
json
{
  "paymentRequestId": "paymentRequestId01"
}

请款状态的值

接口响应中的 transactions 字段值表示请款状态:
参数名称
描述
transactions.transactionType
值为 CAPTURE,表示请款状态。
transactions.transactionResult
请款状态。
以下代码展示了请款成功的示例:
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success"
      }
    }
  ]
}
以下代码展示了请款失败的示例:
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "F",
        "resultCode": "PROCESS_FAIL",
        "resultMessage": "General business failure. No retry."
      }
    }
  ]
}
以下代码展示了请款处理中的示例:
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "U",
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "payment in process"
      }
    }
  ]
}
常见问题
问:我应该多久调用一次 inquiryPayment 接口?
答:以 2 秒的间隔持续调用 inquiryPayment 接口,直到获取最终的支付结果或收到异步支付结果通知。

示例代码

前端完整示例代码:
objectivec
#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";
NSString *merchantAppointParam = @"{ \"storedCard\": { \"needCVV\": true } }"; 
NSDictionary *options = @{
    // 设置沙箱环境。如果将其置空,则默认使用线上正式环境。
    @"sandbox": @"true", 
    // 卡支付场景需要 cvv 校验。
    @"merchantAppointParam": merchantAppointParam,
    // 设置付款完成后不跳转,由您控制后续流程。
    @"notRedirectAfterComplete": @"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 回调函数返回。
类型
代码
描述
后续操作
状态码
SDK_FORM_VERIFICATION_FAILED
表单提交后,验证失败。
引导买家确认输入并重新尝试支付。
Android

用户体验

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

支付流程

对于每种支付方式,支付流程包括以下步骤:
  1. 买家进入结账页面。
  2. 创建支付会话请求。
    买家选择支付方式并提交订单后,您可以通过调用 createPaymentSession(单笔支付)接口获取支付会话。
  3. 调用客户端 SDK。
    在客户端,通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码展示、验证等流程。随后,SDK 将通过 OnCheckoutListener 回调支付结果。
  4. 确认支付结果。
    通过以下两种方法之一获取支付结果:
  5. 获取请款结果。
    对于银行卡支付,通过以下两种方法之一获取请款结果:

集成准备

在您开始集成前,请阅读集成指南及接口概述文档,了解服务端接口的集成步骤及调用接口的注意事项,并确保已完成以下预配置:
  • 已获得 client ID。
  • 已完成密钥配置。
  • 已完成异步通知接收地址的配置。
  • 集成 Antom 服务端 SDK 资源包,并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
  • 参阅 Android 端集成 SDK 资源包文档来集成客户端 SDK 资源包。
注意:暂不支持 ‌Flutter 和 React Native(RN)开发框架。

集成步骤

请按照以下步骤开始集成:
  1. 创建支付会话
  2. 创建并调用 SDK
  3. 获取支付结果
  4. 获取请款结果

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

当买家选择 Antom 提供的支付方式时,您需要收集关键信息,如支付请求 ID、订单金额、支付方式、订单描述、支付重定向链接和支付结果通知链接,调用 createPaymentSession(单笔支付)接口来创建支付会话,并将支付会话返回给客户端。
创建支付会话包含以下参数:
参数名称
是否必需
描述
productCode
是
表示合同中规定的所使用的支付产品。对于单笔支付,此值设置为 CASHIER_PAYMENT。
paymentRequestId
是
商户为识别支付请求而分配的专属 ID。
paymentAmount
是
商户请求以订单币种收取的支付金额。
paymentMethod
是
商户或收单机构用于收款的支付方式。
paymentRedirectUrl
是
支付完成后,买家被重定向到的商户页面链接。
order
是
包括买家、商户、商品、金额、配送信息和购买环境的订单信息。
paymentNotifyUrl
否
支付结果通知地址,可通过接口传递,也可通过 Antom Dashboard 设置为固定值。
settlementStrategy
否
支付请求的结算策略。
paymentFactor.isAuthorization
否
表示支付场景是否为授权场景。当 paymentMethodType 的值为 CARD 时,请将此参数的值设为 true,表示支付场景需要授权。
注意:当此参数的值为 true 时,支付资金在支付方式端被保全并冻结,您可以使用 capture(单笔支付)接口扣除支付资金。
以上参数是创建支付会话的基本参数,完整参数和特定支付方式的额外要求请参考 createPaymentSession(单笔支付)。
以下示例代码展示了如何调用 createPaymentSession(单笔支付)接口:
java
public static void createCardPaymentSession() {
  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("CARD").build();
  alipayPaymentSessionRequest.setPaymentMethod(paymentMethod);

  // 设置授权请款支付模式
  PaymentFactor paymentFactor = PaymentFactor.builder().isAuthorization(true).build();
  alipayPaymentSessionRequest.setPaymentFactor(paymentFactor);

  // 替换为您的 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();
    // 处理错误情况
  }
}
以下代码展示了一个请求报文的示例:
json
{
  "order": {
    "buyer": {
      "referenceBuyerId": "yourBuyerId"
    },
    "orderAmount": {
      "currency": "SGD",
      "value": "4200"
    },
    "orderDescription": "antom testing order",
    "referenceOrderId": "referenceOrderId01"
  },
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentFactor": {
    "isAuthorization": true
  },
  "paymentMethod": {
    "paymentMethodType": "CARD"
  },
  "paymentNotifyUrl": "https://www.yourNotifyUrl.com",
  "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
  "paymentRequestId": "paymentRequestId01",
  "productCode": "CASHIER_PAYMENT"
}
以下代码展示了一个响应的示例,其中包含以下参数:
  • paymentSessionData:需要返回给前端的支付会话数据。
  • paymentSessionExpiryTime:支付会话的过期时间。
json
{
  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
  "paymentSessionExpiryTime": "2024-01-01T00:00:00+08:00",
  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
常见问题
问:请求参数的值可以使用中文字符吗?
答:为了避免特定支付方式的兼容性问题,请求中的字段请勿使用中文字符。

问:如何设置接收支付通知的地址?
答:在 createPaymentSession(单笔支付)接口中指定 paymentNotifyUrl 字段,以接收支付结果的异步通知(notifyPayment),或者在 Antom Dashboard 中配置接收地址。如果请求和 Antom Dashboard 中都指定了地址,请求中的值优先。

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

Antom SDK 是用于处理支付流程的组件,被会话唤起的组件根据 createPaymentSession(单笔支付)接口中指定的支付方式,进行信息收集、唤端、展示二维码等流程。
当买家在页面上选择支付方式后,您需要创建并使用支付会话初始化 SDK。

1.(可选)预加载 SDK

在创建支付会话前,强烈建议您预加载 SDK,以提升收银台页面的渲染速度,减少买家在支付过程中的等待时间。
调用 createComponent 方法:
参数名称
是否必需
描述
context
是
Android 应用上下文对象。
按照以下代码示例执行预加载操作:
java
AMSCashierPayment.preload(context.getApplicationContext());

2. 初始化 SDK

使用 AMSCashierPayment 创建 SDK 实例并指定基本配置。创建配置对象包括以下方法:
参数名称
是否必需
描述
setLocale
否
用于传递语言信息。有效值如下所示。您可以根据支付方式的地区选择要传递的值。如果传入其他值,默认使用英语:
  • "en", "US":英语
  • "es", "ES":西班牙语
  • "fr", "FR":法语
  • "nl", "NL":荷兰语
  • "it", "IT":意大利语
  • "de", "DE":德语
  • "zh", "CN":简体中文
  • "zh", "HK":繁体中文
  • "pt", "PT":葡萄牙语(葡萄牙)
  • "ro":罗马尼亚语
  • "pl", "PL":波兰语
setOption
否
用于自定义外观主题和功能以及是否使用沙箱环境。有效值包括:
  • "showSubmitButton":选传,Boolean 类型。默认值为 false,表示不启用由 SDK 组件渲染支付按钮。true 表示由 SDK 组件渲染支付按钮。若设定该值为 false,则需要调用实例对象中 submit() 函数触发提交支付流程。该参数仅适用于嵌入式体验。
  • "sandbox", "true":沙箱环境
  • "sandbox", "false":生产环境
  • "notRedirectAfterComplete", "true":选传,Boolean 类型。默认值为 false,表示支付完成后跳回您的页面,当值为空时同理。值为 true 表示支付完成后不跳转,您需要通过客户事件码自行控制绑卡完成后续流程。请注意,客户端返回的支付结果事件码仅用于客户端页面的跳转操作参考,交易状态的更新请以服务端 notifyPayment 或 inquiryPayment 接口返回结果为准。
  • "merchantAppointParam":选传,JSONString 类型。用于自定义功能设置,包含以下参数:
  • storedCard:选传,Object 类型。用于已存卡情况下的自定义功能设置,包含以下参数:
  • needCVV:选传,Boolean 类型。默认值为 false,表示在支付过程中无需用户输入 CVV 校验,当值为空时同理。若设定该值为 true ,则表示在支付过程中需要用户输入 CVV 校验。
setOnCheckoutListener
否
创建一个 结账监听器 接口的实例,用于后续流程中的事件处理。该接口包含以下方法:
  • onEventCallback:必传。一个回调函数,用于监听结账页面上的支付事件,返回 eventCode 和 eventResult。
注意:每个实例只能处理一个支付会话。建议在每次调用 createComponent 之前先创建实例。
以下示例代码展示了如何初始化 SDK:
java
AMSCashierPaymentConfiguration configuration = new AMSCashierPaymentConfiguration();
configuration.setLocale(new Locale("en", "US"));
// 设置沙箱环境。如果将其置空,则默认使用线上正式环境。
configuration.setOption("sandbox", "true");
// 设置强制用户输入 CVV 校验。
configuration.setOption("merchantAppointParam", "{ \"storedCard\": { \"needCVV\": 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 方法:
参数名称
是否必需
描述
sessionData
是
使用 sessionData 参数创建配置对象:将通过 createPaymentSession(单笔支付)接口在响应中获取的完整 paymentSessionData 参数传递给 sessionData 。
在以下情况下调用 onDestroy 方法释放 SDK 组件资源:
以下示例代码展示了如何调用 SDK:
java
checkout.createComponent(activity, sessionData);

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

弹窗体验与嵌入式体验

您可以通过弹窗或嵌入页面的方式在页面上展示 SDK。
弹窗体验
弹窗体验的优势在于对页面样式影响较小,流程相对独立。
当买家在页面上选择支付方式并点击提交后,您需要调用 SDK 并弹出窗口。
javascript
checkout.createComponent(activity, sessionData);
嵌入式体验
嵌入式体验将支付元素嵌入到指定视图中,您需关注支付列表的样式调整。嵌入内容的宽度会自动适应父容器,而高度会随着视图变化动态更新。
javascript
Map<String, Object> appearanceConfig = new HashMap<>();
appearanceConfig.put("showSubmitButton", false);
AMSPaymentAppearance appearance = AMSPaymentAppearance.create(appearanceConfig);
checkout.mountComponent(activity, appearance, sessionData, parentViewGroup);
嵌入式提交支付
调用实例对象中的 submit() 函数:
  • 调用该函数,可触发支付提交流程,返回特定事件码。这些事件码也会通过 onEventCallback 等函数返回。
  • 如果您需要传入提前收集好的 billing address 信息用于 AVS 验证,您可配置如下参数通过 submit 函数传入。
  • billingAddress:选传,Object 类型。用来识别付款人身份和位置的账单地址信息。包含如下参数:
  • region:必传,String (2)。遵循 ISO 3166 标准的二位字母的国家或地区代码。
  • address1:选传,String (256)。地址行 1,例如街道地址、邮政信箱和公司名称。
  • address2:选传,String (256)。地址行 2,例如公寓、套房、单元和建筑物信息。
  • city:选传,String (32)。城市、地区、郊区、城镇或村庄名称。
  • state:选传,String (8)。州、国家或省名称。
  • zipCode:选传,String (32)。邮政编码。
java
let dataString = '{"billingAddress":{"zipCode":"310000","region":"CN"}}';

// 用户输入完成提交绑定。
checkout.submit(dataString);

4. 展示支付结果

支付结果将通过 onEventCallback 函数返回。这里的支付结果仅用于前端展示,最终订单状态以服务器端为准。您需要通过 onEventCallback 返回的数据自定义每个支付结果的处理流程。
以下是 onEventCallback 的支付结果可能返回的事件码:
事件码
信息
解决方案
SDK_PAYMENT_SUCCESSFUL
支付成功。
建议将买家重定向到支付结果页面,随后与服务器确认支付结果。
SDK_PAYMENT_PROCESSING
支付正在处理中。
建议与服务器确认支付结果。如果支付成功,将买家重定向到支付结果页面;如果支付失败,引导买家重新尝试支付。
SDK_PAYMENT_FAIL
支付失败。
建议您检查在 onEventCallback 结果数据中 result.paymentResultCode 的值以获取详细信息。根据获得的信息,引导买家重新尝试支付。
注意:请参阅支付失败或异常说明,以获取 result.paymentResultCode 的含义。
SDK_PAYMENT_CANCEL
支付被取消。
建议使用在有效期内的 paymentSessionData 重新调用 SDK;如果已过期,则需要重新请求 paymentSessionData。
SDK_PAYMENT_ERROR
支付状态异常。
建议与服务器确认支付结果。如果确认支付失败,引导买家重新尝试支付。
以下示例代码展示了如何处理 onEventCallback 事件:
java
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()
      );

      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)) {
          // 支付状态异常。建议与服务器确认支付结果。如果确认支付失败,引导买家重新尝试支付。
        }
      }
    }
  }
);
// 实例化 AMSCashierPayment。
AMSCashierPayment checkout = new AMSCashierPayment.Builder(activity, configuration).build();

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

在商户完成请款或请款超时后,Antom 会通过服务器交互将相应的支付结果发送给您,您可以通过以下方法之一获取支付结果:
  • 接收异步通知
  • 查询结果

接收异步通知

当支付成功或失败时,Antom 会向您在 createPaymentSession(单笔支付)接口的 paymentNotifyUrl 参数中指定的地址发送异步通知(notifyPayment)。收到 Antom 的通知后,您需要按照返回收到确认信息的格式返回响应。
Antom 允许您在 createPaymentSession(单笔支付)接口的 paymentNotifyUrl 参数中指定地址。如果每个支付的地址相同,您也可以在 Antom Dashboard 中配置该地址。
以下代码展示了通知请求的示例:
json
{
  "actualPaymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "cardInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "XXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "notifyType": "PAYMENT_RESULT",
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentCreateTime": "2024-01-01T00:00:00+08:00",
  "paymentId": "20240101123456789XXXX",
  "paymentRequestId": "paymentRequestId01",
  "paymentResultInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "XXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentTime": "2024-01-01T00:01:00+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
如何验证通知的签名并做出响应,请参阅签名和验签。
常见问题
问:何时会发送通知?
答:这取决于支付是否完成:
  • 如果支付成功完成,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 接口来发起对订单结果的查询。
参数名称
是否必需
描述
paymentRequestId
否
由商户生成的支付请求 ID。
完整的参数集,请参考 inquiryPayment 接口文档,获取全部参数及特定支付方式的额外要求。
以下示例代码展示了如何调用 inquiryPayment 接口:
java
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();
    // 处理错误情况
  }
}
以下代码展示了请求报文的示例:
json
{
  "paymentRequestId": "paymentRequestId01"
}
以下代码展示了响应报文的示例:
json
{
  "authExpiryTime": "2024-01-08T00:01:00+08:00",
  "cardInfo": {
    "cardBrand": "MASTERCARD",
    "funding": "DEBIT",
    "issuingCountry": "US"
  },
  "paymentAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "paymentId": "20240101123456789XXXX",
  "paymentMethodType": "CARD",
  "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
  "paymentRequestId": "paymentRequestId01",
  "paymentResultCode": "SUCCESS",
  "paymentResultInfo": {
    "avsResultRaw": "A",
    "cardBrand": "MASTERCARD",
    "cardNo": "****************",
    "cvvResultRaw": "Y",
    "funding": "DEBIT",
    "issuingCountry": "US",
    "networkTransactionId": "networkTransIdXXXX",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "eci": ""
    }
  },
  "paymentResultMessage": "success",
  "paymentStatus": "SUCCESS",
  "paymentTime": "2024-01-01T00:01:00+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
常见问题
问:我应该多久调用一次 inquiryPayment 接口?
答:以 2 秒的间隔持续调用 inquiryPayment 接口,直到获取最终的支付结果或收到异步支付结果通知为止。

问:我在通知中需要使用哪些关键参数?
答:请注意以下关键参数:
  • result:表示此 inquiryPayment 接口调用的结果,需要根据 paymentStatus 来判断订单状态:
  • SUCCESS 和 FAIL 表示最终结果。
  • PROCESSING 表示处理中。
  • paymentAmount:表示支付的金额。

步骤 4:获取请款结果
服务端

在商户完成请款或请款超时后,Antom 会通过服务器交互将相应的请款结果发送给您,您可以通过以下方法之一获取请款结果:
  • 接收异步通知
  • 查询结果

接收异步通知

请款成功或失败时,Antom 会向您在 createPaymentSession(单笔支付)接口的 paymentNotifyUrl 参数中指定的地址发送异步通知(notifyPayment)。收到 Antom 的通知后,您需要按照返回收到确认信息返回响应。
Antom允许您在 createPaymentSession(单笔支付)接口的 paymentNotifyUrl 参数中指定地址。如果每个支付的地址相同,您也可以在 Antom Dashboard 中配置该地址。
以下代码展示了请款成功的示例:
json
{
  "captureAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "notifyType": "CAPTURE_RESULT",
  "captureId": "20240101987654321XXXX",
  "captureRequestId": "captureRequestId01",
  "captureTime": "2024-01-01T00:00:02+08:00",
  "paymentId": "20240101123456789XXXX",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
以下代码展示了请款失败的示例:
json
{
  "captureAmount": {
    "currency": "SGD",
    "value": "4200"
  },
  "notifyType": "CAPTURE_RESULT",
  "captureId": "20240101123456789XXXX",
  "captureRequestId": "captureRequestId01",
  "captureTime": "2024-01-01T00:00:02+08:00",
  "paymentId": "20240101123456789XXXX",
  "result": {
    "resultCode": "PROCESS_FAIL",
    "resultMessage": "fail.",
    "resultStatus": "F"
  }
}
如何验证通知的签名并做出响应,请参阅签名与验签。
常见问题
问:异步通知会被重新发送吗?
答:是的,对于以下情况,异步通知将在 24 小时内自动重新发送:
  • 如果您因网络原因未收到异步通知。
  • 如果您收到来自 Antom 的异步通知,但您没有按照处理通知的示例代码格式进行响应。
通知最多可以重发 8 次,或者直到收到正确的响应以终止发送。发送间隔为:0 分钟,2 分钟,10 分钟,10 分钟,1 小时,2 小时,6 小时和 15 小时。
​
问:在响应异步通知时,我需要添加数字签名吗?
答:如果您收到来自 Antom 的异步通知,您需要按照处理通知的示例代码格式返回响应,但不需要对响应进行签名。
​
问:我需要使用通知中的哪些关键参数?
答:请注意以下关键参数:
  • result:表示订单的请款结果。
  • notifyType:通知类型为 CAPTURE_RESULT。
  • paymentRequestId:您生成的支付请求 ID,用于查询、取消和对账。
  • paymentId:Antom 生成的支付订单 ID,用于退款和对账。
  • acquirerReferenceNo:集成新加坡和香港内银行卡支付服务的商户将在通知中收到特定的收单机构 ID。

查询结果

您可以调用 inquiryPayment 接口来发起对订单结果的查询。
参数名称
是否必需
描述
paymentRequestId
否
由商户生成的支付请求 ID。
有关完整参数集,请参阅 inquiryPayment 接口,获取完整的参数列表以及某些支付方式的额外要求。
以下示例代码展示了如何调用 inquiryPayment 接口:
java
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();
    // 处理错误情况
  }
}
以下是请求报文的示例:
json
{
  "paymentRequestId": "paymentRequestId01"
}

请款状态的值

接口响应中的 transactions 字段值表示请款状态:
参数名称
描述
transactions.transactionType
值为 CAPTURE,表示请款状态。
transactions.transactionResult
请款状态。
以下代码展示了请款成功的示例:
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success"
      }
    }
  ]
}
以下代码展示了请款失败的示例:
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "F",
        "resultCode": "PROCESS_FAIL",
        "resultMessage": "General business failure. No retry."
      }
    }
  ]
}
以下代码展示了请款处理中的示例:
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "captureRequestId01",
      "transactionAmount": {
        "currency": "SGD",
        "value": "4200"
      },
      "transactionTime": "2024-01-01T00:00:02+08:00",
      "transactionId": "20240101123456789XXXX",
      "transactionResult": {
        "resultStatus": "U",
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "payment in process"
      }
    }
  ]
}
常见问题
问:我应该多久调用一次 inquiryPayment 接口?
答:以 2 秒的间隔持续调用 inquiryPayment 接口,直到获取最终的支付结果或收到异步支付结果通知。

示例代码

前端完整示例代码:
java
//(可选)预加载 SDK。在创建支付会话前预加载 SDK,以提升收银台页面的渲染速度,减少买家在支付过程中的等待时间。
AMSCashierPayment.preload(context);

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

// 步骤二:创建 AMSCashierPaymentConfiguration 类。
AMSCashierPaymentConfiguration configuration = new AMSCashierPaymentConfiguration();
configuration.setLocale(new Locale("en", "US"));
// 设置沙箱环境。如果将其置空,则默认使用线上正式环境。
configuration.setOption("sandbox", "true");
// 设置支付完成后不跳转,由商户控制后续流程。
configuration.setOption("notRedirectAfterComplete", "true");
// 设置强制用户输入 CVV 校验。
configuration.setOption("merchantAppointParam", "{ \"storedCard\": { \"needCVV\": true } }");
// 配置支付按钮是否由 SDK 组件呈现。
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, paymentSessionData);

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

事件码

状态码:在组件运行生命周期内,通过 onEventCallback 回调函数返回。
类型
代码
描述
后续操作
状态码
SDK_FORM_VERIFICATION_FAILED
表单提交后,验证失败。
引导买家确认输入并重新尝试支付。