URL: /baas/api/integration/flows/organization-customer/beneficiary-management

---
title: 'Phase 6: Beneficiary Management'
description: '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

<Tabs>
  <Tab title="Request">
    **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"
      }
    }
    ```
  </Tab>
  <Tab title="Response">
    **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"
      }
    }
    ```
  </Tab>
</Tabs>

---

## 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

<Tabs>
  <Tab title="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)
  </Tab>
  <Tab title="Response">
    **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"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

---

## 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 |

<Warning>
  Beneficiaries with `FLAGGED` status cannot be used for transactions until manually reviewed and approved.
</Warning>

---

## Next Step

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

<Card title="Phase 7: Payment Consent Setup" icon="arrow-right" href="/baas/api/integration/flows/organization-customer/payment-consent-setup">
  Create payment consents with restrictions
</Card>