Onboarding via API

Learn how to onboard your sellers with Finix APIs.

Finix offers APIs to onboard your sellers directly to Finix. The process follows the same steps as our Onboarding Forms, while giving you the most control over your seller's onboarding experience. For example, you might build your own hosted onboarding solution on top of Finix's APIs if you board a high volume of merchants or want full control over the user experience.

Onboarding sellers via API involves 5 steps:

  1. Collect your sellers' information and consent to the onboarding process
  2. Create an Identity with your seller's business and personal information
  3. Create a Payment Instrument with your seller's bank account information
  4. Create a Merchant that your seller will use to process payments
  5. Listen for updates to the Merchant account as Finix reviews your seller
Merchant Accounts

Step 1: Collect Information and Consent

To board sellers directly via API, Finix requires you that you:

  • Collect your sellers' business, ownership, processing, and bank account information
  • Present language to your sellers that their information will be verified
  • Present both Finix's and your own terms of service to your sellers
  • Present your payment processing fees to your sellers

Collecting Information

Finix requires you collect the following information about your sellers:

  1. Business information: Finix collects data about your seller's business, such as their business name
  2. Owner information: Finix collects data about your your seller's control person, such as their personal name
  3. Processing information: Finix collects data about your seller's processing information, such as volumes
  4. Bank account information: Finix collects details about your seller's bank account for their payouts

See Onboarding Data and Identities for the full list of required fields and data formats.

Collecting Bank Account Information

When collecting bank account information, you must use the following language to communicate to your sellers that the bank account provided should only be used for business purposes:

Copy
Copied
You agree to use this bank account for legitimate business purposes, and not for personal, family, or household purposes.

Verification Consent

You must present your sellers with language informing them that they are applying for payment processing services, and that their identity will be verified. Please add the following text at the beginning of your onboarding process:

Copy
Copied
The information you provide will be used to verify your identity. Additional information may be requested.

Terms of Service

You must present both Finix's and your own terms of service to your sellers, which your sellers must explicitly consent to via click-through agreement. Please add the following text to your onboarding process, which should hyperlink to both Finix's and your own terms of service:

Copy
Copied
By continuing, you agree to our Terms of Service and the Finix Terms of Service.

The Finix Terms of Service version you link to varies by your seller's business country and payment processor:

Country Processor Terms of Service Version
United States (USA) FINIX_V1 Link
United States (USA) LITLE_V1 Link
United States (USA) VANTIV_V1 Link
Canada (CAN) FINIX_V1 Link

Finix will collect information about your seller's consent on the Identity resource in the next step.

Presenting Fees

You must present your payment processing fees to your sellers clearly and prominently in your onboarding process. In addition, you must communicate fee changes to your sellers with prior notice.

Step 2: Create an Identity

After the previous step is complete, you are ready to create an Identity for your seller. The Identity holds the business, personal, processing, and consent information from your seller, which Finix underwrites during the review process. Each Identity can hold one person's information; should your seller's business have one or more beneficial owners with 25% or more ownership, you must create an Associated Identity for each beneficial owner.

See Onboarding Data and Identities for the full list of required fields and data formats.

USACANAssociated Identity
Copy
Copied
curl -i -X POST \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  https://finix.sandbox-payments-api.com/identities \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "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.112",
      "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
      }
    },
    "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": 1200000,
      "ach_max_transaction_amount": 1000000,
      "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": "14158885080",
      "principal_percentage_ownership": 50,
      "tax_id": "123456789",
      "title": "CEO",
      "url": "https://www.finix.com"
    },
    "identity_roles": [
      "SELLER"
    ],
    "tags": {
      "Studio Rating": "4.7"
    },
    "type": "BUSINESS"
  }'
