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.An Identity resource represents either a person or a business. The Identity resource helps manage bank accounts, cards, payout history, and the details of your customers.

Finix also uses this information as part of Know Your Customer (KYC) verification procedures. For more information, see Verification Requirements.

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u US9bhCUqoTxo7V6di8ceb3Td:e704591a-1972-4b41-9884-6a67f5d7cdbb \
    -d '{
    "identity_roles" : ["RECIPIENT"],
    "entity": {
      "phone": "7145677613",
      "first_name": "John",
      "last_name": "Smith",
      "email": "example@finix.com",
      "personal_address": {
        "city": "San Mateo",
        "country": "USA",
        "region": "CA",
        "line2": "Apartment 7",
        "line1": "741 Douglass St",
        "postal_code": "94114"
      }
    },
    "tags": {
      "key": "value"
    }
  }'

Example Response

Copy
Copied
{
  "id" : "ID4a4cYBQU1NoS25b7J7FLBe",
  "created_at" : "2023-12-07T17:53:05.22Z",
  "updated_at" : "2023-12-07T17:53:05.22Z",
  "application" : "AP5Tq3MMxKwHYX7soDncrCQ3",
  "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" : "example@finix.com",
    "first_name" : "John",
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "last_name" : "Smith",
    "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" : [ "RECIPIENT" ],
  "tags" : {
    "key" : "value"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/ID4a4cYBQU1NoS25b7J7FLBe/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/AP5Tq3MMxKwHYX7soDncrCQ3"
    }
  }
}

HTTP Request

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

Request Arguments

FieldTypeDescription
identity_rolesarray, requiredRole of the Identity. For Payouts, always use RECIPIENT
emailstring, optionalThe email address of the recipient where they can be reached (max 100 characters).
first_namestring, requiredThe legal first name of the recipient (max 20 characters).
last_namestring, requiredThe legal last name of the recipient (max 20 characters).
personal_addressobject, requiredRecipient's shipping address or billing address.
phonestring, optionalPhone number where the recipient can be reached.
tagsobject, optionalKey value pair for annotating custom metadata (e.g. order numbers)

Address-object Request Arguments

FieldTypeDescription
citystring, requiredCity (max 20 characters).
countrystring, required3-Letter Country code.
line1string, requiredFirst line of the address (max 35 characters).
line2string, requiredSecond line of the address (max 35 characters).
postal_codestring, requiredZip or Postal code (max 7 characters).
regionstring, required2-letter State code.

Step 2: Create a Payment Instrument for the Recipient

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.
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.
If you have any questions about creating Payment Instruments, reach out to your Finix Point of Contact or Finix Support.
Tokenize via APITokenize using 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_token_id}",
      "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

FieldTypeDescription
processorstring, optionalName 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)

The response above means the funds were successfully sent, and the funds will soon be ready to get paid out to the recipient.

Next Steps