bank payouts.md

Bank Payouts

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 whom 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 Data

Required	Optional	Invalid

Field	`type: PERSONAL`	`type: 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`

API Request

Personal Recipient Recipient (Personal)

{
  "id": "IDdRDX7H6hNcm4HexJBeZVUV",
  "created_at": "2024-08-08T09:36:10.26Z",
  "updated_at": "2024-08-08T09:36:10.26Z",
  "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": "Jeremy",
    "max_transaction_amount": 0,
    "mcc": null,
    "ownership_type": null,
    "personal_address": {
      "line1": "789 Oak Drive",
      "line2": null,
      "city": "Springfield",
      "region": "IL",
      "postal_code": "62704",
      "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/IDdRDX7H6hNcm4HexJBeZVUV"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDdRDX7H6hNcm4HexJBeZVUV/verifications"
    },
    "merchants": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDdRDX7H6hNcm4HexJBeZVUV/merchants"
    },
    "settlements": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDdRDX7H6hNcm4HexJBeZVUV/settlements"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDdRDX7H6hNcm4HexJBeZVUV/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDdRDX7H6hNcm4HexJBeZVUV/transfers"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDdRDX7H6hNcm4HexJBeZVUV/payment_instruments"
    },
    "associated_identities": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDdRDX7H6hNcm4HexJBeZVUV/associated_identities"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDdRDX7H6hNcm4HexJBeZVUV/disputes"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    }
  }
}

Business Recipient Recipient (Business)

{
  "id": "IDjYHnn5kKQjpxh4gaFBih1n",
  "created_at": "2024-08-08T09:26:15.85Z",
  "updated_at": "2024-08-08T09:26:15.85Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "entity": {
    "ach_max_transaction_amount": 0,
    "amex_mid": null,
    "annual_card_volume": 0,
    "business_address": {
      "line1": "7890 Oak Drive",
      "line2": "Suite 101",
      "city": "Smalltown",
      "region": "TX",
      "postal_code": "75432",
      "country": "USA"
    },
    "business_name": "Blue Horizon Technologies",
    "business_phone": null,
    "business_tax_id_provided": false,
    "business_type": null,
    "default_statement_descriptor": null,
    "discover_mid": null,
    "dob": null,
    "doing_business_as": "B.H. Technologies",
    "email": null,
    "first_name": "John",
    "has_accepted_credit_cards_previously": false,
    "incorporation_date": null,
    "last_name": "Jeremy",
    "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/IDjYHnn5kKQjpxh4gaFBih1n"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjYHnn5kKQjpxh4gaFBih1n/verifications"
    },
    "merchants": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjYHnn5kKQjpxh4gaFBih1n/merchants"
    },
    "settlements": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjYHnn5kKQjpxh4gaFBih1n/settlements"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjYHnn5kKQjpxh4gaFBih1n/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjYHnn5kKQjpxh4gaFBih1n/transfers"
    },
    "payment_instruments": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjYHnn5kKQjpxh4gaFBih1n/payment_instruments"
    },
    "associated_identities": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjYHnn5kKQjpxh4gaFBih1n/associated_identities"
    },
    "disputes": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDjYHnn5kKQjpxh4gaFBih1n/disputes"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    }
  }
}

Step 2: Create a Payment Instrument for the Recipient

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.

Bank Account Payment Instrument - Bank Account

{
  "id": "PIkfiTDWYhQ4VbtQkC1U1ceJ",
  "created_at": "2024-06-21T04:09:03.77Z",
  "updated_at": "2024-06-21T04:09:03.77Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": null,
  "disabled_message": null,
  "enabled": true,
  "fingerprint": "FPRxpMNPZbZqVQfcHzRUJnzkR",
  "identity": "IDpYDM7J9n57q849o9E9yNrG",
  "instrument_type": "BANK_ACCOUNT",
  "account_type": "BUSINESS_CHECKING",
  "bank_account_validation_check": "NOT_ATTEMPTED",
  "bank_code": "122105278",
  "country": "USA",
  "institution_number": null,
  "masked_account_number": "XXXXXX0019",
  "name": "Smith & Associates Consulting",
  "transit_number": null,
  "tags": {},
  "third_party": null,
  "third_party_token": null,
  "type": "BANK_ACCOUNT",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/transfers"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIkfiTDWYhQ4VbtQkC1U1ceJ/verifications"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG"
    }
  }
}

Plaid Bank Account Payment Instrument - Plaid Bank Account

