Phase 6: Beneficiary Management

Add and manage business beneficiaries with enhanced due diligence

Phase 6: Beneficiary Management

Business beneficiaries require additional information compared to individual beneficiaries, including business relationship details and enhanced due diligence data.

Prerequisites

Requirement	Status
Organization Status	`ACTIVE`
Wallet Status	`ACTIVE`
Valid Session	JWT token with appropriate role

Add Business Beneficiary

Endpoint: POST /api/v2.1/fintrans/{accountId}/beneficiaries

Headers:

http

Authorization: Bearer {jwt-token}
Content-Type: application/json

Request Body:

json

{
  "partyType": "BUSINESS_CUSTOMER",
  "companyName": "Supplier Corporation Ltd",
  "registrationNumber": "REG-SUPP-001",
  "taxId": "TAX-SUPP-001",
  "iban": "GB82WEST12345698765432",
  "currency": "EUR",
  "country": "GB",
  "email": "payments@supplier-corp.com",
  "phoneNumber": "+442071234567",
  "shortName": "Supplier Corp",
  "bicSwiftCode": "WESTGB21",
  "networkName": "SEPA",
  "bankName": "Westminster Bank",
  "bankAddress": "London, UK",
  "correspondentBankBic": null,
  "correspondentBankName": null,
  "purposeCode": "INVOICE_PAYMENT",
  "businessRelationship": {
    "relationshipType": "SUPPLIER",
    "contractReference": "CNT-2024-001",
    "monthlyVolume": "50000",
    "averageTransactionSize": "5000"
  },
  "additionalData": {
    "taxId": "GB123456789",
    "vatNumber": "GB987654321",
    "industryCode": "6201",
    "dueDiligenceCompleted": true,
    "sanctionsCheckDate": "2026-01-10"
  }
}

Status: 201 Created

json

{
  "code": 201,
  "message": "Beneficiary created successfully",
  "data": {
    "beneficiaryId": "benef-2233e8400-e29b-41d4-a716-446655440190",
    "accountId": "wallet-aa0e8400-e29b-41d4-a716-446655440120",
    "partyType": "BUSINESS_CUSTOMER",
    "beneficiaryName": "Supplier Corporation Ltd",
    "iban": "GB82WEST12345698765432",
    "bic": "WESTGB21",
    "bicType": "external",
    "currency": "EUR",
    "country": "GB",
    "networkName": "SEPA",
    "bankName": "Westminster Bank",
    "purposeCode": "INVOICE_PAYMENT",
    "pepCheckResult": "VERIFIED",
    "sanctionsCheckResult": "CLEAR",
    "status": "active",
    "createdAt": "2026-01-15T15:00:00.000Z",
    "verifiedAt": "2026-01-15T15:00:00.000Z"
  }
}

Business Relationship Types

Relationship Type	Description
`SUPPLIER`	Goods or services supplier
`VENDOR`	Vendor relationship
`PARTNER`	Business partner
`SUBSIDIARY`	Subsidiary company
`AFFILIATE`	Affiliated company
`CONTRACTOR`	Contract service provider

Purpose Codes

Code	Description
`INVOICE_PAYMENT`	Payment for invoices
`SALARY_PAYMENT`	Employee salary payments
`TAX_PAYMENT`	Tax payments to authorities
`LOAN_REPAYMENT`	Loan repayment
`DIVIDEND_PAYMENT`	Dividend distribution
`INVESTMENT`	Investment transfers

Enhanced Due Diligence Fields

Field	Description
`taxId`	Beneficiary’s tax identification
`vatNumber`	VAT registration number
`industryCode`	Industry classification code
`dueDiligenceCompleted`	Due diligence status
`sanctionsCheckDate`	Date of last sanctions check

List Beneficiaries

Endpoint: GET /api/v2.1/fintrans/{accountId}/beneficiaries

Query Parameters:

status: Filter by status (active, inactive)
partyType: Filter by party type
network: Filter by network (SEPA, SWIFT)

Status: 200 OK

json

{
  "code": 200,
  "message": "Beneficiaries retrieved successfully",
  "data": [
    {
      "beneficiaryId": "benef-2233e8400-e29b-41d4-a716-446655440190",
      "beneficiaryName": "Supplier Corporation Ltd",
      "iban": "GB82WEST12345698765432",
      "network": "SEPA",
      "status": "active",
      "lastUsed": "2026-01-15T16:00:00.000Z"
    }
  ]
}

Beneficiary Verification

All beneficiaries undergo automatic verification:

Check	Description	Result
PEP Check	Politically Exposed Person screening	VERIFIED / FLAGGED
Sanctions Check	Global sanctions list screening	CLEAR / FLAGGED
IBAN Validation	IBAN format and checksum	VALID / INVALID

Next Step

After adding beneficiaries, proceed to Phase 7: Payment Consent Setup.

Phase 7: Payment Consent Setup

Create payment consents with restrictions