Getting Started

Step 1: Create an Identity for a Merchant

Before we can begin charging cards we'll need to provision a Merchant account for your seller. This requires 3-steps, which we'll go into greater detail in the next few sections:

  1. First, create an Identity resource with the merchant's underwriting and identity verification information

    POST https://finix.sandbox-payments-api.com/identities/

  2. Second, create a Payment Instrument representing the merchant's bank account where processed funds will be settled (i.e. deposited)

    POST https://finix.sandbox-payments-api.com/payment_instruments/

  3. Finally, provision the Merchant account

    POST https://finix.sandbox-payments-api.com/identities/:IDENTITY_ID/merchants

Let's start with the first step by creating an Identity resource. Each Identity represents either a person or a business. We use this resource to associate cards and payouts. This structure makes it simple to manage and reconcile payment instruments and payout history. Accounting of funds is done using the Identity so it's recommended to have an Identity per recipient of funds. Additionally, the Identity resource is optionally used to collect KYC information.

You'll want to store the ID of the newly created Identity resource for reference later.

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "additional_underwriting_data": {
	        "merchant_agreement_accepted": true,
	        "merchant_agreement_ip_address": "42.1.1.113",
	        "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
	        },
	        "average_ach_transfer_amount": 200000,
	        "annual_ach_volume": 200000,
	        "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
	        "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
	        "credit_check_timestamp": "2021-04-28T16:42:55Z",
	        "credit_check_allowed": true,
	        "merchant_agreement_timestamp": "2021-04-28T16:42:55Z",
	        "business_description": "SB3 vegan cafe",
	        "average_card_transfer_amount": 200000,
	        "credit_check_ip_address": "42.1.1.113",
	        "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
	        "card_volume_distribution": {
	            "card_present_percentage": 30,
	            "mail_order_telephone_order_percentage": 10,
	            "ecommerce_percentage": 60
	        }
	    },
	    "tags": {
	        "Studio Rating": "4.7"
	    },
	    "entity": {
	        "last_name": "Sunkhronos",
	        "max_transaction_amount": 12000000,
	        "has_accepted_credit_cards_previously": true,
	        "default_statement_descriptor": "Petes Coffee",
	        "personal_address": {
	            "city": "San Mateo",
	            "country": "USA",
	            "region": "CA",
	            "line2": "Apartment 7",
	            "line1": "741 Douglass St",
	            "postal_code": "94114"
	        },
	        "incorporation_date": {
	            "year": 1978,
	            "day": 27,
	            "month": 6
	        },
	        "business_address": {
	            "city": "San Mateo",
	            "country": "USA",
	            "region": "CA",
	            "line2": "Apartment 8",
	            "line1": "741 Douglass St",
	            "postal_code": "94114"
	        },
	        "ownership_type": "PRIVATE",
	        "first_name": "dwayne",
	        "title": "CEO",
	        "business_tax_id": "123456789",
	        "doing_business_as": "Petes Coffee",
	        "principal_percentage_ownership": 50,
	        "email": "user@example.org",
	        "mcc": "0742",
	        "phone": "1234567890",
	        "business_name": "Petes Coffee",
	        "tax_id": "123456789",
	        "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
	        "business_phone": "+1 (408) 756-4497",
	        "dob": {
	            "year": 1978,
	            "day": 27,
	            "month": 6
	        },
	        "url": "www.PetesCoffee.com",
	        "annual_card_volume": 12000000
	    }
	}'

Example Response:

