Skip to main content
POST
/
api
/
v2.1
/
fintrans
/
{accountId}
/
beneficiaries
Create beneficiary
curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Forwarded-For: <x-forwarded-for>' \
  --header 'X-Forwarded-From: <x-forwarded-from>' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --header 'deviceId: <deviceid>' \
  --header 'platform: <platform>' \
  --data '
{
  "partyType": "INDIVIDUAL_CUSTOMER",
  "companyName": "Acme Supplier Ltd",
  "shortName": "Acme Supplier",
  "iban": "LT121000011101001000",
  "currency": "EUR",
  "country": "LT",
  "email": "payments@acme-supplier.test",
  "phoneNumber": "+37060012345",
  "bicSwiftCode": "HABALT22",
  "networkName": "SEPA",
  "bankName": "Sample Bank",
  "purposeCode": "SUPP",
  "accountNumber": "1000011101001000",
  "bankCode": "73000",
  "addressLine1": "123 Business Avenue",
  "addressLine2": "Suite 7",
  "city": "Vilnius",
  "stateProvince": "Vilnius County",
  "postalCode": "LT-01001",
  "organizationId": "123e4567-e89b-12d3-a456-426614174010",
  "customerId": "123e4567-e89b-12d3-a456-426614174011",
  "firstName": "Jane",
  "dateOfBirth": "1990-01-15T00:00:00.000Z",
  "lastName": "Doe",
  "name": "Jane Doe",
  "targetCustomerId": "123e4567-e89b-12d3-a456-426614174012",
  "type": "EXTERNAL",
  "bankAddress": "1 Bank Street, Vilnius",
  "bic": "HABALT22",
  "allowedOperations": [
    "SEPA_TRANSFER"
  ]
}
'
import requests

url = "https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries"

payload = {
    "partyType": "INDIVIDUAL_CUSTOMER",
    "companyName": "Acme Supplier Ltd",
    "shortName": "Acme Supplier",
    "iban": "LT121000011101001000",
    "currency": "EUR",
    "country": "LT",
    "email": "payments@acme-supplier.test",
    "phoneNumber": "+37060012345",
    "bicSwiftCode": "HABALT22",
    "networkName": "SEPA",
    "bankName": "Sample Bank",
    "purposeCode": "SUPP",
    "accountNumber": "1000011101001000",
    "bankCode": "73000",
    "addressLine1": "123 Business Avenue",
    "addressLine2": "Suite 7",
    "city": "Vilnius",
    "stateProvince": "Vilnius County",
    "postalCode": "LT-01001",
    "organizationId": "123e4567-e89b-12d3-a456-426614174010",
    "customerId": "123e4567-e89b-12d3-a456-426614174011",
    "firstName": "Jane",
    "dateOfBirth": "1990-01-15T00:00:00.000Z",
    "lastName": "Doe",
    "name": "Jane Doe",
    "targetCustomerId": "123e4567-e89b-12d3-a456-426614174012",
    "type": "EXTERNAL",
    "bankAddress": "1 Bank Street, Vilnius",
    "bic": "HABALT22",
    "allowedOperations": ["SEPA_TRANSFER"]
}
headers = {
    "X-Tenant-ID": "<x-tenant-id>",
    "X-Forwarded-For": "<x-forwarded-for>",
    "X-Forwarded-From": "<x-forwarded-from>",
    "platform": "<platform>",
    "deviceId": "<deviceid>",
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    'X-Tenant-ID': '<x-tenant-id>',
    'X-Forwarded-For': '<x-forwarded-for>',
    'X-Forwarded-From': '<x-forwarded-from>',
    platform: '<platform>',
    deviceId: '<deviceid>',
    Authorization: '<authorization>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    partyType: 'INDIVIDUAL_CUSTOMER',
    companyName: 'Acme Supplier Ltd',
    shortName: 'Acme Supplier',
    iban: 'LT121000011101001000',
    currency: 'EUR',
    country: 'LT',
    email: 'payments@acme-supplier.test',
    phoneNumber: '+37060012345',
    bicSwiftCode: 'HABALT22',
    networkName: 'SEPA',
    bankName: 'Sample Bank',
    purposeCode: 'SUPP',
    accountNumber: '1000011101001000',
    bankCode: '73000',
    addressLine1: '123 Business Avenue',
    addressLine2: 'Suite 7',
    city: 'Vilnius',
    stateProvince: 'Vilnius County',
    postalCode: 'LT-01001',
    organizationId: '123e4567-e89b-12d3-a456-426614174010',
    customerId: '123e4567-e89b-12d3-a456-426614174011',
    firstName: 'Jane',
    dateOfBirth: '1990-01-15T00:00:00.000Z',
    lastName: 'Doe',
    name: 'Jane Doe',
    targetCustomerId: '123e4567-e89b-12d3-a456-426614174012',
    type: 'EXTERNAL',
    bankAddress: '1 Bank Street, Vilnius',
    bic: 'HABALT22',
    allowedOperations: ['SEPA_TRANSFER']
  })
};

