Processing In-Person Payments with the Finix API is similar to processing Online Payments.
Along with creating aMerchant
and Authorization
, you also create a Device
to represent the payment terminal. info
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
.
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) |
{
"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 aDevice
under the Merchant
provisioned to process In-Person Payments. Include the Device#model
of the payment terminal you'll be using to process cards.A breakdown of the payment terminals available can be found in Managing Payment Terminals.
The payment terminals available for integrations using the Finix API include:
- Desk 3500
- Desk 5000
- Lane 3000
- Lane 7000
- Lane 8000
- Link 2500
- Move 5000
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:
|
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). |
{
"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 Payment Terminal
Once theDevice
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.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). |
{
"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 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 4a: Connect to the Network
If your payment terminal has an ethernet port, connect it to your router or internet modem.
If your payment terminal can connect to a Wi-Fi network, when you first boot up the payment terminal, 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 payment terminal.
- 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 payment terminal.
If the symbol in the top left turns green, then the payment terminal is connected to the internet.
Wi-Fi Payment Terminals
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 Payment Terminal
Once the terminal is connected to the internet, install any outstanding updates before processing a payment.
To update a payment terminal:
- 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 payment terminal connected, you can begin processing In-Person payments.
Use theDevice
you enabled to create a Sale
.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 aTransfer
, 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). |
{
"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"
}
}
}
Authorizations
, you can proceed with managing payouts, and the Post-Payments lifecycle.