Bank Payouts

Make a payout to a recipient's bank account.


Send funds to your recipient's bank account using Payouts. If you have any questions about sending payouts, reach out to your Finix Point of Contact or Finix Support.

Step 1: Create a Recipient Identity

The first step for making a payout is creating a RECIPIENT Identity to represent who you'll send funds to. The Identity resource helps manage bank accounts, cards, payout history, and the details of your customers. You can create either PERSONAL or BUSINESS Recipients.

Required field
Optional field
Invalid field
Fieldtype: PERSONALtype: BUSINESS
Type
type
First Name
first_name
Last Name
last_name
Personal Address
personal_address
Business Name
business_name
Doing Business As
doing_business_as
Business Address
business_address
Business Phone
business_phone
Personal Email
email
Personal Phone
phone
Personal RecipientBusiness Recipient
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": {
        "first_name": "John",
        "last_name": "Doe",
        "personal_address": {
          "line1": "741 Douglass St",
          "line2": "Apartment 7",
          "city": "San Mateo",
          "region": "CA",
          "postal_code": "94114",
          "country": "USA"
        }
      },
      "identity_roles": [
        "RECIPIENT"
      ],
      "type": "PERSONAL"
    }'
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": {
        "first_name": "John",
        "last_name": "Doe",
        "personal_address": {
          "line1": "741 Douglass St",
          "line2": "Apartment 7",
          "city": "San Mateo",
          "region": "CA",
          "postal_code": "94114",
          "country": "USA"
        },
        "business_name": "ABC Corporation",
        "doing_business_as": "ABC Corp",
        "business_address": {
          "line1": "123 Main Street",
          "line2": "Suite 101",
          "city": "San Francisco",
          "region": "CA",
          "postal_code": "94114",
          "country": "USA"
        }
      },
      "identity_roles": [
        "RECIPIENT"
      ],
      "type": "BUSINESS"
    }'

This will create a Recipient Identity:

Personal RecipientBusiness Recipient
Copy
Copied
{
    "id": "ID2dgoqygWvVthU9kQBKz7t4",
    "created_at": "2024-07-31T18:28:05.92Z",
    "updated_at": "2024-07-31T18:28:05.92Z",
    "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": null,
        "first_name": "John",
        "has_accepted_credit_cards_previously": false,
        "incorporation_date": null,
        "last_name": "Doe",
        "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": null,
        "principal_percentage_ownership": null,
        "short_business_name": null,
        "tax_authority": null,
        "tax_id_provided": false,
        "title": null,
        "url": null
    },
    "identity_roles": ["RECIPIENT"],
    "tags": {},
    "type": "PERSONAL",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2dgoqygWvVthU9kQBKz7t4"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2dgoqygWvVthU9kQBKz7t4/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2dgoqygWvVthU9kQBKz7t4/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2dgoqygWvVthU9kQBKz7t4/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2dgoqygWvVthU9kQBKz7t4/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2dgoqygWvVthU9kQBKz7t4/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2dgoqygWvVthU9kQBKz7t4/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2dgoqygWvVthU9kQBKz7t4/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2dgoqygWvVthU9kQBKz7t4/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}
Copy
Copied
{
    "id": "ID6a5FiSiDxTwYJ5n8RJdRb5",
    "created_at": "2024-07-31T18:28:35.84Z",
    "updated_at": "2024-07-31T18:28:35.84Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "entity": {
        "ach_max_transaction_amount": 0,
        "amex_mid": null,
        "annual_card_volume": 0,
        "business_address": {
            "line1": "123 Main Street",
            "line2": "Suite 101",
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94114",
            "country": "USA"
        },
        "business_name": "ABC Corporation",
        "business_phone": null,
        "business_tax_id_provided": false,
        "business_type": null,
        "default_statement_descriptor": null,
        "discover_mid": null,
        "dob": null,
        "doing_business_as": "ABC Corp",
        "email": null,
        "first_name": "John",
        "has_accepted_credit_cards_previously": false,
        "incorporation_date": null,
        "last_name": "Doe",
        "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": null,
        "principal_percentage_ownership": null,
        "short_business_name": null,
        "tax_authority": null,
        "tax_id_provided": false,
        "title": null,
        "url": null
    },
    "identity_roles": ["RECIPIENT"],
    "tags": {},
    "type": "BUSINESS",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID6a5FiSiDxTwYJ5n8RJdRb5"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID6a5FiSiDxTwYJ5n8RJdRb5/verifications"
        },
        "merchants": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID6a5FiSiDxTwYJ5n8RJdRb5/merchants"
        },
        "settlements": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID6a5FiSiDxTwYJ5n8RJdRb5/settlements"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID6a5FiSiDxTwYJ5n8RJdRb5/authorizations"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID6a5FiSiDxTwYJ5n8RJdRb5/transfers"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID6a5FiSiDxTwYJ5n8RJdRb5/payment_instruments"
        },
        "associated_identities": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID6a5FiSiDxTwYJ5n8RJdRb5/associated_identities"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID6a5FiSiDxTwYJ5n8RJdRb5/disputes"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
    }
}

