Skip to main content
GET
https://sandbox.finhub.cloud
/
api
/
v2.1
/
fintrans
/
{accountId}
/
beneficiaries
Beneficiaries API
curl --request GET \
  --url https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --data '
{
  "name": "<string>",
  "type": "<string>",
  "paymentMethod": "<string>",
  "iban": "<string>",
  "bic": "<string>",
  "accountNumber": "<string>",
  "routingNumber": "<string>"
}
'
{
  "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"
      }
    ]
  }
}

​
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

List Beneficiaries

GET /fintrans/{accountId}/beneficiaries

Add Beneficiary

POST /fintrans/{accountId}/beneficiaries

​
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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

{
  "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
​
name
string
required
Beneficiary name
​
type
string
required
Beneficiary type: INDIVIDUAL or CORPORATE
​
paymentMethod
string
required
Payment method: SEPA, SWIFT, or INTERNAL
​
iban
string
IBAN (required for SEPA)
​
bic
string
BIC/SWIFT code
​
accountNumber
string
Account number (for SWIFT)
​
routingNumber
string
Routing number (for SWIFT)

​
Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/acc_12345/beneficiaries" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "type": "INDIVIDUAL",
    "paymentMethod": "SEPA",
    "iban": "FR7630006000011234567890189",
    "bic": "BNPAFRPP"
  }'

{
  "success": true,
  "data": {
    "beneficiaryId": "ben_11111",
    "status": "ACTIVE",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

​
Beneficiary Types Comparison

​
Individual vs Business Beneficiaries

FieldIndividual CustomerBusiness Customer
RequiredfirstName, lastNamecompanyName, registrationNumber
IdentityPersonal ID/passportTax ID, incorporation docs
ContactPersonal email, phoneBusiness contact person
NetworkSEPA, SWIFTSEPA, SWIFT, TARGET2
PEP CheckYes (if applicable)Yes (for beneficial owners)
Sanctions CheckAlwaysAlways

​
Required Fields by Party Type

​
For INDIVIDUAL_CUSTOMER:

{
  "partyType": "INDIVIDUAL_CUSTOMER",
  "firstName": "John",
  "lastName": "Doe",
  "iban": "DE89370400440532013000",
  "currency": "EUR",
  "country": "DE",
  "email": "[email protected]",
  "phoneNumber": "+491234567890",
  "shortName": "John D.",
  "bicSwiftCode": "COBADEFFXXX",
  "networkName": "SEPA"
}

​
For BUSINESS_CUSTOMER:

{
  "partyType": "BUSINESS_CUSTOMER",
  "companyName": "Acme Corporation GmbH",
  "registrationNumber": "HRB 123456",
  "taxId": "DE123456789",
  "iban": "DE89370400440532013000",
  "currency": "EUR",
  "country": "DE",
  "email": "[email protected]",
  "phoneNumber": "+491234567890",
  "shortName": "Acme Corp",
  "bicSwiftCode": "COBADEFFXXX",
  "networkName": "SEPA",
  "businessRelationship": {
    "relationshipType": "SUPPLIER",
    "contractReference": "CONTRACT-2024-001",
    "monthlyVolume": "50000",
    "averageTransactionSize": "5000"
  }
}

​
Network Types

NetworkDescriptionCoverageRequired Fields
SEPASingle Euro Payments AreaEU + EEA + othersIBAN, BIC (optional)
SWIFTInternational wire transfersGlobalIBAN/Account Number, BIC/SWIFT code
TARGET2Real-time gross settlementEurozone central banksIBAN, BIC
ACHAutomated Clearing HouseUSAAccount Number, Routing Number
WIREDomestic wire transferCountry-specificAccount 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

StatusDescriptionCan Transfer
ACTIVEFully verified, ready for payments✅ Yes
PENDINGAwaiting compliance review❌ No
SUSPENDEDTemporarily suspended❌ No
REJECTEDFailed compliance checks❌ No

​
Business Relationship Fields

For business beneficiaries, document the relationship:
FieldPurposeExample
relationshipTypeType of business relationshipSUPPLIER, CUSTOMER, PARTNER
contractReferenceContract/agreement IDCONTRACT-2024-001
monthlyVolumeExpected monthly transaction volume50000 EUR
averageTransactionSizeTypical transaction amount5000 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

CodeDescription
200Beneficiaries retrieved successfully
201Beneficiary created successfully
204Beneficiary deleted successfully
400Invalid request data or validation failed
403Access denied
404Beneficiary or account not found
409Beneficiary already exists
422Compliance check failed (PEP/sanctions)
500Internal 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

VersionDateChanges
v1.02026-01-13Comprehensive beneficiaries management documentation