Copy
Copied
{
  "id" : "IDpYDM7J9n57q849o9E9yNrG",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "entity" : {
    "title" : "CEO",
    "first_name" : "dwayne",
    "last_name" : "Sunkhronos",
    "email" : "user@example.org",
    "business_name" : "Petes Coffee",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Petes Coffee",
    "phone" : "1234567890",
    "business_phone" : "+1 (408) 756-4497",
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 8",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "mcc" : "0742",
    "dob" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "max_transaction_amount" : 12000000,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : "www.PetesCoffee.com",
    "annual_card_volume" : 12000000,
    "has_accepted_credit_cards_previously" : true,
    "incorporation_date" : {
      "day" : 27,
      "month" : 6,
      "year" : 1978
    },
    "principal_percentage_ownership" : 50,
    "short_business_name" : null,
    "ownership_type" : "PRIVATE",
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : true,
    "default_statement_descriptor" : "Petes Coffee"
  },
  "tags" : {
    "Studio Rating" : "4.7"
  },
  "created_at" : "2022-01-27T07:36:52.11Z",
  "updated_at" : "2022-01-27T07:36:52.11Z",
  "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
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/identities

Business-specific Request Arguments

Field Type Description
business_name string, required Merchant's full legal business name (If INDIVIDUAL_SOLE_PROPRIETORSHIP, please input first name, Full legal last name and middle initial; max 120 characters)
doing_business_as string, required Alternate name of the business. If no other name is used please use the same value for business_name (max 60 characters)
business_type string, required Please select one of the following values: INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, PARTNERSHIP, ASSOCIATION_ESTATE_TRUST, TAX_EXEMPT_ORGANIZATION, INTERNATIONAL_ORGANIZATION, GOVERNMENT_AGENCY
business_tax_id string, required Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN). If the business_type is INDIVIDUAL_SOLE_PROPRIETORSHIP and they do not have an EIN, use the sole proprietor's Social Security Number (SSN).
url string, required Merchant's publicly available website (max 100 characters)
business_phone string, required Customer service phone number where the merchant can be reached (max 10 characters)
incorporation_date object, required Date company was founded (See below for a full list of the child attributes)
business_address object, required Primary address for the legal entity (Full description of child attributes below)
ownership_type string, required Values can be either PUBLIC to indicate a publicly traded company or PRIVATE for privately held businesses
amex_mid integer, optional Assigned amexMid value. If provided must be 10 or 11 digits
discover_mid integer, optional Assigned discoverMid value

Control Person specific Request Arguments

The control person is the authorized representative or primary contact responsible for the account.

Field Type Description
first_name string, required Full legal first name of the merchant's control person (max 20 characters)
last_name string, required Full legal last name of the merchant's control person (max 20 characters)
title string, required Control person's corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters)
principal_percentage_ownership integer, required Percentage of company owned by the control person (must be greater than 0; max 100)
tax_id string, required Nine digit Social Security Number (SSN) for the control person.
dob object, required Control person's date of birth (Full description of child attributes below)
phone string, required Control person's phone number (max 10 characters)
email string, required Control person's email address where they can be reached (max 100 characters)
personal_address object, required Control person's personal home address. This field is used for identity verification purposes (Full description of child attributes below)

Processing-specific Request Arguments

Field Type Description
default_statement_descriptor string, required Billing descriptor displayed on the buyer's bank or card statement (Length must be between 1 and 20 characters)
annual_card_volume integer, required Approximate annual credit card sales expected to be processed in cents by this merchant (max 19 characters)
max_transaction_amount integer, required Maximum amount that can be transacted for a single transaction in cents (max 12 characters)
mcc string, required Merchant Category Code (MCC) that this merchant will be classified under
has_accepted_credit_cards_previously boolean, optional Defaults to false if not passed

Address-object Request Arguments

Field Type Description
line1 string, optional First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
city string, optional City (max 20 characters)
region string, optional 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, optional 3-Letter Country code

Incorporation Date-object Request Arguments

Field Type Description
day integer, required Day business was incorporated (between 1 and 31)
month integer, required Month business was incorporated (between 1 and 12)
year integer, required Year business was incorporated (4-digit)

DOB-object Request Arguments

Field Type Description
day integer, required Day of birth (between 1 and 31)
month integer, required Month of birth (between 1 and 12)
year integer, required Year of birth (4-digit)
attention

The Additional Underwriting Data object is required for Finix Flex customers only. If you have additional questions, contact Support.

Additional Underwriting Request Arguments

