Finix API Quickstart

A brief technical overview of integrating and processing payments with Finix.

This quick start provides a brief technical overview of what's involved when integrating with Finix. This includes:

Signing up for Finix and creating an API key.
Collecting the details of buyers and sellers.
Making a payment.

Prerequisites

Sign Into Finix

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.

Finix Dashboard

Create an API Key

Use the Finix Dashboard or the Finix API to create API keys. To create an API key with the dashboard, log in and click Developer > Create API Key.

Continue following the prompts and your API key will get generated. Make sure you save the username and password that gets returned. You won't be able to access the credentials again after closing the Create a new API Key window.

Step 1: Create an Identity for Your Seller

To onboard your seller or service provider, you'll need to create an Identity by collecting basic information (e.g. company name, address, etc.) that's necessary to identify and verify the business.

If your seller is a business that has multiple owners who own 25% or more of the business, you'll also need to create Associated Identities for each owner as well.

For this example, we'll onboard an individual person which is classified as a sole proprietorship and therefore wouldn't have multiple owners.

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 '
	{
	    "entity": {
	        "annual_card_volume": 12000000,
	        "business_address": {
	            "city": "San Mateo",
	            "country": "USA",
	            "region": "CA",
	            "line2": "Apartment 8",
	            "line1": "741 Douglass St",
	            "postal_code": "94114"
	        },
	        "business_name": "Finix Flowers",
	        "business_phone": "+1 (408) 756-4497",
	        "business_tax_id": "123456789",
	        "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
	        "default_statement_descriptor": "Finix Flowers",
	        "dob": {
	            "year": 1978,
	            "day": 27,
	            "month": 6
	        },
	        "doing_business_as": "Finix Flowers",
	        "email": "user@example.org",
	        "first_name": "John",
	        "has_accepted_credit_cards_previously": true,
	        "incorporation_date": {
	            "year": 1978,
	            "day": 27,
	            "month": 6
	        },
           "last_name": "Smith",
	        "max_transaction_amount": 12000000,
	        "mcc": "0742",
	        "ownership_type": "PRIVATE",
	        "personal_address": {
	            "city": "San Mateo",
	            "country": "USA",
	            "region": "CA",
	            "line2": "Apartment 7",
	            "line1": "741 Douglass St",
	            "postal_code": "94114"
	        },
	        "phone": "1234567890",
	        "principal_percentage_ownership": 50,
	        "tax_id": "123456789",
	        "title": "CEO",
	        "url": "www.Finix.com"
	    },
       "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"
	    }
	}'

A successful response returns 201 and the newly created Identity.

Copy

Copied

{
  "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" : "0742",
    "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"
    }
  }
}

As you go through this article, you'll see that your activity with the Finix API shows up on the Finix Dashboard.

Step 2: Tokenize Seller's Bank Account for Payouts

Now that we've created an Identity for your seller, you need to add a bank account where we can payout the funds for they payments they process.

In the Finix API, cards and bank accounts get represented by the Payment Instrument resource. To secure the details of your seller's bank account, create a Payment Instrument with their bank account information and include the previously created Identity#id to link the two resources.

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_number": "123123123",
	    "account_type": "SAVINGS",
	    "bank_code": "123123123",
	    "country": "USA",
	    "identity": "IDvHGrfeVmB3i7uL78xjemNk",
	    "name": "John",
	    "type": "BANK_ACCOUNT"
	}'

A successful response returns 201 with the newly created Payment Instrument.

Copy

Copied

{
  "id" : "PIcsMDFxZrxFXRVfyQCzXNC9",
  "created_at" : "2022-10-10T04:42:09.12Z",
  "updated_at" : "2022-10-10T04:42:09.12Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "created_via" : "API",
  "currency" : "USD",
  "enabled" : true,
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "identity" : "IDvHGrfeVmB3i7uL78xjemNk",
  "instrument_type" : "BANK_ACCOUNT",
  "account_type" : "SAVINGS",
  "bank_account_validation_check" : "NOT_ATTEMPTED",
  "bank_code" : "123123123",
  "country" : "USA",
  "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"
    }
  }
}

Step 3: Verify and Onboard Your Seller

Now that you have an Identity and a linked Payment Instrument for your seller, you need to create a Merchant which submits the payment details you collect and allows your seller to begin processing payments. The onboarding process for a Merchant is asynchronous, and will initially return an onboarding_state = PROVISIONING while Finix complete's the appropriate compliance checks.

In production — unless the seller triggers our API for a manual review — this process typically takes just a few minutes. In sandbox, the state transitions within a few seconds. We recommend that you integrate into our webhooks to listen for the status changes.

Copy

Copied

# Send DUMMY_V1 as the processor to use your sandbox environment; your Finix point of contact will provide the processor to use for live payments.

curl https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk/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" 
	}'

