Sell gift cards on behalf of your customers

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.

Get started

Guides

Sell gift cards on behalf of your customers

List the cards you can sell

Submit a card for review

Track the sale

​List the cards you can sell

​Submit a card for review

​Track the sale

List the cards you can sell

Submit a card for review

Track the sale