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

iOS

此章节为您提供 iOS 端嵌入式卡支付体验 SDK 的集成指南，帮助您快速开始手机 App 内支付相关页面的渲染。

 

集成准备

在您开始集成前，确保已完成以下环境准备工作：

  • 已安装 Xcode 12 或更高版本。
  • 确保 iOS 系统为 iOS 11 及以上版本。

 

集成步骤

请按照以下步骤完成集成：

1

集成 SDK 资源包

商户客户端

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

 

 

2

通过 AMSCashierPayment 构造函数创建 SDK 实例：

商户客户端
  1. 初始化收银台实例，包含以下参数：
    • configuration：必传，AMSCashierPaymentConfiguration 类型的一个对象，包含所有配置参数。
  2. 创建 AMSCashierPaymentConfiguration 类，包含以下参数：
    • ​​locale: 选传，NSString 类型。商户客户端识别用户浏览器使用的语言种类，并传入浏览器语言信息，SDK 根据此信息提供对应语言的页面。目前 SDK 支持以下几种多语言，如果传入的值不是以下几 种，将提供英语页面：
      • en_US：英语
      • nl_NL：荷兰语
      • it_IT：意大利语
      • de_DE：德语
      • fr_FR：法语
      • es_ES：西班牙语
      • ko_KR：韩语
      • pt_BR：葡萄牙语
      • zh_CN：中文简体
      • zh_HK：中文繁体
    • options: 选传，NSDictionary 类型，用于设置是否采用默认loading样式以及是否使用沙箱环境，支持的值包括：
      • "sandbox", "true"：沙箱环境
      • "sandbox", "false"：生产环境
      • "showLoading", "true"：使用默认 loading 样式
      • "showLoading", "false"：不使用默认 loading 样式
      • "showSubmitButton", "true"：配置由 SDK 组件渲染支付按钮。
      • "showSubmitButton", "false"：配置由商户渲染支付按钮，同时需要调用实例对象中 submit 函数触发提交支付流程。
      • "notRedirectAfterComplete", "true"：默认值为 false，表示支付完成后跳回您的页面，当值为空时同理。值为 true 表示支付完成后不跳转，您需要通过客户事件码自行控制支付完成后续流程。需要注意的是客户端返回的支付结果事件码仅用于客户端页面的跳转操作参考，交易状态的更新请以服务端 支付结果通知 或 支付查询 接口返回结果为准。
      • "merchantAppointmentParam"：选传，JSON String类型，用于自定义功能设置，包含以下参数：
        • storedCard：选传，Object 类型，用于已存卡情况下的自定义功能设置，包含以下参数：
          • needCVV：选传，Boolean 类型，默认值为 false，表示在支付过程中无需用户输入CVV校验，当值为空时同理。若设定该值为 true ，则表示在支付过程中需要用户输入CVV校验。
  3. 实现 AMSPaymentProtocol 的协议，用于后续流程中对应事件发生时的处理，包含以下方法：
    • onEventCallback：收银台支付事件回调函数，返回事件码（eventCode）和事件具体信息（eventResult）。
  4. 实现 AMSLoggerProtocol 的协议，用于管理日志输出，包含以下方法：
    • logWithName: 默认输出日志的回调函数。
创建 SDK 实例的接口示例：
Objective-C
Editor
3

发起 支付会话创建 请求

商户服务端

买家在支付方式选择页选择卡支付方式后，您的客户端需自行实现支付按钮的点击事件监听。当监听到支付按钮被买家点击后，您的服务端需向 POP 服务器发起 支付会话创建 请求。收到支付会话创建请求的响应后，将响应中的 paymentSessionData 参数值用于步骤 4 。

对于已绑卡的卡令牌支付模式下您需要通过 paymentMethod.paymentMethodId 字段传入买家绑卡后 POP 返回给您的卡令牌，获取卡令牌方式如下：

  • 独立绑卡：通过 POP 向您发送的资产绑定结果通知中的 card.cardToken 字段获取卡令牌。
  • 非独立绑卡：通过 POP 向您发送的支付结果通知或主动查询支付结果的响应中的 paymentResultInfo.cardToken 字段获取卡令牌。

