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:

Step	Description
Provision a Merchant	Onboard merchants and set up their payment terminals to accept in-person payments.
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	Create a `Device` resource and connect your payment terminal to Finix's API.
Activate the Payment Terminal	Activate the payment terminal to begin setup.
Check Connection	Check connection to the payment terminal to ensure it is ready to process payments.
Create a Sale	Create a sale to debit a buyer for an in-person transaction.

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

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"
    }'

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

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.

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.

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

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.

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"
        }
    }'

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.

Next Steps

Testing Your Integration

Learn how to test your In-Person Payments integration.