Step 2: Create a Payment Instrument for the Recipient

attention
Creating 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, Mobile Tokenization, or Plaid to accept payment details and comply with PCI regulations.
Now that we've created an Identity for our recipient, we'll need to create a Payment Instrument using the recipient's bank account. A Payment Instrument represents the recipient's payment method that will receive funds. When creating Payment Instruments for Payouts, attempt_bank_account_validation_check must be set to true.

If you have any questions about creating Payment Instruments, reach out to your Finix Point of Contact or Finix Support.

Tokenize via APITokenize via Plaid
Copy
Copied
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u US9bhCUqoTxo7V6di8ceb3Td:e704591a-1972-4b41-9884-6a67f5d7cdbb \
    -d '{
      "account_number": "123123123",
      "account_type": "PERSONAL_CHECKING",
      "bank_code": "123123123",
      "identity": "ID4a4cYBQU1NoS25b7J7FLBe",
      "name": "John Smith",
      "type": "BANK_ACCOUNT",
      "attempt_bank_account_validation_check": true
    }'
Copy
Copied
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u US9bhCUqoTxo7V6di8ceb3Td:e704591a-1972-4b41-9884-6a67f5d7cdbb \
    -d '{
      "identity": "ID4a4cYBQU1NoS25b7J7FLBe",
      "third_party": "PLAID",
      "third_party_token": "processor-sandbox-0asd1-a92nc",
      "type": "BANK_ACCOUNT"
    }'

Example response:

Tokenize via APITokenize via Plaid
Copy
Copied
{
    "id": "PI9P9BctY8CjkRXsem4FYiRp",
    "created_at": "2024-04-09T21:43:19.93Z",
    "updated_at": "2024-04-09T21:43:19.93Z",
    "application": "AP5Tq3MMxKwHYX7soDncrCQ3",
    "created_via": "API",
    "currency": "USD",
    "disabled_code": null,
    "disabled_message": null,
    "enabled": true,
    "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg",
    "identity": "ID4a4cYBQU1NoS25b7J7FLBe",
    "instrument_type": "BANK_ACCOUNT",
    "account_type": "PERSONAL_CHECKING",
    "bank_account_validation_check": "INCONCLUSIVE",
    "bank_code": "123123123",
    "country": "USA",
    "institution_number": null,
    "masked_account_number": "XXXXX3123",
    "name": "John Smith",
    "transit_number": null,
    "tags": {},
    "third_party": null,
    "third_party_token": null,
    "type": "BANK_ACCOUNT",
    "_links": {}
}
Copy
Copied
{
    "id": "PI3AbkuRR1JbT5kPiGQCXvD9",
    "created_at": "2022-10-11T01:42:53.29Z",
    "updated_at": "2022-10-11T01:42:53.29Z",
    "application": "AP5Tq3MMxKwHYX7soDncrCQ3",
    "created_via": "API",
    "currency": "USD",
    "enabled": true,
    "third_party": "PLAID",
    "third_party_token": "processor-sandbox-0asd1-a92nc",
    "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg",
    "identity": "ID4a4cYBQU1NoS25b7J7FLBe",
    "instrument_type": "BANK_ACCOUNT",
    "account_type": "PERSONAL_CHECKING",
    "bank_account_validation_check": "VALID",
    "bank_code": "123123123",
    "country": "USA",
    "masked_account_number": "XXXXX3123",
    "name": "John Doe",
    "tags": {},
    "type": "BANK_ACCOUNT",
    "_links": {}
}

Step 3: Verify and Onboard the Recipient

Now that we've associated a Payment Instrument with our recipient's Identity we're ready to provision a recipient account. This is the last step before you can begin paying out a recipient Identity. Luckily you've already done most of the heavy lifting - make one final POST request, and a Merchant resource will get returned.
Copy
Copied
curl https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe/merchants \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u US9bhCUqoTxo7V6di8ceb3Td:e704591a-1972-4b41-9884-6a67f5d7cdbb \
    -d '{
      "processor": "DUMMY_V1"
    }'

Example response:

