Platform Quickstart

This quickstart provides a guide on how to onboard sellers onto your platform and process payments with Finix.

Create your Finix API Key

Get started by creating a sandbox account with Finix. This sandbox account gives you access to the Finix Dashboard. You can use the Finix Dashboard to review your payment activity and manage how your sellers are configured.

Finix Dashboard

To create an API key with the dashboard, log in and click Developer > Create API Key. Make sure you save the username and password that gets returned. You won't be able to access the credentials again after closing the window.

As you use the credentials in your Finix API requests, you'll see that activity show up in the Finix Dashboard.

Supported Countries

Finix supports entities in the following countries:

United States
Canada

Be sure to include the correct country when creating an Identity and Merchant. To process payments in multiple countries, create a Merchant for each country the entity is registered in.

Step 1: Create an Identity for Your Seller

To onboard a seller or service provider, create an Identity by collecting basic information (e.g. company name, address, etc.) that's necessary to verify the business.

For businesses that have multiple owners who own 25% or more of the business, you'll need to create Associated Identities for each owner.

In this example, we'll onboard an individual person who is sole proprietorship and does not have additional owners.

USACanada

Copy

Copied

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": {
      "annual_card_volume": 12000000,
      "business_address": {
          "city": "San Mateo",
          "country": "USA",
          "region": "CA",
          "line2": "Apartment 8",
          "line1": "741 Douglass St",
          "postal_code": "94114"
      },
      "business_name": "Finix Flowers",
      "business_phone": "+1 (408) 756-4497",
      "business_tax_id": "123456789",
      "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
      "default_statement_descriptor": "Finix Flowers",
      "dob": {
          "year": 1978,
          "day": 27,
          "month": 6
      },
      "doing_business_as": "Finix Flowers",
      "email": "user@example.org",
      "first_name": "John",
      "has_accepted_credit_cards_previously": true,
      "incorporation_date": {
          "year": 1978,
          "day": 27,
          "month": 6
      },
      "last_name": "Smith",
      "max_transaction_amount": 12000000,
      "mcc": "4900",
      "ownership_type": "PRIVATE",
      "personal_address": {
          "city": "San Mateo",
          "country": "USA",
          "region": "CA",
          "line2": "Apartment 7",
          "line1": "741 Douglass St",
          "postal_code": "94114"
      },
      "phone": "1234567890",
      "principal_percentage_ownership": 50,
      "tax_id": "123456789",
      "title": "CEO",
      "url": "www.Finix.com"
    },
  "additional_underwriting_data": {
      "annual_ach_volume": 200000,
      "average_ach_transfer_amount": 200000,
      "average_card_transfer_amount": 200000,
      "business_description": "SB3 vegan cafe",
      "card_volume_distribution": {
          "card_present_percentage": 30,
          "mail_order_telephone_order_percentage": 10,
          "ecommerce_percentage": 60
      },
      "credit_check_allowed": true,
      "credit_check_ip_address": "42.1.1.113",
      "credit_check_timestamp": "2021-04-28T16:42:55Z",
      "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
      "merchant_agreement_accepted": true,
      "merchant_agreement_ip_address": "42.1.1.113",
      "merchant_agreement_timestamp": "2021-04-28T16:42:55Z",
      "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
      "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
      "volume_distribution_by_business_type": {
          "other_volume_percentage": 0,
          "consumer_to_consumer_volume_percentage": 0,
          "business_to_consumer_volume_percentage": 0,
          "business_to_business_volume_percentage": 100,
          "person_to_person_volume_percentage": 0
      }
  },
  "tags": {
      "Studio Rating": "4.7"
    }
}'

Copy