Copy

Copied

{
  "id" : "MU7cXuKj2xx41hhZZi6bZ13A",
  "created_at" : "2022-10-10T04:42:43.97Z",
  "updated_at" : "2022-10-10T04:42:43.97Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "card_cvv_required" : false,
  "card_expiration_date_required" : true,
  "convenience_charges_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "default_partial_authorization_enabled" : false,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "gross_settlement_enabled" : false,
  "identity" : "IDvHGrfeVmB3i7uL78xjemNk",
  "level_two_level_three_data_enabled" : false,
  "mcc" : "0742",
  "merchant_name" : "Finix Flowers",
  "merchant_profile" : "MPrMfLCw7S17vVfamHWazG3Q",
  "mid" : null,
  "onboarding_state" : "PROVISIONING",
  "processing_enabled" : false,
  "processor" : "DUMMY_V1",
  "processor_details" : { },
  "ready_to_settle_upon" : "RECONCILIATION",
  "rent_surcharges_enabled" : false,
  "settlement_enabled" : false,
  "settlement_funding_identifier" : "UNSET",
  "tags" : {},
  "verification" : "VIhTP4Hwej6BmTPqfrVTZNLa",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU7cXuKj2xx41hhZZi6bZ13A"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU7cXuKj2xx41hhZZi6bZ13A/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPrMfLCw7S17vVfamHWazG3Q"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIhTP4Hwej6BmTPqfrVTZNLa"
    }
  }
}

If you'd rather not use webhooks, you can simply make a GET request to the Merchant resource to check it's onboarding_state.

Copy

Copied

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

Copy

Copied

{
  "id" : "MU7cXuKj2xx41hhZZi6bZ13A",
  "created_at" : "2022-10-10T04:42:43.97Z",
  "updated_at" : "2022-10-10T04:43:01.51Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "card_cvv_required" : false,
  "card_expiration_date_required" : true,
  "convenience_charges_enabled" : false,
  "creating_transfer_from_report_enabled" : true,
  "default_partial_authorization_enabled" : false,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "gross_settlement_enabled" : false,
  "identity" : "IDvHGrfeVmB3i7uL78xjemNk",
  "level_two_level_three_data_enabled" : false,
  "mcc" : "0742",
  "merchant_name" : "Finix Flowers",
  "merchant_profile" : "MPrMfLCw7S17vVfamHWazG3Q",
  "mid" : "FNXbPdexTT8zcxwzCZGDAWnVk",
  "onboarding_state" : "APPROVED",
  "processing_enabled" : true,
  "processor" : "DUMMY_V1",
  "processor_details" : {
    "mid" : "FNXbPdexTT8zcxwzCZGDAWnVk",
    "api_key" : "secretValue"
  },
  "ready_to_settle_upon" : "RECONCILIATION",
  "rent_surcharges_enabled" : false,
  "settlement_enabled" : true,
  "settlement_funding_identifier" : "UNSET",
  "tags" : {},
  "verification" : "VIhTP4Hwej6BmTPqfrVTZNLa",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU7cXuKj2xx41hhZZi6bZ13A"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MU7cXuKj2xx41hhZZi6bZ13A/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPrMfLCw7S17vVfamHWazG3Q"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIhTP4Hwej6BmTPqfrVTZNLa"
    }
  }
}

Step 4: Create an Identity for Your Buyer

Now that you've successfully onboarded a Merchant for your seller, you can start processing payments for them.

Next, create an Identity and Payment Instrument for the buyer. As opposed to sellers, the details required to create an Identity for a buyer are optional. However, this example collects the buyer's name, address, and email. Collecting this and additional information helps with managing accounting, reconciliation, and chargebacks.

Do not pass the business_type field when creating an Identity for a buyer. Including business_type configures our API to treat the created Identity as a seller.

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 '
	{
	    "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" : "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 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 Fields to securely gather card payment while staying 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 Fields to collect the details of buyers and sellers. If you think you qualify to handle raw card data, reach out to the Finix Support team.

For the purposes of this guide, 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 '
	{
	    "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"
	}'

A successful response returns the newly created Payment Instrument you'll use to make a payment to your seller.

Copy

Copied

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

Now that we've successfully onboarded a seller and tokenized the buyer's payment details, 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 '
	{
	    "amount": 662154,
	    "currency": "USD",
	    "merchant": "MU7cXuKj2xx41hhZZi6bZ13A",
	    "source": "PI6fBxWjm2GfdhCughovSWQr"
	}'

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

Copy

Copied

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

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

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 more details 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. Read on about about various nuances your integration will need to take into account to process live payments.

Onboarding

Learn how to onboard your sellers and what information you'll need to verify.

Integration Checklist

Verify you integration is ready to process live transactions.

Our Integration Checklist provides an overview of what's required to take an integration live.