Finix API

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

Processing In-Person Payments with the Finix API is similar to processing Online Payments.

Along with creating a Merchant and Authorization, you also create a Device to represent the card reader. If you're interested in processing In-Person Payments, contact your Finix point of contact or the Finix Support team.

Step 1: Provision a Merchant

To process card-present transactions with our API first, create a Merchant resource for your seller.

Include DATACAP_V1 as the Merchant#gateway.
Include VANTIV_V1 as the Merchant#processor.

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities/IDuy7QZ4kWCvhDA79VLJGSDR/merchants \
        -H "Content-Type: application/vnd.json+api" \
        -H 'Finix-Version:2022-02-01' \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
        {
            "gateway": "DATACAP_V1",
            "processor": "VANTIV_V1"
        }'

HTTP Request

POST https://finix.sandbox-payments-api.com/identities/:IDENTITY_ID:/merchants

URL Parameters

`Parameter`	Description
:IDENTITY_ID:	ID of the `Identity`

Request Arguments

Field	Type	Description
`gateway`	string, required	Name of the gateway. Pass DATACAP_V1 to enable In-Person card-present transactions with Finix; Finix uses Datacap to gateway card-present transactions.
`processor`	string, required	Name of the processor. Pass VANTIV_V1 to enable In-Person card-present transactions with Finix; Finix uses Vantiv to process card-present transactions.
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers)

Copy

Copied

{
  "id" : "MU4LYrniAvqVKUBqcATb7Y7p",
  "created_at" : "2022-10-10T05:50:02.21Z",
  "updated_at" : "2022-10-10T05:50:02.21Z",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "card_cvv_required" : false,
  "card_expiration_date_required" : true,
  "convenience_charges_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "default_partial_authorization_enabled" : false,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "gross_settlement_enabled" : false,
  "identity" : "IDuy7QZ4kWCvhDA79VLJGSDR",
  "level_two_level_three_data_enabled" : false,
  "mcc" : null,
  "merchant_name" : null,
  "merchant_profile" : "MPeGFDyZjBu4G5sNZhnYdLVT",
  "mid" : null,
  "onboarding_state" : "PROVISIONING",
  "processing_enabled" : false,
  "processor" : "VANTIV_V1",
  "processor_details" : { },
  "ready_to_settle_upon" : "RECONCILIATION",
  "rent_surcharges_enabled" : false,
  "settlement_enabled" : false,
  "settlement_funding_identifier" : "UNSET",
  "tags" : { },
  "verification" : "VI8AzaREBqoE1zTDQ9XANrcx",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU4LYrniAvqVKUBqcATb7Y7p"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDuy7QZ4kWCvhDA79VLJGSDR"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU4LYrniAvqVKUBqcATb7Y7p/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPeGFDyZjBu4G5sNZhnYdLVT"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI8AzaREBqoE1zTDQ9XANrcx"
    }
  }
}

Step 2: Create a Device

Create a Device under the Merchant provisioned to process In-Person Payments. Include the Device#model of the card reader you'll be using to process cards.

A breakdown of the Card Readers available can be found in Managing Card Readers.

The card readers available for integrations using the Finix API include:

Link 2500
Lane 3000
Lane 5000
Lane 7000
Lane 8000

Copy

Copied

curl https://finix.sandbox-payments-api.com/merchants/MU4LYrniAvqVKUBqcATb7Y7p/devices \
        -H "Content-Type: application/vnd.json+api" \
        -H 'Finix-Version:2022-02-01' \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
      {
        "configuration": {
          "prompt_amount_confirmation": true
        },
        "description": "John Smith",
        "model": "LINK_2500",
        "name": "My First Finix Device",
        "serial_number" : "18123123012"
      }'

HTTP Request

POST https://finix.sandbox-payments-api.com/merchants/:MERCHANT_ID:/devices

URL Parameters

Field	Type	Description
:MERCHANT_ID:	string, required	ID of `Device`.

Request Arguments

Field	Type	Description
`description`	string, optional	Additional information about the device (e.g. self serving terminal).
`model`	string, required	Pass the following values to lets Finix know the type of device is being used: LINK_2500 LANE_3000 LANE_5000 LANE_7000 LANE_8000
`name`	string, required	The display name of the `Device` used for filtering purposes.
`serial_number`	string, required	The serial number of the `Device`. You must have the serial number set before activating the device. The `serial_number` is the 16 digit number in the back of the device. The `serial_number` can be added at a later time via a PUT request.
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers).

Configuration Arguments

Field	Type	Description
`allow_debit`	boolean, optional	Sets whether the device will allow debit transactions (defaults to true).
`bypass_device_on_capture`	boolean, required	Sets if the device will be used to capture transactions. This field must be set to true (defaults to false).
`check_for_duplicate_transactions`	boolean, optional	Sets if the device will check for duplicate transactions.
`prompt_amount_confirmation`	boolean, optional	Sets if the cardholder needs to confirm the amount they'll pay (defaults to true).
`prompt_manual_entry`	boolean, optional	If true, sets the the default card input method to manual entry (defaults to false).

Copy

Copied

{
  "id" : "DVbFNEoNLAGJjrc7wvy1ctji",
  "created_at" : "2022-10-10T05:51:42.172580Z",
  "updated_at" : "2022-10-10T05:51:42.172580Z",
  "configuration_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0,
    "bypass_device_on_capture" : true
  },
  "description" : "John Smith",
  "enabled" : true,
  "idle_message" : null,
  "merchant" : "MU4LYrniAvqVKUBqcATb7Y7p",
  "model" : "LINK_2500",
  "name" : "My First Finix Device",
  "serial_number" : "18123123012",
  "tags" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVbFNEoNLAGJjrc7wvy1ctji"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU4LYrniAvqVKUBqcATb7Y7p"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Step 3: Activate the Card Reader

