Sell gift cards

Your customers gift balance at a Venezuelan store —Farmatodo, Arturo’s and others— and whoever receives it spends it from a link, with no account or app: they pay at the store with Pago Móvil until the balance runs out. The page they see carries your brand: your logo, your colors and your copy.

You pay for each gift card with your USD balance in Bolívar Connect, at the moment you issue it. If the card expires unspent, whatever was left goes back to your balance.

What you need

An API key with giftcards:write (full keys already include it).
USD balance. It is funded like the rest of your program; check it with GET /v1/treasury/position?asset=USD.
A test key (mode: test) to try it without spending: it issues sandbox cards that look the same but cannot be redeemed and are not charged.

1. Your brand

The kit. It replaces the whole kit every time you send it. We return all errors together.

curl -X PUT https://api.bolivarconnect.com/v1/giftcards/programa \
  -H "x-api-key: $BC_KEY" -H "content-type: application/json" -d '{
  "kit": {
    "nombre": "Acme Remesas",
    "colores": { "primario": "#6C3BFF", "acento": "#00C2A8", "fondo": "#0F0B1E",
                 "superficie": "#1A1430", "texto": "#FFFFFF", "texto_secundario": "#B9B3D1" },
    "radio": 14,
    "textos": { "titulo": "Tu regalo Acme Remesas · {marca}", "boton_pagar": "Pagar en {marca}",
                "regalo_para": "Para ti, de parte de tu familia" },
    "soporte": { "whatsapp": "5491122334455", "email": "ayuda@acme-remesas.example" },
    "pie_legal": "Acme Remesas S.A."
  }
}'

The textos are what the recipient reads, so they usually go in Spanish.

The logo. PNG or JPEG, up to 180 kB, as data:. null removes it.

curl -X PUT https://api.bolivarconnect.com/v1/giftcards/programa/logo \
  -H "x-api-key: $BC_KEY" -H "content-type: application/json" \
  -d "{\"logo\":\"data:image/png;base64,$(base64 -i logo.png)\"}"

The stores. By default you sell all the ones we enabled for you. To sell only some, send them in marcas (null goes back to all).

curl -X PUT https://api.bolivarconnect.com/v1/giftcards/programa \
  -H "x-api-key: $BC_KEY" -H "content-type: application/json" \
  -d '{"marcas": ["farmatodo", "arturos"]}'

Field	Rule
`colores.*`	`#RRGGBB`. `texto` on `fondo` and on `superficie`: contrast ≥ 4.5 (WCAG AA).
`radio`	Integer from 0 to 32 (px).
`textos.*`	Up to 60 characters. `{marca}` is replaced with the store’s name.
`soporte`	`whatsapp` with country code and digits only; `url` with `https://`.
`pie_legal`	Up to 240 characters. The “Operado por Bolívar Connect” footer is always shown.

2. The catalog

curl https://api.bolivarconnect.com/v1/giftcards/catalogo -H "x-api-key: $BC_KEY"

{
  "mode": "live",
  "brands": [
    { "id": "farmatodo", "name": "Farmatodo", "tagline": "Salud y bienestar",
      "logoUrl": "https://…/farmatodo-logo.webp", "color": "#0066B3",
      "minAmount": 100, "maxAmount": 50000 }
  ],
  "asset": "USD",
  "fee": { "bps": 300, "fixed": "0" }
}

Amounts are in USD cents: 2000 is $20.00. fee.bps is your margin in hundredths of 1%: 300 is 3%, and it is charged separately from the card’s value. The 3% is an example: your margin depends on your commercial agreement and your volume, and it is the one your program returns in fee.

3. Issuing

curl -X POST https://api.bolivarconnect.com/v1/giftcards \
  -H "x-api-key: $BC_KEY" -H "content-type: application/json" -d '{
  "externalId": "acme-order-88213",
  "brandId": "farmatodo",
  "amount": 2000,
  "expiresInDays": 90,
  "beneficiaryName": "María",
  "giftSender": "Carlos",
  "giftMessage": "Para tus medicinas, mamá. Te quiero.",
  "sticker": "💐"
}'

{
  "giftcard": {
    "id": "6f1c…", "externalId": "acme-order-88213", "mode": "live",
    "brandId": "farmatodo",
    "amount":  { "asset": "USD", "amount": "2000" },
    "fee":     { "asset": "USD", "amount": "60" },
    "balance": { "asset": "USD", "amount": "2000" },
    "status": "activa", "opened": false,
    "expiresAt": "2027-01-05T14:02:11.000Z", "createdAt": "2026-10-07T14:02:11.000Z"
  },
  "url": "https://…/g/k3n8sp2qz7wd#k=Zm9vYmFy…"
}

$20.60 comes out of your balance: the value plus the example’s 3%.

The possible responses

HTTP	What happened
`201`	Issued. It carries the `url`. If you repeat the request with the same `Idempotency-Key`, the `201` arrives with `url: null` and the `Idempotent-Replayed: true` header: request it with `?includeLink=1`.
`200`	That `externalId` had already been issued: it is the same card (`replay: true`) and it is not charged again. No `url`: request it with `?includeLink=1`.
`202`	The issuer did not respond in time. The card stays `pendiente` (pending) with the money held and resolves on its own in seconds or minutes: you get `giftcard.issued` or `giftcard.failed`. Do not issue again with another `externalId`.
`409` `giftcard_external_id_reused`	That `externalId` was already used with another store or another amount.
`422` `insufficient_tenant_funds`	Your USD balance is not enough. Nothing was charged.
`422` `giftcard_brand_not_allowed`	The store is not in your catalog. `meta.allowedBrands` says which ones are.
`503` `giftcards_unavailable`	Our problem, not yours. Nothing was charged: retry with the same `externalId`.

The externalId is your order id: with it, retrying after a timeout never issues two cards or charges twice.

4. Looking them up

curl "https://api.bolivarconnect.com/v1/giftcards/6f1c…" -H "x-api-key: $BC_KEY"
curl "https://api.bolivarconnect.com/v1/giftcards?externalId=acme-order-88213" -H "x-api-key: $BC_KEY"
curl "https://api.bolivarconnect.com/v1/giftcards?status=activa&limit=50" -H "x-api-key: $BC_KEY"

status: pendiente (pending) → activa (active) → usada (used, balance at zero) or expirada (expired). fallida (failed) is an issuance that did not go through: its money is already back in your balance. To paginate, pass the createdAt of the last one you received in before.

5. Webhooks

They arrive at your usual URL, signed the same way as the rest (Webhooks). The payload is the gift card, as in the API.

Event	When	Also carries
`giftcard.issued`	Issued (also when a `pendiente` one is resolved).	—
`giftcard.failed`	It could not be issued; the money went back to your balance.	`error`
`giftcard.opened`	Your customer opened the gift (the first time).	—
`giftcard.redeemed`	They paid at a store.	`redemption`: `amount` (USD), `amountBs`, `exchangeRate`, `merchant`, `reference`
`giftcard.expired`	It expired; what was not spent went back to your balance.	`refunded`

No webhook carries the url with the spending key.

What is charged

On issuance: card value + your margin, from your USD balance.
If it is not issued (rejection or outage): everything is refunded.
On expiry: the unspent balance goes back to your balance. The margin is not refunded.
A gift card never uses your credit line: only your prefunded balance.

The time to spend it ranges from 1 to 365 days (90 if you do not say). The recipient spends it in bolívares at the rate at the time of payment, in one or several purchases.