Skip to main content
POST
Send an International Payout

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Customer-facing request body for POST .../international/payouts.

The customer pre-creates the payee and its bank destination via the Finogates resource APIs (/payees and /payees/bank-accounts/{payee_id}), then references them here by ID. The sender, the recipient's full details, and bank-info fields are resolved internally from those records and from the platform's configured Sender Defaults.

payeeId
string<uuid>
required

ID of a Finogates-managed payee (created via the payees API).

walletId
string<uuid>
required

ID of the wallet to debit for this payout. Required — there is no implicit default wallet. The wallet must belong to your platform and its currency must match sourceCurrency.

amount
required

Amount in sourceCurrency to debit from your wallet.

Required range: x > 0
sourceCurrency
string
required

ISO-4217 funding-side currency (e.g. USD).

Required string length: 3
destinationCurrency
string
required

ISO-4217 recipient-side currency (e.g. INR).

Required string length: 3
destinationId
string<uuid> | null

ID of a bank destination that belongs to payeeId. Optional — when omitted the server uses the payee's sole active bank destination. Required only when the payee owns multiple banks.

addressId
string<uuid> | null

ID of an address that belongs to payeeId (created via the payee addresses API). Required only for destinations whose corridor mandates the recipient's address, phone, or ID document — the payout is rejected without it there, and rejected if its country does not match the payout's destination country. Optional for corridors that need none of those. When supplied, the recipient's address / phone / document for this payout are taken from this record; one payee can hold a different address per destination country.

fromHold
boolean
default:false

Draw this payout from the wallet's frozen (held) funds instead of its available balance. The held balance must cover the amount plus any payer-borne fee, or the request is rejected with insufficient_held_funds. Omit for a normal payout from available balance.

reference
string | null

Customer-supplied reference / idempotency anchor. Auto-generated when omitted.

Maximum string length: 32
payoutBranchId
integer | null

Optional fallback for the destination branch id. The canonical place to store this is on the bank destination itself (payout_branch_id set when adding the bank destination via POST .../payees/bank-accounts/{payee_id}); supply it here only when the destination predates that field — newer registrations have it stored and Finogates resolves the routing automatically.

Required range: x >= 1

Response

Successful Response

Standard response wrapper for single-object responses and errors.

Generic over the payload type. A route that declares CommonResponse[SomeModel] gets the real data schema rendered in OpenAPI/Swagger; a bare CommonResponse leaves data untyped.

status_code
integer
required

HTTP status code for the response.

data
any
required

Payload or error details.

query_generated_time
integer
required

UTC timestamp (milliseconds since epoch) when response was generated.