Developer Quick Start - In-Person Payments

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

In-Person Payments API Overview

Take the following steps to integrate your point of sale application with the Finix API:

Step	Description
1. Provision a Merchant	Onboard merchants and set up their payment terminals to accept in-person payments (also known as Card Present transactions).
2. Create a Device	Create a `Device` resource and connect your payment terminal to Finix's API.
3. Activate the Payment Terminal	Activate the payment terminal to begin setup.
4. Set up the Payment Terminal	Complete the initial set up of the payment terminal. This includes connecting the terminal to your Wi-fi network and installing any outstanding updates.
5. Check Connection	Check connection to the device to ensure it is ready to process payments.
6. Create a Sale	Create a sale to debit a buyer for an in-person transaction.

Processing In-Person Payments with the Finix API is similar to processing Online Payments.The Finix API facilitates communication between your platforms's backend, the payment terminal, and the Finix API.

If you're interested in processing In-Person Payments, contact your Finix point of contact or the Finix Support team.

Step 1: Onboard a Seller (Optional)

info

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 card-present 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: 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 Available Devices.

Pax A800Pax A920 Pro

Copy

Copied

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

Copy

Copied

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

Example Response

Pax A800Pax A920 Pro

Copy

Copied

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

Copy

Copied

{
    "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 3: 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 as true. The device must be online and connected to the network with the app in the front in order for the request to succeed.

Copy

Copied

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

Example Request

Copy

Copied

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

Example Response

Copy

Copied

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

shelljson

Copy

Copied

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

Copy

Copied

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

Developer Quick Start - In-Person Payments

In-Person Payments API Overview

Step 1: Onboard a Seller (Optional)

info

Step 2: Create a Device

Step 3: Activate the Payment Terminal

Step 4: Set up the Payment Terminal

Step 5: Check Connection

Example Request

Example Response

Step 6: Create a Sale

Next Steps

Managing Payment Terminals

Testing In-Person Payments