> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lipafy.xyz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lipafy.xyz/_mcp/server.

# Beneficiaries & Destination Registry

> How to register, verify, and secure payment destinations across Kenyan rails.

A **Beneficiary** represents a validated, encrypted payment destination stored within your workspace. Agents and operators refer to beneficiaries by immutable UUIDs rather than passing raw telecom credentials in every payload.

---

## 🔒 Security & Privacy Guarantees

* **Encrypted at Rest:** All account numbers and phone numbers are encrypted with AES-256-GCM.
* **Cryptographic Fingerprinting:** A SHA-256 hash of the normalized destination is indexed to prevent accidental duplicate beneficiary registration and duplicate payouts.
* **Masked in Audit Logs:** Sensitive numbers appear masked in telemetry logs and API responses (e.g. `2547****1234` or `PayBill 150501 (Ref: ****456)`).
* **Risk Aging:** Lipafy tracks when a destination was created or last updated. If bank account numbers or phone numbers were modified within the last 48 hours, approval screens flag the destination with an elevated risk notice to guard against invoice manipulation.

---

## 🛠️ Registering a Beneficiary (API)

```bash
curl -X POST https://api.lipafy.xyz/v1/beneficiaries \
  -H "Authorization: Bearer lip_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Safaricom Home Fibre - Office",
    "type": "paybill",
    "payment_rail": "MPESA_B2B",
    "destination": "150501",
    "account_reference_required": true,
    "default_account_reference": "0722123456"
  }'
```

### Destination Types & Required Fields

| Destination Type          | `type` Value   | `payment_rail` | Required Destination Format                           | Account Reference Required?     |
| :------------------------ | :------------- | :------------- | :---------------------------------------------------- | :------------------------------ |
| **M-Pesa PayBill**        | `paybill`      | `MPESA_B2B`    | 5–7 digit PayBill shortcode (e.g. `150501`, `444400`) | **Yes** (Account / Invoice No.) |
| **M-Pesa Buy Goods Till** | `till`         | `MPESA_B2B`    | 5–7 digit Till number (e.g. `565444`)                 | **No**                          |
| **M-Pesa B2C Mobile**     | `phone`        | `MPESA_B2C`    | Kenyan phone in `254XXXXXXXXX` format                 | **No**                          |
| **PesaLink Bank Account** | `bank_account` | `PESALINK`     | Account number + Destination bank routing code        | **Optional**                    |
| **Lipafy @tag**           | `tag`          | `INTERNAL`     | `@username` (e.g. `@alice`)                           | **No**                          |