Copied

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": {
      "annual_card_volume": 12000000,
      "business_address": {
          "city": "Toronto",
          "country": "CAN",
          "region": "Ontario",
          "line2": "Suite 1234",
          "line1": "123 Main Street",
          "postal_code": "M5K 1E6"
      },
      "business_name": "Finix Flowers",
      "business_phone": "+1 (408) 756-4497",
      "business_tax_id": "123456789",
      "business_type": "CORPORATION",
      "default_statement_descriptor": "Finix Flowers",
      "dob": {
          "year": 1978,
          "day": 27,
          "month": 6
      },
      "doing_business_as": "Finix Flowers",
      "email": "user@example.org",
      "first_name": "Amy",
      "has_accepted_credit_cards_previously": true,
      "incorporation_date": {
          "year": 1978,
          "day": 27,
          "month": 6
      },
      "last_name": "Wilson",
      "max_transaction_amount": 1000000,
      "mcc": "4900",
      "ownership_type": "PRIVATE",
      "personal_address": {
          "city": "Toronto",
          "country": "CAN",
          "region": "Ontario",
          "line2": "Apartment 7",
          "line1": "741 Douglass St",
          "postal_code": "M5K 1E6"
      },
      "phone": "1234567890",
      "principal_percentage_ownership": 100,
      "tax_id": "123456789",
      "title": "CEO",
      "url": "www.Finix.com"
    },
  "additional_underwriting_data": {
      "amex_marketing_consent": {
        "accepted": true,
        "ip_address": "42.1.1.112",
        "timestamp": "2021-04-28T16:42:55Z",
        "user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)"
      },
      "annual_ach_volume": 200000,
      "average_ach_transfer_amount": 200000,
      "average_card_transfer_amount": 200000,
      "business_description": "SB3 vegan cafe",
      "card_volume_distribution": {
          "card_present_percentage": 30,
          "mail_order_telephone_order_percentage": 10,
          "ecommerce_percentage": 60
      },
      "credit_check_allowed": true,
      "credit_check_ip_address": "42.1.1.113",
      "credit_check_timestamp": "2021-04-28T16:42:55Z",
      "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
      "merchant_agreement_accepted": true,
      "merchant_agreement_ip_address": "42.1.1.113",
      "merchant_agreement_timestamp": "2021-04-28T16:42:55Z",
      "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
      "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
      "volume_distribution_by_business_type": {
          "other_volume_percentage": 0,
          "consumer_to_consumer_volume_percentage": 0,
          "business_to_consumer_volume_percentage": 0,
          "business_to_business_volume_percentage": 100,
          "person_to_person_volume_percentage": 0
      }
  },
  "tags": {
      "Studio Rating": "4.7"
    }
}'

A successful response returns 201 and the newly created Identity.

USACanada

Copy

Copied

{
    "id": "IDpU2s47QCAgzWcCbs5xEcUE",
    "created_at": "2022-10-31T05:06:25.75Z",
    "updated_at": "2022-10-31T05:06:25.75Z",
    "additional_underwriting_data": {
        "annual_ach_volume": 200000,
        "average_ach_transfer_amount": 200000,
        "average_card_transfer_amount": 200000,
        "business_description": "SB3 vegan cafe",
        "card_volume_distribution": {
            "card_present_percentage": 30,
            "ecommerce_percentage": 60,
            "mail_order_telephone_order_percentage": 10
        },
        "credit_check_allowed": true,
        "credit_check_ip_address": "42.1.1.113",
        "credit_check_timestamp": "2021-04-28T16:42:55Z",
        "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
        "merchant_agreement_accepted": true,
        "merchant_agreement_ip_address": "42.1.1.113",
        "merchant_agreement_timestamp": "2021-04-28T16:42:55Z",
        "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
        "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
        "volume_distribution_by_business_type": {
            "business_to_business_volume_percentage": 100,
            "business_to_consumer_volume_percentage": 0,
            "consumer_to_consumer_volume_percentage": 0,
            "other_volume_percentage": 0,
            "person_to_person_volume_percentage": 0
        }
    },
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "entity": {
        "amex_mid": null,
        "annual_card_volume": 12000000,
        "business_address": {
            "line1": "741 Douglass St",
            "line2": "Apartment 8",
            "city": "San Mateo",
            "region": "CA",
            "postal_code": "94114",
            "country": "USA"
        },
        "business_name": "Finix Flowers",
        "business_phone": "+1 (408) 756-4497",
        "business_tax_id_provided": true,
        "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "default_statement_descriptor": "Finix Flowers",
        "discover_mid": null,
        "dob": {
            "day": 27,
            "month": 6,
            "year": 1978
        },
        "doing_business_as": "Finix Flowers",
        "email": "user@example.org",
        "first_name": "John",
        "has_accepted_credit_cards_previously": true,
        "incorporation_date": {
            "day": 27,
            "month": 6,
            "year": 1978
        },
        "last_name": "Smith",
        "max_transaction_amount": 12000000,
        "mcc": "4900",
        "ownership_type": "PRIVATE",
        "personal_address": {
            "line1": "741 Douglass St",
            "line2": "Apartment 7",
            "city": "San Mateo",
            "region": "CA",
            "postal_code": "94114",
            "country": "USA"
        },
        "phone": "1234567890",
        "principal_percentage_ownership": 50,
        "short_business_name": null,
        "tax_authority": null,
        "tax_id_provided": true,
        "title": "CEO",
        "url": "www.Finix.com"
    },
    "tags": {
        "Studio Rating": "4.7"
    },
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}

