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.

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. For business_type GOVERNMENT_AGENCY and TAX_EXEMPT_ORGANIZATION the ownership_type should be set to PUBLIC. For business_type INDIVIDUAL_SOLE_PROPRIETORSHIP, the ownership_type should be set to PRIVATE.
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

Control person is the authorized representative or primary contact responsible for the account). All representatives with 25% or more ownership of the business must be added as beneficial owners on the Identity as Associated Identities.

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 (min 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, required First line of the address (max 35 characters)
line2 string, optional Second line of the address (max 35 characters)
city string, required City (max 20 characters)
region string, required 2-letter State code
postal_code string, required Zip or Postal code (max 7 characters)
country string, required 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). Year must be greater than 1900.
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, required Sets whether this merchant has consented and accepted to a credit check
credit_check_ip_address string, required IP address of the merchant when this merchant consented to a credit check (e.g., 42.1.1.113 )
credit_check_timestamp string, required Timestamp of when this merchant consented to a credit check. (e.g., 2021-04-28T16:42:55Z)
credit_check_user_agent string, required 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 the 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)