Developer Quickstart

Finix supports both Online Payments and In-Person Payments. This quickstart provides details on how your business can accept a payment with Finix.

Online Payments

Online Payments Hero

Accept online payments with Finix's complete solution, whether you're building a custom checkout experience or need a quick payment solution.

Flexible integrations: Build custom payment flows with our APIs, or get started with our low-code / no-code solutions
Multiple payment methods: Accept credit cards, debit cards, bank accounts, digital wallets, and more.
Security first: Protect sensitive payment data with our PCI-compliant tokenization system.

To see an example of our Tokenization Forms and Hosted Checkout, you can visit our sample store and related GitHub Project.

Our Tokenization Forms allow you to build a custom checkout page you own and control. This option is great if you want maximum customizability.

Step 1: Create an Identity for Your Buyer

With your API Key and Merchant ID, you can start processing payments.

To process a payment, we’ll need to create an Identity that represents your buyer. You won’t need to capture the same amount of information from your buyer. So long as you don’t pass a identity#business_type field all the other fields are optional.

Usually, we suggest at least collecting the buyer’s name and email to help with accounting, reconciliation, and chargebacks.

Do not pass the business_type field when creating an Identity for a buyer. Including business_type configures our API to treat the created Identity as a seller.

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
     "entity": {
         "phone": "7145677613",
         "first_name": "Collen",
         "last_name": "Wade",
         "email": "therock@gmail.com",
         "personal_address": {
             "city": "San Mateo",
             "country": "USA",
             "region": "CA",
             "line2": "Apartment 7",
             "line1": "741 Douglass St",
             "postal_code": "94114"
         }
     }
 }'

A successful response returns the Identity you'll use in the next step.

{
    "id": "IDn7rfwM88AJrBituwUjcX2Y",
    "created_at": "2023-10-25T17:42:22.23Z",
    "updated_at": "2023-10-25T17:42:22.23Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "entity": {
        "ach_max_transaction_amount": 0,
        "amex_mid": null,
        "annual_card_volume": 0,
        "business_address": null,
        "business_name": null,
        "business_phone": null,
        "business_tax_id_provided": false,
        "business_type": null,
        "default_statement_descriptor": null,
        "discover_mid": null,
        "dob": null,
        "doing_business_as": null,
        "email": "therock@gmail.com",
        "first_name": "Collen",
        "has_accepted_credit_cards_previously": false,
        "incorporation_date": null,
        "last_name": "Wade",
        "max_transaction_amount": 0,
        "mcc": null,
        "ownership_type": null,
        "personal_address": {
            "line1": "741 Douglass St",
            "line2": "Apartment 7",
            "city": "San Mateo",
            "region": "CA",
            "postal_code": "94114",
            "country": "USA"
        },
        "phone": "7145677613",
        "principal_percentage_ownership": null,
        "short_business_name": null,
        "tax_authority": null,
        "tax_id_provided": false,
        "title": null,
        "url": null
    },
    "identity_roles": [],
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}

Step 2: Tokenize Payment Details

Now that we have an Identity resource representing your buyer, we’ll need to create a Payment Instrument for your buyer to represent the credit card you’ll be debiting (i.e. charging).

You’ll also need to include your buyer’s Identity#id from the previous request to link the Payment Instrument that's created with your buyer's details.

Please note that creating Payment Instruments and passing payment details (account number, card number, etc.) directly via the API should only be done for testing purposes. You must use the Tokenization Forms or mobile tokenization (see Android or iOS tokenization) to accept payment details and remain out of PCI scope.

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
     "address": {
         "city": "San Francisco",
         "country": "USA",
         "line1": "900 Metro Center Blv",
         "postal_code": "94404",
         "region": "CA"
     },
     "expiration_month": 12,
     "expiration_year": 2029,
     "identity": "IDbKCkEWUXALZGkvrMfQcnS9",
     "name": "John Smith",
     "number": "4895142232120006",
     "security_code": "022",
     "type": "PAYMENT_CARD"
 }'

A successful response returns the newly created Payment Instrument you'll use to process the buyer's payment.

{
    "id": "PIcacm9WBYXZSd7NB5DmpN6E",
    "created_at": "2023-10-25T17:43:09.94Z",
    "updated_at": "2023-10-25T17:43:09.94Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "USD",
    "disabled_code": null,
    "disabled_message": null,
    "enabled": true,
    "fingerprint": "FPRogKWsRQks2HGaau5eGR9AF",
    "identity": "IDbKCkEWUXALZGkvrMfQcnS9",
    "instrument_type": "PAYMENT_CARD",
    "address": {
        "line1": "900 Metro Center Blv",
        "line2": null,
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94404",
        "country": "USA"
    },
    "address_verification": "UNKNOWN",
    "bin": "489514",
    "brand": "VISA",
    "card_type": "UNKNOWN",
    "expiration_month": 12,
    "expiration_year": 2029,
    "issuer_country": "UNKNOWN",
    "last_four": "0006",
    "name": "John Smith",
    "security_code_verification": "UNKNOWN",
    "tags": {},
    "type": "PAYMENT_CARD",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/verifications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9"
        },
        "updates": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/updates"
        }
    }
}

