Gift cards

Issue one closed-loop BreezeGift card per request. The API auto-delivers a claim link to the recipient (email, and WhatsApp when a phone number is provided). Raw gift codes are never returned.


POST /ext/breeze/v1/giftcards/breeze/issue

Limits

Rule	Value
Face value	₦10,000 – ₦500,000
Quantity	Always 1
Wallet	Debited for the face value; 402 if balance is insufficient or no wallet is enrolled
Idempotency	`request_id` unique per merchant (409 on replay)

Request

Field	Required	Description
`request_id`	Yes	Your idempotency key
`face_value`	Yes	Amount as a string, e.g. `"10000"`
`currency`	No	Defaults to `NGN`
`recipient_name`	Yes	Name shown on the gift
`recipient_email`	Yes	Claim email destination
`recipient_phone`	No	Nigerian MSISDN for WhatsApp delivery
`buyer_name`	No	Sender name (defaults to `Breeze`)
`buyer_email`	No	Optional buyer confirmation
`gift_message`	No	Short message to the recipient

Example


curl -X POST "https://staging-intelligent-70287b6a3284.herokuapp.com/ext/breeze/v1/giftcards/breeze/issue" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Key: mk_live_your_key_id" \
  -H "X-Merchant-Secret: sk_live_your_secret" \
  -d '{
    "request_id": "reseller-gift-001",
    "face_value": "10000",
    "currency": "NGN",
    "recipient_name": "Ada Okafor",
    "recipient_email": "ada@example.com",
    "recipient_phone": "08031234567",
    "buyer_name": "Reseller Co",
    "gift_message": "Enjoy your gift"
  }'

Success response (`201`)


{
  "data": {
    "batch_id": 123,
    "request_id": "reseller-gift-001",
    "status": "issued",
    "recipient_email": "ada@example.com",
    "email_sent": true,
    "buyer_email_sent": false,
    "whatsapp_sent": true,
    "cards": [
      {
        "id": 456,
        "claim_url": "https://breezegift.com/c/…",
        "whatsapp_url": "https://wa.me/…",
        "face_value": "10000",
        "balance": "10000",
        "currency": "NGN",
        "expires_at": "2027-07-28T00:00:00Z",
        "status": "active"
      }
    ]
  }
}

The recipient opens claim_url (or the WhatsApp deep link) to claim and spend the card. Your integration should store request_id, batch_id, and claim_url — not a gift code.

Errors

HTTP	Meaning
`400`	Invalid body (face value out of range, missing recipient, etc.)
`401`	Missing or invalid merchant credentials
`402`	Insufficient wallet balance, or wallet not enrolled
`409`	Duplicate `request_id` for this merchant
`503`	Gift card service unavailable

Check balance before issuing: Wallet balance.