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:

StepDescription
1. Provision a MerchantOnboard merchants and set up their payment terminals to accept in-person payments (also known as Card Present transactions).
2. Create a DeviceCreate a Device resource and connect your payment terminal to Finix's API.
3. Activate the Payment TerminalActivate the payment terminal to begin setup.
4. Set up the Payment TerminalComplete the initial set up of the payment terminal. This includes connecting the terminal to your Wi-fi network and installing any outstanding updates.
5. Create a SaleCreate 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.

In-person Payments - Finix API Overview

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

Next Steps

Managing Payment Terminals

Learn what payment terminals Finix has available for In-Person Payments.

Testing In-Person Payments

Learn how to test your In-Person Payments integration.