init()

2026-06-26 11:26

Note: Translation in progress.

init() 方法由商户应用调用，用于初始化 AMSPaymentElement 实例并传入 SDK 配置参数。

注意：该方法必须在 createComponent() 之前调用。

方法签名

copy
Future<void> init(
  Map<String, dynamic>? configurations,
  void Function(AMSStatusResult) onResult,
)

参数

参数	类型	是否必需	描述
configurations	Map<String, dynamic>	否	SDK 配置对象，以 key-value 形式传入。详见支持的配置项。
onResult	Function	是	初始化结果回调函数。用于返回初始化成功或失败的结果。详见 `onResult`。

支持的配置项

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

onResult

init() 方法的结果回调，接收一个 AMSStatusResult 对象，指示初始化是否成功。

参数	类型	是否必需	描述
result	AMSStatusResult	是	包含初始化状态和错误详情的状态结果。

返回值

此方法无返回值，初始化结果通过 onResult 回调异步返回。

错误码

*结果码（code***）	*状态（status***）	*建议给买家的提示（message***）	描述	操作建议
`UI_STATE_ERROR`	N/A	请求异常，交易无法发起。	创建 SDK 实例或 `createComponent()` 时机异常	集成代码异常，请自行排查。有问题联系 Antom 技术支持

最佳实践

回跳商户页面

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

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

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