{
  "id": "PItvWj6QGrLbDcdLoovPhD8y",
  "created_at": "2024-08-02T04:41:32.36Z",
  "updated_at": "2024-08-02T04:41:32.36Z",
  "application": "APrMqXwT4CE9sRjtGaHcYJN7",
  "created_via": "API",
  "currency": "USD",
  "disabled_code": null,
  "disabled_message": null,
  "enabled": true,
  "fingerprint": "FPRxAutj19xH1AH6ykGx2dwa7",
  "identity": "IDeA9DMHJooeBhA5YotF7g1u",
  "instrument_type": "BANK_ACCOUNT",
  "account_type": "BUSINESS_CHECKING",
  "bank_account_validation_check": "VALID",
  "bank_code": "011401533",
  "country": "USA",
  "institution_number": null,
  "masked_account_number": "XXXXXXXXXXX0000",
  "name": "Alberta Bobbeth Charleson",
  "transit_number": null,
  "tags": {},
  "third_party": "PLAID",
  "third_party_token": "processor-sandbox-1487e3ec-fd86-40e2-b8d3-c8f260b4340c",
  "type": "BANK_ACCOUNT",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PItvWj6QGrLbDcdLoovPhD8y"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PItvWj6QGrLbDcdLoovPhD8y/authorizations"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PItvWj6QGrLbDcdLoovPhD8y/transfers"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/payment_instruments/PItvWj6QGrLbDcdLoovPhD8y/verifications"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APrMqXwT4CE9sRjtGaHcYJN7"
    },
    "identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/IDeA9DMHJooeBhA5YotF7g1u"
    }
  }
}

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.

Example API Definition Example Merchant

{
  "id": "MUeTBamsYxqr1KSnT4U2x9SP",
  "created_at": "2024-08-16T13:11:36.72Z",
  "updated_at": "2024-08-16T13:11:36.72Z",
  "application": "APgPDQrLD52TYvqazjHJJchM",
  "card_cvv_required": false,
  "card_expiration_date_required": true,
  "card_network_details": null,
  "convenience_charges_enabled": false,
  "country": "USA",
  "creating_transfer_from_report_enabled": true,
  "currencies": [
    "USD"
  ],
  "default_partial_authorization_enabled": false,
  "disbursements_ach_pull_enabled": false,
  "disbursements_ach_push_enabled": false,
  "disbursements_card_pull_enabled": false,
  "disbursements_card_push_enabled": false,
  "disbursements_same_day_ach_pull_enabled": false,
  "disbursements_same_day_ach_push_enabled": false,
  "fee_ready_to_settle_upon": "RECONCILIATION",
  "gateway": null,
  "gross_settlement_enabled": false,
  "identity": "ID6ZC4KedcaCwECQcWr7SM4m",
  "instant_payouts_card_push_enabled": false,
  "level_two_level_three_data_enabled": false,
  "loan_repayment": null,
  "mcc": "4900",
  "merchant_name": "Blue Horizon Technologies",
  "merchant_profile": "MP8aC84QAtA69Qhv6BJSyvHr",
  "mid": null,
  "onboarding_state": "PROVISIONING",
  "processing_enabled": false,
  "processor": "DUMMY_V1",
  "processor_details": {},
  "ready_to_settle_upon": "RECONCILIATION",
  "ready_to_settle_upon_delay_alignment": "NONE",
  "rent_surcharges_enabled": false,
  "settlement_enabled": false,
  "settlement_funding_identifier": "UNSET",
  "surcharges_enabled": false,
  "tags": {
    "key_2": "value_2"
  },
  "unreferenced_refund_manual_entry_enabled": false,
  "verification": "VI7jopNSiaVMXWKkhxt6dJm7",
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/merchants/MUeTBamsYxqr1KSnT4U2x9SP"
    },
    "identity": {
      "href": "https://finix.sandbox-payments-api.com/identities/ID6ZC4KedcaCwECQcWr7SM4m"
    },
    "verifications": {
      "href": "https://finix.sandbox-payments-api.com/merchants/MUeTBamsYxqr1KSnT4U2x9SP/verifications"
    },
    "merchant_profile": {
      "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MP8aC84QAtA69Qhv6BJSyvHr"
    },
    "application": {
      "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "verification": {
      "href": "https://finix.sandbox-payments-api.com/verifications/VI7jopNSiaVMXWKkhxt6dJm7"
    }
  }
}

API Definition

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.
Recommended to include an idempotency_id field in the payload. For more information, see Idempotent Requests.

Example API Definition Transfers can have two possible states: SUCCEEDED and FAILED.

Bank Payout Speeds

Finix supports two types of bank payout options:

Next Day ACH: Funds sent via Next Day ACH will be available in a customer's bank account by 9 AM in their local bank time.
Same Day ACH: Funds sent via Same Day ACH are available Same Day if sent by the cutoff times below.

Cutoff Times

The table below outlines cutoff times for Next Day ACH and Same Day ACH.

Bank Payout	Speed Finix Cutoff time	Funds in Recipient's bank account
Next Day ACH	9:30 PM ET	By 9 AM the next business day Local Time. (Can vary by bank)
Same Day ACH	11:30 AM ET	5 PM Local Time of bank
Same Day ACH	2:30 PM ET	End of processing day

Choosing Your Payout Speed

Next Day ACH

For Next Day ACH, set the operation_key to PUSH_TO_ACH.

Example API Definition

Same Day ACH

For Same Day ACH, set the operation_key to PUSH_TO_SAME_DAY_ACH.

Default Same Day ACH is not enabled by default. If you are interested in Same Day ACH, please contact your Finix representative to enable disbursements_same_day_ach_push_enabled for your Application.