Skip to content

Developer Documentation

Beneficiaries

Manage a list of saved payment destinations for quick and easy transfers.

List Beneficiaries

GET /v1/payments/beneficiaries

Retrieve all saved beneficiaries for the authenticated user.

Query Parameters
Request Body
{}
Body Parameters
Test Request
Response
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "user_id": 101,
      "alias": "Mom",
      "destination": "254700000000",
      "currency": "KES",
      "created_at": "2025-10-26 11:00:00"
    },
    {
      "id": 2,
      "user_id": 101,
      "alias": "Landlord",
      "destination": "00100123456789",
      "currency": "KES",
      "created_at": "2025-10-26 11:05:00"
    }
  ]
}

Add Beneficiary

POST /v1/payments/beneficiaries

Save a new payment destination to your address book.

Request Body
{
  "alias": "Utility Bill",
  "destination": "987654",
  "currency": "KES"
}
Body Parameters
  • alias (string, required): A friendly name for the beneficiary.
  • destination (string, required): The destination account number or identifier.
  • currency (string, optional): The currency code (e.g., 'KES'). Defaults to 'KES'.
Test Request
Response
{
  "status": "success",
  "id": "3"
}

Delete Beneficiary

DELETE /v1/payments/beneficiaries

Remove a beneficiary from your address book using its unique ID.

Request Body
{
  "id": 3
}
Body Parameters
  • id (integer, required): The unique ID of the beneficiary to delete.
Test Request
Response
{
  "status": "success",
  "message": "Beneficiary deleted"
}