Canjear una tarjeta de regalo en mostrador

POST

https://app.recurrente.com/api/gift_cards/:gift_card_id/redemption

POST

/api/gift_cards/:gift_card_id/redemption

curl -X POST https://app.recurrente.com/api/gift_cards/gift_card_id/redemption \
     -H "X-SECRET-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "amount_in_cents": 4000
}'

{
  "id": "gc_9f8e7d6c",
  "account_id": "ac_7890abcd",
  "code": "GC-7X9Y-Z3PQ",
  "status": "active",
  "currency": "GTQ",
  "initial_amount_in_cents": 25000,
  "balance_in_cents": 21000,
  "expires_on": "2024-12-31",
  "recipient": {
    "name": "Carlos Méndez",
    "email": "carlos.mendez@example.com",
    "phone": "+502 5555 1234"
  },
  "message": "Feliz cumpleaños, disfruta tu regalo!",
  "deliver_on": "2024-01-10",
  "delivered_at": "2024-01-10T15:45:00Z",
  "purchaser": {
    "name": "Ana López",
    "email": "ana.lopez@example.com"
  },
  "checkout_id": "chk_4567efgh",
  "public_url": "https://recurrente.com/gift_cards/gc_9f8e7d6c",
  "transactions": [
    {
      "id": "gct_1234abcd",
      "kind": "issue",
      "amount_in_cents": 25000,
      "balance_after_in_cents": 25000,
      "currency": "GTQ",
      "account_id": "ac_7890abcd",
      "checkout_id": "chk_4567efgh",
      "note": "Emisión inicial de la tarjeta",
      "created_at": "2023-12-01T10:00:00Z"
    },
    {
      "id": "gct_5678efgh",
      "kind": "redeem",
      "amount_in_cents": -4000,
      "balance_after_in_cents": 21000,
      "currency": "GTQ",
      "account_id": "ac_7890abcd",
      "checkout_id": "null",
      "note": "Canje en mostrador por venta en efectivo",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "created_at": "2023-12-01T10:00:00Z"
}

Gasta saldo de la tarjeta por una venta cobrada fuera de un checkout de Recurrente (efectivo, otra terminal), como “Canjear” en el panel. Un canje en otra sucursal de la organización se le paga a esa sucursal. Emite gift_card.redeem. Requiere que la llave pueda mover dinero.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

Path parameters

gift_card_idstringRequired

Request

This endpoint expects an object.

amount_in_centsintegerRequired

notestringOptional

Response

La tarjeta, con el canje

idstringOptional

account_idstringOptional

La cuenta que la vendió.

codestringOptional

El código que se canjea. Es un secreto al portador.

statusenumOptional

Allowed values:

currencystringOptional

initial_amount_in_centsintegerOptional

balance_in_centsintegerOptional

expires_ondate or nullOptional

recipientobjectOptional

messagestring or nullOptional

deliver_ondate or nullOptional

delivered_atdatetime or nullOptional

purchaserobjectOptional

checkout_idstring or nullOptional

El checkout que la vendió.

public_urlstringOptional

La página de saldo de la tarjeta, la que abre su QR.

transactionslist of objectsOptional

Sus movimientos, del más viejo al más nuevo.

created_atdatetimeOptional

Errors

403

Forbidden Error

422

Unprocessable Entity Error