Field Type Description
annual_ach_volume integer, required Approximate annual ACH sales expected to be processed in cents by this merchant (max 10 characters)
average_ach_transfer_amount integer, required Approximate average ACH sale amount in cents for this merchant (max 10 characters)
average_card_transfer_amount integer, required Approximate average credit card sale amount in cents for this merchant (max 10 characters)
business_description string, required Description of this merchant's business (max 200 characters)
card_volume_distribution object, required Merchant's distribution of credit card volume (See below for a full list of the child attributes). Sum of card_volume_distribution must be 100.
credit_check_allowed boolean, optional Sets whether this merchant has consented and accepted to a credit check
credit_check_ip_address string, optional IP address of the merchant when this merchant consented to a credit check (e.g., 42.1.1.113 )
credit_check_timestamp string, optional Timestamp of when this merchant consented to a credit check (e.g., 2021-04-28T16:42:55Z)
credit_check_user_agent string, optional The user agent of the browser when this merchant consented to a credit check (e.g., Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6))
merchant_agreement_accepted boolean, required Sets whether this merchant has accepted the terms and conditions of the merchant agreement
merchant_agreement_ip_address string, required IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113 )
merchant_agreement_timestamp string, required Timestamp of when this merchant agreed to Finix's terms of service (e.g., 2021-04-28T16:42:55Z)
merchant_agreement_user_agent string, required The user agent of the browser when this merchant accepted the merchant agreement (e.g., Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6))
refund_policy string, required Please select one of the following values: NO_REFUNDS, MERCHANDISE_EXCHANGE_ONLY, WITHIN_30_DAYS, OTHER
volume_distribution_by_business_type object, required Merchant's distribution of credit card volume by business type (See below for a full list of the child attributes). Sum of volume_distribution_by_business_type must be 100.

Card Volume Distribution-object Request Arguments

Field Type Description
card_present_percentage integer, required Merchant's percentage of business that is card present (between 0 and 100)
ecommerce_present_percentage integer, required Merchant's percentage of business that is ecommerce (between 0 and 100)
mail_order_telephone_order_percentage integer, required Merchant's percentage of business that is mail order or telephone order (between 0 and 100)

Volume Distribution by Business Type-object Request Arguments

Field Type Description
business_to_business_volume_percentage integer, required Merchant's percentage of volume that is business to business (between 0 and 100)
business_to_consumer_volume_percentage integer, required Merchant's percentage of volume that is business to consumer (between 0 and 100)
consumer_to_consumer_volume_percentage integer, required Merchant's percentage of volume that is consumer to consumer (between 0 and 100)
person_to_person_volume_percentage integer, required Merchant's percentage of volume that is person to person (between 0 and 100)
other_volume_percentage integer, required Merchant's percentage of volume that is not represented by the previous fields (between 0 and 100)

Step 1.5: Add Additional Benefical Owners for a Merchant

If you have beneficial owners with at least 25% ownership, each beneficial owners must be addded along with the primary prinicipal in step 1. This is a requirement from our financial partners and regulators.

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/associated_identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "entity": {
	        "first_name": "John",
	        "last_name": "Smith",
	        "title": "Founder",
	        "dob": {
	            "month": 1,
	            "day": 1,
	            "year": 2013
	        },
	        "principal_percentage_ownership": 25,
	        "phone": "1234567890",
	        "personal_address": {
	            "city": "San Francisco",
	            "region": "CA",
	            "postal_code": "90650",
	            "line1": "123 Main Street",
	            "country": "USA"
	        },
	        "email": "john.smith@company1.com",
	        "tax_id": "123456789"
	    }
	}'

Example Response:

