# POS Integration

Learn how to accept payments at the point of sale using the Finix API.

## POS Integration Overview

Follow these six steps to integrate your POS system with Finix:

div
div
| **Step** | **Description** |
|  --- | --- |
| [Provision a Merchant](#step-1-onboard-a-seller-optional) | Onboard merchants and set up their payment terminals to accept in-person payments. |
| [Set up the Payment Terminal](#step-2-set-up-the-payment-terminal) | Configure the payment terminal by connecting it to Wi-Fi and installing required updates to prepare it for processing payments. |
| [Create a Device](#step-3-create-a-device) | Create a `Device` resource and connect your payment terminal to Finix's API. |
| [Activate the Payment Terminal](#step-4-activate-the-payment-terminal) | Activate the payment terminal to begin setup. |
| [Check Connection](#step-5-check-connection) | Check connection to the payment terminal to ensure it is ready to process payments. |
| [Create a Sale](#step-6-create-a-sale) | Create a sale to debit a buyer for an in-person transaction. |
| [Cancelling a Transaction](#step-7-cancelling-a-transaction) | Learn how to cancel a transaction. |


div
img
## Step 1: Onboard a Seller (Optional)

This step is not required if you are only processing payments for yourself. Your Finix Point of Contact will provide you with a `Merchant` resource to use for payments.

To process in-person transactions with our API first, you must have an approved seller.

If you are a Software Platform or Marketplace that is onboarding sellers, please see our [Platform Quickstart](/guides/platform-payments/platform-quickstart) to learn how to quickly onboard sellers.

## Step 2: Set up the Payment Terminal

Place the payment terminal where you'll use it to process the majority of payments.

To set up the payment terminal, you'll need:

- A Wi-Fi network and router.
- The Wi-Fi network's name and password.
- Physical access to the payment terminal being activated.


## Step 3: Create a Device

Create a `Device` under the `Merchant` provisioned to process In-Person Payments. Include the `Device.model` of the payment terminal you'll be using to process cards.

For more details about the payment terminals available, see our [available devices](/guides/in-person-payments/select-your-device).

Pax A800

```shell Request
curl "https://finix.sandbox-payments-api.com/merchants/MUeDVrf2ahuKc9Eg5TeZugvs/devices" \
    -H "Content-Type: application/json" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -X POST \
    -d '{
        "description": "Cashier Two",
        "model": "PAX_A800",
        "name": "My Pax Finix Device",
        "serial_number": "19046260945"
    }'
```


```json Response
{
    "id": "DVe1vSY97utE2559bwSV3Sp9",
    "created_at": "2024-10-30T18:34:49.725938Z",
    "updated_at": "2024-10-30T18:34:49.725938Z",
    "configuration_details": {
        "allow_debit": true,
        "check_for_duplicate_transactions": true,
        "prompt_amount_confirmation": true,
        "prompt_manual_entry": false,
        "signature_threshold_amount": 10000,
        "bypass_device_on_capture": true,
        "prompt_receipt_confirmation": true,
        "display_tip_on_receipt": false,
        "prompt_tip_on_screen": false,
        "allow_standalone_authorizations": false,
        "allow_standalone_sales": false,
        "allow_standalone_refunds": false,
        "tipping_details": {
            "percent_tipping_threshold": 0,
            "percent_options": [18, 20, 22],
            "fixed_options": [100, 150, 200]
        },
        "idle_message": null,
        "idle_image_file_id": null,
        "automatic_receipt_delivery_methods": null,
        "available_receipt_methods": null,
        "prompt_for_signature": "NEVER"
    },
    "description": "Cashier Two",
    "enabled": false,
    "idle_message": null,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "model": "PAX_A800",
    "name": "My Pax Finix Device",
    "serial_number": "19046260945",
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/devices/DVe1vSY97utE2559bwSV3Sp9"
        },
        "merchant": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUeDVrf2ahuKc9Eg5TeZugvs"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/transfers"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/authorizations"
        }
    }
}
```

Pax A920 Pro

```shell Request

curl "https://finix.sandbox-payments-api.com/merchants/MUeDVrf2ahuKc9Eg5TeZugvs/devices" \
    -H "Content-Type: application/json" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -X POST \
    -d '{
        "description": "Cashier Two",
        "model": "PAX_A920PRO",
        "name": "My Pax Finix Device",
        "serial_number": "19046260945"
    }'
```


```json Response
{
    "id": "DVaStvSYXnxEjnMSDUFtWc5D",
    "created_at": "2024-10-30T18:37:01.607546Z",
    "updated_at": "2024-10-30T18:37:01.607546Z",
    "configuration_details": {
        "allow_debit": true,
        "check_for_duplicate_transactions": true,
        "prompt_amount_confirmation": true,
        "prompt_manual_entry": false,
        "signature_threshold_amount": 10000,
        "bypass_device_on_capture": true,
        "prompt_receipt_confirmation": true,
        "display_tip_on_receipt": false,
        "prompt_tip_on_screen": false,
        "allow_standalone_authorizations": false,
        "allow_standalone_sales": false,
        "allow_standalone_refunds": false,
        "tipping_details": {
            "percent_tipping_threshold": 0,
            "percent_options": [18, 20, 22],
            "fixed_options": [100, 150, 200]
        },
        "idle_message": null,
        "idle_image_file_id": null,
        "automatic_receipt_delivery_methods": null,
        "available_receipt_methods": null,
        "prompt_for_signature": "NEVER"
    },
    "description": "Cashier Two",
    "enabled": false,
    "idle_message": null,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "model": "PAX_A920PRO",
    "name": "My Pax Finix Device",
    "serial_number": "19046260945",
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/devices/DVaStvSYXnxEjnMSDUFtWc5D"
        },
        "merchant": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUeDVrf2ahuKc9Eg5TeZugvs"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/transfers"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/authorizations"
        }
    }
}
```

## Step 4: Activate the Payment Terminal

Once the `Device` is created and the `serial_number` is set, you can link the `Device` resource with the payment terminal you'll use by sending an activation request to the payment terminal. A successful request returns `Device.enabled: true`. The device must be online and connected to the network with the app in the front in order for the request to succeed.


```shell Activate Device
curl -i -X PUT \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    https://finix.sandbox-payments-api.com/devices/DV7DvjGoZ2AEdhAKhtKXVv4b \
    -H 'Accept: application/hal+json' \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -d '{
        "action": "ACTIVATE"
    }'
```

## Step 5: Check Connection

Prior to initiating a payment, you can check the connection to verify that the device is ready to process payments. Checking connection will confirm that the:

- Device is powered on
- Finix Payment App is open
- Device is connected to internet
- Device was able to connect to the Finix Server


Use the `Device` you enabled to check Connection. Below is a sample request and response.

- The `connection` field in the response has two potential values:
  - `open`: the device is ready to process payments.
  - `closed`: the device has not met the criteria outlined above to process payment.


If the `connection` is `closed` and a payment is initiated, the `Transfer` will fail with an error of `DEVICE_UNREACHABLE`.


```shell Check Connection Request
curl "https://finix.sandbox-payments-api.com/devices/DVgGZMwiJJYzj4T69YDtcTgs?include_connection=true" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
```


```json Check Connection Response
{
    "id": "DVgGZMwiJJYzj4T69YDtcTgs",
    "created_at": "2025-01-16T17:19:40.197790Z",
    "updated_at": "2025-01-16T17:19:40.197790Z",
    "configuration_details": {
        "allow_debit": true,
        "check_for_duplicate_transactions": true,
        "prompt_amount_confirmation": true,
        "prompt_manual_entry": false,
        "signature_threshold_amount": 10000,
        "bypass_device_on_capture": true,
        "prompt_receipt_confirmation": true,
        "display_tip_on_receipt": false,
        "prompt_tip_on_screen": false,
        "allow_standalone_authorizations": false,
        "allow_standalone_sales": false,
        "allow_standalone_refunds": false,
        "tipping_details": {
            "percent_tipping_threshold": 0,
            "percent_options": [18, 20, 22],
            "fixed_options": [100, 150, 200]
        },
        "idle_message": null,
        "idle_image_file_id": null,
        "automatic_receipt_delivery_methods": null,
        "available_receipt_methods": null,
        "prompt_for_signature": "NEVER",
        "surcharge_basis_points": null
    },
    "connection": "Closed",
    "description": "Cashier Two",
    "enabled": false,
    "idle_message": null,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "model": "PAX_A800",
    "name": "My Pax Finix Device",
    "serial_number": "19046260945",
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/devices/DVgGZMwiJJYzj4T69YDtcTgs"
        },
        "merchant": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUeDVrf2ahuKc9Eg5TeZugvs"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/transfers"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/authorizations"
        }
    }
}
```

## Step 6: Create a Sale

With the payment terminal connected, you can begin processing In-Person payments. Use the `Device` you enabled to create a `Sale`.


```shell Sale Request
curl -i -X POST \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    https://finix.sandbox-payments-api.com/transfers \
    -H 'Accept: application/hal+json' \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -d '{
        "amount": 150,
        "currency": "USD",
        "device": "DV7DvjGoZ2AEdhAKhtKXVv4b",
        "operation_key": "CARD_PRESENT_DEBIT",
        "tags": {
        "order_number": "chris123transfer"
        }
    }'
```


```json Sale Response
{
    "id": "TRarp7Pz21Low4u2Urw5Ub4W",
    "created_at": "2019-04-29T20:44:00.13Z",
    "updated_at": "2022-10-10T05:59:17.59Z",
    "3ds_redirect_url": null,
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "address_verification": null,
    "amount": 3138,
    "amount_requested": 3138,
    "application": "APeUbTUjvYb1CdPXvNcwW1wP",
    "capture_amount": 150,
    "card_present_details": {
        "emv_data": {
            "application_identifier": "A0000001523010",
            "application_label": "DISCOVER",
            "application_preferred_name": null,
            "application_transaction_counter": "0005",
            "cryptogram": "ARCQ F666F8891F870D33",
            "issuer_code_table_index": null,
            "pin_verified": false,
            "tags": null
        },
        "masked_account_number": "************0059",
        "name": "Test Card 05",
        "brand": "DISCOVER",
        "entry_mode": "CHIP_ENTRY",
        "payment_type": "CREDIT",
        "approval_code": "004839"
    },
    "currency": "USD",
    "device": "DVfKLD9GZtsjcJxLtc2yCcfd",
    "expires_at": "2019-05-06T20:44:00.13Z",
    "failure_code": null,
    "failure_message": null,
    "idempotency_id": null,
    "is_void": false,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "IDsbTBawhnLBAVeinRb84vFR",
    "messages": [],
    "raw": null,
    "security_code_verification": null,
    "source": "PImTHaz7XVPx4M7mhu9x8gkU",
    "state": "SUCCEEDED",
    "tags": {
        "TicketNumber": "45878"
    },
    "trace_id": "FNX35FSuraeKKJr65wkGVFJni",
    "void_state": "UNATTEMPTED",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/authorizations/AUarp7Pz21Low4u2Urw5Ub4W"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
        },
        "transfer": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRqQCAX7nYHUnkE5YPFTknqd"
        },
        "device": {
            "href": "https://finix.sandbox-payments-api.com/devices/DVfKLD9GZtsjcJxLtc2yCcfd"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
        }
    }
}
```

Once complete, similar to other Finix `Transfers`, you can proceed with managing payouts, and the Post-Payments lifecycle.

## Step 7: Cancelling a Transaction

There maybe times when you need to cancel a transaction. For example, if the buyer cancels the transaction or the transaction is declined.

To cancel a transaction, send a `CANCEL` request to the `Device` resource. Below is a sample request of the `Device` resource and the response you will receive on the cancelled transaction.


```shell Cancel Transfer Request
curl -i -X PUT \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    https://finix.sandbox-payments-api.com/devices/{device_id} \
    -H 'Accept: application/hal+json' \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -d '{
        "action": "CANCEL"
    }'
```


```json Cancel Transfer Response
{
    "id": "TRt3LfP6ot6s5HG1ZN9QE5qc",
    "created_at": "2025-07-18T23:20:55.95Z",
    "updated_at": "2025-07-18T23:20:55.95Z",
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "additional_purchase_data": null,
    "address_verification": null,
    "amount": 2000,
    "amount_requested": 2000,
    "application": "APc9vhYcPsRuTSpKD9KpMtPe",
    "card_present_details": {
        "emv_data": {
            "application_identifier": null,
            "application_label": null,
            "application_preferred_name": null,
            "application_transaction_counter": null,
            "cryptogram": null,
            "issuer_code_table_index": null,
            "network_emv_response": null,
            "pin_verified": false,
            "tags": null
        },
        "masked_account_number": null,
        "name": null,
        "brand": "UNKNOWN",
        "entry_mode": "UNKNOWN",
        "payment_type": null,
        "approval_code": null,
        "digital_signature_file_id": null
    },
    "currency": "USD",
    "destination": null,
    "device": "DVae7HFLS7BXNaFpKhdH1K6x",
    "externally_funded": "UNKNOWN",
    "failure_code": "CANCELLATION_VIA_API",
    "failure_message": "The transaction was canceled via API before the transaction was completed. The cardholder needs to attempt the transaction again.",
    "fee": 0,
    "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj",
    "idempotency_id": null,
    "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm",
    "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H",
    "messages": ["RAW MESSAGE"],
    "operation_key": "CARD_PRESENT_SALE",
    "parent_transfer": null,
    "parent_transfer_trace_id": null,
    "raw": null,
    "ready_to_settle_at": null,
    "receipt_last_printed_at": null,
    "security_code_verification": null,
    "source": "PIhGjmMzFiT3oorhhBoMHdKc",
    "split_transfers": [],
    "state": "FAILED",
    "statement_descriptor": "FLX*FINIX FLOWERS",
    "subtype": "API",
    "supplemental_fee": null,
    "tags": {
        "order_number": "Test Transaction"
    },
    "tip_amount": null,
    "trace_id": "433ca932-11c4-4667-8a21-90db472b7691",
    "type": "DEBIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRt3LfP6ot6s5HG1ZN9QE5qc"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H"
        },
        "device": {
            "href": "https://finix.sandbox-payments-api.com/devices/DVae7HFLS7BXNaFpKhdH1K6x"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRt3LfP6ot6s5HG1ZN9QE5qc/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRt3LfP6ot6s5HG1ZN9QE5qc/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRt3LfP6ot6s5HG1ZN9QE5qc/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRt3LfP6ot6s5HG1ZN9QE5qc/disputes"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj"
        }
    }
}
```

## Next Steps

Testing Your Integration
Learn how to test your In-Person Payments integration.