createMandate

2026-10-20 09:48

POST /v1/payments/createMandate

Call this API to create a one-time payment mandate.

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 field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

If the data type of a field is Integer and its value is 20, set it as "20".
If the data type of a field is Boolean and its value is true, set it as "true".

Request parameters

mandateRequestId String REQUIRED

Payment mandate request assigned by the merchant. The system queries and uniquely identifies an operation by merchantId + mandateRequestId.

More information:

Maximum length: 64 characters

accessToken String REQUIRED

Antom agreement token obtained after authorization is completed. This token must belong to the current merchant and be resolvable to a valid agreement.

More information:

Maximum length: 128 characters

paymentAmount Amount REQUIRED

Payment amount.

The channel creates a one-time payment mandate based on the exact amount and currency in this object. Subsequent payments must use the same bound amount and currency.

Show child parameters

Response parameters

result Result REQUIRED

Result of the API call.

Show child parameters

mandateRequestId String

Request ID provided by the merchant. Returned only when APO successfully parses this parameter. This parameter is used for request correlation and does not indicate that the payment mandate was successfully created.

More information:

Maximum length: 64 characters

mandateId String

Antom payment mandate ID.

Note: This parameter is returned only when result.resultStatus is S. Used for subsequent one-time payment calls.

More information:

Maximum length: 64 characters

validFrom Datetime

Effective time of the payment mandate.

Note: This parameter is returned only when result.resultStatus is S.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

validUntil Datetime

Expiration time of the payment mandate.

Note: This parameter is returned only when result.resultStatus is S.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

API Explorer

Request

URL

Method

POST

Request Body

Response

Response Body

Error codes

*resultCode*	Value	Message	Further action
`SUCCESS`	`S`	A new order is created successfully, or an original `SUCCESS` result is replayed.	Save the original mandate and validity period.
`CURRENCY_NOT_SUPPORT`	`F`	The currency is not included in the system-supported currency enum values.	Check and use a value from the system currency enum. Passing enum validation does not necessarily mean the currency is supported by the channel. Existing orders are still processed according to the original amount and currency comparison rules.
`INVALID_ACCESS_TOKEN`	`F`	In the new creation path, the token cannot be parsed into a valid format, or the channel authoritatively confirms that the agreement does not exist and the reason cannot be further categorized.	Do not return the token content. Correct the token or sign the agreement again. Do not assume that the token is expired or revoked.
`PAYMENT_NOT_QUALIFIED`	`F`	The channel explicitly returns `NOT_SUPPORT_MERCHANT`.	Contact integration support to verify channel capability. Do not confuse this with API authentication.
`REPEAT_REQ_INCONSISTENT`	`F`	The repeated request content is inconsistent.	Check paymentAmount.currency and paymentAmount.value against the original request record and restore the original amount and currency. Do not modify the original order.
`REPEATED_SUBMIT`	`F`	An existing order with the same amount and currency is in `INIT` or `PROCESSING` status, or the first concurrent insert failed due to competition.	Only retry with the same request ID after waiting according to the backoff guidance in this document, or use a new order after the 10-minute condition is met.
`UNKNOWN_EXCEPTION`	`U`	The first channel gateway result is `UNKNOWN_EXCEPTION`.	The original order is in `PROCESSING` status. Keep the original request ID and query with the same ID according to the backoff guidance in this document. A new order can be created after the 10-minute condition is met.
`REQUEST_TRAFFIC_EXCEED_LIMIT`	`F`	The request traffic exceeds the limit. This product error code has been confirmed to exist.	Keep the original request ID, amount, and currency. Follow the explicit retry instructions or back off as recommended. Do not infer the final status of the historical original order based on this error.
`PARAM_ILLEGAL`	`F`	Required request parameters are missing, blank, too long, or in an invalid format, or request validation fails, such as paymentAmount.value not being an integer greater than 0.	Check and correct the parameters according to the request field definitions, and then call the API again. When recovering an existing order with the same request ID, keep the original business intent, amount, and currency. Do not resubmit invalid parameters unchanged.
`PROCESS_FAIL`	`F`	During creation result assembly, the order status is not one of `SUCCESS`, `FAIL`, `INIT`, or `PROCESSING`, or the failure result information is missing. This code is also returned when the channel response code is a recognizable standardized `PROCESS_FAIL`.	Stop subsequent debits. Keep the original request ID, response, and masked trace, and contact Antom technical support for troubleshooting. Before verifying the original creation result, do not blindly recreate the order with a new request ID, and do not rewrite the original order status based on this error.