Online Payments Quickstart

Get started with using Finix to accept card payments online.

This guide explains how to get started with online payments. Finix offers multiple integration options for accepting payments online, including via API or our low-code / no-code solutions. Your buyers can make payments with their cards or bank accounts, which Finix lets you collect and store securely with our tokenization forms / SDKs, as well as our digital wallet and Plaid integrations. In addition, Finix offers many features for customizing your payments flow and managing risk.

To learn about in-person payments, read our In-Person Payments guide.

Making Payments via API

Customers that want the most flexibility for their online payments needs can use our APIs to build out their own payments flows. This option works well for customers that want to integrate payment acceptance into their website or app, and have developer resources to build that integration.

Step 1: Create a Buyer

First, create an Identity to represent your buyer. The Identity resource represents both buyers and sellers. If you're a platform managing multiple sellers, see our Platform Payments guide to learn how to onboard sellers.

Your buyer's Identity stores their personal data (such as name and email), and helps manage their payments, payment methods, identity verification, and more.

Buyer Identity Data

All buyer Identity fields are optional. However, Finix recommends including basic information (name, email, address, and phone) to make payment operations easier.

Buyer Identity Request

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 \
    -X POST \
    -d '{
        "entity": {
            "email": "user@example.org",
            "first_name": "John",
            "last_name": "Smith",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "line1": "741 Douglass St",
                "line2": "Apartment 7",
                "postal_code": "94114",
                "region": "CA"
            },
            "phone": "7145677613"
        }
    }'

Buyer Identity

{
    "id": "IDnytkgHCbgJkvtbpqrZtbnk",
    "created_at": "2025-01-05T15:29:14.19Z",
    "updated_at": "2025-01-05T15:29:14.19Z",
    "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": "user@example.org",
        "first_name": "John",
        "has_accepted_credit_cards_previously": false,
        "incorporation_date": null,
        "last_name": "Smith",
        "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": {},
    "type": "PERSONAL",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDnytkgHCbgJkvtbpqrZtbnk"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDnytkgHCbgJkvtbpqrZtbnk/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDnytkgHCbgJkvtbpqrZtbnk/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDnytkgHCbgJkvtbpqrZtbnk/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDnytkgHCbgJkvtbpqrZtbnk/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDnytkgHCbgJkvtbpqrZtbnk/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDnytkgHCbgJkvtbpqrZtbnk/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDnytkgHCbgJkvtbpqrZtbnk/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDnytkgHCbgJkvtbpqrZtbnk/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}

Step 2: Create a Payment Instrument

Payment Instruments represent your buyer's payment methods (either cards or bank accounts), from which you can accept payments. Buyers can have multiple Payment Instruments associated with their Identity.

Finix offers many different solutions for securely collecting payment method information from your buyers, including our tokenization forms / SDKs, as well as our digital wallet and Plaid integrations. Finix's vault securely encrypts and stores your buyers' Payment Instruments.

When you use one of our secure options to tokenize your buyer's card or bank account information, you can use the token Finix sends you to create a Payment Instrument. (When you use one of our digital wallet or Plaid integrations, Finix will send you a third_party_token).

Handling Raw Card Data

If you are PCI-compliant and wish to handle raw card data directly, see Handling Raw Card Data.

Payment Instruent Request

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 \
    -X POST \
    -d '{
        "token": "TKiMxe323RE5Dq3wLVtG8kSW",
        "type": "TOKEN",
        "identity": "IDpYDM7J9n57q849o9E9yNrG"
    }'

Payment Instruent

{
    "id": "PIwWisLuZNwPBoLbCgQVTCoY",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "fingerprint": "FPRmYp7ejhA3yDjSor4A5Ji2D",
    "tags": {
        "card_name": "Business Card"
    },
    "expiration_month": 12,
    "expiration_year": 2029,
    "bin": "400000",
    "last_four": "9979",
    "brand": "VISA",
    "card_type": "UNKNOWN",
    "name": "Amy White",
    "address": {
        "line1": "900 Metro Center Blv",
        "line2": null,
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94404",
        "country": "USA"
    },
    "address_verification": "NO_MATCH",
    "security_code_verification": "UNMATCHED",
    "created_at": "2022-08-15T23:13:06.13Z",
    "updated_at": "2022-08-15T23:13:06.88Z",
    "instrument_type": "PAYMENT_CARD",
    "type": "PAYMENT_CARD",
    "currency": "USD",
    "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY/verifications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K"
        },
        "updates": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY/updates"
        }
    }
}

