Integration Overview

Before integrating with Finix, review Finix's account structure and key resources to familiarize yourself with the Finix API and help streamline the integration process.

Integrating with Finix involves the following steps:

Sign into Finix.
Create an API Key.
Create an Identity for your seller or service provider.
Tokenize a bank account for payouts.
Verify the Identity.
Create an Identity for your buyer.
Tokenize the buyer's payment information.
Make a payment.

Step 1: Sign Into Finix

If you haven't already, create an account with Finix. This account gives you access to the Finix Dashboard.

Finix Dashboard

You can use the Finix Dashboard to create API keys. Additionally, as you go through this guide, you'll see that your activity with the Finix API shows up on the Finix Dashboard. You can use the Finix Dashboard to review your activity and manage configurations for your sellers.

Step 2: Create an API Key

To create an API key, log in to the Finix Dashboard and click Developer > Create API Key.

Follow the prompts to create an API key. Make sure you save the username and password as you won't be able to access the credentials after closing the Create a new API Key window.

Test API Key

It's possible that your initial Finix point of contact gave you an API key before you personally logged into the Dashboard. Feel free to use that API key as well.

Step 3: Create an Identity

You need to onboard your seller or service provider. They are represented in Finix as an Identity. Each Identity represents either a person or a business and stores their identifying information. This information gets verified during the onboarding step. Collect your seller's identifying information and create an Identity. You also need to provide underwriting data which details how the seller will process payments.

If your seller is a business, and has multiple owners who own 25% or more of the business, you'll also need to create Associated Identities for each owner with a stake greater than 25%.

hosted onboarding

You can create your own onboarding experience with the API, but you can also use our hosted onboarding forms which will handle steps 1-5 of this overview.

For this example, this guide onboards an individual person, also called a sole-proprietorship. This means the business is the person themselves, and they wouldn't have multiple owners.

Onboarding businesses

When you onboard a business, if they have multiple owners, you'll need to create Associated Identities for every owner with stakes greater than 25%.

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": "Smith",
	        "max_transaction_amount": 12000000,
	        "has_accepted_credit_cards_previously": true,
	        "default_statement_descriptor": "Finix Flowers",
	        "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": "John",
	        "title": "CEO",
	        "business_tax_id": "123456789",
	        "doing_business_as": "Finix Flowers",
	        "principal_percentage_ownership": 50,
	        "email": "user@example.org",
	        "mcc": "0742",
	        "phone": "1234567890",
	        "business_name": "Finix Flowers",
	        "tax_id": "123456789",
	        "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
	        "business_phone": "+1 (408) 756-4497",
	        "dob": {
	            "year": 1978,
	            "day": 27,
	            "month": 6
	        },
	        "url": "www.Finix.com",
	        "annual_card_volume": 12000000
	    }
	}'

A successful response returns 201 and the newly created identity.

Copy

Copied

{
  "id" : "IDpYDM7J9n57q849o9E9yNrG",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "entity" : {
    "title" : "CEO",
    "first_name" : "John",
    "last_name" : "Smith",
    "email" : "user@example.org",
    "business_name" : "Finix Flowers",
    "business_type" : "INDIVIDUAL_SOLE_PROPRIETORSHIP",
    "doing_business_as" : "Finix Flowers",
    "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.Finix.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" : "Finix Flowers"
  },
  "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"
    }
  }
}

Step 4: Tokenize a Bank Account For Payouts

Now that we've created an Identity for your seller, you need to add their bank account where the funds they earn processing payments will get paid out to.In the API, all payment and payout information is represented by the payment_instrument resource. This includes your seller's bank accounts, as well as the buyer's payment methods such as credit cards or Apple Pay.To tokenize your seller's bank account, create a payment_instrument with their bank account information. Make sure to include the ID of their Identity. This configures the created payment_instrument as your seller's bank account where they'll get paid out.

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": "John",
	    "tags": {
	        "Bank Account": "Company Account"
	    },
	    "country": "USA",
	    "bank_code": "123123123",
	    "account_number": "123123123",
	    "type": "BANK_ACCOUNT",
	    "identity": "IDpYDM7J9n57q849o9E9yNrG"
	}'

A successful response returns 201 with the newly created payment_instrument.

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"
    }
  }
}

Step 5: Verify and Onboard Your Seller

Now that you have an Identity and an associated Payment Instrument for your seller, you need to trigger their verification and onboarding approval. This is done by creating a merchant.A merchant represents your sellers's capability to process payment. Creating a merchant triggers the verification (Know Your Customer) process within Finix. The verification process is asynchronous, which means merchants will be in a PROVISIONING state at first.

When creating a merchant, specify the processor as DUMMY_V1 to use the Sandbox environment.
When you go live, your Finix point of contact will give you the specific processor to use.

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"
	    }
	}'

A successfully initial merchant verification returns 201 and the newly created merchant with the status of PROVISIONING.

PROVISIONING Merchant

Copy

Copied

