Add beneficiary (account)

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",
  "firstName": "Jane",
  "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",
  "lastName": "Doe",
  "name": "Jane Doe",
  "targetCustomerId": "123e4567-e89b-12d3-a456-426614174012",
  "type": "EXTERNAL",
  "bankAddress": "1 Bank Street, Vilnius",
  "bic": "HABALT22",
  "allowedOperations": [
    "SEPA_TRANSFER"
  ]
}
'

{
  "code": 201,
  "data": {
    "beneficiaryId": "<string>",
    "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>",
    "message": "<string>"
  },
  "message": "Success"
}

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",
  "firstName": "Jane",
  "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",
  "lastName": "Doe",
  "name": "Jane Doe",
  "targetCustomerId": "123e4567-e89b-12d3-a456-426614174012",
  "type": "EXTERNAL",
  "bankAddress": "1 Bank Street, Vilnius",
  "bic": "HABALT22",
  "allowedOperations": [
    "SEPA_TRANSFER"
  ]
}
'

{
  "code": 201,
  "data": {
    "beneficiaryId": "<string>",
    "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>",
    "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>

required

Party type

Available options:

INDIVIDUAL_CUSTOMER,

BUSINESS_CUSTOMER

Pattern: \S

Example:

"INDIVIDUAL_CUSTOMER"

firstName

string

required

Beneficiary first name

Pattern: \S

Example:

"Jane"

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"

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"

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

Show child attributes

message

string

Result message

Example:

"Success"

Get wallets by customer Get beneficiaries for wallet

⌘I

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

Add beneficiary (account)

Endpoint

Sample cURL

Response Example

Missing Headers Error Example

Headers

Path Parameters

Body

Response

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Endpoint

​Sample cURL

​Response Example

​Missing Headers Error Example

Headers

Path Parameters

Body

Response

Endpoint

Sample cURL

Response Example

Missing Headers Error Example