# inquiryPayment

> The inquiryPayment API is called by the POS to query the payment status, typically when the POS does not receive a transaction response from the payment terminal.

POST `/v2/payments/inquiryPayment`

The **inquiryPayment** API is called by the POS to query the payment status, typically when the POS does not receive a transaction response from the payment terminal.

## Structure

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

-   [Request header](https://docs.antom.com/ac/omnichannel/api_fund.md#NvOFY)
-   [Response header](https://docs.antom.com/ac/omnichannel/api_fund.md#neaKh)

### Request parameters

| **Parameter name** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| _paymentRequestId_ | String | Yes | The unique ID that is defined by the POS provider to identify a payment request. - Maximum length: 64 characters. - Only letters (a-z, A-Z), numbers (0-9), and underscores (\_) are allowed. > **Note**: This parameter is unique for each store. Call the **inquiryPayment** API with the _paymentRequestId_ to query the payment status. Each call returns the latest payment result. |

### Response parameters

| **Parameter name** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| _result_ | [Result](#ragr7) | Yes | The result of the API call. |
| _paymentRequestId_ | String | Yes | The unique ID that is defined by the POS provider to identify a payment request. - Maximum length: 64 characters. - Only letters (a-z, A-Z), numbers (0-9), and underscores (\_) are allowed. > **Note**: This parameter is unique for each store. Call the **inquiryPayment** API with the _paymentRequestId_ to query the payment status. Each call returns the latest payment result. |
| _paymentId_ | String | Yes | The unique ID that is defined by the POS provider to identify a payment and consistent with the _paymentId_ in transaction reports. |
| _paymentCreateTime_ | String | Yes | The date and time when the payment is created. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". |
| _paymentTime_ | String | Yes | The date and time when the payment reaches a final state of success. The value follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. For example, "2019-11-27T12:01:01+08:00". |
| _paymentStatus_ | String | Yes | Indicates the final status of payment. Valid values are: - `SUCCESS`: The payment is successful. - `FAIL`: The payment failed. - `PROCESSING`: The payment is under processing. - `CANCELLED`: The payment is canceled. - `PENDING`: The payment completed, waiting for final payment result. |
| _paymentAmount_ | [Amount](#ragr7) | Yes | The payment amount that the merchant requests to receive in the order currency. |
| _paymentMethod_ | String | Yes | The payment method that is used to collect the payment by the merchant or acquirer. For the supported payment methods, see [Supported payment methods](https://docs.antom.com/ac/omnichannel/n950.md#fXQ3O). |

#### Result

| **Parameter name** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| _resultStatus_ | String | Yes | The result status. Valid values are: - `S`: Successful - `F`: Failed - `U`: Unknown |
| _resultCode_ | String | No | The result code. Maximum length: 64 characters |
| _resultMessage_ | String | No | The result message that describes the result code in detail. Maximum length: 256 characters |

#### Amount

| **Parameter name** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| _value_ | Integer | Yes | The amount value in the currency's smallest unit. For example, `10000` means 100.00 in SGD. Value range: 0-2147483647 |
| _currency_ | String | Yes | The 3-character currency code that follows ISO-4217. For example, `USD`. Maximum length: 3 characters |

## Result codes

| **_resultCode_** | **_resultStatus_** | **_resultMessage_** | **Further action** |
| --- | --- | --- | --- |
| `SUCCESS` | `S` | Success. | No action is required. |
| `PROCESS_FAIL` | `F` | A general business failure occurred. Do not retry. | Contact Antom Technical Support to troubleshoot the issue. |
| `PARAM_ILLEGAL` | `F` | Parameter names or values do not meet the specified requirements. The result message can vary according to the specific error encountered. | Check whether the request parameters, including the header parameters and body parameters, are correct and valid. For more information about the parameters of this API, see the [Request header](https://docs.antom.com/ac/omnichannel/api_fund.md#NvOFY) section. |
| `INVALID_API` | `F` | The called API is invalid. | Check whether the correct API name is used when making the API call. API names are case-insensitive. |
| `CLIENT_INVALID` | `F` | The client ID is invalid. | Check whether the correct client ID is used. The payment terminal integration uses the serial number (SN) of the payment terminal as the client ID. |
| `INVALID_SIGNATURE` | `F` | The signature is not validated. | Refer to the sample code to check whether the correct public key, signed message, and signature algorithm are used. |
| `INVALID_ENCRPT_DATA` | `F` | The encrypted data is invalid. | Refer to the sample code to check whether the correct encrypted data is used. |
| `METHOD_NOT_SUPPORTED` | `F` | The server does not implement the requested HTTP method. | Ensure the HTTP method is `POST`. |
| `TERMINAL_NOT_LOGIN` | `F` | The payment terminal is not logged in. | Log in to the payment terminal. |
| `TERMINAL_BUSY` | `F` | The payment terminal is busy. | Try again later. |
| `PAYMENT_NOT_EXIST` | `F` | The payment does not exist. | Contact Antom Technical Support to troubleshoot the issue. |
| `UNKNOWN_EXCEPTION` | `U` | An API calling is failed, which is caused by unknown reasons. | Call the API again. |

## Samples

The following code shows a request message:

```json
{
  "paymentRequestId": "pay_1089760038715669_1027757450XXXXX"
}
```

The following code shows a response message:

```json
{
  "result":{
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  },
  "paymentRequestId": "pay_1089760038715669_1027757450XXXXX",
  "paymentId": "202502081140108001001888202003XXXXX",
  "paymentCreateTime": "2025-02-08T12:01:01+08:00",
  "paymentTime": "2025-02-08T12:01:01+08:00",
  "paymentStatus": "Success",
  "paymentAmount":{
    "currency": "SGD",
    "value": "50000"
  },
  "paymentMethod":"CARD"
}
```