Copy
Copied
{
  "id" : "IDqXfTAYjLL4Lyce4Xq33g9k",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "entity" : {
    "title" : "Founder",
    "first_name" : "John",
    "last_name" : "Smith",
    "email" : "john.smith@company1.com",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "1234567890",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "123 Main Street",
      "line2" : null,
      "city" : "San Francisco",
      "region" : "CA",
      "postal_code" : "90650",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : {
      "day" : 1,
      "month" : 1,
      "year" : 2013
    },
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : 25,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : { },
  "created_at" : "2022-01-27T07:37:01.87Z",
  "updated_at" : "2022-01-27T07:37:01.93Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDqXfTAYjLL4Lyce4Xq33g9k"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDqXfTAYjLL4Lyce4Xq33g9k/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDqXfTAYjLL4Lyce4Xq33g9k/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDqXfTAYjLL4Lyce4Xq33g9k/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDqXfTAYjLL4Lyce4Xq33g9k/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDqXfTAYjLL4Lyce4Xq33g9k/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDqXfTAYjLL4Lyce4Xq33g9k/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDqXfTAYjLL4Lyce4Xq33g9k/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDqXfTAYjLL4Lyce4Xq33g9k/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/identities/:IDENTITY_ID/associated_identities

Principal-specific Request Arguments

(i.e. authorized representative or primary contact responsible for the account)

Field Type Description
dob object, required Principal's date of birth (Full description of child attributes below)
email string, required Principal's email address where they can be reached (max 100 characters)
first_name string, required Full legal first name of the merchant's principal representative (max 20 characters)
last_name string, required Full legal last name of the merchant's principal representative (max 20 characters)
personal_address object, required Principal's personal home address. This field is used for Identity verification purposes (Full description of child attributes below)
phone string, required Principal's phone number (max 10 characters)
principal_percentage_ownership integer, required Percentage of company owned by the principal (must be greater than 0; max 100)
tax_id string, required Nine digit Social Security Number (SSN) for the principal
title string, required Principal's corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters)

Address-object Request Arguments

Field Type Description
city string, optional City (max 20 characters)
country string, optional 3-Letter Country code
line1 string, optional First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
postal_code string, required Zip or Postal code (max 7 characters)
region string, optional 2-letter State code

DOB-object Request Arguments

Field Type Description
day integer, required Day of birth (between 1 and 31)
month integer, required Month of birth (between 1 and 12)
year integer, required Year of birth (4-digit)

Step 2: Tokenize a Bank Account for Funding your Merchant

Now that we've created an Identity for our merchant, we'll need to add a bank account where funds will be disbursed (i.e. their funding account).

In the API, bank accounts -- as well as credit cards -- are represented by the Payment Instrument resource.

To classify the Payment Instrument as a bank account you'll need to pass BANK_ACCOUNT in the type field of your request, and you'll also want to pass the ID of the Identity that you created in the last step via the identity field to properly associate it with your merchant.

Copy
Copied
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "account_type": "SAVINGS",
	    "name": "Alice",
	    "tags": {
	        "Bank Account": "Company Account"
	    },
	    "country": "USA",
	    "bank_code": "123123123",
	    "account_number": "123123123",
	    "type": "BANK_ACCOUNT",
	    "identity": "IDpYDM7J9n57q849o9E9yNrG"
	}'

Example Response:

Copy
Copied
{
  "id" : "PI8sdzepdapDehPWKFTcre1m",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "tags" : {
    "Bank Account" : "Company Account"
  },
  "bank_code" : "123123123",
  "country" : "USA",
  "masked_account_number" : "XXXXX3123",
  "name" : "Alice",
  "account_type" : "SAVINGS",
  "created_at" : "2022-01-27T07:36:57.62Z",
  "updated_at" : "2022-01-27T07:36:57.62Z",
  "instrument_type" : "BANK_ACCOUNT",
  "type" : "BANK_ACCOUNT",
  "currency" : "USD",
  "identity" : "IDpYDM7J9n57q849o9E9yNrG",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI8sdzepdapDehPWKFTcre1m"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI8sdzepdapDehPWKFTcre1m/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI8sdzepdapDehPWKFTcre1m/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI8sdzepdapDehPWKFTcre1m/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/payment_instruments

Request Arguments

Field Type Description
account_number string, required Bank account number
bank_code string, required Bank routing number
type string, required Type of Payment Instrument (for bank accounts use BANK_ACCOUNT)
identity string, required ID for the Identity resource which the account is associated
account_type string, required Either CHECKING or SAVINGS
name string, required Account owner's full name (max 40 characters)

Step 3: Provision Merchant Account

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. Take a second to inspect this newly created resource, particularly the onboarding_state, which can have 3 potential states that indicate its ability to process and settle funds:

  1. PROVISIONING : Request is pending (state will typically change after two minutes)
    • processing _ enabled: False
    • settlement _ enabled: False
  2. APPROVED : Merchant has been approved and can begin processing
    • processing _ enabled: True
    • settlement _ enabled: True
  3. REJECTED : Merchant was rejected by the processor 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)
    • processing _ enabled: False
    • settlement _ enabled: False
attention

Provisioning a Merchant account is an asynchronous request. We recommend creating a Webhook to listen for the state change.

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/merchants \
    -H "Content-Type: application/vnd.json+api" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "processor": "DUMMY_V1",
	    "tags": {
	        "key_2": "value_2"
	    }
	}'

