In-Person Payments - Tripos Cloud

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 payment terminal.

Tripos Cloud Deprecated

This guide is only for existing integrations that use TRIPOS_CLOUD_V1 as a gateway; Finix has deprecated new integrations with Tripos Cloud. For details on how to create an In-Person Payments integration with Finix, see In-Person Payments - 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 payment terminal.

Note: If you're using a card-present device, the time it takes to get a response may be longer if buyers take longer to complete a transaction on the payment terminal. To accommodate this, requests sent to the Finix API using Tripos Cloud have a maximum timeout of 5 minutes.

Step 1: Provision a Merchant

First, create a Merchant resource for your seller. This Merchant will be configured specifically to process In-Person Payments.

Include TRIPOS_CLOUD_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/json" \
        -H 'Finix-Version: 2022-02-01' \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
        {
            "gateway": "TRIPOS_CLOUD_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 TRIPOS_CLOUD_V1 to enable In-Person card-present transactions with Finix; Finix uses triPOS 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",
  "surcharges_enabled": false,
  "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 payment terminal you'll use to process cards.

The payment terminals 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/json" \
        -H 'Finix-Version: 2022-02-01' \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
      {
        "configuration": {
          "allow_debit": true,
          "bypass_device_on_capture": true,
          "prompt_signature": "NEVER"
        },
        "description": "John Smith",
        "model": "LANE_3000",
        "name": "Finix Lane 3000"
      }'

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.
`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).
`prompt_signature`	string, optional	Sets if the device prompts the cardholder for a signature by default. Used in conjunction with `signature_threshold_amount` so when the threshold gets reached, the signature form appears on the device's screen (defaults to always). Available values include: ALWAYS NEVER AMOUNT
`signature_threshold_amount`	integer, optional	The threshold that needs to be reached to prompt a signature. Used when `prompt_signature` is set to AMOUNT (defaults to 0).

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" : "MX915",
  "name" : "Finix  triPOS #1",
  "serial_number" : null,
  "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 Device

After you've created the Device resource, boot up the payment terminal and connect it to the internet. An activation code will appear on the device's display.

Update the Device resource you created and use the code on the screen of the payment terminal as the Device#activation_code.

Copy

Copied

curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
  -H "Content-Type: application/json" \
  -H 'Finix-Version: 2022-02-01' \
  -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
  -X PUT \
  -d '
    {
      "activation_code": "C887298",
      "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.
`activation_code`	string, required	Input the code that's displayed on the screen of 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" : "Mike Jones",
  "enabled" : false,
  "idle_message" : null,
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "model" : "MX915",
  "name" : "Johnnys Juice Shop",
  "serial_number" : "343434343",
  "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: Create an Authorization

Create an Authorization using the Device you created and enabled to process In-Person Payments.

Copy

Copied

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

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 Authorizations, you can enable several fields to verify different payment details for that individual transaction.

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. 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 is true).
`prompt_manual_entry`	boolean, optional	If true, sets the the default card input method to manual entry (defaults to false).
`prompt_signature`	string, optional	Sets if the device prompts the cardholder for a signature by default. Used in conjunction with `signature_threshold_amount` so when the threshold gets reached, the signature form appears on the device's display (defaults to always). Available values include: ALWAYS NEVER AMOUNT
`signature_threshold_amount`	integer, optional	The threshold that needs to get reached to prompt a signature. Used when prompt_signature is set to AMOUNT (defaults to 0).

Copy

Copied

{
  "id" : "AUarp7Pz21Low4u2Urw5Ub4W",
  "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" : "MU4LYrniAvqVKUBqcATb7Y7p",
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "messages" : [ ],
  "raw" : null,
  "security_code_verification" : null,
  "source" : "PImTHaz7XVPx4M7mhu9x8gkU",
  "state" : "SUCCEEDED",
  "tags" : {
    "TicketNumber" : "45878"
  },
  "trace_id" : "FNX35FSuraeKKJr65wkGVFJni",
  "transfer" : "TRqQCAX7nYHUnkE5YPFTknqd",
  "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"
    }
  }
}

Step 5: Capture Authorization

Update the created Authorization with a capture_amount. Once the Authorization gets updated with a capture_amount (i.e. Captured), a Transfer gets made to debit funds from the cardholder.

Copy

Copied

curl https://finix.sandbox-payments-api.com/authorizations/AUarp7Pz21Low4u2Urw5Ub4W \
   -H "Content-Type: application/json" \
   -H 'Finix-Version: 2022-02-01' \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
   -X PUT \
   -d '
     {
         "capture_amount": 150
     }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/authorizations/:AUTHORIZATION_ID:

URL Parameters

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

Request Arguments

Field	Type	Description
`capture_amount`	integer, required	The amount of the `Authorization` you would like to capture in cents.

Copy

Copied

{
  "id" : "AUarp7Pz21Low4u2Urw5Ub4W",
  "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" : "MU4LYrniAvqVKUBqcATb7Y7p",
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "messages" : [ ],
  "raw" : null,
  "security_code_verification" : null,
  "source" : "PImTHaz7XVPx4M7mhu9x8gkU",
  "state" : "SUCCEEDED",
  "tags" : {
    "TicketNumber" : "45878"
  },
  "trace_id" : "FNX35FSuraeKKJr65wkGVFJni",
  "transfer" : "TRqQCAX7nYHUnkE5YPFTknqd",
  "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.

Next Steps

Getting Started

Learn what options are available to process In-Person Payments.

Device Overview

Learn how to manage your payment terminal and basic troubleshooting tips.

In-Person Payments - Tripos Cloud

Tripos Cloud Deprecated

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 Device

HTTP Request

URL Parameters

Request Arguments

Step 4: Create an Authorization

HTTP Request

Request Arguments

Configuration Arguments

Step 5: Capture Authorization

HTTP Request

URL Parameters

Request Arguments

Next Steps

Previous

Next