Product · Digital Cards

Gift Cards

Purchase digital gift cards for top international brands, or accept gift cards from your users for redemption with automated payout and webhook trade updates.

Base path/api/v1/partner/giftcards

Authx-api-key (+ x-signature on purchase/sell)

Max amount₦1,000,000 per transaction

Webhooksgiftcard.sale.approved · giftcard.sale.declined

1. List Gift Card Products

Query the catalog of digital cards with support for pagination and type filtering:

List available gift cards

GET /partner/giftcards/products

API key only

Query Param	Type	Default	Description
type	string	`buy`	Filter by trade direction: `buy` or `sell`
category	string	—	Filter by category ID
page	integer	`1`	Page number
limit	integer	`20`	Results per page

cURL

curl "https://api.billpadi.com/api/v1/partner/giftcards/products?type=buy&page=1&limit=20" \
  -H "x-api-key: $API_KEY"

Example response — 200 OK

{
  "success": true,
  "message": "Gift cards retrieved successfully",
  "data": [
    {
      "id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "name": "Apple / iTunes Gift Card",
      "country": "US",
      "currency": "USD",
      "denominations": [10, 25, 50, 100],
      "buyRate": 1450,
      "sellRate": 1280
    }
  ],
  "pagination": {
    "total": 35,
    "page": 1,
    "limit": 20,
    "totalPages": 2,
    "hasNext": true,
    "hasPrev": false
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/giftcards/products"
}

2. Purchase a Gift Card

Purchase digital codes instantly using your main partner wallet balance:

Purchase digital gift card

POST /partner/giftcards/purchase

Signature required

Field	Type	Required	Description
giftCardId	string (ObjectId)	required	24-character hexadecimal ID from products catalog
productId	string (ObjectId)	optional	Optional variant ID (if card has specific denominations)
amount	number	required	Card face value in foreign currency (e.g. `50` USD)
quantity	integer	required	Number of cards (1 to 10)
partnerReference	string	required	Unique reference string (2–100 characters) for idempotency

cURL

Node.js

curl -X POST https://api.billpadi.com/api/v1/partner/giftcards/purchase \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "giftCardId": "64f1a2b3c4d5e6f7a8b9c0d1",
    "amount": 50,
    "quantity": 1,
    "partnerReference": "PR-GC-10293"
  }'

const res = await partnerClient.post("/giftcards/purchase", {
  giftCardId: "64f1a2b3c4d5e6f7a8b9c0d1",
  amount: 50,
  quantity: 1,
  partnerReference: "PR-GC-10293"
});

Example response — 201 Created

{
  "success": true,
  "message": "Giftcard purchased successfully",
  "data": {
    "transactionReference": "TXN_1720603200000_3A91",
    "partnerReference": "PR-GC-10293",
    "status": "success",
    "amount": 50,
    "quantity": 1,
    "codes": [
      { "code": "X92K-LL92-MM10-PP41", "pin": "9921" }
    ]
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/giftcards/purchase"
}

3. Sell a Gift Card

Submit customer gift card redemption details and images for automated processing and review:

Submit gift card for sale

POST /partner/giftcards/sell

Signature required

Field	Type	Required	Description
giftCardId	string (ObjectId)	required	24-character hexadecimal ID
amount	number	required	Face value of the card
quantity	integer	required	Number of cards (1 to 10)
cards	array<string>	required	1 to 10 URLs pointing to card front/back images or receipts
comment	string	optional	Optional redemption note (e.g. e-code details)
partnerReference	string	required	Unique reference string for idempotency

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/giftcards/sell \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "giftCardId": "64f1a2b3c4d5e6f7a8b9c0d1",
    "amount": 100,
    "quantity": 1,
    "cards": ["https://cdn.yourdomain.com/uploads/card-front.jpg"],
    "comment": "Physical card with purchase receipt",
    "partnerReference": "PR-GCS-88213"
  }'

Example response — 201 Created

{
  "success": true,
  "message": "Giftcard sold successfully",
  "data": {
    "transactionReference": "TXN_1720603200000_7C12",
    "partnerReference": "PR-GCS-88213",
    "status": "pending_manual"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/giftcards/sell"
}

When the card is reviewed, Billpadi fires a giftcard.sale.approved webhook (and credits your wallet) or a giftcard.sale.declined webhook with the decline reason — see Webhooks.

4. Transaction Status & Listing

Get gift card transaction status

GET /partner/giftcards/transactions/:transactionRef

API key only

List gift card transactions

GET /partner/giftcards/transactions

API key only

← PreviousEducation (WAEC / JAMB)Next →Crypto Trading