Create Beneficiary

curl --request POST \
  --url https://api.finhub.cloud/api/v2.1/fintrans/wal_abc123def456/beneficiaries \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Tenant-ID: fh_api_finsei_ltd_7f957f77' \
  --header 'Content-Type: application/json' \
  --data '{
    "partyType": "INDIVIDUAL_CUSTOMER",
    "firstName": "John",
    "lastName": "Doe",
    "shortName": "John Doe",
    "iban": "FR1420041010050500013M02606",
    "currency": "EUR",
    "country": "FR",
    "email": "john.doe@example.com",
    "phoneNumber": "+33123456789",
    "bicSwiftCode": "BNPAFRPP",
    "networkName": "SEPA",
    "bankName": "BNP Paribas",
    "bankAddress": "16 Boulevard des Italiens, 75009 Paris, France",
    "purposeCode": "SALA"
  }'
```text`n## Example Request - Business Beneficiary

```bash
curl --request POST \
  --url https://api.finhub.cloud/api/v2.1/fintrans/wal_abc123def456/beneficiaries \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Tenant-ID: fh_api_finsei_ltd_7f957f77' \
  --header 'Content-Type: application/json' \
  --data '{
    "partyType": "BUSINESS_CUSTOMER",
    "companyName": "Acme Corporation",
    "shortName": "Acme Corp",
    "iban": "DE89370400440532013000",
    "currency": "EUR",
    "country": "DE",
    "email": "finance@acme.com",
    "phoneNumber": "+49123456789",
    "bicSwiftCode": "DEUTDEFF",
    "networkName": "SEPA",
    "bankName": "Deutsche Bank AG",
    "bankAddress": "Taunusanlage 12, 60325 Frankfurt am Main, Germany",
    "purposeCode": "CBFF"
  }'
```text`n## Example Response

```json
{
  "data": {
    "id": "ben_xyz789abc123",
    "status": "ACTIVE",
    "createdAt": "2025-01-23T12:00:00.000Z",
    "partyType": "INDIVIDUAL_CUSTOMER",
    "shortName": "John Doe"
  }
}
```text`n## Validation Rules

1. **IBAN Validation**: Must be valid format for the specified country
2. **Duplicate Prevention**: System checks for existing beneficiaries with same IBAN
3. **BIC/SWIFT Validation**: Must match standard format (8 or 11 characters)
4. **Currency Support**: Must be supported by the account and network

## Network Requirements

| Network | Supported Countries | Currency | Processing Time |
|---------|-------------------|----------|-----------------|
| SEPA | EU/EEA countries | EUR | 1-2 business days |
| SWIFT | Worldwide | Multiple | 3-5 business days |
| INTERNAL | Same platform | Multiple | Instant |

## Purpose Codes Reference

| Code | Description | Use Case |
|------|-------------|----------|
| SALA | Salary | Employee payments |
| CBFF | Capital Building | Business investments |
| GDDS | Goods | Product purchases |
| SCVE | Services | Service payments |
| REFU | Refund | Customer refunds |
| LOAN | Loan | Loan disbursements |

## Bulk Beneficiary Creation

For adding multiple beneficiaries:

```javascript
const beneficiaries = [
  {
    partyType: "INDIVIDUAL_CUSTOMER",
    firstName: "John",
    lastName: "Doe",
    // ... other fields
  },
  {
    partyType: "BUSINESS_CUSTOMER",
    companyName: "Acme Corporation",
    // ... other fields
  }
];

for (const beneficiary of beneficiaries) {
  const response = await createBeneficiary(walletId, beneficiary);
  console.log(`Added beneficiary: ${response.data.shortName}`);
}
```text`n## Integration with Payment Consents

Beneficiaries added through this endpoint can be:
1. **Included in payment consent allowed lists** - For restricted transfers
2. **Subject to transaction limits** - Based on consent parameters
3. **Validated during transfer execution** - Ensuring compliance

## Error Handling

| Error Code | Description | Resolution |
|------------|-------------|------------|
| 400 | Invalid IBAN format | Check IBAN validation |
| 409 | Duplicate beneficiary | Beneficiary already exists |
| 422 | Invalid country/currency combination | Verify network support |

## PowerShell Script Example

```powershell
# Add beneficiaries for transfers
$beneficiaries = @(
    @{
        partyType    = "INDIVIDUAL_CUSTOMER"
        firstName    = "John"
        lastName     = "Doe"
        shortName    = "John Doe"
        iban         = "FR1420041010050500013M02606"
        currency     = "EUR"
        country      = "FR"
        email        = "john.doe@example.com"
        phoneNumber  = "+33123456789"
        bicSwiftCode = "BNPAFRPP"
        networkName  = "SEPA"
        bankName     = "BNP Paribas"
        bankAddress  = "16 Boulevard des Italiens, 75009 Paris, France"
        purposeCode  = "SALA"
    },
    @{
        partyType    = "BUSINESS_CUSTOMER"
        companyName  = "Acme Corporation"
        shortName    = "Acme Corp"
        iban         = "DE89370400440532013000"
        currency     = "EUR"
        country      = "DE"
        email        = "finance@acme.com"
        phoneNumber  = "+49123456789"
        bicSwiftCode = "DEUTDEFF"
        networkName  = "SEPA"
        bankName     = "Deutsche Bank AG"
        bankAddress  = "Taunusanlage 12, 60325 Frankfurt am Main, Germany"
        purposeCode  = "CBFF"
    }
)

$beneficiaryIds = @()

foreach ($beneficiary in $beneficiaries) {
    try {
        # Use fintrans API endpoint
        $beneficiaryUrl = "$baseUrl/api/v2.1/fintrans/$walletId/beneficiaries"
        $beneficiaryBody = $beneficiary | ConvertTo-Json
        
        # Create headers with authentication
        $headers = @{
            "Authorization" = "Bearer $token"
            "Content-Type"  = "application/json"
            "Accept"        = "application/json"
            "X-Tenant-Id"   = $xTenantId
            "X-Session-Id"  = $sessionId
        }
        
        $beneficiaryResponse = Invoke-RestMethod -Uri $beneficiaryUrl -Method Post -Headers $headers -Body $beneficiaryBody
        
        $benName = if ($beneficiary.shortName) { $beneficiary.shortName } else { "Unknown" }
        Write-Host "Added beneficiary: $benName" -ForegroundColor Green
        
        if ($beneficiaryResponse.data -and $beneficiaryResponse.data.id) {
            $beneficiaryIds += $beneficiaryResponse.data.id
            Write-Host "  ID: $($beneficiaryResponse.data.id)" -ForegroundColor White
        }
        
        # Save beneficiary data
        $beneficiaryData = @{
            customerId     = $customerId
            walletId       = $walletId
            beneficiaryIds = $beneficiaryIds
            beneficiaries  = $beneficiaries
            addedAt        = (Get-Date).ToString("yyyy-MM-dd HH:mm:ss")
        }
        
        # Optionally save to file
        $beneficiaryFile = "./beneficiaries_$(Get-Date -Format 'yyyyMMddHHmmss').json"
        $beneficiaryData | ConvertTo-Json -Depth 5 | Set-Content -Path $beneficiaryFile
    }
    catch {
        $benName = if ($beneficiary.shortName) { $beneficiary.shortName } else { "Unknown" }
        Write-Host "Failed to add beneficiary $benName : $($_.Exception.Message)" -ForegroundColor Red
        
        # Check for duplicate error
        if ($_.Exception.Message -match "duplicate|already exists") {
            Write-Host "  Beneficiary already exists" -ForegroundColor Yellow
        }
    }
}

Write-Host "Total beneficiaries added: $($beneficiaryIds.Count)" -ForegroundColor Cyan
```text`n## Related Endpoints

- [Get Beneficiaries](/latest/api-reference/v2.1/fintrans/get-beneficiaries) - List all beneficiaries
- [Update Beneficiary](/latest/api-reference/v2.1/fintrans/update-beneficiary) - Modify beneficiary details
- [Delete Beneficiary](/latest/api-reference/v2.1/fintrans/delete-beneficiary) - Remove beneficiary
- [Create Payment Consent](/latest/api-reference/v2.1/fintrans/create-payment-consent) - Set beneficiary restrictions