Step 3: Make a Payment

At this point, we've tokenized a buyer's payment details. We can now create a payment.

To make a payment, you need to create a Transfer. Include the buyer’s Payment Instrument#id as the source field and the your Merchant#id in the merchant field.

Finding your Merchant ID

If you are a Direct Merchant, you will be provided a merchant_id to use. You can find this in your Developer section on the Dashboard. If you need help finding this ID, please contact our support team or your Finix point of contact.
If you are a Platform, you will need to onboard each of your sellers. Each seller will be provided a unique merchant_id.

Creating a Payment

For the request below, please note that the amount field is in cents.

curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
     "amount": 662154,
     "currency": "USD",
     "merchant": "MU7cXuKj2xx41hhZZi6bZ13A",
     "source": "PIcacm9WBYXZSd7NB5DmpN6E"
 }'

A successful response returns the Transfer with type: DEBIT and state: SUCCEEDED.

{
    "id": "TRBuZ2qrAw268K2npdBpdT9",
    "created_at": "2023-10-25T17:43:34.23Z",
    "updated_at": "2023-10-25T17:43:35.10Z",
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "additional_purchase_data": null,
    "address_verification": null,
    "amount": 662154,
    "amount_requested": 662154,
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "currency": "USD",
    "destination": null,
    "externally_funded": "UNKNOWN",
    "failure_code": null,
    "failure_message": null,
    "fee": 0,
    "idempotency_id": null,
    "merchant": "MU7cXuKj2xx41hhZZi6bZ13A",
    "merchant_identity": "IDvHGrfeVmB3i7uL78xjemNk",
    "messages": [],
    "parent_transfer": null,
    "parent_transfer_trace_id": null,
    "raw": null,
    "ready_to_settle_at": null,
    "receipt_last_printed_at": null,
    "security_code_verification": null,
    "source": "PIcacm9WBYXZSd7NB5DmpN6E",
    "split_transfers": [],
    "state": "SUCCEEDED",
    "statement_descriptor": "FNX*FINIX FLOWERS",
    "subtype": "API",
    "tags": {},
    "trace_id": "a395feb9-0fcd-45ab-b4e6-280d2d7cdf5d",
    "type": "DEBIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/disputes"
        },
        "source": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
    }
}

The above response means the buyer was successfully charged and the funds will soon be ready to pay out. Finix creates a Settlement resource which maps transactions and fees to calculate your payout. Read Payouts for more details on how to manage and reconcile payouts.

Authorizations

Alternatively, you can create an Authorization to capture the same Authorization in two API calls. This is useful when you want to verify the payment details and capture a specific amount at a later date. For more details, see Creating and Capturing an Authorization.

Fraud Session ID

We recommend including a fraud_session_id to detect and block potential fraudulent payments. For more information, see Fraud Detection.

In-Person Payments

In-Person Payments Hero

Accept in-person payments with Finix’s flexible, platform-ready solution—built for custom POS flows or turnkey hardware experiences.

Flexible integrations: Power your POS with our APIs or launch fast with our Standalone Terminals.
Modern payment methods: Accept chip, tap, swipe, mobile wallets, and contactless payments across supported devices.
Security first: Protect sensitive payment data with our PCI-compliant tokenization system.

To get started with our In-Person Payments, select one of the links below.

Select Your Device

Learn about the payment terminals available for In-Person Payments integrations.

Building your Integration

Learn about Finix's POS and mobile in-person payments integrations.

Standalone Terminals

Learn about Finix's Standalone Terminals.

Additional Resources

Payment Features

Finix supports a variety of different payment features to let you customize your payments integration:

Use authorizations and captures to create temporary holds before capturing full amounts later.
Enable buyer charges to collect additional fees, such as convenience or service fees.
Split Transactions across different approved merchants.
Collect tips from buyers.
Accept FSA and HSA cards for health-related payments.
Enable Level 2 / Level 3 processing to reduce interchange rates.
Send receipts to your buyers.

Wallet Payments

Integrate Apple Pay to create a frictionless experience on web or mobile.
Integrate Google Pay to let users pay on web or on android device.

Fraud and Risk

Learn about the variety of tools that Finix offers to manage fraud and risk:

Use 3D Secure Authentication for an extra security layer when accepting card payments.
Disable payment instruments you know to be fraudulent.
Integrate into Finix's fraud detection solution to mitigate chargeback risk.
Handle declined payments to learn what to do when payments fail.
Enable risk rules and card checks to verify card details before accepting payments.

After the Payment

After accepting an online payment, there are some final steps: