# Overview

> Antom online and in-store payment products offer a set of APIs that provide the ability to integrate with Antom. You can use the POST method to send HTTPS requests and receive responses accordingly.

Antom online and in-store payment products offer a set of APIs that provide the ability to integrate with Antom. You can use the `POST` method to send HTTPS requests and receive responses accordingly.

The following section introduces the message structure and the end-to-end message transmission workflow.

## Versioning

The current API version is `v2`. The version is specified in the URL. For example, `https://host/openapi/v2/payments/pay`.

## Message structure

Before you make any payments, it is important to understand how Antom APIs work and how requests and responses are structured. This section presents general information (such as message structure and message transmission workflow) of online messages between your system and Antom. A message refers to the request message or the response message.

### Request structure

The following figure illustrates the request message structure:

![Request structure.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/9a262f04-ad0a-4672-851b-1e77ff55e4be.png)

Figure 1. Request structure

#### HTTPS method

POST

#### Request header

The request header mainly contains the following fields.

> **Note**: Field names are case-insensitive.

| **Header field** | **Required** | **Description** | **Code sample** |
| --- | --- | --- | --- |
| _Signature_ | Yes | Contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=). The following keys can be configured: - **algorithm**: Specifies the digital signature algorithm used to generate the signature. RSA256 is supported, and the key length must be 2048 bits. - **keyVersion**: Specifies the key version used to generate or verify the signature. By default, the value is the latest version of the key associated with _Client-Id_. - **signature**: Contains the signature value for the request. | `Signature: algorithm=RSA256, keyVersion=1, signature=****` |
| _Encrypt_ | Yes | Uses keys to transform plaintext into ciphertext through an encryption algorithm which can be transmitted securely. - **algorithm**: Specifies the digital signature algorithm used to generate the signature. Only RSA\_AES is supported, which indicates that both RSA and AES are used for encryption. - **keyVersion**: Specifies the key version that is used to encrypt. By default, the value is the latest version of the key associated with _Client-Id_. - **symmetricKey**: Specifies the key used to convert ciphertext into plaintext or plaintext into ciphertext, consisting of numbers, words, letters and, their combinations. | `algorithm=RSA_AES,keyVersion=1,symmetricKey=********` |
| _Content-Type_ | Yes | Indicates the media type of the body of the request, in which, _charset_ is used for generating/validating a signature. | `Content-Type: application/json; charset=UTF-8` |
| _Client-Id_ | Yes | Used to identify a client and is associated with the keys that are used for the signature. > **Note**: The serial number of the payment terminal is the value of this field. | `Client-Id: ****` |
| _Request-Time_ | Yes | Specifies the timestamp of when the request is sent, as defined by [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html). > **Note**: The value of this field must be accurate to milliseconds. | `Request-Time: 2019-04-04T12:08:56.253+05:30` |
| _Accept_ | No | Used by the client to inform the server of which content types the client can handle. To specify the value of this field, enter MIME content types and use commas to separate each type. > **Note**: For requests sent by D-Store, the value of the Accept field is `text/plain,text/xml,text/javascript,text/html,application/json`. | `Accept: text/plain,text/xml,text/javascript,text/html,application/json` |

#### Request body

The request body contains the detailed request information in JSON format. Fields enclosed in the request body vary depending on services. The request body must contain the following fields:

| **Field** | **Type** | **Required** | **Description** | **Sample** |
| --- | --- | --- | --- | --- |
| _extendInfo_ | String | Yes | Extended information field for the merchant to pass custom data. | ```json { "extendInfo": "test" } ``` |

For more information, see the specific API specification document.

### Response structure

The following figure illustrates the response structure:

![Response structure.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/b3cbb3ad-faf7-44c1-a164-701309891c17.png)

Figure 2. Response structure

#### Response header

The response header carries the information about the response, mainly containing the following fields.

> **Note**: Field names are case-insensitive.

