Beneficiaries API

APIs for managing payment beneficiaries and recipients. Beneficiaries must be pre-registered before executing transfers.

Base URL: https://sandbox.finhub.cloud/api/v2.1/fintrans

For complete details on authentication and headers, refer to the Standard HTTP Headers reference documentation.

Why Pre-Register Beneficiaries?

Security & Compliance:

PEP (Politically Exposed Person) screening
Sanctions list checking
Adverse media screening
Anti-money laundering (AML) verification

Efficiency:

One-time registration, multiple uses
Faster payment processing
Reduced errors in payment details
Transaction history per beneficiary

Prerequisites

Before adding beneficiaries:

Account must be ACTIVATED
Wallet must be ACTIVE
Valid payment network access (SEPA, SWIFT, etc.)
Beneficiary details verified (IBAN/account number)

Available Operations

Method	Path	Description
`GET`	`/fintrans/{accountId}/beneficiaries`	List beneficiaries for an account
`POST`	`/fintrans/{accountId}/beneficiaries`	Create beneficiary (with account context)
`POST`	`/fintrans/beneficiaries`	Create beneficiary (no account context, nested request)
`PUT`	`/fintrans/beneficiaries/{beneficiaryId}`	Update an existing beneficiary
`DELETE`	`/fintrans/{accountId}/beneficiaries/{beneficiaryId}`	Delete a beneficiary
`POST`	`/wallets/{walletId}/beneficiaries`	List beneficiaries linked to a wallet (via WalletResource)

List Beneficiaries

Retrieves all beneficiaries for an account.

Request

accountId

string

required

Account identifier

Authorization

string

required

Bearer token for authentication

X-Tenant-ID

string

required

Tenant identifier

Code Examples

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/fintrans/acc_12345/beneficiaries" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

{
  "success": true,
  "data": {
    "beneficiaries": [
      {
        "beneficiaryId": "ben_12345",
        "name": "John Doe",
        "type": "INDIVIDUAL",
        "paymentMethod": "SEPA",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "status": "ACTIVE",
        "createdAt": "2024-01-10T10:00:00Z"
      },
      {
        "beneficiaryId": "ben_67890",
        "name": "Acme Corp",
        "type": "CORPORATE",
        "paymentMethod": "SWIFT",
        "accountNumber": "123456789",
        "routingNumber": "021000021",
        "bankName": "Chase Bank",
        "bankCountry": "US",
        "status": "ACTIVE",
        "createdAt": "2024-01-12T14:00:00Z"
      }
    ]
  }
}

Add Beneficiary

Adds a new beneficiary to the account.

Request

accountId

string

required

Account identifier

partyType

string

required

Beneficiary party type. Determines routing to WSO2 B2C or B2B API.Valid Values: INDIVIDUAL_CUSTOMER, BUSINESS_CUSTOMER, INDIVIDUAL, ORGANIZATION

INDIVIDUAL maps to INDIVIDUAL_CUSTOMER and ORGANIZATION maps to BUSINESS_CUSTOMER internally.

firstName

string

First name (required for INDIVIDUAL_CUSTOMER)

lastName

string

Last name (required for INDIVIDUAL_CUSTOMER)

shortName

string

required

Short display name for the beneficiary

companyName

string

Company name (required for BUSINESS_CUSTOMER)

iban

string

required

IBAN of the beneficiary account

currency

string

Currency code (default: EUR)

country

string

ISO 3166-1 alpha-2 country code (e.g., DE, GB)

string

Contact email address

phoneNumber

string

Contact phone number in E.164 format

bicSwiftCode

string

BIC/SWIFT code of the beneficiary’s bank

networkName

string

Payment network: SEPA, SWIFT

bankName

string

Name of the beneficiary’s bank

purposeCode

string

Purpose code (e.g., SALA for salary, CBFF for business fees)

customerId

string

required

Source customer ID (required in INTEGRATION mode). For organizations, use the organization’s customer UUID.

organizationId

string

required

Organization ID — required in INTEGRATION mode for all party types (not just BUSINESS_CUSTOMER). The BFF uses this to resolve the WSO2 organization context.

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/acc_12345/beneficiaries" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "partyType": "INDIVIDUAL_CUSTOMER",
    "firstName": "Jane",
    "lastName": "Smith",
    "shortName": "Jane Smith",
    "iban": "FR7630006000011234567890189",
    "bicSwiftCode": "BNPAFRPP",
    "currency": "EUR",
    "country": "FR",
    "email": "jane.smith@example.com",
    "networkName": "SEPA",
    "customerId": "cust_12345"
  }'