Once the Device is created and the serial_number is set, you can link the Device resource with the card reader you'll use by sending an activation request to the card reader. A successful request returns Device#enabled as true.

Copy

Copied

curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
  -H "Content-Type: application/vnd.json+api" \
  -H 'Finix-Version:2022-02-01' \
  -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
  -X PUT \
  -d '
    {
      "action": "ACTIVATE"
    }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/devices/:DEVICE_ID:

URL Parameters

Field	Type	Description
:DEVICE_ID:	string, required	ID of the `Device` that's configured to connect with Finix.

Request Arguments

Field	Type	Description
`action`	string, required	`action` must include ACTIVATE to enable the device.
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers).

Copy

Copied

{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "created_at" : "2019-03-01T02:27:20.366Z",
  "updated_at" : "2022-04-05T18:48:40.383Z",
  "configuration_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : false,
    "prompt_manual_entry" : true,
    "prompt_signature" : "AMOUNT",
    "signature_threshold_amount" : 10,
    "bypass_device_on_capture" : false
  },
  "description" : "John Smith",
  "enabled" : true,
  "idle_message" : null,
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "model" : "LINK_2500",
  "name" : "My First Finix Device",
  "serial_number" : "18123123012",
  "tags" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Step 4: Set up the Card Reader

Place the card reader where you'll use it to process the majority of payments.

To set up the card reader, you'll need:

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

Step 4a: Connect to the Network

If your card reader has an ethernet port, connect it to your router or internet modem.

If your card reader can connect to a Wi-Fi network, when you first boot up the card reader, a prompt should display with the prompt to "Set up Wi-Fi?":

Press the Enter (Green) key to be taken to the Configure Wi-Fi flow of the card reader.
Select 1-Scan Networks.
Once scanning is complete, select your Wi-Fi network.
Type in the network's password and press the Enter (Green) key.
You'll get returned to the menu of the card reader.

If the symbol in the top left turns green, then the card reader is connected to the internet.

Wi-Fi Card Readers

If the “Set up Wi-Fi?” page doesn't display, it's likely one of the menus timed out due to inactivity or the “Cancel (Red)” key was pressed. To manually bring up the Set up Wi-Fi? page:

From the idle screen press the F key (silver circle key).
Select Admin Mode.
Enter 123456A for the admin password .
Select Tetra Admin.
Select 3-Configure Wi-Fi

Step 4b: Update the Card Reader

Once the reader is connected to the internet, install any outstanding updates before processing a payment.

To update a card reader:

From the idle screen, press the F key. If prompted for an amount press the F key a second time.
Select Admin Mode if given the option.
If prompted for the admin password type 123456A then press the Enter (Green) key.
Select Tetra Admin.
Select 1-Download Application.
Select 2-Start Download.
Press the Enter (Green) key when you're prompted to Enter package name. No value is needed.
The device will reboot twice then settle on the idle screen.

Set Date and Time (Optional)

From the idle screen, press the F key. If prompted for amount press the F key a second time.
Select Admin Mode if given the option.
If prompted for the admin password type 123456A then press the "Enter (Green)" key.
Select Tetra Admin.
Select Set Date and Time.
Select Set Date.
Enter the date in a mm/dd/yyyy format and press the Enter (Green) key.
Select Set Time.
Enter time in a hh:mm format and press the Enter (Green) key.
Press the Enter (Green) key
Press Cancel (Red) key twice to return to the idle screen.

Step 5: Create a Sale

With the card reader connected, you can begin processing In-Person payments.

Use the Device you enabled to create a Sale.

Copy

Copied

curl https://finix.sandbox-payments-api.com/transfers \
   -H "Content-Type: application/vnd.json+api" \
   -H 'Finix-Version:2022-02-01' \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
   -d '
   {
     "amount": 150,
     "currency": "USD",
     "device": "DVf2H8sh4LZZC52GTUrwCPPf",
     "operation_key": "CARD_PRESENT_DEBIT",
     "tags": {
       "order_number": "test123transfer"
     }
   }'

HTTP Request

POST https://finix.sandbox-payments-api.com/authorizations

Request Arguments

Field	Type	Description
`amount`	integer, required	Amount of the sale.
`currency`	string, required	Currency of sale.
`device`	string, required	The ID of the activated `Device`.
`operation_key`	string, required	Describes the operation that's performed in the transaction.
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers).

Configuration Arguments

While creating a Transfer, you can enable several fields to verify different payment details for the transaction getting processed.

Field	Type	Description
`allow_debit`	boolean, optional	Sets whether device will allow debit by default or not (defaults to true).
`bypass_device_on_capture`	boolean, required	Sets if the device will be used to capture transactions. (defaults to true).
`check_for_duplicate_transactions`	boolean, optional	Sets if the device will check for duplicate transactions.
`prompt_amount_confirmation`	boolean, optional	Sets if the cardholder needs to confirm the amount they'll pay (defaults is true).
`prompt_manual_entry`	boolean, optional	If true, sets the the default card input method to manual entry (defaults to false).

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_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 Authorizations, you can proceed with managing payouts, and the Post-Payments lifecycle.

Finix API

Step 1: Provision a Merchant

HTTP Request

URL Parameters

Request Arguments

Step 2: Create a Device

HTTP Request

URL Parameters

Request Arguments

Configuration Arguments

Step 3: Activate the Card Reader

HTTP Request

URL Parameters

Request Arguments

Step 4: Set up the Card Reader

Step 4a: Connect to the Network

Wi-Fi Card Readers

Step 4b: Update the Card Reader

Set Date and Time (Optional)

Step 5: Create a Sale

HTTP Request

Request Arguments

Configuration Arguments

Next Steps

Managing Card Readers

Testing In-Person Payments