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

Field	Type	Description
`identity_roles`	array, required	Role of the `Identity`. For Payouts, always use RECIPIENT
`email`	string, optional	The email address of the recipient where they can be reached (max 100 characters).
`first_name`	string, required	The legal first name of the recipient (max 20 characters).
`last_name`	string, required	The legal last name of the recipient (max 20 characters).
`personal_address`	object, required	Recipient's shipping address or billing address.
`phone`	string, optional	Phone number where the recipient can be reached.
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers)

Address-object Request Arguments

Field	Type	Description
`city`	string, required	City (max 20 characters).
`country`	string, required	3-Letter Country code.
`line1`	string, required	First line of the address (max 35 characters).
`line2`	string, required	Second line of the address (max 35 characters).
`postal_code`	string, required	Zip or Postal code (max 7 characters).
`region`	string, required	2-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

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

HTTP Request

Request Arguments

Address-object Request Arguments

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 Payout

Verification Requirements