A payout pays a beneficiary in their local currency. Fin.com offers two settlement methods, and the one that applies is decided when the beneficiary is created rather than when you send the money. This guide covers what you need in place first, how each method works, and how to follow a payout through to completion.
Everything here follows on from Beneficiary onboarding. If you have not created a beneficiary yet, start there.
Prerequisites
A newly created beneficiary starts in PROCESSING with active = true. It cannot receive a payout until Fin.com moves it to ACTIVE. Listen for the Beneficiary Status webhook rather than sending funds and hoping. A REJECTED beneficiary cannot transact at all: create a new one. Preview what the payout will cost before you send it with Calculate Exchange Rates. Pass beneficiary_id to get a developer-fee-aware calculation. Your developer_fee on the beneficiary applies as fixed plus (percentage × payout amount). Which modality applies to you
The transfer modality depends on whether the beneficiary was created with settlement_config.auto_settlement set to true or false.
settlement_config is optional at Create Beneficiary. Skip it and auto_settlement is set to true automatically, so a beneficiary created without it settles automatically. The value is returned on the beneficiary record, so check it there if you are unsure which method a given beneficiary uses.
One exception overrides the field. If you maintain prefunded balances with Fin.com, you must always trigger payouts programmatically, regardless of the beneficiary’s auto_settlement value. Use the without auto-settlement flow below.
With auto-settlement
Without auto-settlement
auto_settlement: true. Fin.com initiates the fiat payout automatically when crypto is received in the beneficiary’s liquidation address. There is no payout endpoint to call: funding the address is the instruction to pay.How it works
Read the liquidation address
Fetch the beneficiary and take deposit_instruction.liquidation_address, along with the currency and rail it was configured for. Send USDC to it
Send the payout amount to that address on the rail the beneficiary was created with.
Fin.com confirms the deposit
The beneficiary.liquidation.deposit webhook fires when funds hit the liquidation address, carrying the amount, the liquidation_address, and the on-chain txn_hash. See Beneficiary Liquidation Deposit. The payout settles on its own
Fin.com converts the deposit and pays the beneficiary. Nothing further is required from you.
This method only applies when you are funding each payout with crypto. If you hold a prefunded balance with Fin.com, payouts must be triggered programmatically even for a beneficiary created with auto_settlement: true.
auto_settlement: false. Fin.com holds the crypto in the liquidation address until you trigger the payout. Use this when you need control over timing, when you are paying many beneficiaries at once, or whenever you are drawing on a prefunded balance.Single payout
Create the transfer
Call Create a Transfer V2 with the beneficiary_id, your own reference_id, the amount, source_currency, deduct_from, and remarks. Send exactly one of source_amount or destination_amount, never both. Amounts are integers in cents, and source_amount has a minimum of 500 cents. Documents you uploaded against the beneficiary can be carried through here in the attachments array.Nothing moves at this point. The response returns a transfer_id and a quotation showing what the beneficiary receives. Settle it
Call Settle a Transfer V2 with the transfer_id. This is the call that releases the payout, and it returns the transaction_id the payout is tracked under. Choosing where the funds come from
You decide which source each payout draws on with the deduct_from field on Create a Transfer V2.Only PREFUNDED_BALANCE transfers are eligible for refunds if they fail. Weigh that when choosing the source.
Many payouts at once
Use Execute Batch Transfer in place of the create and settle pair. Each item reports separately on batch.transaction.item.status, so the outcome of one item tells you nothing about the rest. Check progress with Fetch Batch Details.V1 remains available at Create a Transfer and Settle a Transfer for integrations already built on it. V1 takes a single amount and offers no source_currency or deduct_from, so the choice of funding source is V2 only. A transfer created on V2 must be settled on V2. Tracking the payout
All webhook payloads carry HMAC signatures. See Verifying webhooks and Transaction Status.
If a payout fails, funds are returned to the refund_instruction wallet you set on the beneficiary. 