注意：在调用 支付会话创建 接口时，请求参数 paymentRedirectUrl 的值需要使用您提供的支付完成后跳转页面对应的 URL Scheme 。

支付会话创建请求示例，仅包含了必传字段及部分选传字段：
未绑卡
Token 支付
Editor
支付会话创建请求的响应示例
Editor
4

渲染支付要素收集页面

商户客户端
  • 使用实例对象中的 mountComponent 函数:
    • 使用 sessionData 参数创建配置对象: 将步骤 4 获取的 paymentSessionData 字段的完整数据传入 sessionData 参数。
    • 调用实例对象中的 mountComponent() 函数初始化 SDK。
  • 调用实例对象中的 submit() 函数：
    • 调用该函数，可触发支付提交流程，返回特定事件码。这些事件码也会通过 onError 或 onEventCallback 等函数返回。
    • 如果您需要传入提前收集好的 billing address 信息用于 AVS 验证，您可配置如下参数通过 submit 函数传入。
      • billingAddress：选传，Object 类型。用来识别付款人身份和位置的账单地址信息。包含如下参数：
        • region：必传，String (2)。遵循 ISO 3166 标准的二位国家码。
        • zipCode：选传，String (32)。邮政编码。
        • address2：选传，String (256)。地址行 2，例如公寓、套房、单元和建筑物信息。
        • address1：选传，String (256)。地址行 1，例如街道地址、邮政信箱和公司名称。
        • city：选传，String (32)。城市、地区、郊区、城镇或村庄名称。
        • state：选传，String (8)。州、国家或省名称。

  • 调用实例对象中的onDestroy() 函数进行 SDK 组件的资源回收，请在以下三种场景中调用：

    • 用户切换视图退出支付页面，需要回收 支付会话创建 中的组件资源。
    • 用户发起多笔支付，需要回收上一次 支付会话创建 中的组件资源。
    • 用户完成支付并配置了 notRedirectAfterComplete 为  true，可获取明确支付结果事件码时，需要回收组件资源。