Copy
Copied
{
    "id": "MUgQ71pEuuXi5t66rhAzvods",
    "created_at": "2023-12-07T17:55:43.67Z",
    "updated_at": "2023-12-07T17:55:43.67Z",
    "application": "AP5Tq3MMxKwHYX7soDncrCQ3",
    "card_cvv_required": false,
    "card_expiration_date_required": true,
    "convenience_charges_enabled": false,
    "country": "USA",
    "creating_transfer_from_report_enabled": false,
    "currencies": ["USD"],
    "default_partial_authorization_enabled": false,
    "disbursements_ach_pull_enabled": false,
    "disbursements_ach_push_enabled": true,
    "disbursements_card_pull_enabled": false,
    "disbursements_card_push_enabled": true,
    "fee_ready_to_settle_upon": "PROCESSOR_WINDOW",
    "gateway": null,
    "gross_settlement_enabled": false,
    "identity": "ID4a4cYBQU1NoS25b7J7FLBe",
    "level_two_level_three_data_enabled": false,
    "mcc": null,
    "merchant_name": "John Smith",
    "merchant_profile": "MPjsV92nmV8FvVQi6xJrd3vu",
    "mid": null,
    "onboarding_state": "PROVISIONING",
    "processing_enabled": false,
    "processor": "DUMMY_V1",
    "processor_details": {},
    "ready_to_settle_upon": "PROCESSOR_WINDOW",
    "rent_surcharges_enabled": false,
    "settlement_enabled": false,
    "settlement_funding_identifier": "UNSET",
    "surcharges_enabled": false,
    "tags": {},
    "verification": "VImp8NSKFB7hM3nKSu3NrXny",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUgQ71pEuuXi5t66rhAzvods"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUgQ71pEuuXi5t66rhAzvods/verifications"
        },
        "merchant_profile": {
            "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPjsV92nmV8FvVQi6xJrd3vu"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/AP5Tq3MMxKwHYX7soDncrCQ3"
        },
        "verification": {
            "href": "https://finix.sandbox-payments-api.com/verifications/VImp8NSKFB7hM3nKSu3NrXny"
        }
    }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/identities/identity_id/merchants

Request Arguments

FieldTypeDescription
processorstring, requiredName of the verification processor.

Step 4: Create a Bank Payout

Next you'll need to create a Transfer. A Transfer represents any flow of funds either to or from a Payment Instrument. In this case a payout to a bank account.

To create a Transfer:
  • Include the ID of the Payment Instrument of the previously tokenized bank account as the destination.
  • In amount, set the funds to send in cents. In the below example, $150.00 is getting paid out.
Transfers can have two possible states: SUCCEEDED and FAILED.
Copy
Copied
curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  US9bhCUqoTxo7V6di8ceb3Td:e704591a-1972-4b41-9884-6a67f5d7cdbb \
    -d '{
      "currency": "USD",
      "amount": 15000,
      "operation_key": "PUSH_TO_ACH",
      "processor":"DUMMY_V1",
      "destination": "PIin2ENAnCtMwMkrnq7AMKuW"
    }'

Example response:

Copy
Copied
{
    "id": "TRcFLUnEEJGTUEeb16y7cq6",
    "created_at": "2023-12-08T19:35:56.15Z",
    "updated_at": "2023-12-08T19:35:57.27Z",
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "additional_purchase_data": null,
    "address_verification": null,
    "amount": 15000,
    "amount_requested": 15000,
    "application": "AP5Tq3MMxKwHYX7soDncrCQ3",
    "currency": "USD",
    "destination": "PIin2ENAnCtMwMkrnq7AMKuW",
    "externally_funded": "UNKNOWN",
    "failure_code": null,
    "failure_message": null,
    "fee": 0,
    "idempotency_id": null,
    "merchant": "MUxwJ1j8Mjbc95pu5157YfLN",
    "merchant_identity": "ID2jCuKfJHgbQGjdSoUThUQV",
    "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": null,
    "split_transfers": [],
    "state": "PENDING",
    "statement_descriptor": null,
    "subtype": "API",
    "tags": {},
    "trace_id": "0aa8a67f-ed2d-42b0-8be8-e42a6935db3d",
    "type": "CREDIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/AP5Tq3MMxKwHYX7soDncrCQ3"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRcFLUnEEJGTUEeb16y7cq6"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2jCuKfJHgbQGjdSoUThUQV"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRcFLUnEEJGTUEeb16y7cq6/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRcFLUnEEJGTUEeb16y7cq6/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRcFLUnEEJGTUEeb16y7cq6/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRcFLUnEEJGTUEeb16y7cq6/disputes"
        },
        "destination": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIin2ENAnCtMwMkrnq7AMKuW"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPmtT4MYmiAs1qjLjneQmk4d"
        }
    }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/transfers

Request Arguments

FieldTypeDescription
amountinteger, requiredThe total amount that will be charged in cents (e.g. 100 cents to charge $1.00)
countrystring, optional3-Letter Country code. This attribute is currently only applicable for our Latin America partners.
currencystring, required3-letter ISO code designating the currency of the Transfers (e.g. USD)
destinationstring, requiredID of the Payment Instrument where funds will be sent
idempotency_idstring, optionalA randomly generated value that gets tied with the request.
operation_keystring, requiredDetails what specific Transfer will occur. Available options inlcude:
  • PUSH_TO_ACH
  • PULL_FROM_ACH
Use PUSH_TO_ACH for Bank Payouts.
tagsobject, optionalKey value pair for annotating custom metadata (e.g. order numbers)

Next Steps