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",
"addressId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"fromHold": false,
"reference": "<string>",
"payoutBranchId": 2
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/international/payouts"
payload = {
"payeeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 1,
"sourceCurrency": "<string>",
"destinationCurrency": "<string>",
"destinationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"addressId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"fromHold": False,
"reference": "<string>",
"payoutBranchId": 2
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
payeeId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
walletId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
amount: 1,
sourceCurrency: '<string>',
destinationCurrency: '<string>',
destinationId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
addressId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
fromHold: false,
reference: '<string>',
payoutBranchId: 2
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/international/payouts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.finogates.com/v1/platform/international/payouts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'payeeId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'walletId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'amount' => 1,
'sourceCurrency' => '<string>',
'destinationCurrency' => '<string>',
'destinationId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'addressId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'fromHold' => false,
'reference' => '<string>',
'payoutBranchId' => 2
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.finogates.com/v1/platform/international/payouts"
payload := strings.NewReader("{\n \"payeeId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"sourceCurrency\": \"<string>\",\n \"destinationCurrency\": \"<string>\",\n \"destinationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"addressId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"fromHold\": false,\n \"reference\": \"<string>\",\n \"payoutBranchId\": 2\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.finogates.com/v1/platform/international/payouts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"payeeId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"sourceCurrency\": \"<string>\",\n \"destinationCurrency\": \"<string>\",\n \"destinationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"addressId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"fromHold\": false,\n \"reference\": \"<string>\",\n \"payoutBranchId\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/international/payouts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"payeeId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"sourceCurrency\": \"<string>\",\n \"destinationCurrency\": \"<string>\",\n \"destinationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"addressId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"fromHold\": false,\n \"reference\": \"<string>\",\n \"payoutBranchId\": 2\n}"
response = http.request(request)
puts response.read_body{
"status_code": 123,
"data": "<unknown>",
"query_generated_time": 123
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Send an International Payout
Send money abroad to a recipient.
You only need to send the recipient’s payee id (payeeId), the bank
destination to pay into (destinationId), and the transaction details
(amount, sourceCurrency, destinationCurrency). Everything else —
the sender’s details, the recipient’s full details, the bank details, the
collection branch, and which partner delivers the money — is worked out for
you behind the scenes. Your sender details are configured for your platform
by the Finogate team.
Set up the recipient first, in two steps:
- Create the payee —
POST /v1/platform/payees(returns the payee’sid, which is thepayeeIdyou pass here). - Add their bank destination —
POST /v1/platform/payees/bank-accounts/{payee_id}(returns the destination’sid, which is thedestinationIdyou pass here). Includepayout_branch_idso the payout can be routed.
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",
"addressId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"fromHold": false,
"reference": "<string>",
"payoutBranchId": 2
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/international/payouts"
payload = {
"payeeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 1,
"sourceCurrency": "<string>",
"destinationCurrency": "<string>",
"destinationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"addressId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"fromHold": False,
"reference": "<string>",
"payoutBranchId": 2
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
payeeId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
walletId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
amount: 1,
sourceCurrency: '<string>',
destinationCurrency: '<string>',
destinationId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
addressId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
fromHold: false,
reference: '<string>',
payoutBranchId: 2
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/international/payouts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.finogates.com/v1/platform/international/payouts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'payeeId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'walletId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'amount' => 1,
'sourceCurrency' => '<string>',
'destinationCurrency' => '<string>',
'destinationId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'addressId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'fromHold' => false,
'reference' => '<string>',
'payoutBranchId' => 2
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.finogates.com/v1/platform/international/payouts"
payload := strings.NewReader("{\n \"payeeId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"sourceCurrency\": \"<string>\",\n \"destinationCurrency\": \"<string>\",\n \"destinationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"addressId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"fromHold\": false,\n \"reference\": \"<string>\",\n \"payoutBranchId\": 2\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.finogates.com/v1/platform/international/payouts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"payeeId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"sourceCurrency\": \"<string>\",\n \"destinationCurrency\": \"<string>\",\n \"destinationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"addressId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"fromHold\": false,\n \"reference\": \"<string>\",\n \"payoutBranchId\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/international/payouts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"payeeId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount\": 1,\n \"sourceCurrency\": \"<string>\",\n \"destinationCurrency\": \"<string>\",\n \"destinationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"addressId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"fromHold\": false,\n \"reference\": \"<string>\",\n \"payoutBranchId\": 2\n}"
response = http.request(request)
puts response.read_body{
"status_code": 123,
"data": "<unknown>",
"query_generated_time": 123
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Body
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.
ID of a Finogates-managed payee (created via the payees API).
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 in sourceCurrency to debit from your wallet.
x > 0ISO-4217 funding-side currency (e.g. USD).
3ISO-4217 recipient-side currency (e.g. INR).
3ID 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.
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.
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.
Customer-supplied reference / idempotency anchor. Auto-generated when omitted.
32Optional 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.
x >= 1Response
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.