Example Response:

Copy
Copied
{
  "id" : "MUucec6fHeaWo3VHYoSkUySM",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "identity" : "IDpYDM7J9n57q849o9E9yNrG",
  "verification" : "VIdikDHXv7x8nWyJg8JZemGx",
  "merchant_profile" : "MPzW2oRPtkLxK3fymcMACFi",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : true,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : "FNX7CwmebftudY7i5mA4qF6XT",
  "merchant_name" : "Petes Coffee",
  "settlement_funding_identifier" : "UNSET",
  "ready_to_settle_upon" : "RECONCILIATION",
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "level_two_level_three_data_enabled" : false,
  "created_at" : "2022-01-27T07:36:58.19Z",
  "updated_at" : "2022-01-27T07:36:58.46Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "mid" : "FNX7CwmebftudY7i5mA4qF6XT",
    "api_key" : "secretValue"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUucec6fHeaWo3VHYoSkUySM"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUucec6fHeaWo3VHYoSkUySM/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPzW2oRPtkLxK3fymcMACFi"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIdikDHXv7x8nWyJg8JZemGx"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/identities/:IDENTITY_ID/merchants

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

Request Arguments

Field Type Description
processor string, required Name of the processor that you're onboarding the Merchant with (a user can pass either null or DUMMY_V1 for sandbox)
level_two_level_three_data_enabled boolean, optional Set to True to enable Merchant for Level 2 and Level 3 processing. Default value is false.

Step 4: Create an Identity for a Buyer

Now that we have successfully provisioned a Merchant we'll need to create an Identity that represents your buyer. Don't worry though you won't need to capture the same amount of information from your buyer. So long as you don't pass a business_type field all the fields are optional.

warning

Passing a business_type will introduce the underwriting form validators.

Typically, we suggest at least collecting the buyer's name, address, and email to help with accounting, reconciliation, and chargebacks.

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "tags": {
	        "key": "value"
	    },
	    "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"
	        }
	    }
	}'

Example Response:

Copy
Copied
{
  "id" : "IDgWxBhfGYLLdkhxx2ddYf9K",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "entity" : {
    "title" : null,
    "first_name" : "Collen",
    "last_name" : "Wade",
    "email" : "therock@gmail.com",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "7145677613",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : null,
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_authority" : null,
    "tax_id_provided" : false,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : {
    "key" : "value"
  },
  "created_at" : "2022-01-27T07:36:59.91Z",
  "updated_at" : "2022-01-27T07:36:59.91Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/identities

Request Arguments

Field Type Description
first_name string, optional First name
last_name string, optional Last name
email string, optional Email
phone string, optional Phone number
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)
personal_address object, optional Customers shipping address or billing address (Full description of child attributes below)

Address-object Request Arguments

Field Type Description
line1 string, optional First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
city string, optional City (max 20 characters)
region string, optional 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, optional 3-Letter Country code

Step 5: Tokenize a Card

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

warning

Please note that creating cards directly via the API should only be done for testing purposes. You must use the Tokenization hosted fields or javascript client to remain out of PCI scope.

You'll also need to interpolate your own buyer's Identity ID from the previous request to properly associate it.

Please review our guide on how to tokenize cards via the embedded tokenization form

attention

Including an address when tokenizing a card can lower interchange on credit card transactions.

Copy
Copied
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "name": "Amy White",
	    "expiration_year": 2029,
	    "tags": {
	        "card_name": "Business Card"
	    },
	    "number": "4895142232120006",
	    "expiration_month": 12,
	    "address": {
	        "city": "San Francisco",
	        "region": "CA",
	        "postal_code": "94404",
	        "line1": "900 Metro Center Blv",
	        "country": "USA"
	    },
	    "security_code": "022",
	    "type": "PAYMENT_CARD",
	    "identity": "IDgWxBhfGYLLdkhxx2ddYf9K"
	}'