Step 3: Create a Transfer

With your buyer's Identity and their Payment Instrument created, you are ready to make the payment. Finix offers two flows:

Direct Sale: One-step transaction that charges the Payment Instrument directly.
Authorization and Capture: Two-step transaction that creates an Authorization you can capture later

Customers use the authorization and capture flow when they want to create a hold on a card, and charge the full amount later. This flow is available for cards only. For more information, see Auth and Captures.

To make a direct sale, create a Transfer:

Set the source to your Buyer's Payment Instrument ID
Set the merchant to an APPROVED Merchant account
Include a fraud_session_id to reduce fraud risk

Fraud Session ID

Every integration with Finix must include the fraud_session_id to reduce fraud risk. For more information, see Fraud Detection.

Transfer Request

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 '{
        "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
        "currency": "USD",
        "amount": 662154,
        "source": "PIe2YvpcjvoVJ6PzoRPBK137",
        "fraud_session_id": "test_fraud"
    }'

Transfer

{
    "id": "TR29av3LN1TAGPbXscsup1tt",
    "amount": 662154,
    "tags": {},
    "state": "SUCCEEDED",
    "trace_id": "34f40e87-2599-414b-874b-f472790ff521",
    "currency": "USD",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "source": "PIe2YvpcjvoVJ6PzoRPBK137",
    "destination": null,
    "ready_to_settle_at": null,
    "externally_funded": "UNKNOWN",
    "fee": 0,
    "statement_descriptor": "FNX*FINIX FLOWERS",
    "type": "DEBIT",
    "messages": [],
    "raw": null,
    "created_at": "2022-08-25T20:39:37.59Z",
    "updated_at": "2022-08-25T20:39:38.17Z",
    "idempotency_id": null,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
    "subtype": "API",
    "failure_code": null,
    "failure_message": null,
    "additional_buyer_charges": null,
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/disputes"
        },
        "source": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
    }
}

Transfer States

Use the Transfer's state to understand where it is in the payment lifecycle. While you should expect most Transfers to succeed, some may fail (for example, when the buyer's bank declines the transaction). Note that most Sandboxes are configured for instant Transfer approval, but can be configured for asynchronous approval where Transfers return as pending.

State	Description
`PENDING`	The Transfer is still processing and will resolve to another state. If the Transfer stays `PENDING` for an extended period of time, reach out to Finix Support.
`SUCCEEDED`	The Transfer was successful, and the funds will soon be available in a Payout. The `ready_to_settle_at` field indicates when the Transfer will be included / batched into a Settlement.
`FAILED`	The Payment was declined. Refer to the `failure_code` and `failure_message` to learn why the transaction was declined.
`CANCELED`	There was an issue with the processor, please reach out to Finix Support.
`UNKNOWN`	A connection or timeout issue occurred while creating the Transfer. Reattempt the Transfer.

Low-Code / No-Code Solutions

Businesses that want to get started accepting payments without building a custom integration can use Finix's low-code / no-code online payment solutions. Read the guides below to learn how to get started.

Checkout Pages

Build custom low-code Checkout Pages.

Payment Links

Create and send Payment Links to help buyers easily complete transactions.

Virtual Terminal

Create and process payments with Finix's Virtual Terminal.

Payment Methods

Finix lets you accept payments from both cards and bank accounts, which Finix lets you collect and store securely with out tokenization forms / SDKs, as well as our digital wallet and Plaid integrations. You can customize which payment methods you want to support depending on which integration paths you take.

Tokenization

Securely collect payment details for your buyers and sellers.

Digital Wallets

Integrate Apple Pay™ and Google Pay™.

Plaid

Add bank accounts to Finix with Plaid.

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

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: