Buy gift card
Bearer ds_live_ / ds_test_POST
/api/v1/merchant/giftcard/purchaseBuys digital gift cards (Amazon, iTunes, Google Play, Steam and more). Card codes are returned in delivery once successful; while pending, they arrive on the webhook and on requery.
Language
curl -X POST "https://finaldatasub.com/api/v1/merchant/giftcard/purchase" \
-H "Authorization: Bearer ds_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"reference": "ORDER-10031",
"biller": "amazon-us",
"product_id": 1201,
"quantity": 1,
"recipient_email": "customer@example.com",
"sender_name": "Ada"
}'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 |
|---|---|---|---|
| reference | string | Yes | Your unique order reference and idempotency key (max 128 chars). Re-sending it returns the original transaction and never charges twice. |
| product_id | integer | string | Yes | Plan id from List billers / Biller products. You may send the product code instead, but only together with biller. |
| biller | string | No | Gift card brand slug (List billers, category giftcard). |
| quantity | integer | No | Number of cards, 1–10 (default 1). |
| recipient_email | string | No | Email the provider sends the card to (max 160). |
| sender_name | string | No | Name shown on the card email (max 60). |
| narration | string | No | Note stored on the transaction (max 255 chars). |
| save_beneficiary | boolean | No | Save the customer to your beneficiaries after a successful purchase (default true). |
| beneficiary_label | string | No | Label for the saved beneficiary (max 60 chars). |
Responses
201 Created — Successful · 202 Accepted — Pending · 422 Unprocessable Entity — Failed (refunded)
{
"status": "successful",
"reference": "ORDER-10031",
"channel": "api",
"transaction_id": "DS261005104410K7L8M9N0",
"category": "giftcard",
"message": "Transaction successful.",
"biller": "Amazon US",
"biller_slug": "amazon-us",
"product_id": 1201,
"product": "Amazon US $25",
"customer_ref": "customer@example.com",
"quantity": 1,
"unit_amount": "41500.00",
"amount": "41500.00",
"face_amount": "41500.00",
"fee": "0.00",
"discount": "0.00",
"total_deducted": "41500.00",
"balance_before": "50000.00",
"balance_after": "8500.00",
"provider_reference": "PRV-88215510",
"purchased_at": "2026-10-05T10:44:10+01:00",
"delivery": [
{
"card_number": "AQ7X-9KLM-PQ2R",
"pin": "8812"
}
]
}Errors
Errors specific to this endpoint, in addition to the authentication and validation errors common to every request.
| Code | HTTP | When |
|---|---|---|
| INVALID_QUANTITY | 400 | Quantity must be between 1 and 10. |
| INVALID_RECIPIENT_EMAIL | 400 | recipient_email is not a valid email. |
| BILLER_NOT_FOUND | 404 | Unknown or inactive biller / network. |
| PRODUCT_NOT_FOUND | 404 | Plan id / code not found, inactive or not part of this biller. |
| SERVICE_UNAVAILABLE | 503 | The service or biller is disabled or temporarily unavailable. |
| INVALID_AMOUNT | 400 | Amount is zero or outside the biller's minimum / maximum. |
| DAILY_LIMIT_EXCEEDED | 429 | Your daily spend limit for this service is reached. |
| TIER_MAX_BALANCE / TIER_DAILY_LIMIT / TIER_MONTHLY_LIMIT | 429 | An account tier limit is reached. Upgrade KYC to raise it. |
| INSUFFICIENT_BALANCE | 402 | Wallet balance is too low for this purchase. |
| WALLET_INACTIVE | 403 | Your wallet is frozen or not active. |
| WALLET_BUSY | 409 | Another request is updating your wallet. Retry with the same reference. |
| TRANSACTION_FAILED | 422 | The provider could not deliver. Your wallet was refunded. |
| DUPLICATE | 200 / 202 / 409 | The reference was already used. The original transaction is returned. |
Notes
- Treat card codes like cash: store them encrypted and show them only to the buyer.