fetch('https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries', 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://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries",
  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([
    'partyType' => 'INDIVIDUAL_CUSTOMER',
    'companyName' => 'Acme Supplier Ltd',
    'shortName' => 'Acme Supplier',
    'iban' => 'LT121000011101001000',
    'currency' => 'EUR',
    'country' => 'LT',
    'email' => 'payments@acme-supplier.test',
    'phoneNumber' => '+37060012345',
    'bicSwiftCode' => 'HABALT22',
    'networkName' => 'SEPA',
    'bankName' => 'Sample Bank',
    'purposeCode' => 'SUPP',
    'accountNumber' => '1000011101001000',
    'bankCode' => '73000',
    'addressLine1' => '123 Business Avenue',
    'addressLine2' => 'Suite 7',
    'city' => 'Vilnius',
    'stateProvince' => 'Vilnius County',
    'postalCode' => 'LT-01001',
    'organizationId' => '123e4567-e89b-12d3-a456-426614174010',
    'customerId' => '123e4567-e89b-12d3-a456-426614174011',
    'firstName' => 'Jane',
    'dateOfBirth' => '1990-01-15T00:00:00.000Z',
    'lastName' => 'Doe',
    'name' => 'Jane Doe',
    'targetCustomerId' => '123e4567-e89b-12d3-a456-426614174012',
    'type' => 'EXTERNAL',
    'bankAddress' => '1 Bank Street, Vilnius',
    'bic' => 'HABALT22',
    'allowedOperations' => [
        'SEPA_TRANSFER'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json",
    "X-Forwarded-For: <x-forwarded-for>",
    "X-Forwarded-From: <x-forwarded-from>",
    "X-Tenant-ID: <x-tenant-id>",
    "deviceId: <deviceid>",
    "platform: <platform>"
  ],
]);

$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://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries"

	payload := strings.NewReader("{\n  \"partyType\": \"INDIVIDUAL_CUSTOMER\",\n  \"companyName\": \"Acme Supplier Ltd\",\n  \"shortName\": \"Acme Supplier\",\n  \"iban\": \"LT121000011101001000\",\n  \"currency\": \"EUR\",\n  \"country\": \"LT\",\n  \"email\": \"payments@acme-supplier.test\",\n  \"phoneNumber\": \"+37060012345\",\n  \"bicSwiftCode\": \"HABALT22\",\n  \"networkName\": \"SEPA\",\n  \"bankName\": \"Sample Bank\",\n  \"purposeCode\": \"SUPP\",\n  \"accountNumber\": \"1000011101001000\",\n  \"bankCode\": \"73000\",\n  \"addressLine1\": \"123 Business Avenue\",\n  \"addressLine2\": \"Suite 7\",\n  \"city\": \"Vilnius\",\n  \"stateProvince\": \"Vilnius County\",\n  \"postalCode\": \"LT-01001\",\n  \"organizationId\": \"123e4567-e89b-12d3-a456-426614174010\",\n  \"customerId\": \"123e4567-e89b-12d3-a456-426614174011\",\n  \"firstName\": \"Jane\",\n  \"dateOfBirth\": \"1990-01-15T00:00:00.000Z\",\n  \"lastName\": \"Doe\",\n  \"name\": \"Jane Doe\",\n  \"targetCustomerId\": \"123e4567-e89b-12d3-a456-426614174012\",\n  \"type\": \"EXTERNAL\",\n  \"bankAddress\": \"1 Bank Street, Vilnius\",\n  \"bic\": \"HABALT22\",\n  \"allowedOperations\": [\n    \"SEPA_TRANSFER\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Tenant-ID", "<x-tenant-id>")
	req.Header.Add("X-Forwarded-For", "<x-forwarded-for>")
	req.Header.Add("X-Forwarded-From", "<x-forwarded-from>")
	req.Header.Add("platform", "<platform>")
	req.Header.Add("deviceId", "<deviceid>")
	req.Header.Add("Authorization", "<authorization>")
	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://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries")
  .header("X-Tenant-ID", "<x-tenant-id>")
  .header("X-Forwarded-For", "<x-forwarded-for>")
  .header("X-Forwarded-From", "<x-forwarded-from>")
  .header("platform", "<platform>")
  .header("deviceId", "<deviceid>")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"partyType\": \"INDIVIDUAL_CUSTOMER\",\n  \"companyName\": \"Acme Supplier Ltd\",\n  \"shortName\": \"Acme Supplier\",\n  \"iban\": \"LT121000011101001000\",\n  \"currency\": \"EUR\",\n  \"country\": \"LT\",\n  \"email\": \"payments@acme-supplier.test\",\n  \"phoneNumber\": \"+37060012345\",\n  \"bicSwiftCode\": \"HABALT22\",\n  \"networkName\": \"SEPA\",\n  \"bankName\": \"Sample Bank\",\n  \"purposeCode\": \"SUPP\",\n  \"accountNumber\": \"1000011101001000\",\n  \"bankCode\": \"73000\",\n  \"addressLine1\": \"123 Business Avenue\",\n  \"addressLine2\": \"Suite 7\",\n  \"city\": \"Vilnius\",\n  \"stateProvince\": \"Vilnius County\",\n  \"postalCode\": \"LT-01001\",\n  \"organizationId\": \"123e4567-e89b-12d3-a456-426614174010\",\n  \"customerId\": \"123e4567-e89b-12d3-a456-426614174011\",\n  \"firstName\": \"Jane\",\n  \"dateOfBirth\": \"1990-01-15T00:00:00.000Z\",\n  \"lastName\": \"Doe\",\n  \"name\": \"Jane Doe\",\n  \"targetCustomerId\": \"123e4567-e89b-12d3-a456-426614174012\",\n  \"type\": \"EXTERNAL\",\n  \"bankAddress\": \"1 Bank Street, Vilnius\",\n  \"bic\": \"HABALT22\",\n  \"allowedOperations\": [\n    \"SEPA_TRANSFER\"\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Tenant-ID"] = '<x-tenant-id>'
