updateAmount

2026-07-27 07:31

POST /v1/payments/updateAmount

This API allows merchants to increase the authorized amount after completing a pre-authorization using pay (One-time Payments) and before initiating capture. This API can be called only when all of the following conditions are met:

A pre-authorization has been completed.
The initial pre-authorization response is successful.
The value of incrementalAuthorizationAvailable returned in the initial pre-authorization response is true.
No capture has been initiated.
The authorization has not been closed.
There is no in-progress incremental authorization request.

Note: By default, the system supports up to 10 amount adjustments. If the limit of 10 adjustments is exceeded, or if this API is called after capture, Antom returns INCREMENTAL_NOT_SUPPORT.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：

Note: Set the data type of each parameter (except array) as String. This means that you must use double quotation marks (" ") to enclose the parameter value. Examples:
If the data type of a parameter is Integer and its value is 20, set it as "20".
If the data type of a parameter is Boolean and its value is true, set it as "true".

Request parameters

updateRequestId String REQUIRED

The unique ID assigned by the merchant to identify an updateAmount request.

Note: This parameter is an API idempotency parameter. Antom uses this parameter to ensure idempotent processing.

More information:

Maximum length: 64 characters

paymentId String REQUIRED

The paymentId returned for the initial pre-authorization. This value must be the same as the paymentId returned by the pay (One-time Payments) API.

More information:

Maximum length: 64 characters

amount Amount REQUIRED

The new total authorized amount after this amount adjustment, not the incremental amount. In scenarios where the amount is adjusted multiple times, amount must be strictly greater than the current authorized total amount, that is, the amount after the last successful adjustment. If no amount adjustment has been made, the value of amount is equal to the paymentAmount of the initial pre-authorization.

Notes:
This parameter only supports amount increases. Amount decreases are not supported.
The currency must be the same as that of the initial pre-authorization.

Show child parameters

Response parameters

result Result REQUIRED

The result of the API call.

Show child parameters

updateRequestId String REQUIRED

The ID of the amount update request.

More information:

Maximum length: 64 characters

paymentId String REQUIRED

The original payment ID generated by Antom.

More information:

Maximum length: 64 characters

amount Amount REQUIRED

The updated amount.

Show child parameters

API Explorer

Sample CodesRun in Sandbox

Request

URL

Method

POST

Request Body

Response

Response Body

Result process logic

When the value of result.resultStatus is S: The amount adjustment request is accepted successfully. This does not mean that the actual amount adjustment is successful. The final result is returned through notifyPayment, where the value of notifyType is UPDATE_AMOUNT_RESULT.
When the value of result.resultStatus is F: The amount adjustment request fails to be accepted. The incremental amount does not take effect. Subsequent capture requests are still based on the pre-authorized amount or the amount after the last successful increment.
When the value of result.resultStatus is U: The result of the amount adjustment request is unknown. You can call the inquiryPayment API to query the result of this amount adjustment, or wait for the notifyPayment notification.

Result codes

resultCode	resultStatus	resultMessage	Further action
`SUCCESS`	`S`	Success.	No further action is needed.
`INCREMENTAL_NOT_SUPPORT`	`F`	The current transaction does not support incremental authorization. Triggering conditions include: 1. incrementalAuthorizationAvailable of the initial authorization is false; 2. The authorization has already been captured, including an in-progress capture, or has already been closed; 3. There is already an in-progress incremental authorization for the authorization.	Confirm that incrementalAuthorizationAvailable of the initial authorization is `true`, no capture or close has occurred, and there is no in-progress incremental authorization request.
`REPEAT_REQ_INCONSISTENT`	`F`	The same updateRequestId is used with a different amount.	Initiate the request again with a different updateRequestId, or verify the amount and initiate the request again with the same updateRequestId.