Deprecated API Reference

This API Reference is being deprecated. Please use the New API Reference.

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:

First, create an Identity resource with the merchant's underwriting and identity verification information
POST https://finix.sandbox-payments-api.com/identities/
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/
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" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -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.113",
	        "credit_check_timestamp": "2021-04-28T16:42:55Z",
	        "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
	        "merchant_agreement_accepted": true,
	        "merchant_agreement_ip_address": "42.1.1.113",
	        "merchant_agreement_timestamp": "2021-04-28T16:42:55Z",
	        "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
	        "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
	        "volume_distribution_by_business_type": {
	            "other_volume_percentage": 0,
	            "consumer_to_consumer_volume_percentage": 0,
	            "business_to_consumer_volume_percentage": 0,
	            "business_to_business_volume_percentage": 100,
	            "person_to_person_volume_percentage": 0
	        }
	    },
	    "entity": {
	        "annual_card_volume": 12000000,
	        "business_address": {
	            "city": "San Mateo",
	            "country": "USA",
	            "region": "CA",
	            "line2": "Apartment 8",
	            "line1": "741 Douglass St",
	            "postal_code": "94114"
	        },
	        "business_name": "Finix Flowers",
	        "business_phone": "+1 (408) 756-4497",
	        "business_tax_id": "123456789",
	        "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
	        "default_statement_descriptor": "Finix Flowers",
	        "dob": {
	            "year": 1978,
	            "day": 27,
	            "month": 6
	        },
	        "doing_business_as": "Finix Flowers",
	        "email": "user@example.org",
	        "first_name": "John",
	        "has_accepted_credit_cards_previously": true,
	        "incorporation_date": {
	            "year": 1978,
	            "day": 27,
	            "month": 6
	        },
            "last_name": "Smith",
	        "max_transaction_amount": 12000000,
	        "mcc": "0742",
	        "ownership_type": "PRIVATE",
	        "personal_address": {
	            "city": "San Mateo",
	            "country": "USA",
	            "region": "CA",
	            "line2": "Apartment 7",
	            "line1": "741 Douglass St",
	            "postal_code": "94114"
	        },
	        "phone": "1234567890",
	        "principal_percentage_ownership": 50,
	        "tax_id": "123456789",
	        "title": "CEO",
	        "url": "www.Finix.com"
	    },
	    "tags": {
	        "Studio Rating": "4.7"
	    }
	}'

Example Response:

Copy

Copied

{
  "id" : "MUht1bsAEcihT9HA55Tet5dk",
  "created_at" : "2022-10-07T22:21:13.07Z",
  "updated_at" : "2022-10-07T22:21:13.07Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "card_cvv_required" : false,
  "card_expiration_date_required" : true,
  "convenience_charges_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "default_partial_authorization_enabled" : false,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "gross_settlement_enabled" : false,
  "identity" : "IDoZy2xjNQyWCkN5nKZbVp6x",
  "level_two_level_three_data_enabled" : false,
  "mcc" : "0742",
  "merchant_name" : "Finix Flowers",
  "merchant_profile" : "MPh4vD8hWCtqHeJ8JgG4Tsva",
  "mid" : null,
  "onboarding_state" : "PROVISIONING",
  "processing_enabled" : false,
  "processor" : "DUMMY_V1",
  "processor_details" : { },
  "ready_to_settle_upon" : "RECONCILIATION",
  "rent_surcharges_enabled" : false,
  "settlement_enabled" : false,
  "settlement_funding_identifier" : "UNSET",
  "tags" : {
    "key_2" : "value_2"
  },
  "verification" : "VIr27e4C5AWxgvLnyGJmdZQe",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUht1bsAEcihT9HA55Tet5dk"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDoZy2xjNQyWCkN5nKZbVp6x"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUht1bsAEcihT9HA55Tet5dk/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPh4vD8hWCtqHeJ8JgG4Tsva"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIr27e4C5AWxgvLnyGJmdZQe"
    }
  }
}

HTTP Request

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

Business-specific Request Arguments

Field	Type	Description
`amex_mid`	integer, optional	Assigned amexMid value. If provided must be 10 or 11 digits
`business_address`	object, required	Primary address for the legal entity (Full description of child attributes below)
`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)
`business_phone`	string, required	Customer service phone number where the merchant can be reached (max 10 characters)
`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).
`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.
`discover_mid`	integer, optional	Assigned discoverMid value
`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)
`incorporation_date`	object, required	Date company was founded (See below for a full list of the child attributes)
`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.
`url`	string, required	Merchant's publicly available website (max 100 characters)

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
`dob`	object, required	Control person's date of birth (Full description of child attributes below)
`email`	string, required	Control person's email address where they can be reached (max 100 characters)
`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)
`personal_address`	object, required	Control person's personal home address. This field is used for identity verification purposes (Full description of child attributes below)
`phone`	string, required	Control person's phone number (max 10 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
`title`	string, required	Control person's corporate title or role (i.e. Chief Executive Officer, CFO, etc.; max 60 characters)

Processing-specific Request Arguments

Field	Type	Description
`annual_card_volume`	integer, required	Approximate annual credit card sales expected to be processed in cents by this merchant (max 19 characters)
`default_statement_descriptor`	string, required	Billing descriptor displayed on the buyer's bank or card statement (Length must be between 1 and 20 characters)
`has_accepted_credit_cards_previously`	boolean, optional	Defaults to false if not passed
`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

Address-object Request Arguments

Field	Type	Description
`city`	string, required	City (max 20 characters)
`country`	string, required	3-Letter Country code
`line1`	string, required	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, required	2-letter State 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)
`other_volume_percentage`	integer, required	Merchant's percentage of volume that is not represented by the previous fields (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)