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

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.

• Tokenization Forms
• Subscriptions
• Low Code / No Code

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.

Example

post

/identities

• Sandbox server https://finix.sandbox-payments-api.com/identities

cURL

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/identities \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "entity": {
      "email": "finix_example@finix.com",
      "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"
    },
    "identity_roles": [\
      "BUYER"\
    ],
    "tags": {
      "key": "value"
    },
    "type": "PERSONAL"
  }'

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

Identity - Buyer

{
  "id": "IDgjFNYNraTBiKUyTXB4GFNe",
  "created_at": "2025-08-12T19:56:51.90Z",
  "updated_at": "2025-08-12T19:56:51.90Z",
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "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_fingerprint": null,
    "business_tax_id_provided": false,
    "business_type": null,
    "default_statement_descriptor": null,
    "discover_mid": null,
    "dob": null,
    "doing_business_as": null,
    "email": "finix_example@finix.com",
    "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_fingerprint": null,
    "tax_id_provided": false,
    "title": null,
    "url": null
  },
  "identity_roles": [\
    "BUYER"\
  ],
  "tags": {
    "key": "value"
  },
  "type": "PERSONAL",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgjFNYNraTBiKUyTXB4GFNe"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgjFNYNraTBiKUyTXB4GFNe/verifications"
    },
    "merchants": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgjFNYNraTBiKUyTXB4GFNe/merchants"
    },
    "settlements": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgjFNYNraTBiKUyTXB4GFNe/settlements"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgjFNYNraTBiKUyTXB4GFNe/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgjFNYNraTBiKUyTXB4GFNe/transfers"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgjFNYNraTBiKUyTXB4GFNe/payment_instruments"
    },
    "associated_identities": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgjFNYNraTBiKUyTXB4GFNe/associated_identities"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDgjFNYNraTBiKUyTXB4GFNe/disputes"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    }
  }
}

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.

Example

post

/payment_instruments

• Sandbox server https://finix.sandbox-payments-api.com/payment_instruments

cURL

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/payment_instruments \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "address": {
      "city": "San Francisco",
      "country": "USA",
      "line1": "900 Metro Center Blv",
      "postal_code": "94404",
      "region": "CA"
    },
    "expiration_month": 12,
    "expiration_year": 2029,
    "identity": "IDmj1yA97RS4rMjiQgvK3Vio",
    "name": "John Jeremy",
    "number": "5200828282828210",
    "security_code": "022",
    "type": "PAYMENT_CARD"
  }'

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

Payment Instrument - Card

{
  "id": "PI6F5kkcCB3dtGhFy1t8Aua5",
  "created_at": "2024-11-15T09:42:33.42Z",
  "updated_at": "2024-11-15T09:42:33.42Z",
  "account_updater_enabled": false,
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": null,
  "disabled_message": null,
  "enabled": true,
  "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
  "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
  "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": "520082",
  "brand": "MASTERCARD",
  "card_type": "DEBIT",
  "expiration_month": 12,
  "expiration_year": 2029,
  "issuer_country": "NON_USA",
  "last_four": "8210",
  "name": "John Jeremy",
  "network_token_enabled": false,
  "network_token_state": "NOT_ENABLED",
  "security_code_verification": "UNKNOWN",
  "tags": {},
  "third_party": null,
  "third_party_token": null,
  "type": "PAYMENT_CARD",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6F5kkcCB3dtGhFy1t8Aua5"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6F5kkcCB3dtGhFy1t8Aua5/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6F5kkcCB3dtGhFy1t8Aua5/transfers"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6F5kkcCB3dtGhFy1t8Aua5/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/PI6F5kkcCB3dtGhFy1t8Aua5/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 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

Example

post

/transfers

• Sandbox server https://finix.sandbox-payments-api.com/transfers

cURL

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/transfers \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 5000,
    "currency": "CAD",
    "merchant": "string",
    "source": "PIxxxxxxxxxxxxxxxxxx"
  }'

A successful request returns a 201 Created status, with the response body containing a Transfer resource that includes:

• type — either DEBIT or CREDIT, depending on the payment instrument
• state — set to SUCCEEDED

Transfer - USA