Copy

Copied

{
    "id": "IDbuyRPdoEBfEsKcuKEPgkqP",
    "created_at": "2024-02-29T18:18:23.10Z",
    "updated_at": "2024-02-29T18:18:23.10Z",
    "additional_underwriting_data": {
        "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
        "amex_marketing_consent": {
            "accepted": true,
            "ip_address": "42.1.1.112",
            "timestamp": "2021-04-28T16:42:55Z",
            "user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)"
        },
        "credit_check_ip_address": "42.1.1.113",
        "card_volume_distribution": {
            "card_present_percentage": 30,
            "mail_order_telephone_order_percentage": 10,
            "ecommerce_percentage": 60
        },
        "average_ach_transfer_amount": 200000,
        "average_card_transfer_amount": 200000,
        "merchant_agreement_accepted": true,
        "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
        "merchant_agreement_ip_address": "42.1.1.113",
        "annual_ach_volume": 200000,
        "credit_check_allowed": true,
        "business_description": "SB3 vegan cafe",
        "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
        "volume_distribution_by_business_type": {
            "other_volume_percentage": 0,
            "consumer_to_consumer_volume_percentage": 0,
            "business_to_consumer_volume_percentage": 0,
            "business_to_business_volume_percentage": 100,
            "person_to_person_volume_percentage": 0
        },
        "credit_check_timestamp": "2021-04-28T16:42:55Z",
        "merchant_agreement_timestamp": "2021-04-28T16:42:55Z"
    },
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "entity": {
        "ach_max_transaction_amount": 1000000,
        "amex_mid": null,
        "annual_card_volume": 12000000,
        "business_address": {
            "line1": "123 Main Street",
            "line2": "Suite 1234",
            "city": "Toronto",
            "region": "Ontario",
            "postal_code": "M5K 1E6",
            "country": "CAN"
        },
        "business_name": "Finix Flowers",
        "business_phone": "+1 (408) 756-4497",
        "business_tax_id_provided": true,
        "business_type": "CORPORATION",
        "default_statement_descriptor": "Finix Flowers",
        "discover_mid": null,
        "dob": {
            "day": 27,
            "month": 6,
            "year": 1978
        },
        "doing_business_as": "Finix Flowers",
        "email": "user@example.org",
        "first_name": "Amy",
        "has_accepted_credit_cards_previously": true,
        "incorporation_date": {
            "day": 27,
            "month": 6,
            "year": 1978
        },
        "last_name": "Wilson",
        "max_transaction_amount": 1000000,
        "mcc": "4900",
        "ownership_type": "PRIVATE",
        "personal_address": {
            "line1": "741 Douglass St",
            "line2": "Apartment 7",
            "city": "Toronto",
            "region": "Ontario",
            "postal_code": "M5K 1E6",
            "country": "CAN"
        },
        "phone": "1234567890",
        "principal_percentage_ownership": 100,
        "short_business_name": null,
        "tax_authority": null,
        "tax_id_provided": true,
        "title": "CEO",
        "url": "www.Finix.com"
    },
    "identity_roles": [
        "SELLER"
    ],
    "tags": {
        "Studio Rating": "4.7"
    },
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}

Step 2: Add a Bank Account for Payouts

Second, create a Payment Instrument representing a seller's bank account where processed payouts will be settled (i.e. deposited). Include the previously created Identity#id to link the two resources.

A Payment Instrument resource represents the payment details of a credit card or bank account. Payment details get tokenized multiple times and each tokenization produces a unique Payment Instrument. A Payment Instrument is associated with a single Identity. Once a Payment Instrument is created, the Identity it's associated with can't be changed.

USACanada

Copy

Copied

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 '{
    "account_number": "123123123",
    "account_type": "SAVINGS",
    "bank_code": "123123123",
    "country": "USA",
    "currency": "USD",
    "identity": "IDvHGrfeVmB3i7uL78xjemNk",
    "name": "John",
    "type": "BANK_ACCOUNT"
	}'

