In-Person Payments - Cloud

Our Cloud integration lets you gateway card-present transactions.

When your integration uses Cloud to process transactions, your point of sale device connects and processes all payment details through Finix's API.

To learn more about our Cloud integration and get access, please contact Finix Support.

warning

Our Cloud integration is only available for Finix Core customers. If you have additional questions, please reach out to your Finix point of contact.

Step 1: Provision a Merchant with Cloud

To process Cloud card-present transactions first, create a merchant resource for your merchant.

Once created, provision the merchant to enable in-person payments:

  • Include VANTIV_V1 as the processor .
  • Include TRIPOS_CLOUD_V1 as the gateway .
Copy
Copied
curl https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR/merchants \
        -H "Content-Type: application/vnd.json+api" \
        -H 'Finix-Version:2022-02-01' \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
        {
            "processor": "VANTIV_V1",
            "gateway": "TRIPOS_CLOUD_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
processor string, required Name of the processor. Pass VANTIV_V1 to enable card-present transactions with Finix; Finix uses Vantiv to process card-present transactions.
gateway string, required Name of the gateway. Pass TRIPOS_CLOUD_V1 to enable card-present transactions with Finix; Finix uses triPOS to gateway card-present transactions.
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)
Copy
Copied
{
  "id" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "verification" : "VIhjGSJCnvXLzFQZUsUaeHxb",
  "merchant_profile" : "MPgDcdhXsdcJ9MVeJrZRNp79",
  "processor" : "VANTIV_V1",
  "processing_enabled" : false,
  "settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "tags" : { },
  "created_at" : "2019-03-01T00:49:02.47Z",
  "updated_at" : "2019-03-01T00:49:02.47Z",
  "onboarding_state" : "PROVISIONING",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPgDcdhXsdcJ9MVeJrZRNp79"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIhjGSJCnvXLzFQZUsUaeHxb"
    }
  }
}

Step 2: Create a Device

Create a Device under the merchant provisioned with Cloud and include the model of the device you'll be using to process cards.

Copy
Copied
curl https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd/devices \
        -H "Content-Type: application/vnd.json+api" \
        -H 'Finix-Version:2022-02-01' \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
      {
        "name": "Finix  triPOS #1",
        "model": "MX915",
        "description": "John Smith",
        "configuration": {
          "allow_debit": true,
          "prompt_signature": "NEVER",
          "bypass_device_on_capture": true
        }
      }'

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
model string, required Pass the following values to lets Finix know the type of device is being used:
  • IPP320
  • IPP350
  • ISC250
  • ISC480
  • ISMP4
  • LANE_3000
  • LINK_2500
  • MX915
  • MX925
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).
description string, optional Additional information about the device (e.g. self serving terminal).

Configuration Arguments

Field Type Description
allow_debit boolean, optional Sets whether the device will allow debit transactions (defaults to true).
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
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).
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).
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).
prompt_manual_entry boolean, optional If true, sets the the default card input method to manual entry (defaults to false).
Copy
Copied
{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix  triPOS #1",
  "model" : "MX915",
  "description" : "John Smith",
  "serial_number" : null,
  "idle_message" : null,
  "enabled" : false,
  "tags" : { },
  "created_at" : "2022-07-09T00:46:56.378376Z",
  "updated_at" : "2022-07-09T00:46:56.378899Z",
  "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" : false
  },
  "_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 3: Activate Device

After you've created the Device resource, boot up the card reader and connect it to the internet.

An activation code will appear on the device's display. Activate the Device resource you created using the code on the device's display.

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 '
    {
      "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",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix Tripos #1",
  "model" : "MX915",
  "description" : "John Smith",
  "serial_number" : "262-410-025",
  "idle_message" : null,
  "enabled" : true,
  "tags" : { },
  "created_at" : "2019-03-01T02:27:20.366",
  "updated_at" : "2019-03-11T23:19:44.378",
  "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
  },
  "_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

Use the Device you enabled to create an authorization.

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

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).
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
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).
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).
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).
prompt_manual_entry boolean, optional If true, sets the the default card input method to manual entry (defaults to false).
Copy
Copied
{
  "id" : "TReEok8811pDqsR1BbxZLbw1",
  "amount" : 150,
  "tags" : {
    "order_number" : "test123transfer"
  },
  "state" : "SUCCEEDED",
  "trace_id" : "FNXmEM7d6ns8LMMzt61AD8TrR",
  "currency" : "USD",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "source" : "PIcW77CfRyBUWJhA231TWXWf",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*GOLDS GYM",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "card_present_details" : {
    "emv_data" : {
      "application_identifier" : "A0000000031010",
      "application_label" : "Visa Credit",
      "application_preferred_name" : null,
      "application_transaction_counter" : "004F",
      "cryptogram" : "TC F8C706E8A0368D15",
      "issuer_code_table_index" : null,
      "pin_verified" : false
    },
    "masked_account_number" : "************7564",
    "name" : "AARON/CHRISTOPHER W ",
    "brand" : "VISA",
    "entry_mode" : "CHIP_ENTRY",
    "payment_type" : "CREDIT",
    "approval_code" : "000036"
  },
  "created_at" : "2019-03-11T23:36:42.03Z",
  "updated_at" : "2019-03-11T23:36:57.09Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "device" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/payment_instruments"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    },
    "device" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcW77CfRyBUWJhA231TWXWf"
    }
  }

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/AUuCfRve8QG6G1wnPCReiLma \
   -H "Content-Type: application/vnd.json+api" \
   -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" : "AUuCfRve8QG6G1wnPCReiLma",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "amount" : 150,
  "tags" : {
    "order_number" : "chris123transfer"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TRjiUo5CXLmaJp4k9PL7iP8z",
  "messages" : [ ],
  "raw" : null,
  "card_present_details" : null,
  "created_at" : "2019-03-01T03:42:13.59Z",
  "updated_at" : "2019-03-01T03:49:28.67Z",
  "trace_id" : "957ce193-b4e4-4a39-88e2-d88a019982d2",
  "source" : "PIjnHHLBZvRu6GPEZdFt7E2q",
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "device" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "is_void" : false,
  "expires_at" : "2019-03-08T03:42:13.59Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUuCfRve8QG6G1wnPCReiLma"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRjiUo5CXLmaJp4k9PL7iP8z"
    },
    "device" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    }
  }
}

Once complete, similar to other Finix transactions, you can proceed with managing the payout of the merchant and any other steps as needed.

Use-case Description
Payouts An essential part of processing payments is managing payouts and when your sellers get their funds. Learn how to manage payouts and how your sellers will receive their funds.
Void an authorization Void an authorization to remove the hold from the cardholder’s card account.
Referenced Refund Process a refund (full or partial amount) for a previously completed payment through Finix.
Unreferenced Refunds Process a refund or reversal for any amount.