Create Beneficiary
curl --request POST \
--url https://sandbox.api.fin.com/v2/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_id": "cust_123456",
"country": "USA",
"currency": "USD",
"account_holder": {
"type": "INDIVIDUAL",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890"
},
"account_holder_address": {
"street_line_1": "456 Main Street",
"city": "Brooklyn",
"state": "US-NY",
"postcode": "11201",
"country": "USA",
"street_line_2": "Apt 5B"
},
"receiver_meta_data": {
"transaction_purpose_id": 1,
"occupation_remarks": "Software Engineer",
"nationality": "USA",
"transaction_purpose_remarks": "Monthly salary payment",
"occupation_id": 5,
"relationship_remarks": "Long-term contractor",
"govt_id_number": "JG1121316A",
"govt_id_issue_date": "2024-12-30",
"govt_id_expire_date": "2027-12-30"
},
"developer_fee": {
"fixed": 5,
"percentage": 2.5
},
"deposit_instruction": {
"currency": "USDC",
"rail": "POLYGON"
},
"refund_instruction": {
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"currency": "USDC",
"rail": "POLYGON"
},
"bank_account": {
"bank_name": "Chase Bank",
"number": "1234567890"
},
"bank_routing": [
{
"number": "021000021"
}
],
"bank_address": {
"street_line_1": "123 Bank Street",
"city": "New York",
"state": "US-NY",
"postcode": "10001",
"country": "USA",
"street_line_2": "Suite 100"
},
"counter_party": "FIRST_PARTY"
}
'const url = 'https://sandbox.api.fin.com/v2/beneficiaries';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
customer_id: 'cust_123456',
country: 'USA',
currency: 'USD',
account_holder: {
type: 'INDIVIDUAL',
first_name: 'John',
last_name: 'Doe',
email: 'john.doe@example.com',
phone: '+1234567890'
},
account_holder_address: {
street_line_1: '456 Main Street',
city: 'Brooklyn',
state: 'US-NY',
postcode: '11201',
country: 'USA',
street_line_2: 'Apt 5B'
},
receiver_meta_data: {
transaction_purpose_id: 1,
occupation_remarks: 'Software Engineer',
nationality: 'USA',
transaction_purpose_remarks: 'Monthly salary payment',
occupation_id: 5,
relationship_remarks: 'Long-term contractor',
govt_id_number: 'JG1121316A',
govt_id_issue_date: '2024-12-30',
govt_id_expire_date: '2027-12-30'
},
developer_fee: {fixed: 5, percentage: 2.5},
deposit_instruction: {currency: 'USDC', rail: 'POLYGON'},
refund_instruction: {
wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
currency: 'USDC',
rail: 'POLYGON'
},
bank_account: {bank_name: 'Chase Bank', number: '1234567890'},
bank_routing: [{number: '021000021'}],
bank_address: {
street_line_1: '123 Bank Street',
city: 'New York',
state: 'US-NY',
postcode: '10001',
country: 'USA',
street_line_2: 'Suite 100'
},
counter_party: 'FIRST_PARTY'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://sandbox.api.fin.com/v2/beneficiaries")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"customer_id\": \"cust_123456\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"account_holder\": {\n \"type\": \"INDIVIDUAL\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\"\n },\n \"account_holder_address\": {\n \"street_line_1\": \"456 Main Street\",\n \"city\": \"Brooklyn\",\n \"state\": \"US-NY\",\n \"postcode\": \"11201\",\n \"country\": \"USA\",\n \"street_line_2\": \"Apt 5B\"\n },\n \"receiver_meta_data\": {\n \"transaction_purpose_id\": 1,\n \"occupation_remarks\": \"Software Engineer\",\n \"nationality\": \"USA\",\n \"transaction_purpose_remarks\": \"Monthly salary payment\",\n \"occupation_id\": 5,\n \"relationship_remarks\": \"Long-term contractor\",\n \"govt_id_number\": \"JG1121316A\",\n \"govt_id_issue_date\": \"2024-12-30\",\n \"govt_id_expire_date\": \"2027-12-30\"\n },\n \"developer_fee\": {\n \"fixed\": 5,\n \"percentage\": 2.5\n },\n \"deposit_instruction\": {\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"refund_instruction\": {\n \"wallet_address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"bank_account\": {\n \"bank_name\": \"Chase Bank\",\n \"number\": \"1234567890\"\n },\n \"bank_routing\": [\n {\n \"number\": \"021000021\"\n }\n ],\n \"bank_address\": {\n \"street_line_1\": \"123 Bank Street\",\n \"city\": \"New York\",\n \"state\": \"US-NY\",\n \"postcode\": \"10001\",\n \"country\": \"USA\",\n \"street_line_2\": \"Suite 100\"\n },\n \"counter_party\": \"FIRST_PARTY\"\n}")
.asString();import requests
url = "https://sandbox.api.fin.com/v2/beneficiaries"
payload = {
"customer_id": "cust_123456",
"country": "USA",
"currency": "USD",
"account_holder": {
"type": "INDIVIDUAL",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890"
},
"account_holder_address": {
"street_line_1": "456 Main Street",
"city": "Brooklyn",
"state": "US-NY",
"postcode": "11201",
"country": "USA",
"street_line_2": "Apt 5B"
},
"receiver_meta_data": {
"transaction_purpose_id": 1,
"occupation_remarks": "Software Engineer",
"nationality": "USA",
"transaction_purpose_remarks": "Monthly salary payment",
"occupation_id": 5,
"relationship_remarks": "Long-term contractor",
"govt_id_number": "JG1121316A",
"govt_id_issue_date": "2024-12-30",
"govt_id_expire_date": "2027-12-30"
},
"developer_fee": {
"fixed": 5,
"percentage": 2.5
},
"deposit_instruction": {
"currency": "USDC",
"rail": "POLYGON"
},
"refund_instruction": {
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"currency": "USDC",
"rail": "POLYGON"
},
"bank_account": {
"bank_name": "Chase Bank",
"number": "1234567890"
},
"bank_routing": [{ "number": "021000021" }],
"bank_address": {
"street_line_1": "123 Bank Street",
"city": "New York",
"state": "US-NY",
"postcode": "10001",
"country": "USA",
"street_line_2": "Suite 100"
},
"counter_party": "FIRST_PARTY"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.api.fin.com/v2/beneficiaries"
payload := strings.NewReader("{\n \"customer_id\": \"cust_123456\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"account_holder\": {\n \"type\": \"INDIVIDUAL\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\"\n },\n \"account_holder_address\": {\n \"street_line_1\": \"456 Main Street\",\n \"city\": \"Brooklyn\",\n \"state\": \"US-NY\",\n \"postcode\": \"11201\",\n \"country\": \"USA\",\n \"street_line_2\": \"Apt 5B\"\n },\n \"receiver_meta_data\": {\n \"transaction_purpose_id\": 1,\n \"occupation_remarks\": \"Software Engineer\",\n \"nationality\": \"USA\",\n \"transaction_purpose_remarks\": \"Monthly salary payment\",\n \"occupation_id\": 5,\n \"relationship_remarks\": \"Long-term contractor\",\n \"govt_id_number\": \"JG1121316A\",\n \"govt_id_issue_date\": \"2024-12-30\",\n \"govt_id_expire_date\": \"2027-12-30\"\n },\n \"developer_fee\": {\n \"fixed\": 5,\n \"percentage\": 2.5\n },\n \"deposit_instruction\": {\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"refund_instruction\": {\n \"wallet_address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"bank_account\": {\n \"bank_name\": \"Chase Bank\",\n \"number\": \"1234567890\"\n },\n \"bank_routing\": [\n {\n \"number\": \"021000021\"\n }\n ],\n \"bank_address\": {\n \"street_line_1\": \"123 Bank Street\",\n \"city\": \"New York\",\n \"state\": \"US-NY\",\n \"postcode\": \"10001\",\n \"country\": \"USA\",\n \"street_line_2\": \"Suite 100\"\n },\n \"counter_party\": \"FIRST_PARTY\"\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))
}{
"data": {
"id": "ben_123456",
"status": "active"
}
}{
"errors": [
{}
],
"message": "Validation failed!"
}{
"message": "Authentication failed"
}{
"message": "A beneficiary with the same account details already exists.",
"error": {
"beneficiary_id": "d9868585-78ba-4723-b0af-8f5b1cc5f9e2"
}
}{
"message": "<string>",
"errors": [
{}
]
}Create Beneficiary
Create Beneficiary
Create a new beneficiary account for payments and transfers
POST
/
v2
/
beneficiaries
Create Beneficiary
curl --request POST \
--url https://sandbox.api.fin.com/v2/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_id": "cust_123456",
"country": "USA",
"currency": "USD",
"account_holder": {
"type": "INDIVIDUAL",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890"
},
"account_holder_address": {
"street_line_1": "456 Main Street",
"city": "Brooklyn",
"state": "US-NY",
"postcode": "11201",
"country": "USA",
"street_line_2": "Apt 5B"
},
"receiver_meta_data": {
"transaction_purpose_id": 1,
"occupation_remarks": "Software Engineer",
"nationality": "USA",
"transaction_purpose_remarks": "Monthly salary payment",
"occupation_id": 5,
"relationship_remarks": "Long-term contractor",
"govt_id_number": "JG1121316A",
"govt_id_issue_date": "2024-12-30",
"govt_id_expire_date": "2027-12-30"
},
"developer_fee": {
"fixed": 5,
"percentage": 2.5
},
"deposit_instruction": {
"currency": "USDC",
"rail": "POLYGON"
},
"refund_instruction": {
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"currency": "USDC",
"rail": "POLYGON"
},
"bank_account": {
"bank_name": "Chase Bank",
"number": "1234567890"
},
"bank_routing": [
{
"number": "021000021"
}
],
"bank_address": {
"street_line_1": "123 Bank Street",
"city": "New York",
"state": "US-NY",
"postcode": "10001",
"country": "USA",
"street_line_2": "Suite 100"
},
"counter_party": "FIRST_PARTY"
}
'const url = 'https://sandbox.api.fin.com/v2/beneficiaries';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
customer_id: 'cust_123456',
country: 'USA',
currency: 'USD',
account_holder: {
type: 'INDIVIDUAL',
first_name: 'John',
last_name: 'Doe',
email: 'john.doe@example.com',
phone: '+1234567890'
},
account_holder_address: {
street_line_1: '456 Main Street',
city: 'Brooklyn',
state: 'US-NY',
postcode: '11201',
country: 'USA',
street_line_2: 'Apt 5B'
},
receiver_meta_data: {
transaction_purpose_id: 1,
occupation_remarks: 'Software Engineer',
nationality: 'USA',
transaction_purpose_remarks: 'Monthly salary payment',
occupation_id: 5,
relationship_remarks: 'Long-term contractor',
govt_id_number: 'JG1121316A',
govt_id_issue_date: '2024-12-30',
govt_id_expire_date: '2027-12-30'
},
developer_fee: {fixed: 5, percentage: 2.5},
deposit_instruction: {currency: 'USDC', rail: 'POLYGON'},
refund_instruction: {
wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
currency: 'USDC',
rail: 'POLYGON'
},
bank_account: {bank_name: 'Chase Bank', number: '1234567890'},
bank_routing: [{number: '021000021'}],
bank_address: {
street_line_1: '123 Bank Street',
city: 'New York',
state: 'US-NY',
postcode: '10001',
country: 'USA',
street_line_2: 'Suite 100'
},
counter_party: 'FIRST_PARTY'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://sandbox.api.fin.com/v2/beneficiaries")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"customer_id\": \"cust_123456\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"account_holder\": {\n \"type\": \"INDIVIDUAL\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\"\n },\n \"account_holder_address\": {\n \"street_line_1\": \"456 Main Street\",\n \"city\": \"Brooklyn\",\n \"state\": \"US-NY\",\n \"postcode\": \"11201\",\n \"country\": \"USA\",\n \"street_line_2\": \"Apt 5B\"\n },\n \"receiver_meta_data\": {\n \"transaction_purpose_id\": 1,\n \"occupation_remarks\": \"Software Engineer\",\n \"nationality\": \"USA\",\n \"transaction_purpose_remarks\": \"Monthly salary payment\",\n \"occupation_id\": 5,\n \"relationship_remarks\": \"Long-term contractor\",\n \"govt_id_number\": \"JG1121316A\",\n \"govt_id_issue_date\": \"2024-12-30\",\n \"govt_id_expire_date\": \"2027-12-30\"\n },\n \"developer_fee\": {\n \"fixed\": 5,\n \"percentage\": 2.5\n },\n \"deposit_instruction\": {\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"refund_instruction\": {\n \"wallet_address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"bank_account\": {\n \"bank_name\": \"Chase Bank\",\n \"number\": \"1234567890\"\n },\n \"bank_routing\": [\n {\n \"number\": \"021000021\"\n }\n ],\n \"bank_address\": {\n \"street_line_1\": \"123 Bank Street\",\n \"city\": \"New York\",\n \"state\": \"US-NY\",\n \"postcode\": \"10001\",\n \"country\": \"USA\",\n \"street_line_2\": \"Suite 100\"\n },\n \"counter_party\": \"FIRST_PARTY\"\n}")
.asString();import requests
url = "https://sandbox.api.fin.com/v2/beneficiaries"
payload = {
"customer_id": "cust_123456",
"country": "USA",
"currency": "USD",
"account_holder": {
"type": "INDIVIDUAL",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890"
},
"account_holder_address": {
"street_line_1": "456 Main Street",
"city": "Brooklyn",
"state": "US-NY",
"postcode": "11201",
"country": "USA",
"street_line_2": "Apt 5B"
},
"receiver_meta_data": {
"transaction_purpose_id": 1,
"occupation_remarks": "Software Engineer",
"nationality": "USA",
"transaction_purpose_remarks": "Monthly salary payment",
"occupation_id": 5,
"relationship_remarks": "Long-term contractor",
"govt_id_number": "JG1121316A",
"govt_id_issue_date": "2024-12-30",
"govt_id_expire_date": "2027-12-30"
},
"developer_fee": {
"fixed": 5,
"percentage": 2.5
},
"deposit_instruction": {
"currency": "USDC",
"rail": "POLYGON"
},
"refund_instruction": {
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"currency": "USDC",
"rail": "POLYGON"
},
"bank_account": {
"bank_name": "Chase Bank",
"number": "1234567890"
},
"bank_routing": [{ "number": "021000021" }],
"bank_address": {
"street_line_1": "123 Bank Street",
"city": "New York",
"state": "US-NY",
"postcode": "10001",
"country": "USA",
"street_line_2": "Suite 100"
},
"counter_party": "FIRST_PARTY"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.api.fin.com/v2/beneficiaries"
payload := strings.NewReader("{\n \"customer_id\": \"cust_123456\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"account_holder\": {\n \"type\": \"INDIVIDUAL\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\"\n },\n \"account_holder_address\": {\n \"street_line_1\": \"456 Main Street\",\n \"city\": \"Brooklyn\",\n \"state\": \"US-NY\",\n \"postcode\": \"11201\",\n \"country\": \"USA\",\n \"street_line_2\": \"Apt 5B\"\n },\n \"receiver_meta_data\": {\n \"transaction_purpose_id\": 1,\n \"occupation_remarks\": \"Software Engineer\",\n \"nationality\": \"USA\",\n \"transaction_purpose_remarks\": \"Monthly salary payment\",\n \"occupation_id\": 5,\n \"relationship_remarks\": \"Long-term contractor\",\n \"govt_id_number\": \"JG1121316A\",\n \"govt_id_issue_date\": \"2024-12-30\",\n \"govt_id_expire_date\": \"2027-12-30\"\n },\n \"developer_fee\": {\n \"fixed\": 5,\n \"percentage\": 2.5\n },\n \"deposit_instruction\": {\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"refund_instruction\": {\n \"wallet_address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"bank_account\": {\n \"bank_name\": \"Chase Bank\",\n \"number\": \"1234567890\"\n },\n \"bank_routing\": [\n {\n \"number\": \"021000021\"\n }\n ],\n \"bank_address\": {\n \"street_line_1\": \"123 Bank Street\",\n \"city\": \"New York\",\n \"state\": \"US-NY\",\n \"postcode\": \"10001\",\n \"country\": \"USA\",\n \"street_line_2\": \"Suite 100\"\n },\n \"counter_party\": \"FIRST_PARTY\"\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))
}{
"data": {
"id": "ben_123456",
"status": "active"
}
}{
"errors": [
{}
],
"message": "Validation failed!"
}{
"message": "Authentication failed"
}{
"message": "A beneficiary with the same account details already exists.",
"error": {
"beneficiary_id": "d9868585-78ba-4723-b0af-8f5b1cc5f9e2"
}
}{
"message": "<string>",
"errors": [
{}
]
}This endpoint will be deprecated on September 1, 2026. Use Create Beneficiary V3 instead.
Rules
- Beneficiary creation requires the customer to be in the
APPROVEDstatus. - Two beneficiaries with the same destination are not allowed.
De-Duplication Logic
For bank accounts, the system checks:bank_account.scheme, bank_account.number, bank_routing.scheme, bank_routing.number.
For e-wallets: e_wallet.scheme, e_wallet.number.
Country-Specific Validation
GBR (United Kingdom)
- Bank account number: Must match
^[0-9]{4,9}$for bothLOCALandSWIFTschemes.
Authorizations
Bearer token authentication. Obtain token from Issue a Token endpoint
Body
application/json
- Bank Account
- E Wallet
Example:
"cust_123456"
Pattern:
^[A-Z]{3}$Example:
"USA"
Example:
"USD"
- Individual
- Business
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Indicates whether the beneficiary is a first-party or third-party account. Optional.
Available options:
FIRST_PARTY, THIRD_PARTY Example:
"FIRST_PARTY"
Show child attributes
Show child attributes
Response
Beneficiary created successfully
Show child attributes
Show child attributes
⌘I