> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitliva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](https://docs.bitliva.com/api-reference/giftcards-list) 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. |

```json theme={null}
{
  "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`](https://docs.bitliva.com/api-reference/giftcards-sell) 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. |

```bash theme={null}
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:

```json theme={null}
"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](https://docs.bitliva.com/guides/webhooks), and you can also read the sale with [Get one transaction](https://docs.bitliva.com/api-reference/transactions-get.md).

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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.