Copy
Copied
curl -i -X POST \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  https://finix.sandbox-payments-api.com/identities \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "additional_underwriting_data": {
      "annual_ach_volume": 200000,
      "average_ach_transfer_amount": 200000,
      "average_card_transfer_amount": 200000,
      "business_description": "Business offering video editing services.",
      "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.112",
      "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
      }
    },
    "entity": {
      "annual_card_volume": 12000000,
      "business_address": {
        "city": "Vancouver",
        "country": "CAN",
        "region": "BC",
        "line2": null,
        "line1": "456 Elm Avenue",
        "postal_code": "V6B 2L2"
      },
      "business_name": "Video Editing Services",
      "business_phone": "+1 (416) 555-7890",
      "business_tax_id": "123456789",
      "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
      "default_statement_descriptor": "Video Services",
      "dob": {
        "year": 1978,
        "day": 27,
        "month": 6
      },
      "doing_business_as": "Video Editing Services",
      "email": "info@video-editing-services.com",
      "first_name": "Jerry",
      "has_accepted_credit_cards_previously": true,
      "incorporation_date": {
        "year": 1978,
        "day": 27,
        "month": 6
      },
      "last_name": "Dunhill",
      "max_transaction_amount": 1200000,
      "ach_max_transaction_amount": 1000000,
      "mcc": "4900",
      "ownership_type": "PRIVATE",
      "personal_address": {
        "city": "Vancouver",
        "country": "CAN",
        "region": "BC",
        "line2": null,
        "line1": "987 Milo Street",
        "postal_code": "V5K 1Z5"
      },
      "phone": "14158885080",
      "principal_percentage_ownership": 50,
      "tax_id": "123456789",
      "title": "CEO",
      "url": "https://www.video-editing-services.com"
    },
    "identity_roles": [
      "SELLER"
    ],
    "tags": {
      "Studio Rating": "4.7"
    },
    "type": "BUSINESS"
  }'
Copy
Copied
curl -i -X POST \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/associated_identities \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "entity": {
      "first_name": "John",
      "last_name": "Smith",
      "title": "Founder",
      "dob": {
        "month": 1,
        "day": 1,
        "year": 2013
      },
      "principal_percentage_ownership": 25,
      "phone": "14158885080",
      "personal_address": {
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "90650",
        "line1": "123 Main Street",
        "country": "USA"
      },
      "email": "john.smith@company1.com",
      "tax_id": "123456789"
    }
  }'

The response will include the created Identity resource:

USACANAssociated Identity
Copy
Copied
{
    "id": "IDfbYwPeMVE2dVWbGuuZxMyD",
    "created_at": "2024-08-15T21:25:53.55Z",
    "updated_at": "2024-08-15T21:25:53.55Z",
    "additional_underwriting_data": {
        "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
        "credit_check_ip_address": "42.1.1.112",
        "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": "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": 1200000,
        "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": "14158885080",
        "principal_percentage_ownership": 50,
        "short_business_name": null,
        "tax_authority": null,
        "tax_id_provided": true,
        "title": "CEO",
        "url": "https://www.finix.com"
    },
    "identity_roles": [
        "SELLER"
    ],
    "tags": {
        "Studio Rating": "4.7"
    },
    "type": "BUSINESS",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}
Copy
Copied
{
    "id": "IDpNvpkgXiBMArDrGWJ3JRG9",
    "created_at": "2024-08-15T21:26:54.36Z",
    "updated_at": "2024-08-15T21:26:54.36Z",
    "additional_underwriting_data": {
        "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
        "credit_check_ip_address": "42.1.1.112",
        "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": "Business offering video editing services.",
        "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": "456 Elm Avenue",
            "line2": null,
            "city": "Vancouver",
            "region": "BC",
            "postal_code": "V6B 2L2",
            "country": "CAN"
        },
        "business_name": "Video Editing Services",
        "business_phone": "+1 (416) 555-7890",
        "business_tax_id_provided": true,
        "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
        "default_statement_descriptor": "Video Services",
        "discover_mid": null,
        "dob": {
            "day": 27,
            "month": 6,
            "year": 1978
        },
        "doing_business_as": "Video Editing Services",
        "email": "info@video-editing-services.com",
        "first_name": "Jerry",
        "has_accepted_credit_cards_previously": true,
        "incorporation_date": {
            "day": 27,
            "month": 6,
            "year": 1978
        },
        "last_name": "Dunhill",
        "max_transaction_amount": 1200000,
        "mcc": "4900",
        "ownership_type": "PRIVATE",
        "personal_address": {
            "line1": "987 Milo Street",
            "line2": null,
            "city": "Vancouver",
            "region": "BC",
            "postal_code": "V5K 1Z5",
            "country": "CAN"
        },
        "phone": "14158885080",
        "principal_percentage_ownership": 50,
        "short_business_name": null,
        "tax_authority": null,
        "tax_id_provided": true,
        "title": "CEO",
        "url": "https://www.video-editing-services.com"
    },
    "identity_roles": [
        "SELLER"
    ],
    "tags": {
        "Studio Rating": "4.7"
    },
    "type": "BUSINESS",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}