Copy

Copied

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 '{
    "account_number": "123123123",
    "account_type": "PERSONAL_CHECKING",
    "country": "CAN",
    "currency": "CAD",
    "identity": "IDbuyRPdoEBfEsKcuKEPgkqP",
    "institution_number": "123",
    "name": "John Smith",
    "transit_number": "12345",
    "type": "BANK_ACCOUNT"
	}'

A successful response returns 201 with the newly created Payment Instrument.

USACanada

Copy

Copied

{
    "id": "PIcsMDFxZrxFXRVfyQCzXNC9",
    "created_at": "2022-10-10T04:42:09.12Z",
    "updated_at": "2022-10-10T04:42:09.12Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "country": "USA",
    "currency": "USD",
    "enabled": true,
    "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg",
    "identity": "IDvHGrfeVmB3i7uL78xjemNk",
    "instrument_type": "BANK_ACCOUNT",
    "account_type": "SAVINGS",
    "bank_account_validation_check": "NOT_ATTEMPTED",
    "bank_code": "123123123",
    "masked_account_number": "XXXXX3123",
    "name": "John",
    "tags": {},
    "type": "BANK_ACCOUNT",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcsMDFxZrxFXRVfyQCzXNC9"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcsMDFxZrxFXRVfyQCzXNC9/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcsMDFxZrxFXRVfyQCzXNC9/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcsMDFxZrxFXRVfyQCzXNC9/verifications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk"
        }
    }
}

Copy

Copied

{
    "id": "PItgCQRQQAeHLTc6QAEZf22m",
    "created_at": "2024-02-29T18:31:34.31Z",
    "updated_at": "2024-02-29T18:31:34.31Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "CAD",
    "disabled_code": null,
    "disabled_message": null,
    "enabled": true,
    "fingerprint": "FPR8RAHfXm1BMYYVJyHWHhw4J",
    "identity": "IDbuyRPdoEBfEsKcuKEPgkqP",
    "instrument_type": "BANK_ACCOUNT",
    "account_type": "PERSONAL_CHECKING",
    "bank_account_validation_check": "NOT_ATTEMPTED",
    "bank_code": null,
    "country": "CAN",
    "institution_number": "123",
    "masked_account_number": "XXXXX3123",
    "name": "John Smith",
    "transit_number": "12345",
    "tags": {},
    "third_party": null,
    "third_party_token": null,
    "type": "BANK_ACCOUNT",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PItgCQRQQAeHLTc6QAEZf22m"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PItgCQRQQAeHLTc6QAEZf22m/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PItgCQRQQAeHLTc6QAEZf22m/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PItgCQRQQAeHLTc6QAEZf22m/verifications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP"
        }
    }
}

Step 3: Verify and Onboard Your Seller

Now that we've associated a Payment Instrument with our seller’s Identity we’re ready to provision a Merchant account. This is the last step before you can begin processing on their behalf. Luckily you’ve already done most of the heavy lifting. Just make one final POST request, and you’ll be returned a Merchant resource.

Copy

Copied

curl "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/merchants" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -d '{
    "processor": "DUMMY_V1"
      }'

A successful response returns 201 with the newly created Merchant.

Copy

Copied

{
    "id": "MU2ekLKCiV8M5waZ3Ayg7ic6",
    "created_at": "2024-02-29T18:32:11.62Z",
    "updated_at": "2024-02-29T18:32:11.62Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "card_cvv_required": false,
    "card_expiration_date_required": true,
    "convenience_charges_enabled": false,
    "country": "CAN",
    "creating_transfer_from_report_enabled": true,
    "currencies": [
        "CAD"
    ],
    "default_partial_authorization_enabled": false,
    "disbursements_ach_pull_enabled": false,
    "disbursements_ach_push_enabled": false,
    "disbursements_card_pull_enabled": false,
    "disbursements_card_push_enabled": false,
    "fee_ready_to_settle_upon": "RECONCILIATION",
    "gateway": null,
    "gross_settlement_enabled": false,
    "identity": "IDbuyRPdoEBfEsKcuKEPgkqP",
    "level_two_level_three_data_enabled": false,
    "mcc": "4900",
    "merchant_name": "Finix Flowers",
    "merchant_profile": "MPtghSGfMec2LfkCQ2HU4VWu",
    "mid": null,
    "onboarding_state": "PROVISIONING",
    "processing_enabled": false,
    "processor": "DUMMY_V1",
    "processor_details": {},
    "ready_to_settle_upon": "RECONCILIATION",
    "rent_surcharges_enabled": false,
    "settlement_enabled": false,
    "settlement_funding_identifier": "UNSET",
    "surcharges_enabled": false,
    "tags": {},
    "verification": "VInjHQLPa9C9QJEgDMx3gZa9",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MU2ekLKCiV8M5waZ3Ayg7ic6"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MU2ekLKCiV8M5waZ3Ayg7ic6/verifications"
        },
        "merchant_profile": {
            "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPtghSGfMec2LfkCQ2HU4VWu"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "verification": {
            "href": "https://finix.sandbox-payments-api.com/verifications/VInjHQLPa9C9QJEgDMx3gZa9"
        }
    }
}

