Send an International Payout (full payload)
curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/international/payouts/global \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"orderPartnerID": "<string>",
"orderCurrency": "<string>",
"orderAmount": 500000000000,
"payoutBranchID": 2,
"payoutCurrency": "<string>",
"beneficiary": {
"firstName": "<string>",
"lastName": "<string>",
"phone": "<string>",
"nationality": "<string>",
"address": {
"state": "<string>",
"city": "<string>",
"streetAndNumber": "<string>",
"country": "<string>",
"postalCode": "<string>"
},
"document": {
"type": "<string>",
"number": "<string>",
"issueCountry": "<string>"
}
},
"bankInfo": {
"bankAccount": "<string>",
"bankAccType": "<string>",
"bankBranch": "<string>",
"bankDocument": "<string>"
},
"paymentCategory": 1,
"walletId": "<string>",
"payoutAmount": 123,
"fromHold": false,
"meta_data": {}
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/international/payouts/global"
payload = {
"orderPartnerID": "<string>",
"orderCurrency": "<string>",
"orderAmount": 500000000000,
"payoutBranchID": 2,
"payoutCurrency": "<string>",
"beneficiary": {
"firstName": "<string>",
"lastName": "<string>",
"phone": "<string>",
"nationality": "<string>",
"address": {
"state": "<string>",
"city": "<string>",
"streetAndNumber": "<string>",
"country": "<string>",
"postalCode": "<string>"
},
"document": {
"type": "<string>",
"number": "<string>",
"issueCountry": "<string>"
}
},
"bankInfo": {
"bankAccount": "<string>",
"bankAccType": "<string>",
"bankBranch": "<string>",
"bankDocument": "<string>"
},
"paymentCategory": 1,
"walletId": "<string>",
"payoutAmount": 123,
"fromHold": False,
"meta_data": {}
}
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({
orderPartnerID: '<string>',
orderCurrency: '<string>',
orderAmount: 500000000000,
payoutBranchID: 2,
payoutCurrency: '<string>',
beneficiary: {
firstName: '<string>',
lastName: '<string>',
phone: '<string>',
nationality: '<string>',
address: {
state: '<string>',
city: '<string>',
streetAndNumber: '<string>',
country: '<string>',
postalCode: '<string>'
},
document: {type: '<string>', number: '<string>', issueCountry: '<string>'}
},
bankInfo: {
bankAccount: '<string>',
bankAccType: '<string>',
bankBranch: '<string>',
bankDocument: '<string>'
},
paymentCategory: 1,
walletId: '<string>',
payoutAmount: 123,
fromHold: false,
meta_data: {}
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/international/payouts/global', 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/global",
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([
'orderPartnerID' => '<string>',
'orderCurrency' => '<string>',
'orderAmount' => 500000000000,
'payoutBranchID' => 2,
'payoutCurrency' => '<string>',
'beneficiary' => [
'firstName' => '<string>',
'lastName' => '<string>',
'phone' => '<string>',
'nationality' => '<string>',
'address' => [
'state' => '<string>',
'city' => '<string>',
'streetAndNumber' => '<string>',
'country' => '<string>',
'postalCode' => '<string>'
],
'document' => [
'type' => '<string>',
'number' => '<string>',
'issueCountry' => '<string>'
]
],
'bankInfo' => [
'bankAccount' => '<string>',
'bankAccType' => '<string>',
'bankBranch' => '<string>',
'bankDocument' => '<string>'
],
'paymentCategory' => 1,
'walletId' => '<string>',
'payoutAmount' => 123,
'fromHold' => false,
'meta_data' => [
]
]),
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/global"
payload := strings.NewReader("{\n \"orderPartnerID\": \"<string>\",\n \"orderCurrency\": \"<string>\",\n \"orderAmount\": 500000000000,\n \"payoutBranchID\": 2,\n \"payoutCurrency\": \"<string>\",\n \"beneficiary\": {\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"nationality\": \"<string>\",\n \"address\": {\n \"state\": \"<string>\",\n \"city\": \"<string>\",\n \"streetAndNumber\": \"<string>\",\n \"country\": \"<string>\",\n \"postalCode\": \"<string>\"\n },\n \"document\": {\n \"type\": \"<string>\",\n \"number\": \"<string>\",\n \"issueCountry\": \"<string>\"\n }\n },\n \"bankInfo\": {\n \"bankAccount\": \"<string>\",\n \"bankAccType\": \"<string>\",\n \"bankBranch\": \"<string>\",\n \"bankDocument\": \"<string>\"\n },\n \"paymentCategory\": 1,\n \"walletId\": \"<string>\",\n \"payoutAmount\": 123,\n \"fromHold\": false,\n \"meta_data\": {}\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/global")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"orderPartnerID\": \"<string>\",\n \"orderCurrency\": \"<string>\",\n \"orderAmount\": 500000000000,\n \"payoutBranchID\": 2,\n \"payoutCurrency\": \"<string>\",\n \"beneficiary\": {\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"nationality\": \"<string>\",\n \"address\": {\n \"state\": \"<string>\",\n \"city\": \"<string>\",\n \"streetAndNumber\": \"<string>\",\n \"country\": \"<string>\",\n \"postalCode\": \"<string>\"\n },\n \"document\": {\n \"type\": \"<string>\",\n \"number\": \"<string>\",\n \"issueCountry\": \"<string>\"\n }\n },\n \"bankInfo\": {\n \"bankAccount\": \"<string>\",\n \"bankAccType\": \"<string>\",\n \"bankBranch\": \"<string>\",\n \"bankDocument\": \"<string>\"\n },\n \"paymentCategory\": 1,\n \"walletId\": \"<string>\",\n \"payoutAmount\": 123,\n \"fromHold\": false,\n \"meta_data\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/international/payouts/global")
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 \"orderPartnerID\": \"<string>\",\n \"orderCurrency\": \"<string>\",\n \"orderAmount\": 500000000000,\n \"payoutBranchID\": 2,\n \"payoutCurrency\": \"<string>\",\n \"beneficiary\": {\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"nationality\": \"<string>\",\n \"address\": {\n \"state\": \"<string>\",\n \"city\": \"<string>\",\n \"streetAndNumber\": \"<string>\",\n \"country\": \"<string>\",\n \"postalCode\": \"<string>\"\n },\n \"document\": {\n \"type\": \"<string>\",\n \"number\": \"<string>\",\n \"issueCountry\": \"<string>\"\n }\n },\n \"bankInfo\": {\n \"bankAccount\": \"<string>\",\n \"bankAccType\": \"<string>\",\n \"bankBranch\": \"<string>\",\n \"bankDocument\": \"<string>\"\n },\n \"paymentCategory\": 1,\n \"walletId\": \"<string>\",\n \"payoutAmount\": 123,\n \"fromHold\": false,\n \"meta_data\": {}\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 (Full Payload)
Send money abroad by submitting the full payout details in one call.
Unlike POST /payouts — which references a recipient you created earlier
by id — this endpoint accepts the recipient and their bank account inline,
so you don’t have to pre-register them. Send the order details
(orderPartnerID, orderCurrency, orderAmount, payoutCurrency,
payoutBranchID), the recipient (beneficiary), the recipient’s bank
(bankInfo), and the walletId to debit.
Your sender details are configured for your platform by the Finogate team and are applied automatically — you never send them.
The payout is created held for review and is submitted only after a Finogate operator approves it.
POST
/
v1
/
platform
/
international
/
payouts
/
global
Send an International Payout (full payload)
curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/international/payouts/global \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"orderPartnerID": "<string>",
"orderCurrency": "<string>",
"orderAmount": 500000000000,
"payoutBranchID": 2,
"payoutCurrency": "<string>",
"beneficiary": {
"firstName": "<string>",
"lastName": "<string>",
"phone": "<string>",
"nationality": "<string>",
"address": {
"state": "<string>",
"city": "<string>",
"streetAndNumber": "<string>",
"country": "<string>",
"postalCode": "<string>"
},
"document": {
"type": "<string>",
"number": "<string>",
"issueCountry": "<string>"
}
},
"bankInfo": {
"bankAccount": "<string>",
"bankAccType": "<string>",
"bankBranch": "<string>",
"bankDocument": "<string>"
},
"paymentCategory": 1,
"walletId": "<string>",
"payoutAmount": 123,
"fromHold": false,
"meta_data": {}
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/international/payouts/global"
payload = {
"orderPartnerID": "<string>",
"orderCurrency": "<string>",
"orderAmount": 500000000000,
"payoutBranchID": 2,
"payoutCurrency": "<string>",
"beneficiary": {
"firstName": "<string>",
"lastName": "<string>",
"phone": "<string>",
"nationality": "<string>",
"address": {
"state": "<string>",
"city": "<string>",
"streetAndNumber": "<string>",
"country": "<string>",
"postalCode": "<string>"
},
"document": {
"type": "<string>",
"number": "<string>",
"issueCountry": "<string>"
}
},
"bankInfo": {
"bankAccount": "<string>",
"bankAccType": "<string>",
"bankBranch": "<string>",
"bankDocument": "<string>"
},
"paymentCategory": 1,
"walletId": "<string>",
"payoutAmount": 123,
"fromHold": False,
"meta_data": {}
}
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({
orderPartnerID: '<string>',
orderCurrency: '<string>',
orderAmount: 500000000000,
payoutBranchID: 2,
payoutCurrency: '<string>',
beneficiary: {
firstName: '<string>',
lastName: '<string>',
phone: '<string>',
nationality: '<string>',
address: {
state: '<string>',
city: '<string>',
streetAndNumber: '<string>',
country: '<string>',
postalCode: '<string>'
},
document: {type: '<string>', number: '<string>', issueCountry: '<string>'}
},
bankInfo: {
bankAccount: '<string>',
bankAccType: '<string>',
bankBranch: '<string>',
bankDocument: '<string>'
},
paymentCategory: 1,
walletId: '<string>',
payoutAmount: 123,
fromHold: false,
meta_data: {}
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/international/payouts/global', 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/global",
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([
'orderPartnerID' => '<string>',
'orderCurrency' => '<string>',
'orderAmount' => 500000000000,
'payoutBranchID' => 2,
'payoutCurrency' => '<string>',
'beneficiary' => [
'firstName' => '<string>',
'lastName' => '<string>',
'phone' => '<string>',
'nationality' => '<string>',
'address' => [
'state' => '<string>',
'city' => '<string>',
'streetAndNumber' => '<string>',
'country' => '<string>',
'postalCode' => '<string>'
],
'document' => [
'type' => '<string>',
'number' => '<string>',
'issueCountry' => '<string>'
]
],
'bankInfo' => [
'bankAccount' => '<string>',
'bankAccType' => '<string>',
'bankBranch' => '<string>',
'bankDocument' => '<string>'
],
'paymentCategory' => 1,
'walletId' => '<string>',
'payoutAmount' => 123,
'fromHold' => false,
'meta_data' => [
]
]),
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/global"
payload := strings.NewReader("{\n \"orderPartnerID\": \"<string>\",\n \"orderCurrency\": \"<string>\",\n \"orderAmount\": 500000000000,\n \"payoutBranchID\": 2,\n \"payoutCurrency\": \"<string>\",\n \"beneficiary\": {\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"nationality\": \"<string>\",\n \"address\": {\n \"state\": \"<string>\",\n \"city\": \"<string>\",\n \"streetAndNumber\": \"<string>\",\n \"country\": \"<string>\",\n \"postalCode\": \"<string>\"\n },\n \"document\": {\n \"type\": \"<string>\",\n \"number\": \"<string>\",\n \"issueCountry\": \"<string>\"\n }\n },\n \"bankInfo\": {\n \"bankAccount\": \"<string>\",\n \"bankAccType\": \"<string>\",\n \"bankBranch\": \"<string>\",\n \"bankDocument\": \"<string>\"\n },\n \"paymentCategory\": 1,\n \"walletId\": \"<string>\",\n \"payoutAmount\": 123,\n \"fromHold\": false,\n \"meta_data\": {}\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/global")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"orderPartnerID\": \"<string>\",\n \"orderCurrency\": \"<string>\",\n \"orderAmount\": 500000000000,\n \"payoutBranchID\": 2,\n \"payoutCurrency\": \"<string>\",\n \"beneficiary\": {\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"nationality\": \"<string>\",\n \"address\": {\n \"state\": \"<string>\",\n \"city\": \"<string>\",\n \"streetAndNumber\": \"<string>\",\n \"country\": \"<string>\",\n \"postalCode\": \"<string>\"\n },\n \"document\": {\n \"type\": \"<string>\",\n \"number\": \"<string>\",\n \"issueCountry\": \"<string>\"\n }\n },\n \"bankInfo\": {\n \"bankAccount\": \"<string>\",\n \"bankAccType\": \"<string>\",\n \"bankBranch\": \"<string>\",\n \"bankDocument\": \"<string>\"\n },\n \"paymentCategory\": 1,\n \"walletId\": \"<string>\",\n \"payoutAmount\": 123,\n \"fromHold\": false,\n \"meta_data\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/international/payouts/global")
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 \"orderPartnerID\": \"<string>\",\n \"orderCurrency\": \"<string>\",\n \"orderAmount\": 500000000000,\n \"payoutBranchID\": 2,\n \"payoutCurrency\": \"<string>\",\n \"beneficiary\": {\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"phone\": \"<string>\",\n \"nationality\": \"<string>\",\n \"address\": {\n \"state\": \"<string>\",\n \"city\": \"<string>\",\n \"streetAndNumber\": \"<string>\",\n \"country\": \"<string>\",\n \"postalCode\": \"<string>\"\n },\n \"document\": {\n \"type\": \"<string>\",\n \"number\": \"<string>\",\n \"issueCountry\": \"<string>\"\n }\n },\n \"bankInfo\": {\n \"bankAccount\": \"<string>\",\n \"bankAccType\": \"<string>\",\n \"bankBranch\": \"<string>\",\n \"bankDocument\": \"<string>\"\n },\n \"paymentCategory\": 1,\n \"walletId\": \"<string>\",\n \"payoutAmount\": 123,\n \"fromHold\": false,\n \"meta_data\": {}\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
application/json
Full inline payout payload for the global international payout endpoint.
Your reference for this payout. Doubles as the idempotency anchor, so it must not be empty — an empty reference would disable duplicate detection. 1–32 characters, letters and numbers only (no spaces, hyphens, underscores or other special characters). Must be unique per payout (a repeat is rejected as a duplicate).
Required string length:
1 - 32ISO-4217 funding-side currency (e.g. USD).
Required string length:
3Amount in orderCurrency to debit from your wallet. Must be positive; values of 1,000,000,000,000 or greater are rejected (the amount is stored in integer minor units and an unbounded value would overflow that column).
Required range:
0 < x < 1000000000000Destination collection branch id. Required — it identifies the payer and corridor used to route the payout and to validate the recipient against that payer's mandatory fields. Get one from GET /v1/platform/international/branches.
Required range:
x >= 1ISO-4217 recipient-side currency (e.g. INR).
Required string length:
3Show child attributes
Show child attributes
Show child attributes
Show child attributes
Optional. The payment category code to tag this payment with, recording what the payment was for. Omit it and the payment is created exactly as before, untagged. If you do send one it must be a code your platform can currently use, otherwise the request is rejected and no money moves. Fetch the codes from GET /v1/platform/catalog/payment-categories. Codes are issued separately in test and live, so read the list in each mode — the same number does not mean the same category across them.
Required range:
x > 0Example:
1
Optional. ID of the wallet to debit. Omit it to fund the payout from your platform's master wallet for orderCurrency — the recipient is not one of your users, so the payout draws on your platform balance by default. When supplied, the wallet must belong to your platform and its currency must match orderCurrency.
Pre-quoted amount in payoutCurrency. Derived from the live FX rate when omitted.
Draw this payout from the wallet's frozen (held) funds instead of its available balance. The held balance must cover the order amount plus any fee, or the request is rejected with insufficient_held_funds. Omit for a normal payout from available balance.
Optional free-form JSON object stored for your own reference only. It is persisted verbatim with the payout and is never sent to the payout provider — use it to attach your own bookkeeping (order ids, notes, internal tags).
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.