AMSPaymentElementConfiguration

2026-07-03 08:21

AMSPaymentElementConfiguration is used to configure SDK parameters before initializing Payment Element.

Declaration

Objective-C

Swift

copy
@interface AMSPaymentElementConfiguration : AMSConfiguration

- (instancetype)init;

@end

Property

Parameter

Type

Required

Description

locale

String?

Preferred language. Composed of a language code (ISO-639) and country code (ISO-3166) connected by an underscore, for example, new Locale("en", "US").

Valid values are:

en_US: Default value. English
pt_BR: Portuguese (Brazil)
pt_PT: Portuguese
es_ES: Spanish
ko_KR: Korean
zh_CN: Simplified Chinese
zh_HK: Traditional Chinese
ms_MY: Malay
in_ID: Indonesian
th_TH: Thai
vi_VN: Vietnamese
tl_PH: Filipino
it_IT: Italian
de_DE: German
fr_FR: French
nl_NL: Dutch
ja_JP: Japanese
ro: Romanian
pl_PL: Polish
ar_SA: Arabic
tr_TR: Turkish
hi_IN: Hindi

Note: If no value is passed or the language value passed is not within the above range, the system will default to using English.

options

[String: Any]?

Configuration options dictionary, used to pass additional configuration parameters. See Available keys.

Available keys

Key	Data type	Description
sandbox	Bool	Whether to use the sandbox environment. `true`: sandbox environment. `false`: Default value. Production environment.
showLoading	Bool	Whether to display a loading animation during the request process. `true`: Default value. The default loading mode is used. `false`: The default loading mode is not used. When set to `false`, it is recommended to customize your own loading event callbacks.
notRedirectAfterComplete	Bool	Used to set whether to redirect back to your page after payment completion. Valid values are: `false`: Default value. Redirects to your page after successful payment completion. Automatic redirection does not occur in cases of payment failure or other scenarios, and you need to handle those situations manually. The same applies if the value is empty. `true`: No redirection after payment completion. You need to manually control the subsequent payment flow based on client-side event codes. Notes: For best practices on redirecting back to the merchant page upon payment success or failure, please refer to Redirect to the merchant page. The payment result event codes returned on the client-side are for reference only in page navigation. Transaction status updates must be based on the results returned by the server-side notifyPayment or inquiryPayment API. This parameter only takes effect for payment methods that complete payment within the Payment Element.
appearance	String（JSON）	Used for custom appearance configuration. For more information, refer to Appearance customization. It contains the following parameters: theme: String type, theme color. layout: String type, layout configuration. variables: Object type, override underlying CSS custom properties using CSS design tokens (e.g., `content-primary`) to implement theme customization.

Best practices

Redirect to the merchant page

The following scenarios describe how redirecting to the merchant page and returning payment results are handled. Please follow the guidelines below:

notRedirectAfterComplete	Payment result	Recommended action
`true`	Success/Failure	If you set notRedirectAfterComplete to `true` when creating the Payment Element instance and the payment method supports completing payments within the SDK, the payment result will be returned via the `onSubmitPayCallback()` method. You need to handle the redirect logic based on the payment result event code returned by the `onSubmitPayCallback()` method in the corresponding scenario: Non-saved card payment scenario Saved card payment scenario
`false`	Success	After payment is completed, Payment Element will automatically redirect to the paymentRedirectUrl result page you provided in the createPaymentSession (One-time Payments) API.
`false`	Failure	The payment result will be returned via the `onSubmitPayCallback()` method. You need to handle the redirect logic based on the payment result event code returned by the `onSubmitPayCallback()` method in the corresponding scenario: Non-saved card payment scenario Saved card payment scenario

Notes:
If the payment method does not support payment within the SDK, the payment result will not be returned via onSubmitPayCallback(). After completing the payment on the external payment page, the payment method will determine whether to automatically redirect back to the paymentRedirectUrl you provided.
The payment results returned by the onSubmitPayCallback() method are only for client-side page navigation and status display. For the final order status, please obtain it through Step 4: Obtain the payment result.