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 informationPOST 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
accountPOST 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.
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:
{
"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.
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:
{
"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.
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:
{
"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.
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:
{
"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.
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:
{
"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 | |
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.
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:
{
"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.
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:
{
"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) |