调用 mountComponent()
Objective-C
Editor
事件码

    SDK 提供的错误码如下：

    • SDK_INTERNAL_ERROR：SDK内部错误。请联系 Antom 技术支持。
    • SDK_CREATEPAYMENT_PARAMETER_ERROR：mountComponent 函数传入参数异常。请检查参数是否正确并重新初始化组件。
    • SDK_INIT_PARAMETER_ERROR：AMSCashierPayment函数传入参数异常。请检查参数是否正确并重新实例化 SDK。
    • SDK_CREATECOMPONENT_ERROR：组件初始化异常。请联系 Antom 技术支持。
    • SDK_SUBMIT_NETWORK_ERROR：网络原因，导致接口调用失败。在 submit 函数提交中可能会出现。请提示用户再尝试重新提交。

     

    SDK 提供的状态码如下：

    • SDK_START_OF_LOADING：创建组件时，loading 动画开始显示。当配置隐藏 loading，使用自定义动画时，可以在这个时机渲染自定义动画。
    • SDK_END_OF_LOADING：创建组件时，loading 动画结束显示。当配置隐藏 loading，使用自定义动画时，这个时机可以隐藏动画。
    • SDK_CALL_URL_ERROR：此事件码代表以下事件信息中的一种情况：
      • 跳转商户页面失败。
      • 跳转 3D 挑战页面失败。
      • 调用 支付会话创建 请求时 paymentRedirectUrl 参数未传入或未正确传入。

    Web/WAP 场景下跳转链接通常不会异常，建议您校验重定向链接。App 场景下，如果经常出现此异常请联系 Antom 技术支持，排查跳转或唤端问题。

    • SDK_CALL_URL_SUCCESS：跳转商户页面成功。
    • SDK_DUPLICATE_SUBMISSION_BEHAVIOR：表单重复提交。商户可以通过文案提示用户，无需重复点击提交。
    • SDK_PAYMENT_AUTHORIZATION_SUCCESSFUL：支付流程完成，如果配置了支付完成后不跳转功能，建议继续监听对应的支付事件码来处理后续流程。否则可以忽略此事件码，会重定向到您的支付结果页。
    • SDK_PAYMENT_CHALLENGE：触发 3D 挑战，发卡行需要进一步的购物者互动，然后才能验证付款。无需处理，SDK 会跳转挑战页面。

    SDK 提供的支付事件结果码如下：

    • SDK_PAYMENT_SUCCESSFUL：支付成功。建议您重定向到支付结果页。
    • SDK_PAYMENT_FAIL：支付失败。建议您根据 paymentResultCode 错误码提示信息，并重新引导支付。
    • SDK_PAYMENT_PROCESSING：支付处理中。建议您的服务端查询支付状态或等待支付结果通知。
    • SDK_PAYMENT_ERROR：支付状态异常。建议您的服务端查询支付状态或等待支付结果通知。
    • SDK_PAYMENT_CANCEL：买家未点击支付并关闭支付窗口。可以用在有效期内的 paymentSessionData 重新调用SDK。如已过期，需要重新请求 paymentSessionData。
    • SDK_FORM_VERIFICATION_FAILED：提交表单后校验不通过。SDK 会在要素收集页面展示表单错误码。

     

    SDK 查询服务端支付状态（paymentStatus）：

    • SUCCESS: 表示支付成功。
    • FAIL: 表示支付失败。
    • PROCESSING: 表示支付处理中。
    • CANCELLED: 表示支付已取消。
    • PENDING: 表示支付已完成，请等待最终支付结果通知。

     

    SDK 查询服务端结果码（result.resultCode）：

    结果码

    值

    消息

    建议

    SUCCESS

    S

    Success

    -

    ORDER_NOT_EXIST

    F

    The order does not exist.

    建议重新下单。

    PAYMENT_IN_PROCESS

    U

    The payment is being processed.

    等待支付通知或主动查询结果。

    PROCESS_FAIL

    F

    A general business failure occurred.

    通常需要人工确认该问题。 建议您联系 Antom 技术支持解决该问题。

    UNKNOWN_EXCEPTION

    U

    An API call has failed, which is caused by unknown reasons.

    等待支付通知或主动查询结果。

    INQUIRY_PAYMENT_SESSION_FAILED

    F

    Failed to retrieve paymentSessionData, which may have expired or is in an unknown state.

     

    会话已过期。等待支付通知或主动查询结果。

    PAGE_ELEMENT_ILLEGAL

    U

    The payment information is incorrect.

    支付被拒绝，支付要素填写错误。

    SDK 查询服务端支付结果（paymentResultCode）：

    结果码

    值

    消息

    建议

    SUCCESS

    S

    Success

     

    -

    ACCESS_DENIED

    F

    Access is denied.

    权限不足。联系技术支持了解具体原因。

    CURRENCY_NOT_SUPPORT

    F

    The currency is not supported.

    币种不支持。联系技术支持了解具体原因。

    FRAUD_REJECT

    F

    The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.

    欺诈拒绝。如下情况下请联系技术支持：

    • 您需要申诉。
    • 买家两周内未收到退款。

    INVALID_CARD

    F

    The card is invalid. Maybe the credit card number cannot be identified, the card has no corresponding issuing bank, or the card number is in the wrong format.

    无效卡。建议换卡重试。

     

    INVALID_EXPIRY_DATE_FORMAT

    F

    The format of expiryYear or expiryMonth is wrong.

    卡的有效期不正确。建议检查卡有效期的填写格式。

    ISSUER_REJECTS_TRANSACTION

    F

    The issuing bank rejects the transaction.

    发卡行拒绝。建议换卡重试或联系发卡行。

    INVALID_MERCHANT_STATUS

    F

    The merchant status is abnormal because restrictions exist.

    商户状态异常。联系技术支持了解具体原因。

    MERCHANT_KYB_NOT_QUALIFIED

    F

    The payment failed because of the merchant's KYB status. The merchant is either not KYB compliant, or the KYB status is not qualified for this transaction.

    联系技术支持了解具体原因。

    NO_PAY_OPTIONS

    F

    The currency is not supported for the transaction.

    币种不支持。检查支付方式是否支持该币种，或支付方式和币种是否与合同中所签约一致。如有问题，联系技术支持了解具体原因。

    ORDER_IS_CLOSED

    F

    The request you initiated has the same paymentRequestId as that of the existed transaction, which is closed.

    订单已经关闭。发起新的请求重试。

    PAYMENT_AMOUNT_EXCEED_LIMIT

    F

    The payment amount is greater than the maximum amount allowed by the contract or payment method.

    超过限制金额。检查支付金额是否超过限额或使用较低的金额重试。 联系支付宝技术支持了解具体支付限额。

    PAYMENT_COUNT_EXCEED_LIMIT

    F

    The maximum number of payments exceeds the limit that is specified by the payment method.

    超过限制使用次数。联系支付宝技术支持了解具体支付限额。

    PAYMENT_NOT_QUALIFIED

    F

    The merchant is not qualified to pay because the merchant is not registered, does not have a contract for Auto Debit payment, or is forbidden to make a payment.

    商户无权限。联系技术支持了解具体原因。

    PROCESS_FAIL

    F

    A general business failure occurred.

    支付失败。通常需要人工确认该问题。 建议您联系 Antom 技术支持解决该问题。

    RISK_REJECT

    F

    The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.

    风控拒绝。如果买家两周内未收到退款，请联系 Antom 技术支持。

    SUSPECTED_CARD

    F

    The card is suspected of fraud. For example, the card is stolen or restricted.

    风控拒绝。建议换卡重试或联系发卡行。

    SUSPECTED_RISK

    F

    The transaction cannot be further processed because of suspected security issues. You can retry the transaction after one working day. If the transaction is not secure and the user has already paid, the transaction will be refunded.

    风控拒绝。如下情况下请联系技术支持：

    • 您需要申诉。
    • 买家两周内未收到退款。

    USER_AMOUNT_EXCEED_LIMIT

    F

    The payment amount exceeds the user payment limit.

    金额超限。使用小于或等于账户可用余额的金额重新发起支付，或联系 Antom 技术支持。

    USER_BALANCE_NOT_ENOUGH

    F

    The payment cannot be completed because the user balance in the corresponding payment method is not enough.

    用户余额不足。请充值或选择其它支付方式。

    USER_KYC_NOT_QUALIFIED

    F

    The payment failed because of the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified for this transaction (for example, limitations on the payment amount or product information).

    用户先完成 KYC 认证。

    USER_PAYMENT_VERIFICATION_FAILED

    F

    The user is restricted from payment on the payment method side.

    用户未完成验证。联系技术支持了解具体原因。

    USER_STATUS_ABNORMAL

    F

    The user status is abnormal on the payment method side.

    用户状态异常。联系技术支持了解具体原因。

    PAYMENT_IN_PROCESS

    U

    The payment is being processed.

    支付处理中。

    UNKNOWN_EXCEPTION

    U

    An API call has failed, which is caused by unknown reasons.

    未知异常。联系技术支持了解具体原因。

    CARD_NOT_SUPPORTED

    F

    The card used for the transaction is not supported.

    卡不支持。请换卡重试。

    INVALID_EXPIRATION_DATE

    F

    The value of paymentMethod.paymentMethodMetaData.expiryYear or paymentMethod.paymentMethodMetaData.expiryDate is invalid.

    卡的有效期不正确。建议检查卡有效期是否填写及是否填写正确。

    INVALID_CARD_NUMBER

    F

    The number of the card used for the transaction is invalid.

    卡号不正确。建议换卡重试。如重试后还有问题，联系技术支持了解具体原因。
    支付结果事件码处理示例：
    Objective-C
    Editor
    支付结果示例：
    支付成功
    支付失败
    Editor
    集成关键步骤代码示例

    以下代码示例展示了集成过程中的关键步骤。代码中不包括调用 支付会话创建 接口的步骤示例，需要您自行处理服务端接口的调用。

       

      Objective-C
      Editor