Copy
Copied
{
    "id": "IDmqEnFc9DQDAEraGkAZr9Ss",
    "created_at": "2024-08-15T21:33:07.73Z",
    "updated_at": "2024-08-15T21:33:07.73Z",
    "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": {
            "day": 1,
            "month": 1,
            "year": 2013
        },
        "doing_business_as": null,
        "email": "john.smith@company1.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": "123 Main Street",
            "line2": null,
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "90650",
            "country": "USA"
        },
        "phone": "14158885080",
        "principal_percentage_ownership": 25,
        "short_business_name": null,
        "tax_authority": null,
        "tax_id_provided": true,
        "title": "Founder",
        "url": null
    },
    "identity_roles": [
        "BENEFICIAL_OWNER"
    ],
    "tags": {},
    "type": "PERSONAL",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDmqEnFc9DQDAEraGkAZr9Ss/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}

Step 3: Add a Bank Account

Next, you're ready to link your seller's bank account to their Identity with the Payment Instruments API. This is the bank account to which your seller will receive payouts, and is reviewed during Finix's seller underwriting process. Note that step is required for the next step's request (creating your seller's Merchant) to succeed.

You can create the Payment Instrument with your seller's bank account information directly. Alternatively, you can create the Payment Instrument using a Plaid Processor Token (see our Plaid guide for additional context).

USACANPlaid
Copy
Copied
curl -X POST \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  https://finix.sandbox-payments-api.com/payment_instruments \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "account_number": "0000000019",
    "account_type": "BUSINESS_CHECKING",
    "bank_code": "122105278",
    "identity": "IDfbYwPeMVE2dVWbGuuZxMyD",
    "name": "Smith & Associates Consulting",
    "type": "BANK_ACCOUNT"
  }'
Copy
Copied
curl -X POST \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  https://finix.sandbox-payments-api.com/payment_instruments \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "account_number": "123123123",
    "account_type": "PERSONAL_CHECKING",
    "country": "CAN",
    "currency": "CAD",
    "identity": "IDpNvpkgXiBMArDrGWJ3JRG9",
    "institution_number": "123",
    "name": "John Smith",
    "transit_number": "12345",
    "type": "BANK_ACCOUNT"
  }'
Copy
Copied
curl -X POST \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  https://finix.sandbox-payments-api.com/payment_instruments \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "third_party": "PLAID",
    "third_party_token": "processor-sandbox-4855f0a2-c6f4-440c-9e6b-1d0ad9ca0010",
    "type": "BANK_ACCOUNT",
    "identity": "IDfbYwPeMVE2dVWbGuuZxMyD"
  }'

The response will include the created Payment Instrument resource:

