In-Person Payments - Local

Use Finix's Device SDKs to process payments locally through any iOS or Android app.

At the moment, Finix has only made our iOS Device SDK available. However, we're actively working on improving the SDK and releasing more, including our Android Device SDK.

If you're interested in using our iOS Device SDK and providing feedback, please reach out to your Finix point of contact. Finix is super eager to share what our community comes up with and develops!

Device SDK Prerequisites

To use Finix's Device SDK to process payments, you must onboard your merchants and set up their point of sale devices.

Onboarding includes creating an Identity resource for your merchant and:

  1. Provisioning the merchant for in-person payments.
  2. Creating the necessary Finix credentials for that merchant.
  3. Creating a Device resource for the POS sale device the merchant will use.

Taking these steps ensures that every payment gets tied to that merchant only.

Provision Merchant

After you've created an Identity, you can provision your merchant for in-person payments. To provision a merchant send a POST request to /identities/{{IDENTITY_ID}}/merchants.

After provisioning the merchant, you get a merchant ID that starts with "MUxxx".

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_MOBILE_V1"
        }'

URL Parameters

Parameter Description
:IDENTITY_ID: ID of the Identity.

Request Arguments

Field Type Description
processor string, required
  • Name of the Merchant's transaction processor.
  • Include VANTIV_V1 to process in-person payments with Finix's Device SDK and a card reader.
gateway string, required
  • Name of the gateway that processes the Merchant's transaction.
  • Include TRIPOS_MOBILE_V1 to process in-person payments with Finix's Device SDK and a card reader.
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers).

Example Response

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"
    }
  }
}

Get the Provisioning Status

It can take up to 20 minutes to successfully provision a merchant. Fetch the onboarding_state of the merchant to check the status of the provisioning request (or wait for a webhook notification).

Once provisioned, the onboarding_state of the merchant updates to APPROVED.

Copy
Copied
curl https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd \
        -H "Content-Type: application/vnd.json+api" \
        -H 'Finix-Version:2022-02-01' \
        -u "USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3" 

Example Response

Copy
Copied
{
  "id" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "verification" : "VImHURoSqEvAf9haPD6zeHJx",
  "merchant_profile" : "MPcMKhfF9rhWT2JWeUKzQVy2",
  "processor" : "VANTIV_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : { },
  "mcc" : "7999",
  "mid" : "4445029863321",
  "merchant_name" : "Finix Flowers",
  "settlement_funding_identifier" : "UNSET",
  "ready_to_settle_upon" : "RECONCILIATION",
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "level_two_level_three_data_enabled" : false,
  "created_at" : "2019-03-01T01:57:19.95Z",
  "updated_at" : "2019-05-15T18:10:03.00Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "acceptor_id" : "xxxxxxxxxxxxx",
    "default_terminal_id" : "xxxxxxxxxxxxx",
    "mid" : "xxxxxxxxxxxxx",
    "account_token" : "xxxxxxxxxxxxx",
    "account_id" : "xxxxxxxxxxxxx",
    "merchant_ident_string" : "xxxxxxxxxxxxx",
    "id" : "xxxxxxxxxxxxx",
    "vantiv_merchant_id" : "xxxxxxxxxxxxx"
  },
  "convenience_charges_enabled" : false,
  "rent_surcharges_enabled" : false,
  "_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/MPcMKhfF9rhWT2JWeUKzQVy2"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VImHURoSqEvAf9haPD6zeHJx"
    }
  }
}

Create Merchant Credentials

Every provisioned merchant needs at least one set of ROLE_MERCHANT credentials.

All Finix Device SDK calls require ROLE_MERCHANT credentials. Once created, you can use these credentials across multiple devices.

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR/users \
-H "Content-Type: application/vnd.json+api" \
-H 'Finix-Version:2022-02-01' \
-u "USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3" \
-d '{}'

HTTP Request

GET https://finix.sandbox-payments-api.com/identiities/:IDENTITY_ID:/users

URL Parameters

Parameter Description
:IDENTITY_ID: ID of the Identity.

Example Response

Copy
Copied
{
    "id": "USxxxxxxxxxxxxxxxxxxxxxx",
    "password": "xxxxxxxxxxxxxxxxxxxxxx",
    "identity": "IDxxxxxxxxxxxxxxxxxxxxxx",
    "enabled": true,
    "role": "ROLE_MERCHANT",
    "tags": {},
    "created_at": "2019-10-21T21:35:56.81Z",
    "updated_at": "2019-10-21T21:35:56.81Z",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/users/USxxxxxxxxxxxxxxxxxxxxxx"
        },
        "applications": {
            "href": "https://finix.sandbox-payments-api.com/applications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APxxxxxxxxxxxxxxxxxxxxxx"
        }
    }
}

Create Device

Once you've provisioned the merchant, you'll need to create a Device to manage how the card reader gets configured. A Device resource represents a card reader and is required for merchants to process transactions with Finix.

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": "Terminal 1",
    "model": "BBPOS",
    "description": "John Smith"
}'

HTTP Request

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

URL Parameters

Parameter Description
:MERCHANT_ID: ID of the merchant.

Request Arguments

Field Type Description
model string, required Include BBPOS or LINK_2500 to let Finix know what type of device is being used.
name string, required The display name of the Device used for filtering purposes.
tags object, optional Key value pair for annotating custom meta data (e.g. order numbers).
description string, optional Additional information about the device (e.g. self serving terminal).

Example Response

Copy
Copied
{
  "id" : "DVwjHWRiqQ6fcoH7NZC2nU1Z",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Terminal 1",
  "model" : "BBPOS",
  "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" : "ALWAYS",
    "signature_threshold_amount" : 0,
    "bypass_device_on_capture" : false
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVwjHWRiqQ6fcoH7NZC2nU1Z"
    },
    "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"
    }
  }
}

Local Articles

Article Description
iOS Device SDK Use Finix's iOS Device SDK to accept payments with a card reader and your iOS application.