{
  "success": true,
  "data": {
    "beneficiaryId": "ben_11111",
    "assetId": "f1e2d3c4-b5a6-9807-fedc-ba0987654321",
    "status": "ACTIVE",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Important: The assetId returned in the response is the WSO2 wallet asset ID for this beneficiary. Use this value (not the beneficiaryId UUID) as the beneficiaryId parameter in subsequent PrepareOrder calls. The assetId maps to the destination wallet asset in WSO2.

Create Beneficiary (No Account Context)

Creates a beneficiary without specifying an account in the URL path. Uses a nested request format where the beneficiary details and account info are in the body.

POST /api/v2.1/fintrans/beneficiaries

Request Body

The request wraps beneficiary details inside a beneficiary object along with account context:

{
  "beneficiary": {
    "partyType": "BUSINESS_CUSTOMER",
    "companyName": "Acme Corp GmbH",
    "shortName": "Acme Corp",
    "iban": "DE89370400440532013000",
    "bicSwiftCode": "COBADEFFXXX",
    "currency": "EUR",
    "country": "DE",
    "networkName": "SEPA"
  },
  "accountId": "69a7d5b0-58f0-4394-a3fc-4d33058dc89e",
  "organizationId": "org_12345",
  "customerId": "cust_12345"
}

In INTEGRATION mode, organizationId is required for BUSINESS_CUSTOMER party types. The BFF resolves the tenant context from X-Tenant-ID header.

Update Beneficiary

Updates an existing beneficiary’s details.

PUT /api/v2.1/fintrans/beneficiaries/{beneficiaryId}

Request

beneficiaryId

string

required

Beneficiary ID to update

X-Tenant-ID

string

required

Tenant identifier

The request body accepts the same fields as create (partyType, firstName, lastName, companyName, iban, etc.). Only provided fields will be updated.

curl -X PUT "https://sandbox.finhub.cloud/api/v2.1/fintrans/beneficiaries/ben_12345" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: finsei" \
  -d '{
    "shortName": "Jane Smith-Updated",
    "iban": "FR7630006000011234567890189",
    "email": "jane.updated@example.com"
  }'

{
  "code": 200,
  "data": {
    "beneficiaryId": "ben_12345",
    "status": "ACTIVE",
    "updatedAt": "2026-01-15T10:30:00Z"
  }
}

Delete Beneficiary

Deletes (deactivates) a beneficiary from an account.

DELETE /api/v2.1/fintrans/{accountId}/beneficiaries/{beneficiaryId}

Request

accountId

string

required

Account identifier

beneficiaryId

string

required

Beneficiary ID to delete

X-Tenant-ID

string

required

Tenant identifier

curl -X DELETE "https://sandbox.finhub.cloud/api/v2.1/fintrans/acc_12345/beneficiaries/ben_67890" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: finsei"

{
  "code": 200,
  "data": {
    "beneficiaryId": "ben_67890",
    "status": "DELETED"
  }
}

Beneficiary Types Comparison

Individual vs Business Beneficiaries

Field	Individual Customer	Business Customer
Required	firstName, lastName	companyName, registrationNumber
Identity	Personal ID/passport	Tax ID, incorporation docs
Contact	Personal email, phone	Business contact person
Network	SEPA, SWIFT	SEPA, SWIFT, TARGET2
PEP Check	Yes (if applicable)	Yes (for beneficial owners)
Sanctions Check	Always	Always

Required Fields by Party Type

For INDIVIDUAL_CUSTOMER:

{
  "partyType": "INDIVIDUAL_CUSTOMER",
  "firstName": "John",
  "lastName": "Doe",
  "iban": "DE89370400440532013000",
  "currency": "EUR",
  "country": "DE",
  "email": "john.doe@example.com",
  "phoneNumber": "+491234567890",
  "shortName": "John D.",
  "bicSwiftCode": "COBADEFFXXX",
  "networkName": "SEPA",
  "customerId": "cust_12345",
  "organizationId": "org_12345"
}

In INTEGRATION mode, organizationId and customerId are required for all party types. Without organizationId, the BFF returns HTTP 400 (MISSING_ORG_ID). The bicSwiftCode is also strongly recommended — WSO2 B2C requires it as beneficiaryId.

For BUSINESS_CUSTOMER:

{
  "partyType": "BUSINESS_CUSTOMER",
  "companyName": "Acme Corporation GmbH",
  "registrationNumber": "HRB 123456",
  "taxId": "DE123456789",
  "iban": "DE89370400440532013000",
  "currency": "EUR",
  "country": "DE",
  "email": "finance@acme.com",
  "phoneNumber": "+491234567890",
  "shortName": "Acme Corp",
  "bicSwiftCode": "COBADEFFXXX",
  "networkName": "SEPA",
  "customerId": "cust_12345",
  "organizationId": "org_12345"
}

Network Types

Network	Description	Coverage	Required Fields
SEPA	Single Euro Payments Area	EU + EEA + others	IBAN, BIC (optional)
SWIFT	International wire transfers	Global	IBAN/Account Number, BIC/SWIFT code
TARGET2	Real-time gross settlement	Eurozone central banks	IBAN, BIC
ACH	Automated Clearing House	USA	Account Number, Routing Number
WIRE	Domestic wire transfer	Country-specific	Account Number, Routing/Sort Code

PEP and Sanctions Screening

When adding a beneficiary, the system automatically performs:

1. PEP (Politically Exposed Person) Check

Checks if the beneficiary is:

Government official
Senior political figure
Close associate of PEP
Family member of PEP

Result Values:

VERIFIED - Not a PEP, clear to proceed
PENDING - Manual review required
FAILED - PEP detected, enhanced due diligence needed

2. Sanctions Screening

Checks against:

UN sanctions lists
EU sanctions lists
OFAC (US Office of Foreign Assets Control)
National sanctions lists

Result Values:

CLEAR - No sanctions match
FLAGGED - Potential match, review required
PENDING - Screening in progress

3. Adverse Media Screening

Checks for negative news coverage related to:

Financial crimes
Corruption
Fraud
Money laundering

Beneficiary Status

Status	Description	Can Transfer
ACTIVE	Fully verified, ready for payments	✅ Yes
PENDING	Awaiting compliance review	❌ No
SUSPENDED	Temporarily suspended	❌ No
REJECTED	Failed compliance checks	❌ No

Business Relationship Fields

For business beneficiaries, document the relationship:

Field	Purpose	Example
relationshipType	Type of business relationship	SUPPLIER, CUSTOMER, PARTNER
contractReference	Contract/agreement ID	CONTRACT-2024-001
monthlyVolume	Expected monthly transaction volume	50000 EUR
averageTransactionSize	Typical transaction amount	5000 EUR

Why This Matters:

AML compliance
Transaction monitoring
Fraud detection
Regulatory reporting

Document Specifications

IBAN Format

Length: 15-34 characters
Format: 2-letter country code + 2 check digits + up to 30 alphanumeric characters
Example: DE89370400440532013000

BIC/SWIFT Code Format

Length: 8 or 11 characters
Format: 4-letter bank code + 2-letter country code + 2-character location + (optional) 3-character branch
Example: COBADEFFXXX

Phone Number Format

Format: +[country code][number]
Example: +491234567890
Pattern: +[0-9]{1,15}

Response Codes

Code	Description
`200`	Beneficiaries retrieved successfully
`201`	Beneficiary created successfully
`204`	Beneficiary deleted successfully
`400`	Invalid request data or validation failed
`403`	Access denied
`404`	Beneficiary or account not found
`409`	Beneficiary already exists
`422`	Compliance check failed (PEP/sanctions)
`500`	Internal server error

API Schema Reference

For the complete OpenAPI schema specification, see the API Schema Mapping document.

Standard Headers

Complete HTTP headers reference

Wallet Operations

Check wallet balance before adding beneficiaries

Payment Consents

Create payment authorization

Transfers

Execute transfers to beneficiaries

Account Operations

View allowed operations and limits

Changelog

Version	Date	Changes
v1.0	2026-01-13	Comprehensive beneficiaries management documentation

Headers

X-Tenant-ID

string

required

Tenant identifier

Example:

"97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"

Path Parameters

accountId

string

required

Response

200

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Beneficiaries API

​Why Pre-Register Beneficiaries?

​Prerequisites

​Available Operations

​List Beneficiaries

​Request

​Code Examples

​Add Beneficiary

​Request

​Code Examples

​Create Beneficiary (No Account Context)

​Request Body

​Update Beneficiary

​Request

​Delete Beneficiary

​Request

​Beneficiary Types Comparison

​Individual vs Business Beneficiaries

​Required Fields by Party Type

​For INDIVIDUAL_CUSTOMER:

​For BUSINESS_CUSTOMER:

​Network Types

​PEP and Sanctions Screening

​1. PEP (Politically Exposed Person) Check

​2. Sanctions Screening

​3. Adverse Media Screening

​Beneficiary Status

​Business Relationship Fields

​Document Specifications

​IBAN Format

​BIC/SWIFT Code Format

​Phone Number Format

​Response Codes

​API Schema Reference

​Related Endpoints

Standard Headers

Wallet Operations

Payment Consents

Transfers

Account Operations

​Changelog

Headers

Path Parameters

Response

Beneficiaries API

Why Pre-Register Beneficiaries?

Prerequisites

Available Operations

List Beneficiaries

Request

Code Examples

Add Beneficiary

Request

Code Examples

Create Beneficiary (No Account Context)

Request Body

Update Beneficiary

Request

Delete Beneficiary

Request

Beneficiary Types Comparison

Individual vs Business Beneficiaries

Required Fields by Party Type

For INDIVIDUAL_CUSTOMER:

For BUSINESS_CUSTOMER:

Network Types

PEP and Sanctions Screening

1. PEP (Politically Exposed Person) Check

2. Sanctions Screening

3. Adverse Media Screening

Beneficiary Status

Business Relationship Fields

Document Specifications

IBAN Format

BIC/SWIFT Code Format

Phone Number Format

Response Codes

API Schema Reference

Related Endpoints

Changelog