curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/bank/add-account-connected \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
"access_token": "access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/bank/add-account-connected"
payload = {
"user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
"access_token": "access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"
}
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({
user_id: 'b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4',
access_token: 'access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37',
account_id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D'
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/bank/add-account-connected', 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/bank/add-account-connected",
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([
'user_id' => 'b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4',
'access_token' => 'access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37',
'account_id' => 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D'
]),
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/bank/add-account-connected"
payload := strings.NewReader("{\n \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n \"access_token\": \"access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37\",\n \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\"\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/bank/add-account-connected")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n \"access_token\": \"access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37\",\n \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/bank/add-account-connected")
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 \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n \"access_token\": \"access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37\",\n \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\"\n}"
response = http.request(request)
puts response.read_body{
"status_code": 123,
"data": {
"payment_method_id": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
"user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
"method_type": "bank",
"status": "active",
"user_email": "owner@example.com",
"user_name": "Jane Doe",
"nickname": "<string>",
"last4": "1111",
"brand": "Visa",
"exp_month": 12,
"exp_year": 2027,
"cardholder_first_name": "John",
"cardholder_last_name": "Doe",
"cardholder_name": "John Doe",
"card_transfer_aft_enabled": false,
"card_transfer_oct_enabled": false,
"billing_address": {
"city": "New York",
"country": "US",
"line1": "123 Main St",
"postal_code": "10001",
"state": "NY"
},
"bank_name": "Chase Bank",
"account_mask": "****7890",
"routing_last4": "0021",
"routing_number": "021000021",
"is_rtp_enabled": true,
"account_type": "checking",
"account_holder_name": "John Doe",
"bank_address": "270 Park Avenue",
"bank_city": "New York",
"bank_state": "NY",
"bank_zip": "10017",
"bank_country": "US",
"account_holder_address": "123 Main St",
"account_holder_city": "New York",
"account_holder_state": "NY",
"account_holder_zip": "10001",
"account_holder_country": "US",
"rail_code": "<string>",
"rail_capabilities": {},
"created_at": "2026-04-01T10:30:00Z"
},
"query_generated_time": 123
}{
"status_code": 201,
"data": {
"payment_method_id": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
"user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
"method_type": "bank_account",
"status": "active",
"bank_name": "Example Bank",
"account_mask": "7890",
"routing_last4": "0021",
"account_type": "checking",
"account_holder_name": "John Doe",
"rail_code": "ach",
"created_at": "2026-10-12T10:30:00Z"
},
"query_generated_time": 1791801000000
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Add a Bank Account From an Existing Connection
Add a bank account that your own app has already connected and verified, so the user does not have to connect it again. The bank account is saved as connected instantly: it can both add money and receive payouts.
Available only when this is turned on for your account — ask us. It works only for a connection your app made through the same instant bank verification account as ours.
We never take your word for the account details: we read them from the connection ourselves. The account number and routing number are stored encrypted and only ever shown masked.
What you need to send
user_id— the user this bank account belongs toaccess_token— the access token of the user’s bank connection, as your app holds itaccount_id— the one account in that connection to add
What you get back
- 201 — the bank account was added. If the user already had it, added
with its routing and account number, it is upgraded in place: same
payment_method_id, and it can now add money. - 200 — the user already had this bank account connected instantly; it is returned unchanged. Sending the same request again is safe.
Either way we send the payment_method.bank.added webhook when a bank
account is added or upgraded.
Keep the connection
The connection stays shared with your app. If your app removes it, this bank
account stops working until the user connects it again
(payment_method.bank.relink_required).
Errors
bank_connection_not_enabled(403) — not turned on for your account.bank_connection_not_accepted(422) — the access token is not valid for our account.bank_connection_relink_required(422) — the user must sign in to their bank again in your app first.bank_connection_account_not_found(422) —account_idis not in this connection.bank_account_not_eligible(422) — only checking and savings accounts can be added.bank_account_limit_reached(422) — the user already has the most bank accounts allowed.bank_connection_unavailable(502) — the connection could not be checked; try again.
curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/bank/add-account-connected \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
"access_token": "access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"
}
'import requests
url = "https://api-sandbox.finogates.com/v1/platform/bank/add-account-connected"
payload = {
"user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
"access_token": "access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"
}
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({
user_id: 'b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4',
access_token: 'access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37',
account_id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D'
})
};
fetch('https://api-sandbox.finogates.com/v1/platform/bank/add-account-connected', 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/bank/add-account-connected",
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([
'user_id' => 'b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4',
'access_token' => 'access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37',
'account_id' => 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D'
]),
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/bank/add-account-connected"
payload := strings.NewReader("{\n \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n \"access_token\": \"access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37\",\n \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\"\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/bank/add-account-connected")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n \"access_token\": \"access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37\",\n \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/bank/add-account-connected")
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 \"user_id\": \"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4\",\n \"access_token\": \"access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37\",\n \"account_id\": \"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D\"\n}"
response = http.request(request)
puts response.read_body{
"status_code": 123,
"data": {
"payment_method_id": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
"user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
"method_type": "bank",
"status": "active",
"user_email": "owner@example.com",
"user_name": "Jane Doe",
"nickname": "<string>",
"last4": "1111",
"brand": "Visa",
"exp_month": 12,
"exp_year": 2027,
"cardholder_first_name": "John",
"cardholder_last_name": "Doe",
"cardholder_name": "John Doe",
"card_transfer_aft_enabled": false,
"card_transfer_oct_enabled": false,
"billing_address": {
"city": "New York",
"country": "US",
"line1": "123 Main St",
"postal_code": "10001",
"state": "NY"
},
"bank_name": "Chase Bank",
"account_mask": "****7890",
"routing_last4": "0021",
"routing_number": "021000021",
"is_rtp_enabled": true,
"account_type": "checking",
"account_holder_name": "John Doe",
"bank_address": "270 Park Avenue",
"bank_city": "New York",
"bank_state": "NY",
"bank_zip": "10017",
"bank_country": "US",
"account_holder_address": "123 Main St",
"account_holder_city": "New York",
"account_holder_state": "NY",
"account_holder_zip": "10001",
"account_holder_country": "US",
"rail_code": "<string>",
"rail_capabilities": {},
"created_at": "2026-04-01T10:30:00Z"
},
"query_generated_time": 123
}{
"status_code": 201,
"data": {
"payment_method_id": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
"user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
"method_type": "bank_account",
"status": "active",
"bank_name": "Example Bank",
"account_mask": "7890",
"routing_last4": "0021",
"account_type": "checking",
"account_holder_name": "John Doe",
"rail_code": "ach",
"created_at": "2026-10-12T10:30:00Z"
},
"query_generated_time": 1791801000000
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Body
Add a bank account from a connection the platform already holds.
Provider-neutral by construction: the platform-facing neutrality rewrite turns any message naming the provider into a generic error.
The user the bank account belongs to.
"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4"
The access token of the user's bank connection, as your app holds it.
1 - 200"access-production-1f3c9a52-7d1e-4b8a-9c0f-2e6d4a8b1c37"
The id of the one account in that connection to add.
1 - 100"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"

