回调函数可以返回多种类型的数据或值，例如事件码和与支付相关的信息。本文向您介绍通过回调函数返回的事件码、卡支付信息以及风控信息。
回调函数事件码在不同时机通过不同回调函数返回，主要包括以下三种：
在组件运行生命周期内，通过 onEventCallback
回调函数返回，可根据具体事件进行后续处理。 SDK_START_OF_LOADING
：配置 showLoading
为 false
时，使用自定义动画，您可在这个时机渲染并展示自定义加载动画。SDK_END_OF_LOADING
：配置 showLoading
为 false
时，使用自定义动画，您可在这个时机结束自定义加载动画。SDK_PAYMENT_CANCEL
：表示用户取消支付，即用户未提交订单退出支付页面。可使用有效期内的 paymentSessionData 重新调用 SDK。如已过期，需要重新发起 支付会话创建 请求。SDK_CALL_URL_ERROR
：此事件码代表以下事件信息中的一种情况：
- 跳转商户页面失败。
- 跳转支付方式 App 或页面失败。
- 调用 支付会话创建 请求时 paymentRedirectUrl 参数未传入或未正确传入。
Web/WAP 场景下通常不会出现跳转异常，如果出现异常建议您校验重定向链接。App 场景下，如果频繁出现跳转异常，请联系 Antom 技术支持，排查跳转或唤端问题。
SDK_CALL_URL_SUCCESS
：跳转支付方式/商户页面成功。SDK_DUPLICATE_SUBMISSION_BEHAVIOR
：表单重复提交。您可以设置提示，避免用户重复点击提交。SDK_FORM_VERIFICATION_FAILED
：提交表单后校验不通过。SDK 会在要素收集页面展示表单错误码，用户可以重新提交支付。SDK_PAYMENT_AUTHORIZATION_SUCCESSFUL
：支付流程已完成。如果配置了支付后不跳转的方法，建议继续监听相应的支付事件码以处理后续流程。否则，可以忽略此事件码并跳转到您的支付结果页面。SDK_PAYMENT_CHALLENGE
：触发3D验证，发卡行需要与买家进行进一步交互才能验证支付。无需处理，SDK 会自动跳转到验证页面。
在组件初始化阶段，通过 onEventCallback
或 onError
回调函数返回，可根据具体事件进行后续处理。 在支付流程结束时，通过 onEventCallback
回调函数返回，可根据具体事件进行后续处理。 SDK_PAYMENT_SUCCESSFUL
：表示支付成功。建议您重定向到支付结果页。SDK_PAYMENT_FAIL
：表示支付失败。建议您根据 paymentResultCode 错误码提示信息进行处理，并引导重新支付。SDK_PAYMENT_PROCESSING
：表示支付处理中。建议您的服务端查询支付状态或等待支付结果通知，同时可询问用户是否完成，如果用户未完成支付，可以引导重新支付。SDK_PAYMENT_ERROR
：表示支付状态异常。建议您的服务端查询支付状态或等待支付结果通知。SDK_PAYMENT_RETRY
：支付失败后重试。 在开启失败可重试的情况下，引导用户修改信息后再支付。
以下表格为支付失败或异常时的支付结果信息以及对应的处理建议，您可以根据收到的支付结果码作进一步处理。
在卡支付场景下，当支付流程达到成功或失败的最终状态时，您可以在调用 onEventCallback
函数后在响应中收到 cardPaymentResultInfo 参数。 请参阅下表了解 cardPaymentResultInfo 的子参数信息: 注意：如果支付流程完成，用户被重定向到跳转链接，您将不会收到 cardPaymentResultInfo 参数。
返回的卡片信息的示例代码：
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
},
"paymentStatus": "SUCCESS",
"paymentResultCode": "SUCCESS",
"paymentResultMessage": "success",
"cardPaymentResultInfo": {
"avsResultRaw": "4",
"cardBin": "409280",
"cardBrand": "VISA",
"cardNo": "************8888",
"cvvResultRaw": "1",
"expiryMonth": "02",
"expiryYear": "27",
"fingerprint": "",
"funding": "DEBIT",
"holdName": "Tom Jay",
"issuerName": "BANCO ITAUCARD, S.A.",
"issuingCountry": "BR",
"lastFour": "0000"
}
}
在卡支付场景下，当支付流程达到成功或失败的最终状态并且您与 Antom 签署了风控服务时，您可以在调用 onEventCallback
函数后在响应中收到 popRiskDecisionResultInfo 参数。 请参阅下表了解 popRiskDecisionResultInfo 的子参数信息: 注意：如果支付流程完成后用户被重定向，您将不会收到 popRiskDecisionResultInfo 参数。
返回的风控信息示例代码：
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
},
"paymentStatus": "SUCCESS",
"paymentResultCode": "SUCCESS",
"paymentResultMessage": "success",
"popRiskDecisionResultInfo": {
"riskDecision": "ACCEPT",
"riskAuthDecision": "NON_3D"
}
}
以下代码示例展示了集成过程中的关键步骤。代码中不包括调用 支付会话创建 接口的步骤示例，需要您自行处理服务端接口的调用。
您可以在桌面浏览器或移动浏览器上集成 Antom 客户端 SDK。以下是两种集成方法的示例代码：
- 使用 npm 集成 SDK 资源包
- 使用 CDN 资源集成 SDK 资源包
import { AMSCashierPayment } from "@alipay/ams-checkout";
// 步骤一：实例化SDK，并处理好事件回调
const onEventCallback = function({ code, result }) {
switch (code) {
case 'SDK_PAYMENT_SUCCESSFUL':
// 支付成功。建议您重定向到支付结果页。
break;
case 'SDK_PAYMENT_PROCESSING':
console.log('可检查支付结果数据', result);
// 支付处理中。建议您通过服务端查询支付状态或等待支付结果通知，同时可询问用户是否完成，如果未完成，可以引导用户重新支付。
break;
case 'SDK_PAYMENT_FAIL':
console.log('可检查支付结果数据', result);
// 支付失败。建议您查阅文中事件码部分的处理建议，并引导用户重新支付。
break;
case 'SDK_PAYMENT_CANCEL':
// 用户在未提交订单状态下退出支付页面。可以用在有效期内的 paymentSessionData 重新调用SDK。如已过期，需要重新请求 paymentSessionData。
break;
case 'SDK_PAYMENT_ERROR':
console.log('可检查支付结果数据', result);
// 支付状态异常。建议您通过服务端查询支付状态或等待支付结果通知，或引导用户重新支付。
break;
case 'SDK_END_OF_LOADING':
// 建议您结束自定义加载动画
break;
default:
break;
}
}
const checkoutApp = new AMSCashierPayment({
environment: "sandbox",
locale: "en_US",
onLog: ({code, message}) => {},
onEventCallback: onEventCallback,
});
// 处理卡支付按钮事件
document
.querySelector("#你的表单id")
.addEventListener("submit", handleSubmit);
async function handleSubmit() {
// 步骤二：服务端调用支付会话创建接口，获取paymentSessionData
async function getPaymentSessionData() {
const url = "填写服务端地址";
const config = {
// 填写请求配置
};
const response = await fetch(url, config);
// 获取响应中的paymentSessionData参数值
const { paymentSessionData } = await response.json();
return paymentSessionData;
}
const paymentSessionData = await getPaymentSessionData();
// 步骤三：创建渲染卡组件
// 最佳实践
await checkoutApp.createComponent({
sessionData: paymentSessionData,
appearance:{
showLoading: true, // 默认为true，表示展示初始化加载动画
},
});
}
// 步骤一：实例化SDK，并处理好事件回调
const onEventCallback = function({ code, result }) {
switch (code) {
case 'SDK_PAYMENT_SUCCESSFUL':
// 支付成功。建议您重定向到支付结果页。
break;
case 'SDK_PAYMENT_PROCESSING':
console.log('可检查支付结果数据', result);
// 支付处理中。建议您通过服务端查询支付状态或等待支付结果通知，同时可询问用户是否完成，如果未完成，可以引导用户重新支付。
break;
case 'SDK_PAYMENT_FAIL':
console.log('可检查支付结果数据', result);
// 支付失败。建议您查阅文末参考信息服务端事件码表格中的处理建议，并引导用户重新支付。
break;
case 'SDK_PAYMENT_CANCEL':
// 用户在未提交订单状态下退出支付页面。可以用在有效期内的 paymentSessionData 重新调用SDK。如已过期，需要重新请求 paymentSessionData。
break;
case 'SDK_PAYMENT_ERROR':
console.log('可检查支付结果数据', result);
// 支付状态异常。建议您通过服务端查询支付状态或等待支付结果通知，或引导用户重新支付。
break;
case 'SDK_END_OF_LOADING':
// 建议您结束自定义加载动画
break;
default:
break;
}
}
const checkoutApp = new window.AMSCashierPayment({
environment: "sandbox",
locale: "en_US",
onLog: ({code, message}) => {},
onEventCallback: onEventCallback,
});
// 处理卡支付按钮事件
document
.querySelector("#你的表单id")
.addEventListener("submit", handleSubmit);
async function handleSubmit() {
// 步骤二：服务端调用支付会话创建接口，获取paymentSessionData
async function getPaymentSessionData() {
const url = "填写服务端地址";
const config = {
// 填写请求配置
};
const response = await fetch(url, config);
// 获取响应中的paymentSessionData参数值
const { paymentSessionData } = await response.json();
return paymentSessionData;
}
const paymentSessionData = await getPaymentSessionData();
// 步骤三：创建渲染卡组件
// 最佳实践
await checkoutApp.createComponent({
sessionData: paymentSessionData,
appearance:{
showLoading: true, // 默认为true，表示展示默认加载动画
},
});
}
以下示例代码展示了如何在 Android 设备上集成客户端 SDK。
AMSCashierPaymentConfiguration configuration = new AMSCashierPaymentConfiguration();
configuration.setLocale(new Locale("en", "US"));
// 设置showLoading参数为true(默认值)时使用内部loading页面，false时商户可通过onPaymentEventCallback中的事件自定义loading动画
configuration.setOption("showLoading", "true");
// 设置沙箱环境，不设置为线上正式环境
configuration.setOption("sandbox", "true");
// 配置是否由SDK组件渲染支付按钮
configuration.setOption("showSubmitButton", "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)) {
// 支付失败。建议您根据 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();
checkout.mountComponent(activity, sessionData);
checkout.onDestroy();
以下示例代码展示了如何在 iOS 设备上集成客户端 SDK。
#import <AMSComponent/AMSComponent-Swift.h>
AMSCashierPaymentConfiguration *componentConfig = [AMSCashierPaymentConfiguration new];
componentConfig.locale = @"en_US";
// sandbox变更设置沙箱环境，不设置为线上正式环境
NSDictionary *options = @{@"showLoading": @"true", @"sandbox": @"true"};
componentConfig.options = options;
[[AMSCashierPayment shared] initConfiguration:componentConfig];
[AMSCashierPayment shared].paymentDelegate = self;
[AMSCashierPayment shared].loggerDelegate = self;
[[AMSCashierPayment shared] createComponent:paymentSessionData];
NSString *dataString = @"{"billingAddress":{"zipCode":"310000","region":"CN"}}";
[[AMSCashierPayment shared] submit: dataString];
#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"]) {
// 支付失败。建议您根据 paymentResultCode 错误码提示信息，并重新引导支付
} else if ([eventCode isEqualToString:@"SDK_PAYMENT_CANCEL"]) {
// 买家未点击支付并关闭支付窗口。可以用在有效期内的 paymentSessionData 重新调用SDK。如已过期，需要重新请求 paymentSessionData
} else if ([eventCode isEqualToString:@"SDK_PAYMENT_ERROR"]) {
// 支付状态异常。建议您的服务端查询支付状态或等待支付结果通知
}
NSLog(@"eventCode%@ eventResult%@", eventCode, eventResult);
}
#pragma AMSLogProtocol
- (void)logWithName:(NSString *)name parameter:(NSDictionary<NSString *,id> *)parameter
{
NSLog(@"name%@ parameter%@", name, parameter);
}
