Developer Quickstart

This quickstart provides details on how your business can accept a payment with Finix.

Before You Begin

Get started by creating a sandbox account with Finix. Choose Individual Business while creating a sandbox account.

This sandbox account gives you access to the Finix Dashboard. You can use the Finix Dashboard to review your payment activity.

Finix Dashboard

Before you can process payments using the Finix API, you need:

Supported Countries

Finix supports entities in the following countries:

  • United States
  • Canada

API Key

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.

Merchant ID

Click Developers to find your business's Merchant ID under Finix Processing Details. Use the Application and Merchant IDs along with the API Key to process payments in your integration.

Step 1: Create an Identity for Your Buyer

With your API Key and Merchant ID, you can start processing payments. 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
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/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"
	        }
	    }
	}'
A successful response returns the Identity you'll use in the next step.
Copy
Copied
{
    "id": "IDn7rfwM88AJrBituwUjcX2Y",
    "created_at": "2023-10-25T17:42:22.23Z",
    "updated_at": "2023-10-25T17:42:22.23Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "entity": {
        "ach_max_transaction_amount": 0,
        "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
    },
    "identity_roles": [],
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDn7rfwM88AJrBituwUjcX2Y/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}

Step 2: Tokenize Payment Details

Now that we have an Identity resource representing your buyer, we’ll need to create a Payment Instrument for your buyer to represent 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
Please note that creating Payment Instruments and passing payment details (account number, card number, etc.) directly via the API should only be done for testing purposes. You must use the Tokenization Forms or Mobile Tokenization to accept payment details and remain out of PCI scope.
Copy
Copied
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"
	}'
A successful response returns the newly created Payment Instrument you'll use to process the buyer's payment.
Copy
Copied
{
    "id": "PIcacm9WBYXZSd7NB5DmpN6E",
    "created_at": "2023-10-25T17:43:09.94Z",
    "updated_at": "2023-10-25T17:43:09.94Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "USD",
    "disabled_code": null,
    "disabled_message": null,
    "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/PIcacm9WBYXZSd7NB5DmpN6E"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/transfers"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E/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/PIcacm9WBYXZSd7NB5DmpN6E/updates"
        }
    }
}

Step 3: Make a Payment

At this point, we've created your Merchant and tokenized a buyer's payment details. We can now create a payment.To make a payment, you need to create a Transfer. Include the buyer’s Payment Instrument#id as the source field and the your 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.
Alternatively, you can create an Authorization 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.
Copy
Copied
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": "PIcacm9WBYXZSd7NB5DmpN6E"
	}'
A successful response returns the Transfer with type: DEBIT and state: SUCCEEDED.
Copy
Copied
{
    "id": "TRBuZ2qrAw268K2npdBpdT9",
    "created_at": "2023-10-25T17:43:34.23Z",
    "updated_at": "2023-10-25T17:43:35.10Z",
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "additional_purchase_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": "MU7cXuKj2xx41hhZZi6bZ13A",
    "merchant_identity": "IDvHGrfeVmB3i7uL78xjemNk",
    "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": "PIcacm9WBYXZSd7NB5DmpN6E",
    "split_transfers": [],
    "state": "SUCCEEDED",
    "statement_descriptor": "FNX*FINIX FLOWERS",
    "subtype": "API",
    "tags": {},
    "trace_id": "a395feb9-0fcd-45ab-b4e6-280d2d7cdf5d",
    "type": "DEBIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRBuZ2qrAw268K2npdBpdT9/disputes"
        },
        "source": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIcacm9WBYXZSd7NB5DmpN6E"
        },
        "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 pay out.

Finix creates a Settlement resource which maps transactions and fees to calculate your payout. Read Payouts for more details on how to manage and reconcile payouts.

Next Steps

Payouts

Learn how to collect the payouts from the payments you process.

Integration Checklist

Learn what's required to process live transactions.