Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

银行卡支付（iOS）

Antom SDK 是一个预构建的用户界面组件，用于收集银行卡信息并为您处理 3D 验证流程。集成此组件不需要您具有 PCI 认证，非常适合那些希望委托 Antom 来收集银行卡信息的用户。

用户体验

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

国际卡-Mobile-SDK集成-首次.png

支付流程

对于每种支付方式，支付流程包括以下步骤：

WAP）-中@3x.png

  1. 用户进入结账页面。
  1. 创建支付会话请求。
    买家选择支付方式并提交订单后，您可以通过调用 支付会话创建（收银台）接口获取支付会话。
  2. 调用客户端SDK。
    在客户端，通过支付会话调用 SDK。SDK 会根据支付方式的特性处理信息收集、重定向、应用调用、二维码显示、验证等流程。
  3. 获取支付结果。
    通过以下两种方法之一获取支付结果：
  1. 获取请款结果。
    对于银行卡支付，通过以下两种方法之一获取请款结果：

集成步骤

通过以下步骤开始集成：

  1. 创建支付会话
  2. 创建并调用 SDK
  3. 获取支付结果
  4. 获取请款结果

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

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

Antom 提供了多种语言的服务器端接口库。以下代码以 Java 为例，您需要安装 Java 6 或更高版本。

安装接口库

您可以在 GitHub 上找到最新版本。

copy
<dependency>
    <groupId>com.alipay.global.sdk</groupId>
    <artifactId>global-open-sdk-java</artifactId>
    <version>2.0.36</version>
</dependency>

初始化请求实例

创建一个单例资源以向 Antom 发起请求。

copy
import com.alipay.global.api.AlipayClient;
import com.alipay.global.api.DefaultAlipayClient;
import com.alipay.global.api.model.constants.EndPointConstants;

public class Sample {
    public static final String        CLIENT_ID            = "";
    public static final String        ANTOM_PUBLIC_KEY     = "";
    public static final String        MERCHANT_PRIVATE_KEY = "";

    private final static AlipayClient CLIENT               = new DefaultAlipayClient(
            EndPointConstants.SG, MERCHANT_PRIVATE_KEY, ANTOM_PUBLIC_KEY, CLIENT_ID);

}

创建支付会话

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

参数名称

是否必需

描述

productCode

✅

代表所使用的支付产品，根据合同规定。对于收银台支付，值设置为 CASHIER_PAYMENT。

paymentRequestId

✅

商家为识别支付请求而分配的专属 ID。

paymentAmount

✅

您请求在订单货币中接收的支付金额。

paymentMethod

✅

由商户或收单机构用于收集支付的支付方式。

paymentRedirectUrl

✅

支付完成后，买家被重定向到的商户页面链接。

order

✅

包括买家、商户、商品、金额、配送信息和购买环境的订单信息。

paymentNotifyUrl

支付结果通知地址，可通过接口传递，也可通过门户设置为固定值。

settlementStrategy

支付请求的结算策略。

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

调用支付会话创建接口的示例代码

以下示例代码展示了如何调用 支付会话创建（收银台）接口：