Merchant#onboarding_state can have 3 potential values that details where the Merchant is in the onboarding process:

Merchant State	Description
PROVISIONING	Request is pending (typically changes after two minutes)
APPROVED	Seller has been approved and can begin processing
REJECTED	Seller was rejected either because the information collected was invalid or it failed one of a number of regulatory and/or compliance checks (e.g. KYC, OFAC or MATCH)

We recommend integrating into our webhooks to be alerted when Merchant#onboarding_state changes. If you don't want to use our webhooks, you can make a GET request to the Merchant resource to check it's onboarding_state.

Canadian Bank Accounts

Canadian sellers are also required to verify their bank accounts. Seller's can verify their Canadian bank accounts by uploading a bank document. Acceptable bank documents include bank statements, bank letters, or voided checks.

To upload bank documents, sellers can use either:

Finix's API
Finix's dashboard

You can also use Onboarding Forms, which handles steps 1-3 and also prompts the seller to verify their bank account.

Finix API

To upload a bank document with the Finix API:

Create a File resource of type: BANK_STATEMENT.
Upload the bank document to the File resource.

Copy

Copied

curl "https://finix.sandbox-payments-api.com/files" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -d '{
    "display_name": "Bank File",
    "linked_to": "IDvMDR4ppijCJmy6Bobntiv6",
    "type": "BANK_STATEMENT"
  }'

See Upload files to Finix for more details about uploading documents to the File resource.

Finix Dashboard

To upload files using the Finix Dashboard:

Log in to your Finix Dashboard and click Merchants > Merchant Accounts.
Select the Merchant, and click the Files tab on the top navigation bar.
Click Upload File and enter the name you want to give the file. Select the Document Type.
Drag and drop the file you want to upload and click Upload File.

If the upload is successful a green banner will appear. You can view the file in your browser by clicking the File ID.

Step 4: Create an Identity for Your Buyer

Now that you've successfully onboarded a Merchant, you can start processing payments for your seller. 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.

attention

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.

Copy

Copied

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 Payment Instrument you'll use in the next step.

Copy

Copied

{
    "id": "IDbKCkEWUXALZGkvrMfQcnS9",
    "created_at": "2022-10-10T04:45:30.12Z",
    "updated_at": "2022-10-10T04:45:30.12Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "entity": {
        "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
    },
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}

Step 5: Tokenize Payment Details

Now that we have an Identity resource representing our buyer, we’ll need to create a Payment Instrument which represents 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.

attention

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 and by PCI Level 1 compliant entities. If you aren't a Level 1 PCI-compliant entity, you must use our Tokenization Forms or Mobile Tokenization to accept payment details and comply with PCI regulations. If you have any questions, please don't hesitate to reach out to your Finix point of contact or email the Finix Support team.

Copy

Copied

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 make a payment to your seller.

Copy

Copied

{
    "id": "PI6fBxWjm2GfdhCughovSWQr",
    "created_at": "2022-10-10T04:47:42.41Z",
    "updated_at": "2022-10-10T04:47:42.41Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "USD",
    "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/PI6fBxWjm2GfdhCughovSWQr"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6fBxWjm2GfdhCughovSWQr/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6fBxWjm2GfdhCughovSWQr/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6fBxWjm2GfdhCughovSWQr/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/PI6fBxWjm2GfdhCughovSWQr/updates"
        }
    }
}

Step 6: Make a Payment

