AMSPaymentElementConfiguration

2026-06-26 10:56

AMSPaymentElementConfiguration 用于在初始化 Payment Element 前配置 SDK 参数。

声明

Objective-C

Swift

copy
@interface AMSPaymentElementConfiguration : AMSConfiguration

- (instancetype)init;

@end

属性

参数

类型

是否必需

描述

locale

String?

否

首选语言。由语言代码（ISO-639）和国家代码（ISO-3166）通过下划线连接组成，例如 new Locale("en", "US")。有效值为：

en_US：默认值。英语
pt_BR：葡萄牙语（巴西）
pt_PT：葡萄牙语
es_ES：西班牙语
ko_KR：韩语
zh_CN：简体中文
zh_HK：繁体中文
ms_MY：马来西亚语
in_ID：印度尼西亚语
th_TH：泰语
vi_VN：越南语
tl_PH：菲律宾语
it_IT：意大利语
de_DE：德语
fr_FR：法语
nl_NL：荷兰语
ja_JP：日语
ro：罗马尼亚语
pl_PL：波兰语
ar_SA：阿拉伯语
tr_TR：土耳其语
hi_IN：印度语

注意：如果不传或传入的语言值不在以上范围内，系统将默认使用英语。

options

[String: Any]?

否

配置选项字典，用于传递额外的配置参数。参见可用的 key。

可用的 key

Key	值类型	描述
sandbox	Bool	是否启用沙箱环境。 `true`：沙箱环境。 `false`：默认值。生产环境。
showLoading	Bool	是否在请求过程中显示加载动画。 `true`：默认值。使用默认加载模式。 `false`：不使用默认加载模式。设为 `false` 时，建议配合加载事件回调自行自定义。
notRedirectAfterComplete	Bool	用于设置支付完成后是否跳转回您的页面。有效值为： `false`：默认值。表示支付成功后自动跳回您的页面，支付失败或其他场景不会自动回跳，需要您自行处理。当值为空时同理。 `true`：表示支付完成后不跳转，您需要通过客户端事件码自行控制支付完成后续流程。注意：支付成功或失败在回跳商户页面的最佳实践参见回跳商户页面。客户端返回的支付结果事件码仅用于客户端页面的跳转操作参考，交易状态的更新请以服务端 notifyPayment 或 inquiryPayment 接口返回的结果为准。该参数仅针对 Payment Element 内完成支付的支付方式生效。
appearance	String（JSON）	用于自定义外观配置，更多信息请参阅自定义外观样式。其包含以下参数： theme：String 类型，主题颜色。 layout：String 类型，布局配置。 variables：Object 类型，通过 CSS 设计 Token（如 `content-primary`）覆盖底层 CSS 自定义属性，实现主题定制。

最佳实践

回跳商户页面

回跳商户页面及返回支付结果有以下情况，请您按照指引进行处理：

notRedirectAfterComplete	支付结果	建议操作
`true`	成功/失败	若您在创建 Payment Element 实例时将 notRedirectAfterComplete 设置为 true 且该支付方式支持在 SDK 内完成支付，将通过 `onSubmitPayCallback()` 返回支付结果，您需要根据对应场景下 `onSubmitPayCallback()` 返回的支付结果事件码自行处理跳转逻辑：非存卡支付场景存卡支付场景
`false`	成功	支付完成后 Payment Element 会自动跳转至您在 createPaymentSession（单笔支付）接口中传入的 paymentRedirectUrl 。
`false`	失败	通过 `onSubmitPayCallback()` 返回支付结果，您需要根据对应场景下 `onSubmitPayCallback()` 返回的支付结果事件码自行处理跳转逻辑：非存卡支付场景存卡支付场景

注意：
如果支付方式不支持在 SDK 内支付，支付结果不会通过 onSubmitPayCallback() 函数返回。跳转到外部支付方式页面完成支付后，由支付方式决策是否自动回跳到您传入的 paymentRedirectUrl。
onSubmitPayCallback() 函数返回的支付结果仅用于客户端页面流转以及状态展示，最终的订单状态请通过步骤 4：获取支付结果获取。