银行卡支付
下架通知：
本指南内容已停止更新。
建议您采用 Payment Element 集成方式，以获得更优的集成体验。
建议您采用 Payment Element 集成方式，以获得更优的集成体验。
Antom SDK 是一个预构建的用户界面组件，用于收集银行卡信息并为您处理 3D 验证流程。集成此组件不需要您具有 PCI 认证，非常适合那些希望委托 Antom 来收集银行卡信息的用户。
Web/WAP
iOS
Android
用户体验
以下图表展示了在购物网站或移动网页应用上支付的用户流程：
Web
WAP
支付流程
以下流程说明了如何通过 Antom SDK 集成单笔支付：
- 买家进入结账页面。
- 创建支付会话请求。
买家选择支付方式并提交订单后，您可以通过调用 createPaymentSession（单笔支付）接口获取支付会话。 - 调用客户端 SDK。
在客户端，通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码展示、验证等流程。随后，SDK 将通过onEventCallback回调支付结果。 - 确认支付结果。
通过以下两种方法之一获取支付结果： - 异步通知：在 createPaymentSession（单笔支付）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付成功或过期时，Antom 会使用 notifyPayment 向您发送异步通知。
- 获取请款结果。
对于银行卡支付，通过以下两种方法之一获取请款结果： - 异步通知：在 createPaymentSession（单笔支付）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付请求成功或过期时，Antom 会使用 notifyCapture（单笔支付）向您发送异步通知。
集成准备
- 已获得 client ID。
- 已完成密钥配置。
- 已完成异步通知接收地址的配置。
- 集成 Antom 服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
- 参阅 Web/WAP 端集成 SDK 资源包文档来集成客户端 SDK 资源包。
集成步骤
请按照以下步骤开始集成：
- 创建支付会话
- 创建并调用 SDK
- 获取支付结果
- 获取请款结果
步骤 1：创建支付会话 服务端
当买家选择 Antom 提供的支付方式时，您需要收集关键信息，如支付请求 ID、订单金额、支付方式、订单描述、支付重定向链接和支付结果通知链接，调用 createPaymentSession（单笔支付）接口来创建支付会话，并将支付会话返回给客户端。
创建支付会话包含以下参数：
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();
// 处理错误情况
}
}
以下代码展示了一个请求报文的示例：
{
"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：支付会话的过期时间。
{
"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 客户端
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
当买家在页面上选择支付方式后，您需要创建 SDK 并使用支付会话进行初始化。
使用实例对象中的
createComponent
或 mountComponent
函数来创建支付组件：弹窗体验与嵌入式体验
您可以通过弹窗或嵌入页面的方式在页面上展示 SDK。
弹窗体验
嵌入式体验
弹窗体验的优势在于对页面样式影响较小，流程相对独立。
当买家在页面上选择支付方式并点击提交后，您需要调用 SDK 并弹出窗口。
async function create(sessionData) {
await checkoutApp.createComponent({
sessionData: sessionData,
notRedirectAfterComplete: true,
});
}
嵌入式体验将支付元素嵌入到指定视图中，您需关注支付列表的样式调整。嵌入内容的宽度会自动适应父容器，而高度会随着视图变化动态更新。
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)。邮政编码。
// 用户输入地址信息并存储在 billingAddress 对象中，用于后续提交。
const billingAddress = {
region: '',
address1: '',
address2: '',
city: '',
state: '',
zipCode: ''
}
// 当用户完成表单填写，点击提交按钮时执行。
checkoutApp.submit({billingAddress}).then(({code, message})=>{})销毁组件
在以下情况下，调用
unmount
方法来释放 SDK 组件资源：- 当买家切换视图离开结账页面时，释放 createPaymentSession（单笔支付）中创建的组件资源。
- 当买家发起多次支付时，释放之前 createPaymentSession（单笔支付）中创建的组件资源。
- 当买家完成支付并设置 notRedirectAfterComplete 为 true时，在获取特定支付结果代码后释放组件资源。
// 释放 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
的支付结果可能返回的事件码：以下示例代码展示了如何处理回调函数
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 中配置该地址。
以下代码展示了通知请求的示例：
{
"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 小时。
问：在响应异步通知时，我需要添加数字签名吗？
问：我在通知中需要使用哪些关键参数？
答：请注意以下关键参数：
- result：表示订单的支付结果。
- paymentRequestId：用于咨询、取消和对账的支付请求 ID。
- paymentId：表示由 Antom 生成的支付订单 ID，用于退款和对账。
- paymentAmount：表示支付金额。
查询结果
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"
}
以下代码展示了响应报文的示例：
{
"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 接口？
问：我在通知中需要使用哪些关键参数？
答：请注意以下关键参数：
- result：表示此 inquiryPayment 接口调用的结果，需要根据 paymentStatus 来判断订单状态：
- SUCCESS和FAIL表示最终结果。
- PROCESSING表示处理中。
- paymentAmount：表示支付的金额。
步骤 4：获取请款结果 服务端
在商户完成请款或请款超时后，Antom 会通过服务器交互将相应的请款结果发送给您，您可以通过以下方法之一获取请款结果：
- 接收异步通知
- 查询结果
接收异步通知
请款成功或失败时，Antom 会向您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定的地址发送异步通知（notifyPayment）。收到 Antom 的通知后，您需要按照返回收到确认信息返回响应。
Antom允许您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定链接。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。
以下代码展示了请款成功的示例：
{
"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"
}
}以下代码展示了请款失败的示例：
{
"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 小时。
问：在响应异步通知时，我需要添加数字签名吗？
问：我需要使用通知中的哪些关键参数？
答：请注意以下关键参数：
- result：表示订单的请款结果。
- notifyType：通知类型为 CAPTURE_RESULT。
- paymentRequestId：您生成的支付请求 ID，用于查询、取消和对账。
- paymentId：Antom 生成的支付订单 ID，用于退款和对账。
- acquirerReferenceNo：集成新加坡和香港内银行卡支付服务的商户将在通知中收到特定的收单机构 ID。
查询结果
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"
}请款状态的值
接口响应中的 transactions 字段值表示请款状态：
以下代码展示了请款成功的示例：
{
"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"
}
}
]
}以下代码展示了请款失败的示例：
{
"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."
}
}
]
}以下代码展示了请款处理中的示例：
{
"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"
}
}
]
}示例代码
前端完整示例代码：
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
回调函数返回。用户体验
以下图表展示了在应用程序中支付的用户流程：
支付流程
对于每种支付方式，支付流程包括以下步骤：
- 买家进入结账页面。
- 创建支付会话请求。
买家选择支付方式并提交订单后，您可以通过调用 createPaymentSession（单笔支付）接口获取支付会话。 - 调用客户端 SDK。
在客户端，通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码展示、验证等流程。随后，SDK 将通过onEventCallback回调支付结果。 - 确认支付结果。
通过以下两种方法之一获取支付结果： - 异步通知：在 createPaymentSession（单笔支付）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付成功或过期时，Antom 会使用 notifyPayment 向您发送异步通知。
- 获取请款结果。
对于银行卡支付，通过以下两种方法之一获取请款结果： - 异步通知：在 createPaymentSession（单笔支付）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付请求成功或过期时，Antom 会使用 notifyCapture（单笔支付）向您发送异步通知。
集成准备
- 已获得 client ID。
- 已完成密钥配置。
- 已完成异步通知接收地址的配置。
- 集成 Antom 服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
- 参阅 iOS 端集成 SDK 资源包文档来集成客户端 SDK 资源包。
注意：暂不支持 Flutter 和 React Native（RN）开发框架。
集成步骤
请按照以下步骤开始集成：
- 创建支付会话
- 创建并调用 SDK
- 获取支付结果
- 获取请款结果
步骤 1：创建支付会话 服务端
当买家选择 Antom 提供的支付方式时，您需要收集关键信息，如支付请求 ID、订单金额、支付方式、订单描述、支付重定向链接和支付结果通知链接，调用 createPaymentSession（单笔支付）接口来创建支付会话，并将支付会话返回给客户端。
创建支付会话包含以下参数：
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();
// 处理错误情况
}
}
以下代码展示了一个请求报文的示例：
{
"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：支付会话的过期时间。
{
"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 客户端
当买家在页面上选择支付方式后，您需要创建并使用支付会话初始化 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";
// 卡支付场景需要进行 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
方法：在以下情况下调用
onDestroy
方法释放 SDK 组件资源：- 当买家离开支付页面时，释放 createPaymentSession（单笔支付） 中创建的组件资源。
- 当买家发起多次支付时，释放之前 createPaymentSession（单笔支付）中创建的组件资源。
以下示例代码展示了如何调用 SDK：
[[AMSCashierPayment shared] createComponent:sessionData];
// 释放 SDK 组件资源
[[AMSCashierPayment shared] onDestroy];弹窗体验与嵌入式体验
您可以通过弹窗或嵌入页面的方式在页面上展示 SDK。
弹窗体验
嵌入式体验
弹窗体验的优势在于对页面样式影响较小，流程相对独立。
当买家在页面上选择支付方式并点击提交后，您需要调用 SDK 并弹出窗口。
[[AMSCashierPayment shared] createComponent:sessionData];
嵌入式体验将支付元素嵌入到指定视图中，您需关注支付列表的样式调整。嵌入内容的宽度会自动适应父容器，而高度会随着视图变化动态更新。
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)。邮政编码。
// 用户输入完成支付
NSString *dataString = @"{"billingAddress":{"zipCode":"310000","region":"CN"}}";
[[AMSCashierPayment shared] submit: dataString];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 参数中指定的地址发送异步通知（notifyPayment）。收到 Antom 的通知后，您需要按照返回收到确认信息的格式返回响应。
Antom 允许您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定地址。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。
以下代码展示了通知请求的示例：
{
"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 小时。
问：在响应异步通知时，我需要添加数字签名吗？
问：我在通知中需要使用哪些关键参数？
答：请注意以下关键参数：
- result：表示订单的支付结果。
- paymentRequestId：用于咨询、取消和对账的支付请求 ID。
- paymentId：表示由 Antom 生成的支付订单 ID，用于退款和对账。
- paymentAmount：表示支付金额。
查询结果
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"
}
以下代码展示了响应报文的示例：
{
"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 接口？
问：我在通知中需要使用哪些关键参数？
答：请注意以下关键参数：
- result：表示此 inquiryPayment 接口调用的结果，需要根据 paymentStatus 来判断订单状态：
- SUCCESS和FAIL表示最终结果。
- PROCESSING表示处理中。
- paymentAmount：表示支付的金额。
步骤 4：获取请款结果 服务端
在商户完成请款或请款超时后，Antom 会通过服务器交互将相应的请款结果发送给您，您可以通过以下方法之一获取请款结果：
- 接收异步通知
- 查询结果
接收异步通知
请款成功或失败时，Antom 会向您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定的地址发送异步通知（notifyPayment）。收到 Antom 的通知后，您需要按照返回收到确认信息返回响应。
Antom允许您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定地址。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。
以下代码展示了请款成功的示例：
{
"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"
}
}以下代码展示了请款失败的示例：
{
"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 小时。
问：在响应异步通知时，我需要添加数字签名吗？
问：我需要使用通知中的哪些关键参数？
答：请注意以下关键参数：
- result：表示订单的请款结果。
- notifyType：通知类型为 CAPTURE_RESULT。
- paymentRequestId：您生成的支付请求 ID，用于查询、取消和对账。
- paymentId：Antom 生成的支付订单 ID，用于退款和对账。
- acquirerReferenceNo：集成新加坡和香港内银行卡支付服务的商户将在通知中收到特定的收单机构 ID。
查询结果
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"
}请款状态的值
接口响应中的 transactions 字段值表示请款状态：
以下代码展示了请款成功的示例：
{
"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"
}
}
]
}以下代码展示了请款失败的示例：
{
"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."
}
}
]
}以下代码展示了请款处理中的示例：
{
"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"
}
}
]
}示例代码
前端完整示例代码：
#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
回调函数返回。用户体验
以下图表展示了在应用程序中支付的用户流程：
支付流程
对于每种支付方式，支付流程包括以下步骤：
- 买家进入结账页面。
- 创建支付会话请求。
买家选择支付方式并提交订单后，您可以通过调用 createPaymentSession（单笔支付）接口获取支付会话。 - 调用客户端 SDK。
在客户端，通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码展示、验证等流程。随后，SDK 将通过OnCheckoutListener回调支付结果。 - 确认支付结果。
通过以下两种方法之一获取支付结果： - 异步通知：在 createPaymentSession（单笔支付）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付成功或过期时，Antom 会使用 notifyPayment 向您发送异步通知。
- 获取请款结果。
对于银行卡支付，通过以下两种方法之一获取请款结果： - 异步通知：在 createPaymentSession（单笔支付）接口中设置 paymentNotifyUrl 字段，以指定接收异步通知的地址。当支付请求成功或过期时，Antom 会使用 notifyCapture（单笔支付）向您发送异步通知。
集成准备
- 已获得 client ID。
- 已完成密钥配置。
- 已完成异步通知接收地址的配置。
- 集成 Antom 服务端 SDK 资源包，并完成接口库安装及请求示例初始化。具体操作请参阅服务端 SDK。
- 参阅 Android 端集成 SDK 资源包文档来集成客户端 SDK 资源包。
注意：暂不支持 Flutter 和 React Native（RN）开发框架。
集成步骤
请按照以下步骤开始集成：
- 创建支付会话
- 创建并调用 SDK
- 获取支付结果
- 获取请款结果
步骤 1：创建支付会话 服务端
当买家选择 Antom 提供的支付方式时，您需要收集关键信息，如支付请求 ID、订单金额、支付方式、订单描述、支付重定向链接和支付结果通知链接，调用 createPaymentSession（单笔支付）接口来创建支付会话，并将支付会话返回给客户端。
创建支付会话包含以下参数：
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();
// 处理错误情况
}
}
以下代码展示了一个请求报文的示例：
{
"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：支付会话的过期时间。
{
"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 客户端
当买家在页面上选择支付方式后，您需要创建并使用支付会话初始化 SDK。
1.（可选）预加载 SDK
在创建支付会话前，强烈建议您预加载 SDK，以提升收银台页面的渲染速度，减少买家在支付过程中的等待时间。
调用
createComponent
方法：按照以下代码示例执行预加载操作：
AMSCashierPayment.preload(context.getApplicationContext());
2. 初始化 SDK
使用
AMSCashierPayment
创建 SDK 实例并指定基本配置。创建配置对象包括以下方法：注意：每个实例只能处理一个支付会话。建议在每次调用
createComponent
之前先创建实例。以下示例代码展示了如何初始化 SDK：
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
方法：在以下情况下调用
onDestroy
方法释放 SDK 组件资源：- 当买家离开支付页面时，释放 createPaymentSession（单笔支付） 中创建的组件资源。
- 当买家发起多次支付时，释放之前 createPaymentSession（单笔支付）中创建的组件资源。
以下示例代码展示了如何调用 SDK：
checkout.createComponent(activity, sessionData);
// 释放 SDK 组件资源
checkout.onDestroy();弹窗体验与嵌入式体验
您可以通过弹窗或嵌入页面的方式在页面上展示 SDK。
弹窗体验
嵌入式体验
弹窗体验的优势在于对页面样式影响较小，流程相对独立。
当买家在页面上选择支付方式并点击提交后，您需要调用 SDK 并弹出窗口。
checkout.createComponent(activity, sessionData);嵌入式体验将支付元素嵌入到指定视图中，您需关注支付列表的样式调整。嵌入内容的宽度会自动适应父容器，而高度会随着视图变化动态更新。
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)。邮政编码。
let dataString = '{"billingAddress":{"zipCode":"310000","region":"CN"}}';
// 用户输入完成提交绑定。
checkout.submit(dataString);4. 展示支付结果
支付结果将通过
onEventCallback
函数返回。这里的支付结果仅用于前端展示，最终订单状态以服务器端为准。您需要通过 onEventCallback
返回的数据自定义每个支付结果的处理流程。以下是
onEventCallback
的支付结果可能返回的事件码：以下示例代码展示了如何处理
onEventCallback
事件：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 中配置该地址。
以下代码展示了通知请求的示例：
{
"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 小时。
问：在响应异步通知时，我需要添加数字签名吗？
问：我在通知中需要使用哪些关键参数？
答：请注意以下关键参数：
- result：表示订单的支付结果。
- paymentRequestId：用于咨询、取消和对账的支付请求 ID。
- paymentId：表示由 Antom 生成的支付订单 ID，用于退款和对账。
- paymentAmount：表示支付金额。
查询结果
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"
}
以下代码展示了响应报文的示例：
{
"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 接口？
问：我在通知中需要使用哪些关键参数？
答：请注意以下关键参数：
- result：表示此 inquiryPayment 接口调用的结果，需要根据 paymentStatus 来判断订单状态：
- SUCCESS和FAIL表示最终结果。
- PROCESSING表示处理中。
- paymentAmount：表示支付的金额。
步骤 4：获取请款结果 服务端
在商户完成请款或请款超时后，Antom 会通过服务器交互将相应的请款结果发送给您，您可以通过以下方法之一获取请款结果：
- 接收异步通知
- 查询结果
接收异步通知
请款成功或失败时，Antom 会向您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定的地址发送异步通知（notifyPayment）。收到 Antom 的通知后，您需要按照返回收到确认信息返回响应。
Antom允许您在 createPaymentSession（单笔支付）接口的 paymentNotifyUrl 参数中指定地址。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。
以下代码展示了请款成功的示例：
{
"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"
}
}以下代码展示了请款失败的示例：
{
"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 小时。
问：在响应异步通知时，我需要添加数字签名吗？
问：我需要使用通知中的哪些关键参数？
答：请注意以下关键参数：
- result：表示订单的请款结果。
- notifyType：通知类型为 CAPTURE_RESULT。
- paymentRequestId：您生成的支付请求 ID，用于查询、取消和对账。
- paymentId：Antom 生成的支付订单 ID，用于退款和对账。
- acquirerReferenceNo：集成新加坡和香港内银行卡支付服务的商户将在通知中收到特定的收单机构 ID。
查询结果
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"
}请款状态的值
接口响应中的 transactions 字段值表示请款状态：
以下代码展示了请款成功的示例：
{
"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"
}
}
]
}以下代码展示了请款失败的示例：
{
"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."
}
}
]
}以下代码展示了请款处理中的示例：
{
"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"
}
}
]
}示例代码
前端完整示例代码：
//（可选）预加载 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
回调函数返回。