# pay

> The pay API is called by the POS to create a payment request. Ensure that the payment terminal is ready to receive payment requests before calling this API.

POST `/v2/payments/pay`

The **pay** API is called by the POS to create a payment request. Ensure that the payment terminal is ready to receive payment requests before calling this API.

## 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 a 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. This parameter is an idempotency key field. For payments that are initiated with the _paymentRequestId_, the same result is to be returned. For details about API idempotency, see [Idempotency](https://docs.antom.com/ac/omnichannel/api_fund.md#o07qw). |
| _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). |
| _paymentAmount_ | [Amount](#WHop6) | Yes | The payment amount that the merchant requests to receive in the order currency. |
| _originalMerchantOrderId_ | String | No | The original and unique ID on the merchant end to identify an order. Maximum length: 255 characters |
| _originalMerchantStoreId_ | String | No | The original and unique ID on the merchant end to identify a store. Maximum length: 255 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 |

### Response parameters

| **Parameter name** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| _result_ | [Result](#fTsps) | Yes | The result of the API call. |
| _paymentId_ | String | Yes | The unique ID that is defined by a POS provider to identify a payment and consistent with the _paymentId_ in transaction reports. |
| _paymentReceipt_ | [Receipt](#KhUnt) | No | The receipt information that is provided to merchants and buyers after the payment is successful. - The information is provided in the key-value structure. In card payment scenarios, values are returned through _customerReceipt_ and _cashierReceipt_. - In QR code payment scenarios, _paymentReceipt_ returns empty values. ``` { "cashierReceipt": "{\"acquirerMerchantId\":\"0000000001XXXXX\",\"acquirerProcessTime\":\"2025-05-13T13:19:51Z\",\"acquirerTerminalId\":\"911XXXXX\",\"aid\":\"A00000000XXXXX\",\"applicationCryptogram\":\"5AC388057A1XXXXX\",\"applicationLabel\":\"VISA CREDIT\",\"approvalCode\":\"0XXXXX\",\"cardBrand\":\"VISA\",\"cardNo\":\"47617300000XXXXX\",\"cvm\":\"NO_CVM\",\"posEntryMode\":\"CONTACTLESS\",\"rrn\":\"2827948XXXXX\",\"tvr\":\"00000XXXXX\"}", "customerReceipt": "{\"acquirerMerchantId\":\"0000000001XXXXX\",\"acquirerProcessTime\":\"2025-05-13T13:19:51Z\",\"acquirerTerminalId\":\"911XXXXX\",\"aid\":\"A00000000XXXXX\",\"applicationCryptogram\":\"5AC388057A1XXXXX\",\"applicationLabel\":\"VISA CREDIT\",\"approvalCode\":\"0XXXXX\",\"cardBrand\":\"VISA\",\"cardNo\":\"47617300000XXXXX\",\"cvm\":\"NO_CVM\",\"posEntryMode\":\"CONTACTLESS\",\"rrn\":\"2827948XXXXX\",\"tvr\":\"00000XXXXX\"}" ``` |

#### 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 |

#### Receipt

| **Parameter name** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| _cashierReceipt_ | String | No | The receipt provided for merchants displays the transaction information. |
| _customerReceipt_ | String | No | The receipt provided for buyers displays the transaction information. |

## 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. |
| `PAYMENT_METHOD_NOT_SUPPORT` | `F` | The payment method is not supported. | Select another payment method. |
| `TERMINAL_BUSY` | `F` | The payment terminal is busy. | Try again later. |
| `PAYMENT_FAIL` | `F` | The payment failed. | Call the [**inquryPayment**](https://docs.antom.com/ac/omnichannel/inquiry_payment.md) API to query the final payment status. or manually check the payment status on the payment terminal and manually update the payment status on the POS. If the above-mentioned methods do not work, contact Antom Technical Support to troubleshoot the issue. |
| `PAYMENT_AMOUNT_EXCEED_LIMIT` | `F` | 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. Contact Antom Technical Support to know the limitation. |
| `PAYMENT_AMOUNT_BELOW_LIMIT` | `F` | The payment amount is less than the minimum amount allowed by the contract or payment method. | Check whether the payment amount is lower than the limit or use a higher amount and try again. Contact Antom Technical Support to know the limitation. |
| `PAYMENT_IN_PROCESS` | `U` | The payment is being processed. | Call the [**inquryPayment**](https://docs.antom.com/ac/omnichannel/inquiry_payment.md) API to query the final payment status. |
| `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",
  "paymentMethod": "CARD",
  "paymentAmount": {
    "currency": "SGD",
    "value": "50000"
  },
  "originalMerchantOrderId": "order_1139563780653456_2031034758XXXXX",
  "originalMerchantStoreId": "store_2034252352003947_1031044734XXXXX"
}
```

The following code shows a response message:

```json
{
  "result":{
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  },
  "paymentId": "201906081140108001001888202003XXXXX",
  "paymentReceipt":{
    "cashierReceipt": "{\"acquirerMerchantId\":\"0000000001XXXXX\",\"acquirerProcessTime\":\"2025-05-13T13:19:51Z\",\"acquirerTerminalId\":\"911XXXXX\",\"aid\":\"A00000000XXXXX\",\"applicationCryptogram\":\"5AC388057A1XXXXX\",\"applicationLabel\":\"VISA CREDIT\",\"approvalCode\":\"0XXXXX\",\"cardBrand\":\"VISA\",\"cardNo\":\"47617300000XXXXX\",\"cvm\":\"NO_CVM\",\"posEntryMode\":\"CONTACTLESS\",\"rrn\":\"2827948XXXXX\",\"tvr\":\"00000XXXXX\"}",
    "customerReceipt": "{\"acquirerMerchantId\":\"0000000001XXXXX\",\"acquirerProcessTime\":\"2025-05-13T13:19:51Z\",\"acquirerTerminalId\":\"911XXXXX\",\"aid\":\"A00000000XXXXX\",\"applicationCryptogram\":\"5AC388057A1XXXXX\",\"applicationLabel\":\"VISA CREDIT\",\"approvalCode\":\"0XXXXX\",\"cardBrand\":\"VISA\",\"cardNo\":\"47617300000XXXXX\",\"cvm\":\"NO_CVM\",\"posEntryMode\":\"CONTACTLESS\",\"rrn\":\"2827948XXXXX\",\"tvr\":\"00000XXXXX\"}"
    }
}
```