Example Response:

Copy
Copied
{
  "id" : "PIe2YvpcjvoVJ6PzoRPBK137",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 12,
  "expiration_year" : 2029,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Amy White",
  "address" : {
    "line1" : "900 Metro Center Blv",
    "line2" : null,
    "city" : "San Francisco",
    "region" : "CA",
    "postal_code" : "94404",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2022-01-27T07:37:00.53Z",
  "updated_at" : "2022-01-27T07:37:00.53Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDgWxBhfGYLLdkhxx2ddYf9K",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137/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/PIe2YvpcjvoVJ6PzoRPBK137/updates"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/payment_instruments

Request Arguments

Field Type Description
identity string, required ID of the Identity that the card should be associated
type string, required Type of Payment Instrument (for cards input PAYMENT_CARD)
number string, required Credit card account number
security_code string, required The 3-4 digit security code for the card (i.e. CVV code)
expiration_month integer, required Expiration month (e.g. 12 for December)
expiration_year integer, required 4-digit expiration year
name string, optional Full name of the registered card holder
address object, required Billing address (Full description of child attributes below)
Note: Including a postal or zip code when tokenizing a card can lower the interchange on credit card transactions

Address-object Request Arguments

Field Type Description
line1 string, optional First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
city string, optional City (max 20 characters)
region string, optional 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, optional 3-Letter Country code

Step 6: Create Sale

At this point we've created resources representing the merchant, the buyer, and the buyer's card.

Next you'll need to create a Transfer. To generate a Transfer we'll supply the buyer's Payment Instrument ID as the source field and the seller's Merchant ID in the merchant field. Note that the amount field is in cents. These specific Transfers are distinguished by their type which return DEBIT.

Alternatively, a user can create an Authorization and then proceed to capture the Authorization in two API calls. This is useful when you're looking to capture a specific amount on a card at a later date. You can find more information on Authorization's flow.

  • We recommend including a fraud_session_id to detect and block potential fraudulent payments. For more information, see Fraud Detection .
  • Learn how to prevent duplicate transfers by passing an idempotency ID in the payload.
Copy
Copied
curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "merchant": "MUucec6fHeaWo3VHYoSkUySM",
	    "currency": "USD",
	    "amount": 662154,
	    "source": "PI8sdzepdapDehPWKFTcre1m",
	    "tags": {
	        "test": "sale"
	    }
	}'

Example Response:

Copy
Copied
{
  "id" : "TRvypRNBeqM597Zi4DcqJ2Vh",
  "amount" : 662154,
  "tags" : {
    "test" : "sale"
  },
  "state" : "PENDING",
  "trace_id" : "61646f46-f3fb-4fba-baae-a875a8bdce72",
  "currency" : "USD",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "source" : "PI8sdzepdapDehPWKFTcre1m",
  "destination" : null,
  "ready_to_settle_at" : null,
  "externally_funded" : "UNKNOWN",
  "fee" : 0,
  "statement_descriptor" : "FNX*DUNDER MIFFLIN",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "created_at" : "2022-01-27T07:37:09.71Z",
  "updated_at" : "2022-01-27T07:37:10.01Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDpYDM7J9n57q849o9E9yNrG",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRvypRNBeqM597Zi4DcqJ2Vh"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRvypRNBeqM597Zi4DcqJ2Vh/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRvypRNBeqM597Zi4DcqJ2Vh/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRvypRNBeqM597Zi4DcqJ2Vh/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRvypRNBeqM597Zi4DcqJ2Vh/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI8sdzepdapDehPWKFTcre1m"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPbDSnEPtaT8Nttxj9NJk7eC"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/transfers

Request Arguments

Field Type Description
source string, required ID of the Payment Instrument that will be debited
merchant string, required Merchant ID of the merchant whom you're charging on behalf of
amount integer, required The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
fee integer, optional The amount of the Transfer you would like to collect as your fee in cents. Defaults to zero (Must be less than or equal to the amount)
currency string, required 3-letter ISO code designating the currency of the Transfers (e.g. USD)processor
idempotency_id string, optional A randomly generated value that you want associated with the request
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)