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 to process a payout is to create an Identity resource 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 a personal or business recipient Identity. These are the required fields for each recipient type:

Field	`type: PERSONAL`	`type: BUSINESS`
Type `type`	✅ Required	✅ Required
First Name `first_name`	✅ Required	✅ Required
Last Name `last_name`	✅ Required	✅ Required
Personal Address `personal_address`	✅ Required	✅ Required
Business Name `business_name`	🚫 Invalid	✅ Required
Doing Business As `doing_business_as`	🚫 Invalid	✅ Required
Business Address `business_address`	🚫 Invalid	✅ Required
Business Phone `business_phone`	🚫 Invalid	🟡 Optional
Personal Email `email`	🟡 Optional	🟡 Optional
Personal Phone `phone`	🟡 Optional	🟡 Optional

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 '{
      "identity_roles": ["RECIPIENT"],
      "type": "PERSONAL",
      "entity": {
        "first_name": "John",
        "last_name": "Doe",
        "personal_address": {
          "city": "San Mateo",
          "country": "USA",
          "region": "CA",
          "line2": "Apartment 7",
          "line1": "741 Douglass St",
          "postal_code": "94114"
        }
      }
    }'

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 '{
      "identity_roles": ["RECIPIENT"],
      "type": "BUSINESS",
      "entity": {
        "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"
        },
        "first_name": "John",
        "last_name": "Doe",
        "personal_address": {
          "city": "San Mateo",
          "country": "USA",
          "region": "CA",
          "line2": "Apartment 7",
          "line1": "741 Douglass St",
          "postal_code": "94114"
        }
      }
    }'

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/identityID/merchants

Request Arguments

Field	Type	Description
`processor`	string, optional	Name 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

Field	Type	Description
`amount`	integer, required	The total amount that will be charged in cents (e.g. 100 cents to charge $1.00)
`country`	string, optional	3-Letter Country code. This attribute is currently only applicable for our Latin America partners.
`currency`	string, required	3-letter ISO code designating the currency of the `Transfers` (e.g. USD)
`destination`	string, required	ID of the `Payment Instrument` where funds will be sent
`idempotency_id`	string, optional	A randomly generated value that gets tied with the request.
`operation_key`	string, required	Details what specific `Transfer` will occur. Available options inlcude: PUSH_TO_ACH PULL_FROM_ACH Use `PUSH_TO_ACH` for Bank Payouts.
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers)

Bank Payouts

Step 1: Create a Recipient Identity

Step 2: Create a Payment Instrument for the Recipient

attention

Step 3: Verify and Onboard the Recipient

HTTP Request

Request Arguments

Step 4: Create a Bank Payout

HTTP Request

Request Arguments

Next Steps

Card Payouts

Verification Requirements