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

iOS

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

集成准备

在您开始集成前，请阅读集成指南及 API 概述文档，了解服务端 API 的集成步骤及 API 的调用注意事项，并确保已完成以下预配置及环境准备工作：

  • 在 开发者中心 获得 client ID
  • 在 开发者中心 完成密钥配置
  • 已安装 Xcode 12 或更高版本
  • 确保 iOS 系统为 iOS 11 及以上版本
关键集成步骤

请根据以下步骤完成集成：

1

集成 SDK 资源包。

商户客户端

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

 

2

通过 AMSCashierPayment创建 SDK 实例：

商户客户端
  • 初始化收银台实例，包含以下参数：
    • configuration：必传，AMSCashierPaymentConfiguration 类型的一个对象，包含所有配置参数。
  • 创建 AMSCashierPaymentConfiguration 类，包含以下参数：
    • locale: 选传，NSString 类型。商户客户端识别用户浏览器使用的语言种类，并传入浏览器语言信息，SDK 根据此信息提供对应语言的页面。目前 SDK 仅支持以下多语言信息的值，如果传入的值不是以下几种，将提供英语页面：
      • en_US：英语
      • es_ES：西班牙语
      • fr_FR：法语
      • nl_NL：荷兰语
      • it_IT：意大利语
      • de_DE：德语
      • zh_CN：简体中文
    • options: 选传，NSDictionary 类型，用于设置是否采用默认loading样式以及是否使用沙箱环境，支持的值包括：​
      • "sandbox", "true"：沙箱环境
      • "sandbox", "false"：生产环境
      • "showLoading", "true"：使用默认 loading 样式
      • "showLoading", "false"：不使用默认 loading 样式
  • 实现 AMSPaymentProtocol 的协议，用于后续流程中对应事件发生时的处理，包含以下方法：
    • onEventCallback：收银台支付事件回调函数，返回事件码（eventCode）和事件具体信息（eventResult）。
  • 实现 AMSLoggerProtocol 的协议，用于管理日志输出，包含以下方法：
    • logWithName：默认输出日志的回调函数。
创建 SDK 实例的接口示例：
Objective-C
Editor
3

向 Alipay 服务器发起 支付会话创建 请求。

商户服务端

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

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

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

使用实例对象中的 createComponent 创建支付要素收集组件:

商户客户端
  • 使用 sessionData 参数创建配置对象: 将 支付会话创建 请求的响应中获取的 paymentSessionData 字段的完整数据传入 sessionData 参数。
  • 调用 createComponent() 函数创建支付要素收集组件。

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

    • 用户退出支付页面时，需要回收 支付会话创建 中的组件资源。
    • 用户发起多笔支付时，需要回收上一次 支付会话创建 中的组件资源。
调用 createComponent() 示例：
Objective-C
Editor
参考信息
事件码

SDK 提供的错误码如下：

  • SDK_INTERNAL_ERROR：SDK内部错误。请联系 Alipay 技术支持。
  • SDK_CREATEPAYMENT_PARAMETER_ERROR：createComponent 函数传入参数异常。请检查参数是否正确并重新初始化组件。
  • SDK_INIT_PARAMETER_ERROR：AMSCashierPayment函数传入参数异常。请检查参数是否正确并重新实例化 SDK。
  • SDK_CREATECOMPONENT_ERROR：组件初始化异常。请联系 Alipay 技术支持。
  • 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 场景下，如果经常出现此异常请联系Alipay 技术支持，排查跳转或唤端问题。

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

 

状态码: 用于展示服务端支付状态

  • 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.

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

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.

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

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.

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

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.

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

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