USACANPlaid
Copy
Copied
{
    "id": "PI3dGTEWFHC8XHZrqpHBHpHc",
    "created_at": "2024-08-16T12:23:02.94Z",
    "updated_at": "2024-08-16T12:23:02.94Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "USD",
    "disabled_code": null,
    "disabled_message": null,
    "enabled": true,
    "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR",
    "identity": "IDfbYwPeMVE2dVWbGuuZxMyD",
    "instrument_type": "BANK_ACCOUNT",
    "account_type": "BUSINESS_CHECKING",
    "bank_account_validation_check": "NOT_ATTEMPTED",
    "bank_code": "122105278",
    "country": "USA",
    "institution_number": null,
    "masked_account_number": "XXXXXX0019",
    "name": "Smith & Associates Consulting",
    "transit_number": null,
    "tags": {},
    "third_party": null,
    "third_party_token": null,
    "type": "BANK_ACCOUNT",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI3dGTEWFHC8XHZrqpHBHpHc"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI3dGTEWFHC8XHZrqpHBHpHc/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI3dGTEWFHC8XHZrqpHBHpHc/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI3dGTEWFHC8XHZrqpHBHpHc/verifications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD"
        }
    }
}
Copy
Copied
{
    "id": "PIwTCBS1DaTQZA93VSnSRFUL",
    "created_at": "2024-08-16T12:24:50.07Z",
    "updated_at": "2024-08-16T12:24:50.07Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "CAD",
    "disabled_code": null,
    "disabled_message": null,
    "enabled": true,
    "fingerprint": "FPR8RAHfXm1BMYYVJyHWHhw4J",
    "identity": "IDpNvpkgXiBMArDrGWJ3JRG9",
    "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/PIwTCBS1DaTQZA93VSnSRFUL"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwTCBS1DaTQZA93VSnSRFUL/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwTCBS1DaTQZA93VSnSRFUL/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIwTCBS1DaTQZA93VSnSRFUL/verifications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9"
        }
    }
}
Copy
Copied
{
    "id": "PIjLyHgshDaZQeXpkThTFFiD",
    "created_at": "2024-08-16T11:56:02.96Z",
    "updated_at": "2024-08-16T11:56:02.96Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "USD",
    "disabled_code": null,
    "disabled_message": null,
    "enabled": true,
    "fingerprint": "FPRxAutj19xH1AH6ykGx2dwa7",
    "identity": "IDpYDM7J9n57q849o9E9yNrG",
    "instrument_type": "BANK_ACCOUNT",
    "account_type": "BUSINESS_CHECKING",
    "bank_account_validation_check": "VALID",
    "bank_code": "011401533",
    "country": "USA",
    "institution_number": null,
    "masked_account_number": "XXXXXXXXXXX0000",
    "name": "Alberta Bobbeth Charleson",
    "transit_number": null,
    "tags": {},
    "third_party": "PLAID",
    "third_party_token": "processor-sandbox-4855f0a2-c6f4-440c-9e6b-1d0ad9ca0010",
    "type": "BANK_ACCOUNT",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIjLyHgshDaZQeXpkThTFFiD"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIjLyHgshDaZQeXpkThTFFiD/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIjLyHgshDaZQeXpkThTFFiD/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIjLyHgshDaZQeXpkThTFFiD/verifications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG"
        }
    }
}

Step 4: Create a Merchant

With your seller's Identity and Payment Instrument created, you are ready to create your seller's Merchant. This step creates the Merchant account that your seller will use to process payments once approved. When you create the Merchant account, Finix automatically creates a Verification on the Merchant, which puts the Merchant into Finix's underwriting process. Each Merchant can use one payments processor; should your seller need multiple processors, you may create one Merchant per processor.

USACAN
Copy
Copied
curl -X POST \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD/merchants \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "processor": "DUMMY_V1"
  }'
Copy
Copied
curl -X POST \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9/merchants \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "processor": "DUMMY_V1"
  }'

The response creates your seller's Merchant, which originates in the PROVISIONING state.