request["X-Forwarded-For"] = '<x-forwarded-for>'
request["X-Forwarded-From"] = '<x-forwarded-from>'
request["platform"] = '<platform>'
request["deviceId"] = '<deviceid>'
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"partyType\": \"INDIVIDUAL_CUSTOMER\",\n  \"companyName\": \"Acme Supplier Ltd\",\n  \"shortName\": \"Acme Supplier\",\n  \"iban\": \"LT121000011101001000\",\n  \"currency\": \"EUR\",\n  \"country\": \"LT\",\n  \"email\": \"payments@acme-supplier.test\",\n  \"phoneNumber\": \"+37060012345\",\n  \"bicSwiftCode\": \"HABALT22\",\n  \"networkName\": \"SEPA\",\n  \"bankName\": \"Sample Bank\",\n  \"purposeCode\": \"SUPP\",\n  \"accountNumber\": \"1000011101001000\",\n  \"bankCode\": \"73000\",\n  \"addressLine1\": \"123 Business Avenue\",\n  \"addressLine2\": \"Suite 7\",\n  \"city\": \"Vilnius\",\n  \"stateProvince\": \"Vilnius County\",\n  \"postalCode\": \"LT-01001\",\n  \"organizationId\": \"123e4567-e89b-12d3-a456-426614174010\",\n  \"customerId\": \"123e4567-e89b-12d3-a456-426614174011\",\n  \"firstName\": \"Jane\",\n  \"dateOfBirth\": \"1990-01-15T00:00:00.000Z\",\n  \"lastName\": \"Doe\",\n  \"name\": \"Jane Doe\",\n  \"targetCustomerId\": \"123e4567-e89b-12d3-a456-426614174012\",\n  \"type\": \"EXTERNAL\",\n  \"bankAddress\": \"1 Bank Street, Vilnius\",\n  \"bic\": \"HABALT22\",\n  \"allowedOperations\": [\n    \"SEPA_TRANSFER\"\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "code": 201,
  "data": {
    "id": "<string>",
    "name": "<string>",
    "iban": "<string>",
    "bic": "<string>",
    "type": "<string>",
    "status": "<string>",
    "currency": "<string>",
    "country": "<string>",
    "email": "<string>",
    "phoneNumber": "<string>",
    "shortName": "<string>",
    "networkName": "<string>",
    "bankName": "<string>",
    "purposeCode": "<string>",
    "assetId": "<string>",
    "message": "<string>"
  },
  "message": "Success"
}

​
Endpoint

POST /api/v2.1/fintrans/{accountId}/beneficiaries
This endpoint requires X-Forwarded-From and a device header. The backend accepts any of: deviceId, X-Device-Id, device-id.

​
Sample cURL

curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "purposeCode": "SUPP",
    "postalCode": "LT-01103",
    "shortName": "",
    "bicSwiftCode": "SONCLT21",
    "lastName": "Customer",
    "city": "Vilnius",
    "email": "customer.20260331114946-387074@testcorp.com",
    "bankName": "UAB Sonect Europe",
    "currency": "EUR",
    "country": "LT",
    "networkName": "SEPA",
    "firstName": "John",
    "bankAddress": "Gedimino pr. 20, Vilnius, Lithuania",
    "customerId": "2dac1793-ab48-420c-b0b5-01292302e188",
    "addressLine1": "1 Test Street",
    "partyType": "INDIVIDUAL_CUSTOMER",
    "iban": "LT213320011000055860",
    "companyName": ""
  }'

