> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="Request">
    **Endpoint:** `POST /api/v2.1/fintrans/{accountId}/beneficiaries`

    **Headers:**

    ```http theme={null}
    Authorization: Bearer {jwt-token}
    Content-Type: application/json
    ```

    **Request Body:**

    ```json theme={null}
    {
      "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 theme={null}
    {
      "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 theme={null}
    {
      "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>