pos integration.md

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.
Cancelling a Transaction	Learn how to cancel a 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.

Pax A800 Model PAX_A800 Device

{
  "id": "DVoDo7F6yYCnX2d6Fj9hvsd",
  "created_at": "2025-11-14T19:01:04.638451Z",
  "updated_at": "2025-11-14T19:01:04.638451Z",
  "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
  },
  "description": "Cashier One",
  "enabled": false,
  "idle_message": null,
  "merchant": "MUsMvN47nRtdgUkE23SRHDC6",
  "model": "PAX_A800",
  "name": "My PAX_A800 Finix Device",
  "serial_number": "1234567891",
  "tags": {},
  "_links": {
    "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVoDo7F6yYCnX2d6Fj9hvsd" },
    "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MUsMvN47nRtdgUkE23SRHDC6" },
    "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" },
    "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" }
  }
}

Pax A920 Pro Model PAX_A920PRO Device

{
  "id": "DV5znKhAQZs6J7rfXqYnr86F",
  "created_at": "2025-05-21T19:02:11.141785Z",
  "updated_at": "2025-05-21T19:02:11.141785Z",
  "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
  },
  "description": "Cashier Two",
  "enabled": false,
  "idle_message": null,
  "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
  "model": "PAX_A920PRO",
  "name": "My PAX_A920PRO Finix Device",
  "serial_number": "1234567892",
  "tags": {},
  "_links": {
    "self": { "href": "https://finix.sandbox-payments-api.com/devices/DV5znKhAQZs6J7rfXqYnr86F" },
    "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MU7noQ1wdgdAeAfymw2rfBMq" },
    "transfers": { "href": "https://finix.sandbox-payments-api.com/transfers" },
    "authorizations": { "href": "https://finix.sandbox-payments-api.com/authorizations" }
  }
}

Pax IM30 Model PAX_IM30 Device

{
  "id": "DVfeMQJxpXaYkvBskg2VdZsh",
  "created_at": "2026-04-11T02:30:15.941482Z",
  "updated_at": "2026-04-11T02:30:15.941482Z",
  "configuration_details": {
    "allow_debit": false,
    "check_for_duplicate_transactions": false,
    "prompt_amount_confirmation": false,
    "prompt_manual_entry": false,
    "signature_threshold_amount": 10000,
    "bypass_device_on_capture": false,
    "prompt_receipt_confirmation": false,
    "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
  },
  "description": "Kiosk Three",
  "enabled": false,
  "idle_message": null,
  "merchant": "MUwfZPNW3r4EqLMzwgr6txw4",
  "model": "PAX_IM30",
  "name": "My PAX_IM30 Finix Device",
  "serial_number": "1234567890",
  "tags": {},
  "_links": {
    "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVfeMQJxpXaYkvBskg2VdZsh" },
    "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MUwfZPNW3r4EqLMzwgr6txw4" },
    "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.

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.

Device

{
  "id": "DVoDo7F6yYCnX2d6Fj9hvsd",
  "created_at": "2025-11-14T19:01:04.638451Z",
  "updated_at": "2025-11-14T19:01:04.638451Z",
  "android_version": "10",
  "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": "Open",
  "description": "Cashier One",
  "enabled": false,
  "firmware_version": "PayDroid_10.0.0_Eucalyptus_V20.1.23_20250108",
  "idle_message": null,
  "merchant": "MUsMvN47nRtdgUkE23SRHDC6",
  "model": "PAX_A800",
  "name": "My PAX_A800 Finix Device",
  "payment_app_version": "5.9.0",
  "serial_number": "2210172205",
  "tags": {},
  "_links": {
    "self": { "href": "https://finix.sandbox-payments-api.com/devices/DVoDo7F6yYCnX2d6Fj9hvsd" },
    "merchant": { "href": "https://finix.sandbox-payments-api.com/merchants/MUsMvN47nRtdgUkE23SRHDC6" },
    "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.

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

{
  "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 may be 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.

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

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