​
Response Example

{
  "code": 200,
  "data": {
    "id": "3114774a-aa94-4648-9e57-5ff226ef02dd",
    "name": "",
    "iban": "LT213320011000055860",
    "type": "INDIVIDUAL_CUSTOMER",
    "status": "ACTIVE",
    "currency": "EUR",
    "country": "",
    "email": "",
    "phoneNumber": "",
    "shortName": "",
    "networkName": "SEPA",
    "bankName": "",
    "purposeCode": "",
    "assetId": "eba40e17-e539-430e-a6cc-2b0f01e4c86e"
  },
  "message": "Success"
}
Use the returned assetId as the beneficiaryId when preparing a financial operation.

​
Missing Headers Error Example

{
  "code": 500,
  "data": {
    "deviceId_accepted": [
      "deviceId",
      "X-Device-Id",
      "device-id"
    ],
    "missingHeaders": [
      "X-Forwarded-From",
      "deviceId"
    ]
  },
  "message": "Missing required header(s)"
}

Headers

​
X-Tenant-ID
string
required
Example:

"tenant-demo-001"

​
X-User-ID
string
​
X-Forwarded-For
string
required

Client IP address

Example:

"127.0.0.1"

​
X-Forwarded-From
string
required

Client source identifier

Example:

"client-app"

​
platform
string
required

Client platform

Example:

"mobile"

​
deviceId
string
required

Device identifier

Example:

"device-demo-001"

​
Authorization
string
required

Bearer JWT

Example:

"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkZW1vLXVzZXIifQ.demo-signature"

Path Parameters

​
accountId
string<uuid>
required
Example:

"00000000-0000-0000-0000-000000000000"

Body

application/json

Beneficiary creation payload

Create beneficiary request

​
partyType
enum<string>

Party type

Available options:
INDIVIDUAL_CUSTOMER,
BUSINESS_CUSTOMER
Example:

"INDIVIDUAL_CUSTOMER"

​
companyName
string

Beneficiary company name

Example:

"Acme Supplier Ltd"

​
shortName
string

Short display name

Example:

"Acme Supplier"

​
iban
string

Beneficiary IBAN

Example:

"LT121000011101001000"

​
currency
string

Transaction currency

Example:

"EUR"

​
country
string

Beneficiary country code

Example:

"LT"

​
email
string

Beneficiary email

Example:

"payments@acme-supplier.test"

​
phoneNumber
string

Beneficiary phone number

Example:

"+37060012345"

​
bicSwiftCode
string

BIC/SWIFT code

Example:

"HABALT22"

​
networkName
string

Payment network name

Example:

"SEPA"

​
bankName
string

Beneficiary bank name

Example:

"Sample Bank"

​
purposeCode
string

Purpose code

Example:

"SUPP"

​
accountNumber
string

Bank account number

Example:

"1000011101001000"

​
bankCode
string

Bank code

Example:

"73000"

​
addressLine1
string

Address line 1

Example:

"123 Business Avenue"

​
addressLine2
string

Address line 2

Example:

"Suite 7"

​
city
string

City

Example:

"Vilnius"

​
stateProvince
string

State or province

Example:

"Vilnius County"

​
postalCode
string

Postal code

Example:

"LT-01001"

​
organizationId
string

Organization identifier

Example:

"123e4567-e89b-12d3-a456-426614174010"

​
customerId
string

Customer identifier

Example:

"123e4567-e89b-12d3-a456-426614174011"

​
firstName
string

Beneficiary first name

Example:

"Jane"

​
dateOfBirth
string

Date of birth (INDIVIDUAL party type)

Example:

"1990-01-15T00:00:00.000Z"

​
lastName
string

Beneficiary last name

Example:

"Doe"

​
name
string

Beneficiary full name

Example:

"Jane Doe"

​
targetCustomerId
string

Target customer identifier

Example:

"123e4567-e89b-12d3-a456-426614174012"

​
type
string

Beneficiary type

Example:

"EXTERNAL"

​
bankAddress
string

Bank address

Example:

"1 Bank Street, Vilnius"

​
bic
string

BIC code

Example:

"HABALT22"

​
allowedOperations
string[]

Allowed operation types

Example:
["SEPA_TRANSFER"]

Response

Beneficiary created

Standard API response wrapper with beneficiary in data

​
code
integer<int32>

HTTP-style status code

Example:

201

​
data
object

Beneficiary

​
message
string

Result message

Example:

"Success"