Vender gift cards

Tus clientes regalan saldo en una tienda venezolana —Farmatodo, Arturo’s y otras— y quien lo recibe lo gasta desde un enlace, sin cuenta ni app: paga en la tienda con Pago Móvil hasta agotar el saldo. La página que ve lleva tu marca: tu logo, tus colores y tus textos.

Pagas cada gift card con tu saldo en USD en Bolívar Connect, al momento de emitirla. Si la tarjeta vence sin gastarse, lo que quedó vuelve a tu saldo.

Lo que necesitas

Una API key con giftcards:write (las keys completas ya lo traen).
Saldo en USD. Se fondea como el resto de tu programa; consúltalo con GET /v1/treasury/position?asset=USD.
Una key de prueba (mode: test) para probar sin gastar: emite tarjetas de sandbox que se ven igual pero no se pueden canjear y no te cobran.

1. Tu marca

El kit. Reemplaza el kit completo cada vez que lo mandas. Te devolvemos todos los errores juntos.

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."
  }
}'

El logo. PNG o JPEG, hasta 180 kB, como data:. null lo quita.

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)\"}"

Las tiendas. Por defecto vendes todas las que te habilitamos. Para vender sólo algunas, mándalas en marcas (null vuelve a todas).

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"]}'

Campo	Regla
`colores.*`	`#RRGGBB`. `texto` sobre `fondo` y sobre `superficie`: contraste ≥ 4,5 (WCAG AA).
`radio`	Entero de 0 a 32 (px).
`textos.*`	Hasta 60 caracteres. `{marca}` se cambia por el nombre de la tienda.
`soporte`	`whatsapp` con código de país y sólo dígitos; `url` con `https://`.
`pie_legal`	Hasta 240 caracteres. El pie «Operado por Bolívar Connect» va siempre.

2. El catálogo

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" }
}

Los montos van en centavos de USD: 2000 son $20,00. fee.bps es tu margen en centésimas de 1 %: 300 es el 3 %, y se cobra aparte del valor de la tarjeta. El 3 % es un ejemplo: tu margen depende de tu acuerdo comercial y de tu volumen, y es el que devuelve tu programa en fee.

3. Emitir

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…"
}

De tu saldo salen $20,60: el valor más el 3 % del ejemplo.

Las respuestas posibles

HTTP	Qué pasó
`201`	Emitida. Trae el `url`. Si repites la petición con la misma `Idempotency-Key`, el `201` llega con `url: null` y la cabecera `Idempotent-Replayed: true`: pídelo con `?includeLink=1`.
`200`	Ese `externalId` ya se había emitido: es la misma tarjeta (`replay: true`) y no se cobra otra vez. Sin `url`: pídelo con `?includeLink=1`.
`202`	El emisor no respondió a tiempo. La tarjeta queda `pendiente` con el dinero retenido y se resuelve sola en segundos o minutos: te llega `giftcard.issued` o `giftcard.failed`. No vuelvas a emitir con otro `externalId`.
`409` `giftcard_external_id_reused`	Ese `externalId` ya se usó con otra tienda u otro monto.
`422` `insufficient_tenant_funds`	No te alcanza el saldo en USD. No se cobró nada.
`422` `giftcard_brand_not_allowed`	La tienda no está en tu catálogo. `meta.allowedBrands` dice cuáles sí.
`503` `giftcards_unavailable`	Problema nuestro, no tuyo. No se cobró nada: reintenta con el mismo `externalId`.

El externalId es tu id de la orden: con él, reintentar por un timeout nunca emite dos tarjetas ni cobra dos veces.

4. Consultar

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 → activa → usada (saldo en cero) o expirada. fallida es una emisión que no salió: su dinero ya volvió a tu saldo. Para paginar, pasa en before el createdAt del último que recibiste.

5. Webhooks

Llegan a tu URL de siempre, firmados igual que el resto (Webhooks). El payload es la gift card, como en la API.

Evento	Cuándo	Además trae
`giftcard.issued`	Emitida (también al resolverse una `pendiente`).	—
`giftcard.failed`	No se pudo emitir; el dinero volvió a tu saldo.	`error`
`giftcard.opened`	Tu cliente abrió el regalo (la primera vez).	—
`giftcard.redeemed`	Pagó en una tienda.	`redemption`: `amount` (USD), `amountBs`, `exchangeRate`, `merchant`, `reference`
`giftcard.expired`	Venció; lo no gastado volvió a tu saldo.	`refunded`

Ningún webhook trae el url con la clave de gasto.

Lo que se cobra

Al emitir: valor de la tarjeta + tu margen, de tu saldo en USD.
Si no se emite (rechazo o caída): se devuelve todo.
Al vencer: el saldo no gastado vuelve a tu saldo. El margen no se devuelve.
Una gift card nunca usa tu línea de crédito: sólo tu saldo prefondeado.

El tiempo para gastarla va de 1 a 365 días (90 si no dices nada). Quien la recibe la gasta en bolívares a la tasa del momento del pago, en una o varias compras.