Save beneficiary
Bearer ds_live_ / ds_test_POST
/api/v1/merchant/beneficiariesSaves a customer. If one already exists with the same category, biller and customer_ref, it is updated instead (upsert).
Language
curl -X POST "https://finaldatasub.com/api/v1/merchant/beneficiaries" \
-H "Authorization: Bearer ds_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"category": "cable",
"biller": "dstv",
"customer_ref": "7034567890",
"customer_name": "JOHN DOE",
"label": "Mum'\''s decoder"
}'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 |
| Content-Type | application/json | 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
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
| category | string | Yes | Service category: data, airtime, electricity, cable, education, betting, internet, voice, bulk_sms, rechargepin, giftcard, esim. |
| customer_ref | string | Yes | Phone, meter, smartcard or customer id (max 60). |
| biller | string | No | Biller slug in that category, e.g. dstv. Unknown slugs are saved without a biller. |
| customer_name | string | No | Verified account name (max 120). |
| label | string | No | Your own nickname for this beneficiary (max 60). |
Responses
201 Created — Saved
{
"success": true,
"message": "Beneficiary saved.",
"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": null,
"last_amount": null,
"metadata": null,
"last_used_at": null,
"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"
}
}
}Errors
Errors specific to this endpoint, in addition to the authentication and validation errors common to every request.
| Code | HTTP | When |
|---|---|---|
| REQUIRED | 400 | category or customer_ref is missing. |
| INVALID_CATEGORY | 400 | category is not a known service category. |
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.