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:

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. 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" \
    -H 'Finix-Version:2022-02-01' \
    -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" \
    -H 'Finix-Version:2022-02-01' \
    -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" \
    -H 'Finix-Version:2022-02-01' \
    -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:

PROVISIONING : Request is pending (state will typically change after two minutes)
- processing _ enabled: False
- settlement _ enabled: False
APPROVED : Merchant has been approved and can begin processing
- processing _ enabled: True
- settlement _ enabled: True
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" \
    -H 'Finix-Version:2022-02-01' \
    -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" \
    -H 'Finix-Version:2022-02-01' \
    -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" \
    -H 'Finix-Version:2022-02-01' \
    -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" \
    -H 'Finix-Version:2022-02-01' \
    -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)