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

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.

## Method signature

When calling this method, please use the following standard method signature format.

```kotlin
fun pay(
    payRequest: PayRequest,
    options: RequestOptions? = null,
    callBack: PayResultListener? = null
)
```

## Parameters

| **Parameter name** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| _payRequest_ | [PayRequest](https://docs.antom.com/ac/omnichannel/usb_structures.md#jcLlS) | Yes | Indicates the object that contains the parameters for creating a payment request. |
| _options_ | [RequestOptions](https://docs.antom.com/ac/omnichannel/usb_structures.md#A6GQM) | No | Indicates the object that contains optional parameters in the API requests. |
| _callBack_ | [PayResultListener](#zisnH) | No | The callback that is used to return the query result. See [_callback_](#zisnH) for details. |

#### _callback_

| **Parameter name** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| _result_ | [PayResultData](#OrnLB) | No | Indicates the result of the payment. |

## Return values

| **Parameter name** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| _result_ | [Result](https://docs.antom.com/ac/omnichannel/usb_structures.md#qrMZE) | 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](https://docs.antom.com/ac/omnichannel/usb_structures.md#akpnA) | 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 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. |
| `PROCESS_FAIL` | `F` | The data format is invalid. | Contact Antom Technical Support to troubleshoot the issue. |
| `PROCESS_FAIL` | `F` | The public key pairing failed. | 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. |
| `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/usb_inquiryPayment.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. |
| `DEVICE_NOT_CONNECT` | `F` | The USB connection failed. | - Check whether the initialization connection has been completed in your code. If not, perform initialization connection. - Check whether both ends of the USB connection are securely connected in your code. If not, connect the two devices again. |
| `TIMEOUT_EXCEPTION` | `U` | Response timeout. | Check whether the payment terminal app is active. If not, activate it again. |
| `UNKNOWN_EXCEPTION` | `U` | The API call failed, which is caused by unknown reasons. | Call the [**inquryPayment**](https://docs.antom.com/ac/omnichannel/usb_inquiryPayment.md) API with the _paymentRequestId_ to query the final payment status. |
| `UNKNOWN_EXCEPTION` | `U` | Failed to decrypt the data returned by the payment terminal. | Contact Antom Technical Support to troubleshoot the issue. |
| `UNKNOWN_EXCEPTION` | `U` | The message format is invalid. | Contact Antom Technical Support to troubleshoot the issue. |

## Samples

The following sample code shows how to call the **pay** API:

```kotlin
PaymentManager.pay(
    request,
    RequestOptions(120000L),
    object : PayResultListener {
        override fun result(result: PayResultData) {
            findViewById<TextView>(R.id.tv_response).post {
                findViewById<TextView>(R.id.tv_response).text = result.toString()
            }
        }

    }
)
```

The following code shows a sample of the response:

```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\"}"
    }
}
```