curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/payees/addresses/{payee_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"label": "Home — Guadalajara",
"line1": "Av. Vallarta 1234",
"city": "Guadalajara",
"state": "Jalisco",
"postal_code": "44100",
"country": "MX",
"phone": "+523312345678",
"doc_number": "GORA850315HJCXYZ01",
"doc_type": "CURP",
"doc_issue_country": "MX",
"purposes": [
"international"
],
"is_default": true
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/payees/addresses/{payee_id}"
payload = {
"label": "Home — Guadalajara",
"line1": "Av. Vallarta 1234",
"city": "Guadalajara",
"state": "Jalisco",
"postal_code": "44100",
"country": "MX",
"phone": "+523312345678",
"doc_number": "GORA850315HJCXYZ01",
"doc_type": "CURP",
"doc_issue_country": "MX",
"purposes": ["international"],
"is_default": True
}
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({
label: 'Home — Guadalajara',
line1: 'Av. Vallarta 1234',
city: 'Guadalajara',
state: 'Jalisco',
postal_code: '44100',
country: 'MX',
phone: '+523312345678',
doc_number: 'GORA850315HJCXYZ01',
doc_type: 'CURP',
doc_issue_country: 'MX',
purposes: ['international'],
is_default: true
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/payees/addresses/{payee_id}', 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/payees/addresses/{payee_id}",
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([
'label' => 'Home — Guadalajara',
'line1' => 'Av. Vallarta 1234',
'city' => 'Guadalajara',
'state' => 'Jalisco',
'postal_code' => '44100',
'country' => 'MX',
'phone' => '+523312345678',
'doc_number' => 'GORA850315HJCXYZ01',
'doc_type' => 'CURP',
'doc_issue_country' => 'MX',
'purposes' => [
'international'
],
'is_default' => true
]),
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/payees/addresses/{payee_id}"
payload := strings.NewReader("{\n \"label\": \"Home — Guadalajara\",\n \"line1\": \"Av. Vallarta 1234\",\n \"city\": \"Guadalajara\",\n \"state\": \"Jalisco\",\n \"postal_code\": \"44100\",\n \"country\": \"MX\",\n \"phone\": \"+523312345678\",\n \"doc_number\": \"GORA850315HJCXYZ01\",\n \"doc_type\": \"CURP\",\n \"doc_issue_country\": \"MX\",\n \"purposes\": [\n \"international\"\n ],\n \"is_default\": true\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/payees/addresses/{payee_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"Home — Guadalajara\",\n \"line1\": \"Av. Vallarta 1234\",\n \"city\": \"Guadalajara\",\n \"state\": \"Jalisco\",\n \"postal_code\": \"44100\",\n \"country\": \"MX\",\n \"phone\": \"+523312345678\",\n \"doc_number\": \"GORA850315HJCXYZ01\",\n \"doc_type\": \"CURP\",\n \"doc_issue_country\": \"MX\",\n \"purposes\": [\n \"international\"\n ],\n \"is_default\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/payees/addresses/{payee_id}")
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 \"label\": \"Home — Guadalajara\",\n \"line1\": \"Av. Vallarta 1234\",\n \"city\": \"Guadalajara\",\n \"state\": \"Jalisco\",\n \"postal_code\": \"44100\",\n \"country\": \"MX\",\n \"phone\": \"+523312345678\",\n \"doc_number\": \"GORA850315HJCXYZ01\",\n \"doc_type\": \"CURP\",\n \"doc_issue_country\": \"MX\",\n \"purposes\": [\n \"international\"\n ],\n \"is_default\": true\n}"
response = http.request(request)
puts response.read_body{
"status_code": 123,
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "<string>",
"label": "<string>",
"address_type": "<string>",
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>",
"phone": "<string>",
"doc_number": "<string>",
"doc_type": "<string>",
"doc_issue_country": "<string>",
"doc_issue_date": "<string>",
"doc_due_date": "<string>",
"doc_issuer": "<string>",
"is_default": false,
"purposes": [
"<string>"
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
},
"query_generated_time": 123
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Add an Address to a Payee
Save an address for a payee. A payee can hold more than one per destination country.
country (ISO 3166-1 alpha-2, e.g. MX, IN, AE) is required. When you send an international payout you reference the address by its ID; its country must match the payout’s destination country and it must carry every field that corridor requires, or the payout is rejected.
purposes is also required — one or more product keys naming what this address may be used for. Fetch the keys your platform can use from GET /v1/platform/payees/address-purposes.
Only one live address per country may carry the international purpose. Adding a second one for a country that already has one returns 409 international_address_conflict, naming the existing address’s ID. Resubmit with on_international_conflict set to replace (the existing address loses the international purpose, or is revoked outright if that was its only one) or keep (the existing address is untouched and international is dropped from this one — it must have at least one other purpose, or the request is rejected).
curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/payees/addresses/{payee_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"label": "Home — Guadalajara",
"line1": "Av. Vallarta 1234",
"city": "Guadalajara",
"state": "Jalisco",
"postal_code": "44100",
"country": "MX",
"phone": "+523312345678",
"doc_number": "GORA850315HJCXYZ01",
"doc_type": "CURP",
"doc_issue_country": "MX",
"purposes": [
"international"
],
"is_default": true
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/payees/addresses/{payee_id}"
payload = {
"label": "Home — Guadalajara",
"line1": "Av. Vallarta 1234",
"city": "Guadalajara",
"state": "Jalisco",
"postal_code": "44100",
"country": "MX",
"phone": "+523312345678",
"doc_number": "GORA850315HJCXYZ01",
"doc_type": "CURP",
"doc_issue_country": "MX",
"purposes": ["international"],
"is_default": True
}
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({
label: 'Home — Guadalajara',
line1: 'Av. Vallarta 1234',
city: 'Guadalajara',
state: 'Jalisco',
postal_code: '44100',
country: 'MX',
phone: '+523312345678',
doc_number: 'GORA850315HJCXYZ01',
doc_type: 'CURP',
doc_issue_country: 'MX',
purposes: ['international'],
is_default: true
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/payees/addresses/{payee_id}', 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/payees/addresses/{payee_id}",
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([
'label' => 'Home — Guadalajara',
'line1' => 'Av. Vallarta 1234',
'city' => 'Guadalajara',
'state' => 'Jalisco',
'postal_code' => '44100',
'country' => 'MX',
'phone' => '+523312345678',
'doc_number' => 'GORA850315HJCXYZ01',
'doc_type' => 'CURP',
'doc_issue_country' => 'MX',
'purposes' => [
'international'
],
'is_default' => true
]),
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/payees/addresses/{payee_id}"
payload := strings.NewReader("{\n \"label\": \"Home — Guadalajara\",\n \"line1\": \"Av. Vallarta 1234\",\n \"city\": \"Guadalajara\",\n \"state\": \"Jalisco\",\n \"postal_code\": \"44100\",\n \"country\": \"MX\",\n \"phone\": \"+523312345678\",\n \"doc_number\": \"GORA850315HJCXYZ01\",\n \"doc_type\": \"CURP\",\n \"doc_issue_country\": \"MX\",\n \"purposes\": [\n \"international\"\n ],\n \"is_default\": true\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/payees/addresses/{payee_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"Home — Guadalajara\",\n \"line1\": \"Av. Vallarta 1234\",\n \"city\": \"Guadalajara\",\n \"state\": \"Jalisco\",\n \"postal_code\": \"44100\",\n \"country\": \"MX\",\n \"phone\": \"+523312345678\",\n \"doc_number\": \"GORA850315HJCXYZ01\",\n \"doc_type\": \"CURP\",\n \"doc_issue_country\": \"MX\",\n \"purposes\": [\n \"international\"\n ],\n \"is_default\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/payees/addresses/{payee_id}")
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 \"label\": \"Home — Guadalajara\",\n \"line1\": \"Av. Vallarta 1234\",\n \"city\": \"Guadalajara\",\n \"state\": \"Jalisco\",\n \"postal_code\": \"44100\",\n \"country\": \"MX\",\n \"phone\": \"+523312345678\",\n \"doc_number\": \"GORA850315HJCXYZ01\",\n \"doc_type\": \"CURP\",\n \"doc_issue_country\": \"MX\",\n \"purposes\": [\n \"international\"\n ],\n \"is_default\": true\n}"
response = http.request(request)
puts response.read_body{
"status_code": 123,
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "<string>",
"label": "<string>",
"address_type": "<string>",
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>",
"phone": "<string>",
"doc_number": "<string>",
"doc_type": "<string>",
"doc_issue_country": "<string>",
"doc_issue_date": "<string>",
"doc_due_date": "<string>",
"doc_issuer": "<string>",
"is_default": false,
"purposes": [
"<string>"
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
},
"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.
Path Parameters
Query Parameters
The unique ID of the user who owns this payee.
"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4"
Body
Create a payee address.
country (ISO 3166-1 alpha-2) is required — it is the key an
international payout matches against the resolved destination country, so an
address with no country could never be used for one. line1 is required
too: a saved "address" with no street is not usable for a mailed check or a
payout's beneficiary block.
Street and number.
255ISO 3166-1 alpha-2 country code, e.g. MX, IN, AE.
Which of your enabled products this address may be used for (e.g. document_mailing, international). At least one is required — fetch the allowed set from GET .../payees/address-purposes.
112030255120120204010050102020255Only meaningful when purposes includes international and this payee already has a different address for the same country tagged international — at most one address per (payee, country) may carry that purpose. Omit on the first attempt: if a conflict exists the request is rejected with international_address_conflict naming the existing address, and you resubmit with this field set. replace drops the international purpose from the existing address (revoking it entirely if that was its only purpose) and gives it to this one. keep leaves the existing address untouched and saves this one for its other purposes only — international is dropped from this address's purposes, so at least one other purpose must be selected or the request is rejected.
replace, keep 
