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

Request

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

Headers:

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

Request Body:

{
  "partyType": "BUSINESS_CUSTOMER",
  "companyName": "Supplier Corporation Ltd",
  "registrationNumber": "REG-SUPP-001",
  "taxId": "TAX-SUPP-001",
  "iban": "GB82WEST12345698765432",
  "currency": "EUR",
  "country": "GB",
  "email": "[e-mail]",
  "phoneNumber": "[phone]",
  "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"
  }
}

Response

Status: 201 Created

{
  "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

Request

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)

Response

Status: 200 OK

{
  "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

Beneficiaries with FLAGGED status cannot be used for transactions until manually reviewed and approved.

---

Next Step

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

Phase 7: Payment Consent Setup

Create payment consents with restrictions