copy
public static void createCardPaymentSession() {
    AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
    alipayPaymentSessionRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

    // replace with your paymentRequestId
    String paymentRequestId = UUID.randomUUID().toString();
    alipayPaymentSessionRequest.setPaymentRequestId(paymentRequestId);

    // set amount
    Amount amount = Amount.builder().currency("SGD").value("4200").build();
    alipayPaymentSessionRequest.setPaymentAmount(amount);

    // set paymentMethod
    PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("CARD").build();
    alipayPaymentSessionRequest.setPaymentMethod(paymentMethod);

    // set auth capture payment mode
    PaymentFactor paymentFactor = PaymentFactor.builder().isAuthorization(true).build();
    alipayPaymentSessionRequest.setPaymentFactor(paymentFactor);

    // replace with your orderId
    String orderId = UUID.randomUUID().toString();

    // set buyer info
    Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

    // set order info
    Order order = Order.builder().referenceOrderId(orderId)
        .orderDescription("antom testing order").orderAmount(amount).buyer(buyer).build();
    alipayPaymentSessionRequest.setOrder(order);

    // replace with your notify url
    alipayPaymentSessionRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");

    // replace with your redirect url
    alipayPaymentSessionRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

    AlipayPaymentSessionResponse alipayPaymentSessionResponse = null;
    try {
        alipayPaymentSessionResponse = CLIENT.execute(alipayPaymentSessionRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

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

copy
{
  "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 ：支付会话的过期时间。
copy
{
  "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"
  }
}

常见问题

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

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

问: 如何设置接收支付通知的链接？

答：在 支付会话创建（收银台）接口中指定 paymentNotifyUrl 字段，以接收支付结果的异步通知（支付通知），或者在 Antom Dashboard 中配置接收链接。如果请求和 Antom Dashboard 中都指定了链接，请求中的值优先。

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

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

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

安装

版本要求：

  • 安装 Xcode 12 或更高版本。
  • 使用 iOS 11 或更高版本。

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

请查阅 iOS 端集成 SDK 资源包文档来集成 SDK 资源包。

初始化 SDK

使用 AMSCashierPayment 创建 SDK 实例并指定基本配置。创建 AMSCashierPaymentConfiguration 对象时，包括以下参数：

参数名称

是否必需

描述

locale

用于传递语言信息。有效值如下所示。您可以根据支付方式的地区选择要传递的值。如果传入其他值，默认使用英语：

  • en_US：英语
  • es_ES：西班牙语
  • fr_FR：法语
  • nl_NL：荷兰语
  • it_IT：意大利语
  • de_DE：德语
  • zh_CN：简体中文

options

用于指定是否使用默认加载模式和沙箱环境。有效值为：

  • "sandbox"， "true"：沙箱环境
  • "sandbox"， "false"：生产环境
  • "showLoading"， "true"：使用默认加载模式。
  • "showLoading"，"false"：不使用默认加载模式。
  • "notRedirectAfterComplete"：可选，布尔类型，默认值为false，意味着支付完成后会重定向回您的页面。值为空时也适用。值为true表示支付完成后不会重定向。您需要使用客户事件代码来控制绑卡以完成后续流程。请注意，客户端返回的支付结果事件代码仅用作客户端页面重定向操作的参考。对于交易状态更新，请参考服务器的 支付通知 或 支付结果查询 接口返回的结果。
  • "merchantAppointmentParam"：可选对象，用于设置自定义功能。它包含以下值：
    • storedCard ：可选对象，用于设置存储卡的自定义特性，包含以下值：
      • needCVV ：可选布尔属性。默认值为false，表示在支付过程中 买家 无需输入 CVV 号码。值为空时也适用。true值表示在支付过程中买家需要输入 CVV 号码。

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

方法

必需

描述

onEventCallback

一个回调函数，用于监控结账页面上的支付事件，返回 eventCode 和 eventResult。

实现 AMSLoggerProtocol，用于管理日志输出。它包含以下方法：

方法

必需

描述

logWithName

默认的日志输出回调函数。

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

copy
#import <AMSComponent/AMSComponent-Swift.h>

AMSCashierPaymentConfiguration *componentConfig = [AMSCashierPaymentConfiguration new];
componentConfig.locale = @"en_US";
// Specify showLoading as true (default value) to use the default loading pattern. Specify it as false to customize the loading animation based on onEventCallback.
// Set the sandbox environment. If you leave it empty, the production environment is used by default.
// Card payment scenarios require cvv authentication.
NSString *merchantAppointParam = @"{\n  \"storedCard\": {\n     \"needCVV\": true\n }\n}"; 
// Set the sandbox environment. If you leave it empty, the production environment is used by default.
NSDictionary *options = @{@"showLoading": @"true", 
                          @"sandbox": @"true", 
                          @"merchantAppointParam": merchantAppointParam,
                          @"notRedirectAfterComplete": @"true"  // Set no jump after payment completion, with the merchant controlling the subsequent process
                          };
componentConfig.options = options;

[[AMSCashierPayment shared] initConfiguration:componentConfig];

// Set the callback to monitor payment events on the checkout page.
[AMSCashierPayment shared].paymentDelegate = self;
[AMSCashierPayment shared].loggerDelegate = self;

// The server calls the createPaymentSession API to obtain paymentSessionData.

调用SDK

调用 createComponent 方法：

参数名称

是否必需

描述

sessionData

✅

使用 sessionData 参数创建配置对象：将通过 支付会话创建（收银台）接口在响应中获取的完整 paymentSessionData 参数传递给 sessionData 。

在以下情况下调用 onDestroy 方法释放 SDK 组件资源：

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

copy
[[AMSCashierPayment shared] createComponent:sessionData];

//Free SDK component resources
[[AMSCashierPayment shared] onDestroy];

显示支付结果

支付结果将通过 onEventCallback 函数返回。这里的支付结果仅用于前端显示，最终订单状态以服务器端为准。您需要通过 onEventCallback 返回的数据自定义每个支付结果的处理流程。

以下是 onEventCallback 返回的支付结果可能的事件代码。

事件码

信息

解决方案

SDK_PAYMENT_SUCCESSFUL

支付成功。

建议将买家重定向到支付结果页面。

SDK_PAYMENT_PROCESSING

支付正在处理中。

建议您检查在onEventCallback结果数据中 paymentResultCode 的值以获取详细信息。根据提供的信息，引导买家重新尝试支付。

SDK_PAYMENT_FAIL

支付失败。

建议您检查onEventCallback结果数据中paymentResultCode的值以获取详细信息。根据提供的信息引导买家重新尝试支付。

SDK_PAYMENT_CANCEL

买家在未提交订单的情况下退出了支付页面。

在有效期内，可以使用 paymentSessionData 重新调用SDK；如果已过期，需要重新请求paymentSessionData。

SDK_PAYMENT_ERROR

支付状态异常。

建议您检查onEventCallback结果数据中paymentResultCode的值以获取详细信息。根据提供的信息，引导买家重新尝试支付。

以下示例代码展示了如何处理 onEventCallback 事件：

copy
#import <AMSComponent/AMSComponent-Swift.h>


#pragma AMSPaymentProtocol
- (void)onEventCallback:(NSString *)eventCode eventResult:(AMSEventResult *)eventResult
{
    if ([eventCode isEqualToString:@"SDK_PAYMENT_SUCCESSFUL"]) {
        // Payment was successful. Redirect buyers to the payment result page.
    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_PROCESSING"]) {
        // Payment was being processed. Guide buyers to retry the payment based on the provided information.

    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_FAIL"]) {
        // Payment failed. Guide buyers to retry the payment based on the provided information.

    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_CANCEL"]) {
        // Guide buyers to retry the payment.

    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_ERROR"]) {
        // The payment status was abnormal. Guide buyers to retry the payment based on the provided information.

    } else if ([eventCode isEqualToString:@"SDK_FORM_VERIFICATION_FAILED"]) {
        // The SDK displays a form error code on the element collection page if the form submission fails.
    }
    NSLog(@"eventCode%@ eventResult%@", eventCode, eventResult);
}

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

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

  • 接收异步通知
  • 查询结果

接收异步通知

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

Antom 允许您在 支付会话创建（收银台）接口的 paymentNotifyUrl 参数中指定链接。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。

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

copy
{
  "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 秒内发送异步通知。对于某些支付方式，如柜台支付（OTC），通知可能会稍有延迟。
  • 如果支付未完成，Antom 需要先关闭订单，然后发送异步通知。不同支付方式关闭订单所需的时间会有所不同，通常默认为 14 分钟。

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

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

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

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

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

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

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

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

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

查询结果

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

参数名称

是否必需

描述

paymentRequestId

由商户生成的支付请求 ID。

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

以下示例代码展示了如何调用 支付结果查询 接口：

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

    // replace with your paymentRequestId
    alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");

    AlipayPayQueryResponse alipayPayQueryResponse = null;
    try {
        alipayPayQueryResponse = CLIENT.execute(alipayPayQueryRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

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

copy
{
  "paymentRequestId": "paymentRequestId01"
}

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

copy
{
  "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"
  }
}

常见问题

问：我应该多久调用一次 支付结果查询 接口？

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

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

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

  • result ：表示此 支付结果查询 接口调用的结果，需要根据 paymentStatus 来判断订单状态：
    • SUCCESS和FAIL表示最终结果。
    • PROCESSING表示处理中。
  • paymentAmount ：表示支付的金额。

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

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

  • 接收异步通知
  • 查询结果

接收异步通知

当请款成功或失败时，Antom会向您在 支付会话创建（收银台）接口的 paymentNotifyUrl 参数中指定的地址发送异步通知（支付通知）。收到 Antom 的通知后，您需要按照返回收到确认信息返回响应。

Antom 允许您在 支付会话创建（收银台）接口的 paymentNotifyUrl 参数中指定链接。如果每个支付的地址相同，您也可以在 Antom Dashboard 中配置该地址。

以下代码显示了成功的请款示例：

copy
{
  "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"
  }
}

以下代码显示了失败的请款示例：

copy
{
  "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。

查询结果

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

参数名称

是否必需

描述

paymentRequestId

由商家生成的支付请求 ID。

有关完整参数集，请参阅 支付结果查询 接口，获取完整的参数列表以及某些支付方式的额外要求。

以下示例代码展示了如何调用 支付结果查询 接口：

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

    // replace with your paymentRequestId
    alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");

    AlipayPayQueryResponse alipayPayQueryResponse = null;
    try {
        alipayPayQueryResponse = CLIENT.execute(alipayPayQueryRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

以下是请求报文的示例：

copy
{
  "paymentRequestId": "paymentRequestId01"
}

请款状态的值

接口响应中的 transactions 字段值表示请款状态：

参数名称

描述

transactions.transactionType

值为 CAPTURE，表示请款状态。

transactions.transactionResult

请款状态

以下代码显示成功的请款示例：

copy
{
  "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"
      }
    }
  ]
}

以下代码显示失败的请款示例：

copy
{
  "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."
      }
    }
  ]
}

以下代码显示处理中的请款示例：

copy
{
  "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"
      }
    }
  ]
}