USACAN
Copy
Copied
{
    "id": "MUa2uYEkaRBzP8EEDeKweE5h",
    "created_at": "2024-08-16T12:23:30.79Z",
    "updated_at": "2024-08-16T12:23:30.79Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "card_cvv_required": false,
    "card_expiration_date_required": true,
    "card_network_details": null,
    "convenience_charges_enabled": false,
    "country": "USA",
    "creating_transfer_from_report_enabled": true,
    "currencies": [
        "USD"
    ],
    "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,
    "disbursements_same_day_ach_pull_enabled": false,
    "disbursements_same_day_ach_push_enabled": false,
    "fee_ready_to_settle_upon": "RECONCILIATION",
    "gateway": null,
    "gross_settlement_enabled": false,
    "identity": "IDfbYwPeMVE2dVWbGuuZxMyD",
    "level_two_level_three_data_enabled": false,
    "loan_repayment": null,
    "mcc": "4900",
    "merchant_name": "Finix Flowers",
    "merchant_profile": "MP7vh4DGaBW9eCKq1kFiJaP4",
    "mid": null,
    "onboarding_state": "PROVISIONING",
    "processing_enabled": false,
    "processor": "DUMMY_V1",
    "processor_details": {},
    "ready_to_settle_upon": "RECONCILIATION",
    "ready_to_settle_upon_delay_alignment": "NONE",
    "rent_surcharges_enabled": false,
    "settlement_enabled": false,
    "settlement_funding_identifier": "UNSET",
    "surcharges_enabled": false,
    "tags": {},
    "verification": "VIrnen8yHQZTQnc4EYA8NL8W",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUa2uYEkaRBzP8EEDeKweE5h"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDfbYwPeMVE2dVWbGuuZxMyD"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUa2uYEkaRBzP8EEDeKweE5h/verifications"
        },
        "merchant_profile": {
            "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MP7vh4DGaBW9eCKq1kFiJaP4"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "verification": {
            "href": "https://finix.sandbox-payments-api.com/verifications/VIrnen8yHQZTQnc4EYA8NL8W"
        }
    }
}
Copy
Copied
{
    "id": "MUu6un1HH6ghMtwak9FbaJX",
    "created_at": "2024-08-16T12:25:45.46Z",
    "updated_at": "2024-08-16T12:25:45.46Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "card_cvv_required": false,
    "card_expiration_date_required": true,
    "card_network_details": null,
    "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,
    "disbursements_same_day_ach_pull_enabled": false,
    "disbursements_same_day_ach_push_enabled": false,
    "fee_ready_to_settle_upon": "RECONCILIATION",
    "gateway": null,
    "gross_settlement_enabled": false,
    "identity": "IDpNvpkgXiBMArDrGWJ3JRG9",
    "level_two_level_three_data_enabled": false,
    "loan_repayment": null,
    "mcc": "4900",
    "merchant_name": "Video Editing Services",
    "merchant_profile": "MPjso886FW3AHS7qC7yZ5UfE",
    "mid": null,
    "onboarding_state": "PROVISIONING",
    "processing_enabled": false,
    "processor": "DUMMY_V1",
    "processor_details": {},
    "ready_to_settle_upon": "RECONCILIATION",
    "ready_to_settle_upon_delay_alignment": "NONE",
    "rent_surcharges_enabled": false,
    "settlement_enabled": false,
    "settlement_funding_identifier": "UNSET",
    "surcharges_enabled": false,
    "tags": {},
    "verification": "VItdfqW6Hyu9n5ak2eWr2SUS",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUu6un1HH6ghMtwak9FbaJX"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDpNvpkgXiBMArDrGWJ3JRG9"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUu6un1HH6ghMtwak9FbaJX/verifications"
        },
        "merchant_profile": {
            "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPjso886FW3AHS7qC7yZ5UfE"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "verification": {
            "href": "https://finix.sandbox-payments-api.com/verifications/VItdfqW6Hyu9n5ak2eWr2SUS"
        }
    }
}

Step 5: Review Process

Your seller will be ready to process payments once their Merchant account is APPROVED. Finix will update the Merchant's onboarding_state after the review process, which often takes just minutes but can take longer if manual intervention is required.

Receiving Webhooks

Finix sends webhooks to update you about your seller's progress throughout the onboarding process. For example, you can listen to the Merchant Updated and Merchant Underwritten events to know when your Merchant transitions from PROVISIONING to another state.

To learn more about webhooks, see Notifications and Webhooks.

Handling Update Requests

Should Finix require additional information to board your seller, we will move their Merchant to an UPDATE_REQUESTED state and explain what additional information is required. Finix provides codes for each information request type, making it easy to build your own experience to manage update requests.

To learn more about handling update requests, see Handling Update Requests.

Next Steps

Next, learn how to handle update requests and listen to webhooks to move your sellers through onboarding.