List beneficiaries
Bearer ds_live_ / ds_test_GET
/api/v1/merchant/beneficiariesLists the phone numbers, meters, smartcards and betting ids you saved, most recently used first. Successful purchases save the customer automatically unless you send save_beneficiary: false.
Language
curl -X GET "https://finaldatasub.com/api/v1/merchant/beneficiaries?category=cable&search=mum&per_page=20" \
-H "Authorization: Bearer ds_live_YOUR_KEY" \
-H "Accept: application/json"Authentication
Send your secret API key in the header. Authorization: Token … and X-API-Key: … are also accepted.
| Header | Value | Required |
|---|---|---|
| Authorization | Bearer ds_live_YOUR_KEY | Yes |
| Accept | application/json | Recommended |
Authentication failures (401 UNAUTHORIZED, 403 IP_NOT_ALLOWED / ACCOUNT_SUSPENDED / API_ACCESS_NOT_APPROVED, 429 RATE_LIMITED) are listed in Authentication.
Parameters
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| category | string | No | Filter by category: data, airtime, electricity, cable, education, betting, internet, voice, bulk_sms, rechargepin, giftcard, esim. |
| search | string | No | Matches label, customer_ref or customer_name. |
| per_page | integer | No | Results per page, 1–100 (default 50). |
| page | integer | No | Page number (default 1). |
Responses
200 OK — OK
{
"success": true,
"message": "Request successful.",
"data": [
{
"id": 52,
"user_id": 1042,
"category": "cable",
"biller_id": 12,
"label": "Mum's decoder",
"customer_ref": "7034567890",
"customer_name": "JOHN DOE",
"last_product_id": 33,
"last_amount": "15700.00",
"metadata": null,
"last_used_at": "2026-10-05T10:30:01.000000Z",
"created_at": "2026-10-05T10:50:00.000000Z",
"updated_at": "2026-10-05T10:50:00.000000Z",
"biller": {
"id": 12,
"name": "DStv",
"slug": "dstv",
"category": "cable",
"network": null,
"logo_url": "https://cdn.example.com/billers/dstv.png"
},
"last_product": {
"id": 33,
"public_id": 640,
"name": "DStv Compact",
"amount": "15700.00"
}
}
],
"meta": {
"current_page": 1,
"last_page": 1,
"per_page": 20,
"total": 1,
"from": 1,
"to": 1
},
"links": {
"first": "/api/v1/merchant/beneficiaries?page=1",
"last": "/api/v1/merchant/beneficiaries?page=1",
"prev": null,
"next": null
}
}Notes
- Beneficiary endpoints use the
{success, message, data}envelope (not the transaction format). Validation errors still use the standard{status: "failed", code, message}body with HTTP 400. last_product.public_idis the plan id to send asproduct_idwhen buying again.