示例代码

前端完整示例代码：

copy
#import <AMSComponent/AMSComponent-Swift.h>

// Step 1: Create an AMSConfiguration object.
AMSCashierPaymentConfiguration *componentConfig = [AMSCashierPaymentConfiguration new];
componentConfig.locale = @"en_US";

// Specify showLoading as true (default value) to use the default loading pattern. Specify it as false to customize the loading animation based on onEventCallback.
// Set the sandbox environment. If you leave it empty, the production environment is used by default.
// Card payment scenarios require cvv authentication.
NSString *merchantAppointParam = @"{\n  \"storedCard\": {\n     \"needCVV\": true\n }\n}"; 
// Set the sandbox environment. If you leave it empty, the production environment is used by default.
NSDictionary *options = @{@"showLoading": @"true", 
                          @"sandbox": @"true", 
                          @"merchantAppointParam": merchantAppointParam,
                          @"notRedirectAfterComplete": @"true"  // Set no jump after payment completion, with the merchant controlling the subsequent process
                          };
componentConfig.options = options;
[[AMSCashierPayment shared] initConfiguration:componentConfig];

// Set the callback to monitor payment events on the checkout page.
[AMSCashierPayment shared].paymentDelegate = self;
[AMSCashierPayment shared].loggerDelegate = self;

