Beneficiaries & Destination Registry

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)

$
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