Skip to main content
POST
/
v1
/
platform
/
international
/
payouts
Send an International Payout
curl --request POST \
  --url https://api-sandbox.finogates.com/v1/platform/international/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payeeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 1,
  "sourceCurrency": "<string>",
  "destinationCurrency": "<string>",
  "destinationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "destinationAmount": 123,
  "payoutBranchId": 2
}
'
{
  "status_code": 123,
  "data": "<unknown>",
  "query_generated_time": 123
}

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.

​
reference
string | null

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

Maximum string length: 32
​
destinationAmount

Pre-quoted amount in destinationCurrency. When omitted Finogates derives it from the live FX rate.

​
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.