{
  "id": "TR8fezr4xCMFJvH5rzCqrUkF",
  "created_at": "2025-10-24T17:38:19.09Z",
  "updated_at": "2025-10-24T17:38:19.09Z",
  "additional_buyer_charges": {
    "convenience_amount": 150,
    "surcharge_amount": 0,
    "rent_surcharge_amount": 0
  },
  "additional_healthcare_data": null,
  "additional_purchase_data": {
    "customer_reference_number": "321xyz",
    "customs_duty_amount": 10,
    "destination_country_code": null,
    "destination_postal_code": null,
    "discount_amount": 100,
    "invoice_reference_number": null,
    "order_date": null,
    "sales_tax": null,
    "sales_tax_finix_generated": 200,
    "ship_from_postal_code": null,
    "shipping_amount": 100,
    "tax_exempt": false,
    "item_data": [\
      {\
        "cost_per_unit": 500,\
        "item_description": "printing paper",\
        "item_discount_amount": 100,\
        "merchant_product_code": "1149611",\
        "quantity": 1,\
        "amount_excluding_sales_tax": 400,\
        "amount_including_sales_tax": 500,\
        "unit_of_measure": "BX",\
        "commodity_code": "175-62-20",\
        "sales_tax_amount": 100,\
        "sales_tax_rate": 0.25\
      },\
      {\
        "cost_per_unit": 500,\
        "item_description": "printing ink",\
        "item_discount_amount": 0,\
        "merchant_product_code": "2149612",\
        "quantity": 1,\
        "amount_excluding_sales_tax": 400,\
        "amount_including_sales_tax": 500,\
        "unit_of_measure": "CTN",\
        "commodity_code": "207-72-54",\
        "sales_tax_amount": 100,\
        "sales_tax_rate": 0.25\
      }\
    ]
  },
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "amount": 1000,
  "amount_requested": 1000,
  "application": "APc9vhYcPsRuTSpKD9KpMtPe",
  "currency": "USD",
  "created_via": "UNKNOWN",
  "destination": null,
  "externally_funded": "UNKNOWN",
  "failure_code": null,
  "failure_message": null,
  "fee": 0,
  "fee_profile": "FP9F2KEnY4wt1XjFvhLBJVjb",
  "idempotency_id": "1234567890",
  "ip_address_details": null,
  "merchant": "MUe17jKSrfPetoeiJQzzjmA2",
  "merchant_identity": "ID6NvZy42D7PChZL8GKKD87F",
  "messages": [],
  "network_details": {
    "brand": "VISA",
    "authorization_code": "252819",
    "acquirer_reference_number": null
  },
  "operation_key": "CARD_NOT_PRESENT_SALE",
  "parent_transfer": null,
  "parent_transfer_trace_id": null,
  "raw": null,
  "ready_to_settle_at": null,
  "receipt_last_printed_at": null,
  "security_code_verification": "MATCHED",
  "source": "PI6iQcTtJNCS8GZAVKYi5Ueb",
  "split_transfers": [\
    "split_transfer_8fv2kE5eWtCvru1NG5gyRL",\
    "split_transfer_8fvi9GJdhMbpWWJwKkHzct"\
  ],
  "state": "SUCCEEDED",
  "statement_descriptor": "FLX*FLEX GYM",
  "subtype": "API",
  "supplemental_fee": null,
  "tags": {
    "tip": "50"
  },
  "third_party_details": {
    "external_trace_id": "7249618074176301904267",
    "type": "CYBERSOURCE"
  },
  "tip_amount": null,
  "trace_id": "0db5b7cf-6fe3-4508-ac52-15b26b9b5e0a",
  "type": "DEBIT",
  "_links": {
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe"
    },
    "self": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR8fezr4xCMFJvH5rzCqrUkF"
    },
    "merchant_identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/ID6NvZy42D7PChZL8GKKD87F"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR8fezr4xCMFJvH5rzCqrUkF/payment_instruments"
    },
    "reversals": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR8fezr4xCMFJvH5rzCqrUkF/reversals"
    },
    "fees": {
      "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TR8fezr4xCMFJvH5rzCqrUkF"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/transfers/TR8fezr4xCMFJvH5rzCqrUkF/disputes"
    },
    "source": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6iQcTtJNCS8GZAVKYi5Ueb"
    },
    "fee_profile": {
      "href": "https://finix.sandbox-payments-api.com/fee_profiles/FP9F2KEnY4wt1XjFvhLBJVjb"
    }
  }
}