Sell gift cards on behalf of your customers

List sellable gift cards with naira rates, then submit a card for review with pictures or an e-code and track it until it is paid.

With the Bitliva Merchant API you can sell a customer’s gift card. You list the cards that can be sold, submit one for review, and you are paid to your wallet once it is approved.

List the cards you can sell

GET /giftcards returns cards with the naira rate per US dollar. minimum is in dollars. You can narrow the list with query parameters:

Parameter	Description
category_id	Only cards in this category. Ids come from categories in the response.
country	Only cards for this country, for example US. Not case sensitive.
form	Only cards of this form, for example physical or ecode. Not case sensitive.

{
  "id": 12,
  "category_id": 3,
  "name": "Amazon USD",
  "rate": "1180.00",
  "minimum": "10.00",
  "form": "physical",
  "country": "US"
}

Submit a card for review

POST /giftcards/sales submits a card for review. Use multipart/form-data when you attach pictures.

Field	Required	Description
customer_id	Yes	The customer’s id.
giftcard_id	Yes	The card id from the gift cards list.
amount	Yes	Card value in US dollars, at least the card’s minimum.
reference	Yes	Your own unique id for this sale, up to 64 letters, numbers and . _ : -.
attachments	Unless you send ecode	Pictures of the card. JPG or PNG, 5MB each, up to 20.
ecode	Unless you send attachments	The card code, for e-codes.
comment	No	Anything the reviewer should know, up to 500 characters.

curl -X POST https://merchant.bitliva.com/api/v1/giftcards/sales \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -F customer_id=2f6d1c0a-8a3e-4d59-b8a1-71e0c4d5f9a3 \
  -F giftcard_id=12 \
  -F amount=50 \
  -F reference=gc-9 \
  -F "attachments[]=@front.jpg" \
  -F "attachments[]=@back.jpg"

For an e-code, you can send ecode instead of pictures. The endpoint also accepts a JSON body when there are no attachments.

Track the sale

The response is 201 with a transaction of type giftcard_sale and status pending. The details object records the card, its value in dollars and the rate that applied:

"details": {
  "card": "Amazon USD",
  "card_value_usd": "50.00",
  "rate": "1180.00"
}

The sale stays pending until it is reviewed, then becomes successful or failed. When it is approved, the naira is paid to your wallet. You are notified by a transaction.successful or transaction.failed webhook, and you can also read the sale with Get one transaction.

Reusing a reference returns the original sale instead of submitting the card twice. Unavailable cards return giftcard_unavailable, and a failed submission returns giftcard_submission_failed.