{
  "id" : "MU2kcQ2g9za2eCYM4jSN2Q1B",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "identity" : "IDpYDM7J9n57q849o9E9yNrG",
  "verification" : "VInvEZgGxS4BvQiRSyGUkz4u",
  "merchant_profile" : "MP82tNrfMTRFnfbXGoPK9QsK",
  "processor" : "DUMMY_V1",
  "processing_enabled" : false,
  "settlement_enabled" : false,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : null,
  "merchant_name" : "Finix Flowers",
  "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-08-28T23:10:40.55Z",
  "updated_at" : "2022-08-28T23:10:40.55Z",
  "onboarding_state" : "PROVISIONING",
  "processor_details" : { },
  "convenience_charges_enabled" : false,
  "rent_surcharges_enabled" : false,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU2kcQ2g9za2eCYM4jSN2Q1B"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID2Q8gYVAsYNJZ8WcDgxM63b"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU2kcQ2g9za2eCYM4jSN2Q1B/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MP82tNrfMTRFnfbXGoPK9QsK"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VInvEZgGxS4BvQiRSyGUkz4u"
    }
  }
}

On Sandbox, the merchant will be approved almost instantly. However, the approval will happen asynchronously to better match how merchants get approved in live environments. To get notified when your sellers get approved, create webhooks and listen for merchant events. This gets explained in detail in Onboarding Sellers.

For sandbox, you can query the merchant ID to see if it's approved.

Copy

Copied

curl https://finix.sandbox-payments-api.com/merchants/MU2kcQ2g9za2eCYM4jSN2Q1B \ 
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Copy

Copied

{
  "id" : "MU2kcQ2g9za2eCYM4jSN2Q1B",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "identity" : "IDpYDM7J9n57q849o9E9yNrG",
  "verification" : "VInvEZgGxS4BvQiRSyGUkz4u",
  "merchant_profile" : "MP82tNrfMTRFnfbXGoPK9QsK",
  "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" : "FNXqQVkMP2U96bVQN9KwbEL9Y",
  "merchant_name" : "Finix Flowers",
  "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-08-28T23:10:40.55Z",
  "updated_at" : "2022-08-28T23:11:01.45Z",
  "onboarding_state" : "APPROVED",
  "processor_details" : {
    "mid" : "FNXqQVkMP2U96bVQN9KwbEL9Y",
    "api_key" : "secretValue"
  },
  "convenience_charges_enabled" : false,
  "rent_surcharges_enabled" : false,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU2kcQ2g9za2eCYM4jSN2Q1B"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID2Q8gYVAsYNJZ8WcDgxM63b"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU2kcQ2g9za2eCYM4jSN2Q1B/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MP82tNrfMTRFnfbXGoPK9QsK"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VInvEZgGxS4BvQiRSyGUkz4u"
    }
  }
}

Step 6: Create an Identity for Your Buyer

Now that you have an APPROVED merchant for your seller, you can start processing payments for them.

Before you can process a payment, you need to:

Create an Identity for your buyer.
Tokenize the buyer's card into a payment_instrument.

The Identity that represents your buyer requires no information. You don't need to capture the same amount of information like your seller but the option is available. This Identity for the buyer allows you to store multiple methods of payments for the buyer as well as their billing information like address.Do not pass the business_type field when creating an Identity for a buyer. Including business_type configures our system to treat the created identity as a seller Identity.

This example collects the buyer's name, address, and email. Collecting this information can help with accounting, reconciliation, and chargeback management.

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"
	        }
	    }
	}'

A successful response returns the payment instrument you'll use in the next step.

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"
    }
  }
}

Step 7: Tokenize the Buyer's Payment Information

Now that you have an Identity resource representing our buyer, we'll need to create a Payment Instrument which represents the buyer's credit card and the Payment Instrument you'll be debiting (i.e. charging).

Use Finix's hosted tokenization fields to securely gather card payment while keeping out of PCI Scope. PCI scope is a set of requirements by the card networks around handling raw card data. They are difficult to meet so most use Finix's hosted tokenization fields.

info

If you think you qualify to handle raw card data, reach out to Finix support and ask how to enable it for you.

For illustrative purposes, this example creates a payment_instrument using raw card data. Create a payment instrument for your buyer by including the buyer's Identity ID.

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": "John Smith",
	    "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"
	}'

A successful response returns the newly created payment_instrument you will use to make a payment to your seller.

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"
    }
  }
}

Step 8: Make a Payment

Now that we've successfully onboarded a seller and tokenized payment information for the buyer, you can make a payment.

To make a payment, you need to create a transfer. A transfer represents a sale. For cards, this include the authorization and the capture.Create a transfer with the buyer's payment_instrument as the source your sellers's merchant ID.

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.

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"
	    }
	}'

A successful response returns the transfer with a type of DEBIT and a state of SUCCEEDED.

Copy

Copied

{
  "id" : "TRvypRNBeqM597Zi4DcqJ2Vh",
  "amount" : 662154,
  "tags" : {
    "test" : "sale"
  },
  "state" : "SUCCEEDED",
  "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*FINIX FLOWERS",
  "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"
    }
  }
}

The above response means the buyer was successfully charged and the funds are now associated to the seller and will soon be ready to get paid out.

Finix create a settlement resource which maps transactions and fees to calculate your seller's payout. Your seller will get paid out according to their payout settings. Read out Payout guide for further explanation on how to manage and reconcile payouts.

Next Steps

After taking these steps, you'll have an integration that is onboarding sellers and buyers, handling payments, and paying out sellers. This guide was a high level integration overview so to dive in deeper into these concepts see:

Compare your integration to the integration checklist, and once you are ready get your sandbox integration certified.