// The server calls the createPaymentSession API to obtain paymentSessionData.


// Step 3: Create and render the card component.
[[AMSCashierPayment shared] createComponent:paymentSessionData];

#pragma AMSPaymentProtocol
- (void)onEventCallback:(NSString *)eventCode eventResult:(AMSEventResult *)eventResult
{
    if ([eventCode isEqualToString:@"SDK_PAYMENT_SUCCESSFUL"]) {
        // Payment was successful. Redirect buyers to the payment result page.
    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_PROCESSING"]) {
        // Payment was being processed. Guide buyers to retry the payment based on the provided information.

    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_FAIL"]) {
        // Payment failed. Guide buyers to retry the payment based on the provided information.

    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_CANCEL"]) {
        // Guide buyers to retry the payment.

    } else if ([eventCode isEqualToString:@"SDK_PAYMENT_ERROR"]) {
        // The payment status was abnormal. Guide buyers to retry the payment based on the provided information.
    }
    NSLog(@"eventCode%@ eventResult%@", eventCode, eventResult);
}

#pragma AMSLogProtocol
- (void)logWithName:(NSString *)name parameter:(NSDictionary<NSString *,id> *)parameter
{
    NSLog(@"name%@ parameter%@", name, parameter);
}

事件码

您可能会看到两种类型的事件码：

  • 状态码：在组件运行生命周期内，通过 onEventCallback 回调函数返回。
  • 错误码：在组件初始化阶段，通过 onEventCallback 或 onError 回调函数返回。

类型

代码

描述

后续操作

状态码

SDK_START_OF_LOADING

配置 showLoading 为 false 时，使用自定义动画，您可在这个时机渲染并展示自定义加载动画。

无需进一步操作。

SDK_END_OF_LOADING

配置 showLoading 为 false 时，使用自定义动画，您可在这个时机结束自定义加载动画。

无需进一步操作。

错误码

SDK_INTERNAL_ERROR

SDK 内部错误。

请联系 Antom 技术支持解决此问题。

SDK_CREATEPAYMENT_PARAMETER_ERROR

createComponent 函数传入参数异常。

确保参数传递正确并重新发送请求。

SDK_CALL_URL_ERROR

表示以下情况之一：

请联系 Antom 技术支持解决此问题。

SDK_INTEGRATION_ERROR

未找到依赖项。

请确保已正确添加依赖项，然后重试集成过程。