| **Header field** | **Required** | **Description** | **Code sample** |
| --- | --- | --- | --- |
| _Signature_ | Yes | Contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=). The following keys can be configured: - **algorithm**: Specifies the digital signature algorithm used to generate the signature. RSA256 is supported, and the key length must be 2048 bits. - **keyVersion**: Specifies the key version used to generate or verify the signature. By default, the value is the latest version of the key associated with _Client-Id_. - **signature**: Contains the signature value for the request. | `Signature: algorithm=RSA256, keyVersion=1, signature=****` |
| _Encrypt_ | Yes | Uses keys to transform plaintext into ciphertext through an encryption algorithm which can be transmitted securely. - **algorithm**: Specifies the digital signature algorithm used to generate the signature. Only RSA\_AES is supported, which indicates that both RSA and AES are used for encryption. - **keyVersion**: Specifies the key version that is used to encrypt. By default, the value is the latest version of the key associated with _Client-Id_. - **symmetricKey**: Specifies the key used to convert ciphertext into plaintext or plaintext into ciphertext, consisting of numbers, words, letters and, their combinations. | `algorithm=RSA_AES,keyVersion=1,symmetricKey=********` |
| _Content-Type_ | Yes | Indicates the media type of the body of the request, in which, _charset_ is used for generating/validating a signature. | `Content-Type: application/json; charset=UTF-8` |
| _Client-Id_ | Yes | Used to identify a client and is associated with the keys that are used for the signature. > **Note**: The serial number of the payment terminal is the value of this field. | `Client-Id: ****` |
| _Request-Time_ | Yes | Specifies the timestamp of when the request is sent, as defined by [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html). > **Note**: The value of this field must be accurate to milliseconds. | `Request-Time: 2019-04-04T12:08:56.253+05:30` |

#### Response body

The response body contains the information responding to the client. Fields in this section vary depending on services. However, the _result_ field, which indicates the result of an API call, is always contained.

When the result status (_resultStatus_) is failed, the result code (_resultCode_) is an error code, the result message (_resultMessage_) is an error message, which is used for troubleshooting. For more information about how to resolve errors, see **R****esult/Error codes** in the specific API.

| **Field** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| _resultStatus_ | String | No | Result status. Valid values are: - `S` : Successful - `F` : Failed - `U` : Unknown |
| _resultCode_ | String (64) | No | Result code. |
| _resultMessage_ | String (256) | No | Result message that describes the result code and status in details. |

## Message transmission workflow

The whole interaction sequence is illustrated below:

![Message transmission workflow.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/f6dc852d-72ae-408f-b7f5-7947167a1fc8.png)

Figure 3. Message transmission workflow

### Overall procedure

Follow the overall procedure to call an API.

#### Preparations

To prevent some potential errors that you might get in the response, consider the following factors:

-   To prevent potential errors that you might get in the response, understand [API idempotency](#o07qw).
-   Encode a request that contains special characters.

##### 1\. Construct a request

Construct a request by complying with the [request structure](#27AER), for example, by adding the _client-Id_, _request-time_, _signature_, and other fields to the request header.

To ensure the message transmission security, perform the following security measures when constructing a request:

-   Sign the request message. Message signing and signature validation are required for all requests and responses. For more information, see [sign a request and validate the signature](https://docs.antom.com/ac/ams/digital_signature.md).
-   Encode the request to prevent errors or ambiguity that might be caused by special characters enclosed in the request. For details, see [Message encoding](https://docs.antom.com/ac/ams/me.md).    

##### 2\. Send a request

You can send a request with your preferred platforms or tools, for example, Postman or cURL command.

##### 3\. Check the response

The response is usually returned in JSON or XML format. For details about the response, see the [Response structure](#kUzLQ) section. After you receive the response, validate the signature of the response.

##### 4\. Check the status code

The response data varies depending on the services. However, the _result_ field, which indicates the result of an API call, is always contained. If an error occurs, an error response is returned, where the [`result`](#bjrQP) object indicates the error code and error message for you to troubleshoot issues.

## Idempotency

During the payment process, the POS system might send the same payment request (with the same _paymentRequestId_) multiple times due to reasons such as network timeouts or repeated submissions. Antom uses an idempotency key to ensure that the same payment request is processed only once. This effectively prevents duplicate deductions and ensures the security of the user's funds.

Processing rules:

-   Payment is successful: If the payment corresponding to this _paymentRequestId_ has been completed, it directly returns:

-   _resultStatus_ = `S` (Success)
-   _resultCode_ = `SUCCESS`

-   Payment in progress: If the payment corresponding to this _paymentRequestId_ is still being processed asynchronously, it returns:

-   _resultStatus_ = `U` (In progress)
-   _resultCode_ = `PAYMENT_IN_PROGRESS`

-   Payment failed: If the payment corresponding to this _paymentRequestId_ has been confirmed as failed, it returns:

-   _resultStatus_ \= `F` (Failed)
-   _resultCode_ = `PAYMENT_FAIL`


By identifying each payment request with a unique _paymentRequestId_ and returning a clear response based on its final status, the reliability and user experience of the payment system are significantly improved.