# submitPayment()

> This method is used to initiate a payment request to the server. After the buyer clicks your custom payment button, the SDK will automatically process payment information, advance the transaction flow based on the selected payment method, and perform operations such as 3D authentication when required.

 This method is used to initiate a payment request to the server. After the buyer clicks your custom payment button, the SDK will automatically process payment information, advance the transaction flow based on the selected payment method, and perform operations such as 3D authentication when required. Payment results and exception information will be returned through asynchronous callbacks.

## Method signature {#FmLyb}

 When calling this method, please use the following standard method signature format.

<!-- TabGroup -->

**Tab: JavaScript**

```javascript
submitPayment(options)
```

**Tab: TypeScript**

```typescript
submitPayment(options?: SubmitFuncParams): Promise<IPaymentApiResponse>
```

<!-- /TabGroup -->

## Parameters {#l1R91}

 The following parameters are used to configure the submission options for the payment request.

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| [*options*](#yVmLP) | Object | No | Configuration options for submitting the payment request. |

### *options* {#yVmLP}

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| *handleActions* | Boolean | No | Indicates whether the SDK handles automatic redirects. Valid values are: - `true`  : Default value. The SDK automatically controls the payment flow. - `false`  : The SDK will return the URL information required for payment, and you will handle the redirect or app launch yourself. This scenario is suitable for non-browser environments or when custom redirect logic is needed.   > **[INFO]** **Note**    : Custom redirect control (when     *handleActions*     is   `false`  ) is only applicable to scenarios other than card, [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md), and [Google Pay](https://docs.antom.com/ac/antomop/googlepay.md). |
| [*shippingInfo*](#Am5lZ) | Object | No | Used to submit shipping address information. |

#### *shippingInfo* {#Am5lZ}

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| [*shippingAddress*](#FdEPO) | Object | Yes | Shipping address information. |
| [*shippingName*](#fIigX) | Object | Yes | Recipient name information. |
| *shippingPhoneNo* | String | Yes | Recipient's phone number in E.164 international standard format. |

##### *shippingAddress* {#FdEPO}

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| *region* | String | Yes | Two-letter country or region code compliant with   [ISO 3166](https://www.iso.org/obp/ui/#search)   standard. |
| *state* | String | Yes | State, province, or 2-3 letter region code compliant with   [ISO 3166-2](https://www.iso.org/obp/ui/#search)   standard. |
| *city* | String | Yes | City name. |
| *address1* | String | Yes | Address line 1. |
| *address2* | String | Yes | Address line 2. |
| *zipCode* | String | Yes | Postal code. |

##### *shippingName* {#fIigX}

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| *firstName* | String | Yes | Recipient's first name. |
| *lastName* | String | Yes | Recipient's last name. |
| *middleName* | String | No | Recipient's middle name (if available). |
| *fullName* | String | No | Recipient's full name. |

## Return value {#4Kxd3}

 Returns a   `Promise`   object that resolves to an object containing the payment result.

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| *status* | String | Yes | Payment status. You can simplify the integration processing based on the value of     *status*    . You may also perform refined exception handling based on     *error?.code*    . Valid values are: - `SUCCESS`  : Payment succeeded. - `FAIL`  : Payment failed. - `PROCESSING`  : Payment processing. - `CANCELLED`  : Payment canceled. |
| *userCanceled3D* | Boolean | No | Indicates whether the buyer actively closed the 3D Secure authentication popup. Valid values are: - `true`  : Buyer actively terminated the 3D process. When this value is returned, it is recommended to poll the result from the server. - `false`  : 3D process was not terminated by the buyer. |
| [*session*](#BvOgO) | Object | No | Payment session information. |
| [*error*](#ewOaK) | Object | No | This parameter is only returned when the operation fails, and is an *error* object containing     *code*     and     *message*     parameters. If not returned, the operation was successful. |

### *session* {#BvOgO}

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| [*nextAction*](#Hmd3J) | Object | No | Provides necessary information when additional steps are required in the payment process (e.g., manual app launch handling). |

#### *nextAction* {#Hmd3J}

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| *applinkUrl* | String | No | App Link URL (iOS Universal Link or Android App Link). |
| *schemeUrl* | String | No | Custom URL Scheme link. |
| *normalUrl* | String | Yes | Regular H5 page link. |

### *error* {#ewOaK}

 | **Parameter** | **Data type** | **Required** | **Description** |
| --- | --- | --- | --- |
| *code* | String | Yes | Error code. |
| *message* | String | Yes | Error message. |
| *traceId* | String | No | Trace ID for issue investigation. |
| *context* | Any | No | Error context information. |

## Error codes {#bflMZ}

 > **[INFO]** **Note**    : The payment results returned by the   `submitPayment().then()`   method are only for client-side page navigation and status display. For the final order status, please obtain it through   [Step 3: Obtain the payment result](https://docs.antom.com/ac/cashierpay/element.md?platform=web-wap#MxqX3)  .

 | ***code*** | ***status*** | **Suggested prompt for buyers (*message*)** | **Description** | **Recommended action** |
| --- | --- | --- | --- | --- |
| `UNKNOWN_EXCEPTION` | `PROCESSING` | 未知异常。请检查付款情况并联系商户。 | Due to unknown reasons, the API call failed. | It is recommended to poll the payment result from the server. If no payment result is found, you can re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `INQUIRY_PAYMENT_SESSION_FAILED` | `FAIL` | 订单状态异常。请检查付款情况并联系商户。 | The payment session has expired. | The order has timed out and been closed. Please use a new     *paymentRequestId*     to initiate the payment again. |
| `UI_STATE_ERROR` | `FAIL` | 请求异常，交易无法发起。 | The timing of the `[mount()](https://docs.antom.com/ac/sdks/web_mount.md)` method call is abnormal. | Integration code exception. Please troubleshoot. If the problem persists, contact Antom technical support. |
| `ERR_DATA_STRUCT_UNRECOGNIZED` | None | 请求异常，交易无法发起。 | The SDK    did not return the required payment information. | Please contact Antom technical support for details. |
| `USER_BALANCE_NOT_ENOUGH` | `FAIL` | 用户余额不足。请充值或选择其它支付方式。 | Payment failed due to insufficient buyer balance for the selected payment method. | Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `ORDER_NOT_EXIST` | `FAIL` | 订单状态异常。请检查付款情况并联系商户。 | The order does not exist. | Please contact Antom technical support for details. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `PROCESS_FAIL` | `FAIL` | 支付失败。请检查付款情况并联系商户。 | Common business failure occurred. | Please contact Antom technical support for details. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `ORDER_IS_CANCELLED` | `FAIL` | 订单状态异常。请检查付款情况并联系商户。 | The order has been cancelled. | The order has been cancelled. To make another payment, you need to use a new *paymentRequestId* to re-initiate the payment. |
| `RISK_REJECT` | `FAIL` | 风控拒绝。建议换卡重试或联系发卡行。 | Due to risk control, the transaction cannot be further processed. If the buyer has made payment for the transaction, it will be refunded. | Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `ORDER_IS_CLOSED` | `FAIL` | 订单状态异常。请检查付款情况并联系商户。 | The request you initiated uses the same     *paymentRequestId*     as a closed transaction. | The order has timed out and been closed. Please use a new     *paymentRequestId*     to initiate the payment again. |
| `ACCESS_DENIED` | `FAIL` | 支付失败。请检查付款情况并联系商户。 | The access is denied. | Please contact Antom technical support for details. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `CARD_EXPIRED` | `FAIL` | 卡片已过期，请核对过期日期或使用其他卡片。 | The bank card used for the transaction has expired. | Antom has notified the buyer, and no further action required. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `INVALID_EXPIRY_DATE_FORMAT` | `FAIL` | 卡片过期时间不正确，请核对过期日期或使用其他卡片。 | The format of     *expiryYear*     or     *expiryMonth*     is incorrect. | Antom has notified the buyer, and no further action required. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `INVALID_EXPIRATION_DATE` | `FAIL` | 卡片过期时间不正确，请核对过期日期或使用其他卡片。 | The value of     *paymentMethod.paymentMethodMetaData.expiryYear*     or     *paymentMethod.paymentMethodMetaData.expiryDate*     is invalid. | Antom has notified the buyer, and no further action required. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `INVALID_CVV` | `FAIL` | 卡片 CVV 不正确，请核对 CVV 或使用其他卡片。 | The bank card used for the transaction has an invalid CVV. | Antom has notified the buyer, and no further action required. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `INVALID_CARD_NUMBER` | `FAIL` | 卡号不正确，建议换卡重试或联系发卡行。 | The bank card used for the transaction has an invalid card number. | Antom has notified the buyer, and no further action required. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `SELECTED_CARD_BRAND_NOT_AVAILABLE` | `FAIL` | 卡品牌不支持，建议换卡重试或联系发卡行。 | The card brand you specified for transactions is not supported. | The card brand you specified for transactions is not supported. Please troubleshoot. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `CARD_NOT_SUPPORTED` | `FAIL` | 卡片不支持。建议换卡重试或联系发卡行。 | The bank card used for the transaction is not supported. | Antom has notified the buyer, and no further action required. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `CARD_BIN_QUERY_ERROR` | `FAIL` | 卡号不正确。建议换卡重试或联系发卡行。 | The bank card used for the transaction has an invalid card number. | Antom has notified the buyer, and no further action required. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `PAYMENT_IN_PROCESS` | `PROCESSING`  / `PENDING` | 支付正在处理中，请等待支付完成。 | The payment is being processed. | `PROCESSING`   indicates that no payment result is found after the SDK inquiry. It is recommended to poll the payment result from the server, and re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. You can check the     *userCanceled3D*     field in the response to determine whether the buyer manually closed the 3D Secure pop-up: - `true`  : The buyer manually aborts the 3D Secure process. - `false`  : The 3D Secure process is not aborted by the buyer. |
| `CURRENCY_NOT_SUPPORT` | `FAIL` | 商户不支持该币种，交易无法发起。 | The currency is not supported. | Please contact Antom technical support for details. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `INVALID_CARD` | `FAIL` | 卡号无效，请核对卡片详细信息或使用其他卡片。 | Invalid bank card. Possible reasons include: the bank card number cannot be recognized, the card has no corresponding issuing bank, or the card number format is incorrect. | Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `ISSUER_REJECTS_TRANSACTION` | `FAIL` | 发卡行拒绝交易，建议换卡重试或联系发卡行。 | The issuing bank rejects the transaction. | Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `INVALID_MERCHANT_STATUS` | `FAIL` | 商户状态异常，交易无法发起。 | The merchant status is abnormal because restrictions exist. | Please contact Antom technical support for details. |
| `KEY_NOT_FOUND` | `FAIL` | 未知异常。请检查付款情况并联系商户。 | The private key or public key of Antom or the merchant is not found. | Please contact Antom technical support for details. |
| `MERCHANT_KYB_NOT_QUALIFIED` | `FAIL` | 商户状态异常，交易无法发起。 | The payment failed to your abnormal KYB status. You are either not KYB compliant, or the KYB status is not qualified for this transaction. | Please contact Antom technical support for details. |
| `NO_PAY_OPTIONS` | `FAIL` | 没有可用的支付选项。 | No payment options are available. | Please contact Antom technical support for details. |
| `PARAM_ILLEGAL` | `FAIL` | 未知异常。请检查付款情况并联系商户。 | The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are incorrect. | Please contact Antom technical support for details. |
| `PAYMENT_AMOUNT_EXCEED_LIMIT` | `FAIL` | 商户支付金额超过限额，交易无法发起。 | The payment amount is greater than the maximum amount allowed by the contract or payment method. | Check whether the payment amount exceeds the limit, or use a lower amount and try again. Use a new *paymentRequestId* to change the amount and re-initiate the payment. |
| `PAYMENT_COUNT_EXCEED_LIMIT` | `FAIL` | 商户支付次数超过限制使用次数，交易无法发起。 | The maximum number of payments exceeds the limit specified by the payment method. | Please contact Antom technical support for details. |
| `PAYMENT_NOT_QUALIFIED` | `FAIL` | 商户状态异常，交易无法发起。 | You are not eligible to make payments, possibly because you are not registered, have not signed the Tokenized Payment contract, or are prohibited from making payments. | Please contact Antom technical support for details. |
| `SUSPECTED_CARD` | `FAIL` | 风控拒绝。建议换卡重试或联系发卡行。 | The bank card is suspected of fraud. For example, it may be stolen or restricted. | Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `SYSTEM_ERROR` | `FAIL` | 未知异常。请检查付款情况并联系商户。 | A system error occurred. | Please contact Antom technical support for details. Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `USER_AMOUNT_EXCEED_LIMIT` | `FAIL` | 金额超限。使用小于或等于账户可用余额的金额重新发起支付。 | The payment amount exceeds the buyer payment limit. | Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `USER_KYC_NOT_QUALIFIED` | `FAIL` | 用户状态异常。建议换卡重试或换支付方式重试。 | The payment failed because of the buyer's KYC status. The buyer 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). | Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `USER_PAYMENT_VERIFICATION_FAILED` | `FAIL` | 用户状态异常。建议换卡重试或联系发卡行。 | The buyer is restricted from making payments by the payment method provider. | Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `USER_STATUS_ABNORMAL` | `FAIL` | 用户状态异常。建议换卡重试或联系发卡行。 | The buyer status is abnormal on the payment method side. | Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `DO_NOT_HONOR` | `FAIL` | 支付被发卡行拒绝。建议换卡重试或联系发卡行。 | The payment is rejected by the issuing bank. | Display a pop-up message to the buyer. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `EXTERNAL_RESOURCE_LOAD_FAILED` | `FAIL` | 请求异常，请检查网络状况或者设备情况。 | Google/Apple resource error. | Buyer network exception detected, or their device does not support payments via Google, Apple, or other third‑party‑dependent platforms. It is recommended to display a pop‑up prompting the buyer to check their payment execution environment. |
| `SUBMIT_PAYMENT_TIMEOUT` | `PROCESSING` | 请求异常，交易无法发起。 | Network exception occurred during payment submission. | Buyer network exception or Antom service exception detected. Please try to poll the payment result from the server. If the payment result cannot be retrieved, re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `PAYMENT_RESULT_TIMEOUT` | `PROCESSING` | 请求异常，交易无法发起。 | Network exception occurred while retrieving the payment result. | Please try to poll the payment result from the server. If the payment result cannot be retrieved, re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `USER_CANCELED` | `PROCESSING` | 无。 | The buyer closed the QR code or leading pop-up manually. | Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |
| `FORM_INVALID` | `FAIL` | 无。 | Incorrect payment information entered. | Antom has notified the buyer, and no further action required. Re-initiate `submitPayment()` using the existing *paymentSessionData* within the payment session validity period. |

## Best practices {#Sb5b0}

### Loading management {#KxZls}

 Before calling the   `submitPayment()`      method, you may add a     *loading*     indicator and close it when handling the callback in the   `.then()`      method.