Platform Quickstart
This quickstart provides a guide on how to onboard sellers onto your platform and process payments with Finix.
Create your Finix API Key
Get started by creating a sandbox account with Finix. This sandbox account gives you access to the Finix Dashboard. You can use the Finix Dashboard to review your payment activity and manage how your sellers are configured.To create an API key with the dashboard, log in and click Developer > Create API Key. Make sure you save the username and password that gets returned. You won't be able to access the credentials again after closing the window.
As you use the credentials in your Finix API requests, you'll see that activity show up in the Finix Dashboard.
Supported Countries
Finix supports entiities in the following countries:
- United States
- Canada
Identity
and Merchant
. To process payments in multiple countries, create a Merchant
for each country the entity is registered in.Step 1: Create an Identity for Your Seller
To onboard a seller or service provider, create an Identity
by collecting basic information (e.g. company name, address, etc.) that's necessary to verify the business.
For businesses that have multiple owners who own 25% or more of the business, you'll need to create Associated Identities
for each owner.
In this example, we'll onboard an individual person who is sole proprietorship and does not have additional owners.
curl "https://finix.sandbox-payments-api.com/identities" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
"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": "4900",
"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"
},
"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
}
},
"tags": {
"Studio Rating": "4.7"
}
}'
curl "https://finix.sandbox-payments-api.com/identities" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
"entity": {
"annual_card_volume": 12000000,
"business_address": {
"city": "Toronto",
"country": "CAN",
"region": "Ontario",
"line2": "Suite 1234",
"line1": "123 Main Street",
"postal_code": "M5K 1E6"
},
"business_name": "Finix Flowers",
"business_phone": "+1 (408) 756-4497",
"business_tax_id": "123456789",
"business_type": "CORPORATION",
"default_statement_descriptor": "Finix Flowers",
"dob": {
"year": 1978,
"day": 27,
"month": 6
},
"doing_business_as": "Finix Flowers",
"email": "user@example.org",
"first_name": "Amy",
"has_accepted_credit_cards_previously": true,
"incorporation_date": {
"year": 1978,
"day": 27,
"month": 6
},
"last_name": "Wilson",
"max_transaction_amount": 1000000,
"mcc": "4900",
"ownership_type": "PRIVATE",
"personal_address": {
"city": "Toronto",
"country": "CAN",
"region": "Ontario",
"line2": "Apartment 7",
"line1": "741 Douglass St",
"postal_code": "M5K 1E6"
},
"phone": "1234567890",
"principal_percentage_ownership": 100,
"tax_id": "123456789",
"title": "CEO",
"url": "www.Finix.com"
},
"additional_underwriting_data": {
"amex_marketing_consent": {
"accepted": true,
"ip_address": "42.1.1.112",
"timestamp": "2021-04-28T16:42:55Z",
"user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)"
},
"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
}
},
"tags": {
"Studio Rating": "4.7"
}
}'
Identity
.{
"id" : "IDpU2s47QCAgzWcCbs5xEcUE",
"created_at" : "2022-10-31T05:06:25.75Z",
"updated_at" : "2022-10-31T05:06:25.75Z",
"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
}
},
"application" : "APgPDQrLD52TYvqazjHJJchM",
"entity" : {
"amex_mid" : null,
"annual_card_volume" : 12000000,
"business_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 8",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"business_name" : "Finix Flowers",
"business_phone" : "+1 (408) 756-4497",
"business_tax_id_provided" : true,
"business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
"default_statement_descriptor" : "Finix Flowers",
"discover_mid" : null,
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"doing_business_as" : "Finix Flowers",
"email" : "user@example.org",
"first_name" : "John",
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"last_name" : "Smith",
"max_transaction_amount" : 12000000,
"mcc" : "4900",
"ownership_type" : "PRIVATE",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"phone" : "1234567890",
"principal_percentage_ownership" : 50,
"short_business_name" : null,
"tax_authority" : null,
"tax_id_provided" : true,
"title" : "CEO",
"url" : "www.Finix.com"
},
"tags" : {
"Studio Rating" : "4.7"
},
"_links" : {
"self" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE"
},
"verifications" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/verifications"
},
"merchants" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/merchants"
},
"settlements" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/settlements"
},
"authorizations" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/authorizations"
},
"transfers" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/transfers"
},
"payment_instruments" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/payment_instruments"
},
"associated_identities" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/associated_identities"
},
"disputes" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDpU2s47QCAgzWcCbs5xEcUE/disputes"
},
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
}
}
}
{
"id" : "IDbuyRPdoEBfEsKcuKEPgkqP",
"created_at" : "2024-02-29T18:18:23.10Z",
"updated_at" : "2024-02-29T18:18:23.10Z",
"additional_underwriting_data" : {
"refund_policy" : "MERCHANDISE_EXCHANGE_ONLY",
"amex_marketing_consent" : {
"accepted" : true,
"ip_address" : "42.1.1.112",
"timestamp" : "2021-04-28T16:42:55Z",
"user_agent" : "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)"
},
"credit_check_ip_address" : "42.1.1.113",
"card_volume_distribution" : {
"card_present_percentage" : 30,
"mail_order_telephone_order_percentage" : 10,
"ecommerce_percentage" : 60
},
"average_ach_transfer_amount" : 200000,
"average_card_transfer_amount" : 200000,
"merchant_agreement_accepted" : true,
"merchant_agreement_user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
"merchant_agreement_ip_address" : "42.1.1.113",
"annual_ach_volume" : 200000,
"credit_check_allowed" : true,
"business_description" : "SB3 vegan cafe",
"credit_check_user_agent" : "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
"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
},
"credit_check_timestamp" : "2021-04-28T16:42:55Z",
"merchant_agreement_timestamp" : "2021-04-28T16:42:55Z"
},
"application" : "APgPDQrLD52TYvqazjHJJchM",
"entity" : {
"ach_max_transaction_amount" : 1000000,
"amex_mid" : null,
"annual_card_volume" : 12000000,
"business_address" : {
"line1" : "123 Main Street",
"line2" : "Suite 1234",
"city" : "Toronto",
"region" : "Ontario",
"postal_code" : "M5K 1E6",
"country" : "CAN"
},
"business_name" : "Finix Flowers",
"business_phone" : "+1 (408) 756-4497",
"business_tax_id_provided" : true,
"business_type" : "CORPORATION",
"default_statement_descriptor" : "Finix Flowers",
"discover_mid" : null,
"dob" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"doing_business_as" : "Finix Flowers",
"email" : "user@example.org",
"first_name" : "Amy",
"has_accepted_credit_cards_previously" : true,
"incorporation_date" : {
"day" : 27,
"month" : 6,
"year" : 1978
},
"last_name" : "Wilson",
"max_transaction_amount" : 1000000,
"mcc" : "4900",
"ownership_type" : "PRIVATE",
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "Toronto",
"region" : "Ontario",
"postal_code" : "M5K 1E6",
"country" : "CAN"
},
"phone" : "1234567890",
"principal_percentage_ownership" : 100,
"short_business_name" : null,
"tax_authority" : null,
"tax_id_provided" : true,
"title" : "CEO",
"url" : "www.Finix.com"
},
"identity_roles" : [ "SELLER" ],
"tags" : {
"Studio Rating" : "4.7"
},
"_links" : {
"self" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP"
},
"verifications" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/verifications"
},
"merchants" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/merchants"
},
"settlements" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/settlements"
},
"authorizations" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/authorizations"
},
"transfers" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/transfers"
},
"payment_instruments" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/payment_instruments"
},
"associated_identities" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/associated_identities"
},
"disputes" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/disputes"
},
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
}
}
}
Step 2: Add a Bank Account for Payouts
Second, create aPayment Instrument
representing a seller's bank account where processed payouts will be settled (i.e. deposited). Include the previously created Identity#id
to link the two resources. A
Payment Instrument
resource represents the payment details of a credit card or bank account. Payment details get tokenized multiple times and each tokenization produces a unique Payment Instrument
. A Payment Instrument
is associated with a single Identity
. Once a Payment Instrument
is created, the Identity
it's associated with can't be changed.curl "https://finix.sandbox-payments-api.com/payment_instruments" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
"account_number": "123123123",
"account_type": "SAVINGS",
"bank_code": "123123123",
"country": "USA",
"currency": "USD",
"identity": "IDvHGrfeVmB3i7uL78xjemNk",
"name": "John",
"type": "BANK_ACCOUNT"
}'
curl "https://finix.sandbox-payments-api.com/payment_instruments" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
"account_number": "123123123",
"account_type": "PERSONAL_CHECKING",
"country": "CAN",
"currency": "CAD",
"identity": "IDbuyRPdoEBfEsKcuKEPgkqP",
"institution_number": "123",
"name": "John Smith",
"transit_number": "12345",
"type": "BANK_ACCOUNT"
}'
Payment Instrument
.{
"id" : "PIcsMDFxZrxFXRVfyQCzXNC9",
"created_at" : "2022-10-10T04:42:09.12Z",
"updated_at" : "2022-10-10T04:42:09.12Z",
"application" : "APgPDQrLD52TYvqazjHJJchM",
"created_via" : "API",
"country": "USA",
"currency" : "USD",
"enabled" : true,
"fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
"identity" : "IDvHGrfeVmB3i7uL78xjemNk",
"instrument_type" : "BANK_ACCOUNT",
"account_type" : "SAVINGS",
"bank_account_validation_check" : "NOT_ATTEMPTED",
"bank_code" : "123123123",
"masked_account_number" : "XXXXX3123",
"name" : "John",
"tags" : {},
"type" : "BANK_ACCOUNT",
"_links" : {
"self" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcsMDFxZrxFXRVfyQCzXNC9"
},
"authorizations" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcsMDFxZrxFXRVfyQCzXNC9/authorizations"
},
"transfers" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcsMDFxZrxFXRVfyQCzXNC9/transfers"
},
"verifications" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcsMDFxZrxFXRVfyQCzXNC9/verifications"
},
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
},
"identity" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk"
}
}
}
{
"id" : "PItgCQRQQAeHLTc6QAEZf22m",
"created_at" : "2024-02-29T18:31:34.31Z",
"updated_at" : "2024-02-29T18:31:34.31Z",
"application" : "APgPDQrLD52TYvqazjHJJchM",
"created_via" : "API",
"currency" : "CAD",
"disabled_code" : null,
"disabled_message" : null,
"enabled" : true,
"fingerprint" : "FPR8RAHfXm1BMYYVJyHWHhw4J",
"identity" : "IDbuyRPdoEBfEsKcuKEPgkqP",
"instrument_type" : "BANK_ACCOUNT",
"account_type" : "PERSONAL_CHECKING",
"bank_account_validation_check" : "NOT_ATTEMPTED",
"bank_code" : null,
"country" : "CAN",
"institution_number" : "123",
"masked_account_number" : "XXXXX3123",
"name" : "John Smith",
"transit_number" : "12345",
"tags" : { },
"third_party" : null,
"third_party_token" : null,
"type" : "BANK_ACCOUNT",
"_links" : {
"self" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PItgCQRQQAeHLTc6QAEZf22m"
},
"authorizations" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PItgCQRQQAeHLTc6QAEZf22m/authorizations"
},
"transfers" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PItgCQRQQAeHLTc6QAEZf22m/transfers"
},
"verifications" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PItgCQRQQAeHLTc6QAEZf22m/verifications"
},
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
},
"identity" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP"
}
}
}
Step 3: Verify and Onboard Your Seller
Now that we've associated a Payment Instrument with our seller’sIdentity
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. curl "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP/merchants" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
"processor": "DUMMY_V1"
}'
Merchant
.{
"id" : "MU2ekLKCiV8M5waZ3Ayg7ic6",
"created_at" : "2024-02-29T18:32:11.62Z",
"updated_at" : "2024-02-29T18:32:11.62Z",
"application" : "APgPDQrLD52TYvqazjHJJchM",
"card_cvv_required" : false,
"card_expiration_date_required" : true,
"convenience_charges_enabled" : false,
"country" : "CAN",
"creating_transfer_from_report_enabled" : true,
"currencies" : [ "CAD" ],
"default_partial_authorization_enabled" : false,
"disbursements_ach_pull_enabled" : false,
"disbursements_ach_push_enabled" : false,
"disbursements_card_pull_enabled" : false,
"disbursements_card_push_enabled" : false,
"fee_ready_to_settle_upon" : "RECONCILIATION",
"gateway" : null,
"gross_settlement_enabled" : false,
"identity" : "IDbuyRPdoEBfEsKcuKEPgkqP",
"level_two_level_three_data_enabled" : false,
"mcc" : "4900",
"merchant_name" : "Finix Flowers",
"merchant_profile" : "MPtghSGfMec2LfkCQ2HU4VWu",
"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",
"surcharges_enabled" : false,
"tags" : { },
"verification" : "VInjHQLPa9C9QJEgDMx3gZa9",
"_links" : {
"self" : {
"href" : "https://finix.sandbox-payments-api.com/merchants/MU2ekLKCiV8M5waZ3Ayg7ic6"
},
"identity" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP"
},
"verifications" : {
"href" : "https://finix.sandbox-payments-api.com/merchants/MU2ekLKCiV8M5waZ3Ayg7ic6/verifications"
},
"merchant_profile" : {
"href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPtghSGfMec2LfkCQ2HU4VWu"
},
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
},
"verification" : {
"href" : "https://finix.sandbox-payments-api.com/verifications/VInjHQLPa9C9QJEgDMx3gZa9"
}
}
}
Merchant#onboarding_state
can have 3 potential values that details where the Merchant
is in the onboarding process:Merchant State | Description |
---|---|
PROVISIONING | Request is pending (typically changes after two minutes) |
APPROVED | Seller has been approved and can begin processing |
REJECTED | Seller was rejected 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) |
Merchant#onboarding_state
changes. If you don't want to use our webhooks, you can make a GET request to the Merchant
resource to check it's onboarding_state
.Canadian Bank Accounts
Canadian sellers are also required to verify their bank accounts. Seller's can verify their Canadian bank accounts by uploading a bank document. Acceptable bank documents include bank statements, bank letters, or voided checks.
To upload bank documents, sellers can use either:
You can also use Onboarding Forms, which handles steps 1-3 and also prompts the seller to verify their bank account.
Finix API
To upload a bank document with the Finix API:
- Create a
File
resource oftype: BANK_STATEMENT
. - Upload the bank document to the
File
resource.
curl "https://finix.sandbox-payments-api.com/files" \
-H "Content-Type: application/vnd.api+json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
"display_name": "Bank File",
"linked_to": "IDvMDR4ppijCJmy6Bobntiv6",
"type": "BANK_STATEMENT"
}'
File
resource.Finix Dashboard
To upload files using the Finix Dashboard:
- Log in to your Finix Dashboard and click Merchants > Merchant Accounts.
- Select the Merchant, and click the Files tab on the top navigation bar.
- Click Upload File and enter the name you want to give the file. Select the Document Type.
- Drag and drop the file you want to upload and click Upload File.
If the upload is successful a green banner will appear. You can view the file in your browser by clicking the File ID.
Step 4: Create an Identity for Your Buyer
Now that you've successfully onboarded aMerchant
, you can start processing payments for your seller. To process a payment, we’ll need to create an Identity
that represents your buyer. You won’t need to capture the same amount of information from your buyer. So long as you don’t pass a identity#business_type
field all the other fields are optional.Usually, we suggest at least collecting the buyer’s name and email to help with accounting, reconciliation, and chargebacks.
attention
business_type
field when creating an Identity
for a buyer. Including business_type
configures our API to treat the created Identity
as a seller.curl "https://finix.sandbox-payments-api.com/identities" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
"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"
}
}
}'
Payment Instrument
you'll use in the next step.{
"id" : "IDbKCkEWUXALZGkvrMfQcnS9",
"created_at" : "2022-10-10T04:45:30.12Z",
"updated_at" : "2022-10-10T04:45:30.12Z",
"application" : "APgPDQrLD52TYvqazjHJJchM",
"entity" : {
"amex_mid" : null,
"annual_card_volume" : 0,
"business_address" : null,
"business_name" : null,
"business_phone" : null,
"business_tax_id_provided" : false,
"business_type" : null,
"default_statement_descriptor" : null,
"discover_mid" : null,
"dob" : null,
"doing_business_as" : null,
"email" : "therock@gmail.com",
"first_name" : "Collen",
"has_accepted_credit_cards_previously" : false,
"incorporation_date" : null,
"last_name" : "Wade",
"max_transaction_amount" : 0,
"mcc" : null,
"ownership_type" : null,
"personal_address" : {
"line1" : "741 Douglass St",
"line2" : "Apartment 7",
"city" : "San Mateo",
"region" : "CA",
"postal_code" : "94114",
"country" : "USA"
},
"phone" : "7145677613",
"principal_percentage_ownership" : null,
"short_business_name" : null,
"tax_authority" : null,
"tax_id_provided" : false,
"title" : null,
"url" : null
},
"tags" : {},
"_links" : {
"self" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9"
},
"verifications" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/verifications"
},
"merchants" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/merchants"
},
"settlements" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/settlements"
},
"authorizations" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/authorizations"
},
"transfers" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/transfers"
},
"payment_instruments" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/payment_instruments"
},
"associated_identities" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/associated_identities"
},
"disputes" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9/disputes"
},
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
}
}
}
Step 5: Tokenize Payment Details
Now that we have anIdentity
resource representing our buyer, we’ll need to create a Payment Instrument
which represents the credit card you’ll be debiting (i.e. charging).You’ll also need to include your buyer’s Identity#id
from the previous request to link the Payment Instrument
that's created with your buyer's details.attention
Payment Instruments
and passing payment details (account number, card number, etc.) directly via the API should only be done for testing purposes and by PCI Level 1 compliant entities. If you aren't a Level 1 PCI-compliant entity, you must use our Tokenization Forms or Mobile Tokenization to accept payment details and comply with PCI regulations. If you have any questions, please don't hesitate to reach out to your Finix point of contact or email the Finix Support team.curl "https://finix.sandbox-payments-api.com/payment_instruments" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
"address": {
"city": "San Francisco",
"country": "USA",
"line1": "900 Metro Center Blv",
"postal_code": "94404",
"region": "CA"
},
"expiration_month": 12,
"expiration_year": 2029,
"identity": "IDbKCkEWUXALZGkvrMfQcnS9",
"name": "John Smith",
"number": "4895142232120006",
"security_code": "022",
"type": "PAYMENT_CARD"
}'
Payment Instrument
you'll use to make a payment to your seller.{
"id" : "PI6fBxWjm2GfdhCughovSWQr",
"created_at" : "2022-10-10T04:47:42.41Z",
"updated_at" : "2022-10-10T04:47:42.41Z",
"application" : "APgPDQrLD52TYvqazjHJJchM",
"created_via" : "API",
"currency" : "USD",
"enabled" : true,
"fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
"identity" : "IDbKCkEWUXALZGkvrMfQcnS9",
"instrument_type" : "PAYMENT_CARD",
"address" : {
"line1" : "900 Metro Center Blv",
"line2" : null,
"city" : "San Francisco",
"region" : "CA",
"postal_code" : "94404",
"country" : "USA"
},
"address_verification" : "UNKNOWN",
"bin" : "489514",
"brand" : "VISA",
"card_type" : "UNKNOWN",
"expiration_month" : 12,
"expiration_year" : 2029,
"issuer_country" : "UNKNOWN",
"last_four" : "0006",
"name" : "John Smith",
"security_code_verification" : "UNKNOWN",
"tags" : {},
"type" : "PAYMENT_CARD",
"_links" : {
"self" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI6fBxWjm2GfdhCughovSWQr"
},
"authorizations" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI6fBxWjm2GfdhCughovSWQr/authorizations"
},
"transfers" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI6fBxWjm2GfdhCughovSWQr/transfers"
},
"verifications" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI6fBxWjm2GfdhCughovSWQr/verifications"
},
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
},
"identity" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbKCkEWUXALZGkvrMfQcnS9"
},
"updates" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI6fBxWjm2GfdhCughovSWQr/updates"
}
}
}
Step 6: Make a Payment
At this point, we've onboarded a seller and tokenized a buyer's payment details. We can now create a payment. You create a payment by creating aTransfer
.To make a payment, you need to create a Transfer
. We’ll include the buyer’s Payment Instrument#id
as the source
field and the seller’s Merchant
ID in the merchant
field.- We recommend including a
fraud_session_id
to detect and block potential fraudulent payments. For more information, see Fraud Detection. - Note that the
amount
field is in cents.
Authorization
and to capture the same Authorization
in two API calls. This is useful when you want to verify the payment details and capture a specific amount at a later date. For more details, see Creating and Capturing an Authorization.curl "https://finix.sandbox-payments-api.com/transfers" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
"amount": 662154,
"currency": "USD",
"merchant": "MU7cXuKj2xx41hhZZi6bZ13A",
"source": "PI6fBxWjm2GfdhCughovSWQr"
}'
curl "https://finix.sandbox-payments-api.com/transfers" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{
"amount": 350,
"currency": "CAD",
"merchant": "MU2ekLKCiV8M5waZ3Ayg7ic6",
"source": "PIkvt7XgquT2zzCx7jLPkh5z"
}'
currency
of the Transfer
or Authorization
must match the currencies
on the Merchant
. At the moment, you may only have one currencies
value associated to a Merchant
. A successful response returns the Transfer
with a type
of DEBIT and a state
of SUCCEEDED.{
"id" : "TRsZQyem5h5vtRFSWBorBfSs",
"created_at" : "2022-10-10T04:48:59.06Z",
"updated_at" : "2022-10-10T04:48:59.76Z",
"additional_buyer_charges" : null,
"additional_healthcare_data" : null,
"address_verification" : null,
"amount" : 662154,
"amount_requested" : 662154,
"application" : "APgPDQrLD52TYvqazjHJJchM",
"currency" : "USD",
"destination" : null,
"externally_funded" : "UNKNOWN",
"failure_code" : null,
"failure_message" : null,
"fee" : 0,
"idempotency_id" : null,
"merchant_identity" : "IDvHGrfeVmB3i7uL78xjemNk",
"messages" : [ ],
"raw" : null,
"ready_to_settle_at" : null,
"security_code_verification" : null,
"source" : "PI6fBxWjm2GfdhCughovSWQr",
"state" : "SUCCEEDED",
"statement_descriptor" : "FNX*FINIX FLOWERS",
"subtype" : "API",
"tags" : {},
"trace_id" : "5576e040-f497-474b-a153-722f49ba007f",
"type" : "DEBIT",
"_links" : {
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
},
"self" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TRsZQyem5h5vtRFSWBorBfSs"
},
"merchant_identity" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk"
},
"payment_instruments" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TRsZQyem5h5vtRFSWBorBfSs/payment_instruments"
},
"reversals" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TRsZQyem5h5vtRFSWBorBfSs/reversals"
},
"fees" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TRsZQyem5h5vtRFSWBorBfSs/fees"
},
"disputes" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TRsZQyem5h5vtRFSWBorBfSs/disputes"
},
"source" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PI6fBxWjm2GfdhCughovSWQr"
},
"fee_profile" : {
"href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
}
}
}
{
"id" : "TR6wCGWsuj9Mw6oLfTTLavFY",
"created_at" : "2024-02-29T18:34:29.94Z",
"updated_at" : "2024-02-29T18:34:30.69Z",
"additional_buyer_charges" : null,
"additional_healthcare_data" : null,
"additional_purchase_data" : null,
"address_verification" : null,
"amount" : 350,
"amount_requested" : 350,
"application" : "APgPDQrLD52TYvqazjHJJchM",
"currency" : "CAD",
"destination" : null,
"externally_funded" : "UNKNOWN",
"failure_code" : null,
"failure_message" : null,
"fee" : 0,
"idempotency_id" : null,
"merchant" : "MU2ekLKCiV8M5waZ3Ayg7ic6",
"merchant_identity" : "IDbuyRPdoEBfEsKcuKEPgkqP",
"messages" : [ ],
"parent_transfer" : null,
"parent_transfer_trace_id" : null,
"raw" : null,
"ready_to_settle_at" : null,
"receipt_last_printed_at" : null,
"security_code_verification" : null,
"source" : "PIkvt7XgquT2zzCx7jLPkh5z",
"split_transfers" : [ ],
"state" : "SUCCEEDED",
"statement_descriptor" : "FNX*FINIX FLOWERS",
"subtype" : "API",
"tags" : { },
"trace_id" : "f6f19976-66de-4cea-8764-83e7044b45b3",
"type" : "DEBIT",
"_links" : {
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
},
"self" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6wCGWsuj9Mw6oLfTTLavFY"
},
"merchant_identity" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDbuyRPdoEBfEsKcuKEPgkqP"
},
"payment_instruments" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6wCGWsuj9Mw6oLfTTLavFY/payment_instruments"
},
"reversals" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6wCGWsuj9Mw6oLfTTLavFY/reversals"
},
"fees" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6wCGWsuj9Mw6oLfTTLavFY/fees"
},
"disputes" : {
"href" : "https://finix.sandbox-payments-api.com/transfers/TR6wCGWsuj9Mw6oLfTTLavFY/disputes"
},
"source" : {
"href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIkvt7XgquT2zzCx7jLPkh5z"
},
"fee_profile" : {
"href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
}
}
}
The above response means the seller successfully charged the buyer, and the funds will soon be ready to get paid out to the seller.
Finix creates aSettlement
resource that maps transactions and fees to calculate your seller's payout. Read our Payout guide for more details on managing and reconciling payouts.Canada
Support for Canada is currently in early access. All CanadianSettlements
will temporarily get settled on a Daily Net schedule. Your Finix point of contact will keep you informed of changes to Candian Settlements
and updates to our support in Canada.Next Steps
Our Platform Checklist provides an overview of what's required to take an platform live.