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 anIdentity
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 |
---|---|---|
Typetype | ✅ Required | ✅ Required |
First Namefirst_name | ✅ Required | ✅ Required |
Last Namelast_name | ✅ Required | ✅ Required |
Personal Addresspersonal_address | ✅ Required | ✅ Required |
Business Namebusiness_name | 🚫 Invalid | ✅ Required |
Doing Business Asdoing_business_as | 🚫 Invalid | ✅ Required |
Business Addressbusiness_address | 🚫 Invalid | ✅ Required |
Business Phonebusiness_phone | 🚫 Invalid | 🟡 Optional |
Personal Emailemail | 🟡 Optional | 🟡 Optional |
Personal Phonephone | 🟡 Optional | 🟡 Optional |
Personal RecipientBusiness Recipient
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"
}
}
}'
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
{
"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"
}
}
}
{
"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.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
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
}'
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
{
"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" : {}
{
"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 aPayment 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.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:
{
"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 aTransfer
. 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 thedestination
. - 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
.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:
{
"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 for Bank Payouts. |
tags | object, optional | Key value pair for annotating custom metadata (e.g. order numbers) |