At this point, we've onboarded a seller and tokenized a buyer's payment details. We can now create a payment. You create a payment by creating a Transfer.To make a payment, you need to create a Transfer. We’ll include the buyer’s Payment Instrument#id as the source field and the seller’s Merchant ID in the merchant field.

We recommend including a fraud_session_id to detect and block potential fraudulent payments. For more information, see Fraud Detection.
Note that the amount field is in cents.

Alternatively, you can create an Authorization and 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.

USACanada

Copy

Copied

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": "PI6fBxWjm2GfdhCughovSWQr"
  }'

Copy

Copied

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": 350,
    "currency": "CAD",
    "merchant": "MU2ekLKCiV8M5waZ3Ayg7ic6",
    "source": "PIkvt7XgquT2zzCx7jLPkh5z"
  }'

Note: The currency of the Transfer or Authorization must match the currencies on the Merchant. At the moment, you may only have one currencies value associated to a Merchant. A successful response returns the Transfer with a type of DEBIT and a state of SUCCEEDED.

USACanada

Copy

Copied

{
    "id": "TRsZQyem5h5vtRFSWBorBfSs",
    "created_at": "2022-10-10T04:48:59.06Z",
    "updated_at": "2022-10-10T04:48:59.76Z",
    "additional_buyer_charges": null,
    "additional_healthcare_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_identity": "IDvHGrfeVmB3i7uL78xjemNk",
    "messages": [],
    "raw": null,
    "ready_to_settle_at": null,
    "security_code_verification": null,
    "source": "PI6fBxWjm2GfdhCughovSWQr",
    "state": "SUCCEEDED",
    "statement_descriptor": "FNX*FINIX FLOWERS",
    "subtype": "API",
    "tags": {},
    "trace_id": "5576e040-f497-474b-a153-722f49ba007f",
    "type": "DEBIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRsZQyem5h5vtRFSWBorBfSs"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRsZQyem5h5vtRFSWBorBfSs/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRsZQyem5h5vtRFSWBorBfSs/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRsZQyem5h5vtRFSWBorBfSs/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRsZQyem5h5vtRFSWBorBfSs/disputes"
        },
        "source": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6fBxWjm2GfdhCughovSWQr"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
    }
}

Copy

Copied

{
    "id": "TR6wCGWsuj9Mw6oLfTTLavFY",
    "created_at": "2024-02-29T18:34:29.94Z",
    "updated_at": "2024-02-29T18:34:30.69Z",
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "additional_purchase_data": null,
    "address_verification": null,
    "amount": 350,
    "amount_requested": 350,
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "currency": "CAD",
    "destination": null,
    "externally_funded": "UNKNOWN",
    "failure_code": null,
    "failure_message": null,
    "fee": 0,
    "idempotency_id": null,
    "merchant": "MU2ekLKCiV8M5waZ3Ayg7ic6",
    "merchant_identity": "IDbuyRPdoEBfEsKcuKEPgkqP",
    "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": "PIkvt7XgquT2zzCx7jLPkh5z",
    "split_transfers": [],
    "state": "SUCCEEDED",
    "statement_descriptor": "FNX*FINIX FLOWERS",
    "subtype": "API",
    "tags": {},
    "trace_id": "f6f19976-66de-4cea-8764-83e7044b45b3",
    "type": "DEBIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR6wCGWsuj9Mw6oLfTTLavFY"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR6wCGWsuj9Mw6oLfTTLavFY/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR6wCGWsuj9Mw6oLfTTLavFY/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR6wCGWsuj9Mw6oLfTTLavFY/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR6wCGWsuj9Mw6oLfTTLavFY/disputes"
        },
        "source": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkvt7XgquT2zzCx7jLPkh5z"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
    }
}

The above response means the seller successfully charged the buyer, and the funds will soon be ready to get paid out to the seller.

Finix creates a Settlement resource that maps transactions and fees to calculate your seller's payout. Read our Payout guide for more details on managing and reconciling payouts.

Canada

Support for Canada is currently in early access. All Canadian Settlements will temporarily get settled on a Daily Net schedule. Your Finix point of contact will keep you informed of changes to Canadian Settlements and updates to our support in Canada.

Next Steps

Our Platform Checklist provides an overview of what's required to take an platform live.

Onboarding Sellers

Learn how to onboard your sellers and what information you'll need to verify.

Platform Checklist

Verify your platform is ready to process live transactions.