Anular una tarjeta de regalo

POST

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

POST

/api/gift_cards/:gift_card_id/void

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

{
  "id": "gc_9f8e7d6c",
  "account_id": "ac_7890abcd",
  "code": "GC-4F7H-JK9L",
  "status": "voided",
  "currency": "GTQ",
  "initial_amount_in_cents": 25000,
  "balance_in_cents": 0,
  "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-10T10:15: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": "void",
      "amount_in_cents": -15000,
      "balance_after_in_cents": 0,
      "currency": "GTQ",
      "account_id": "ac_7890abcd",
      "checkout_id": "chk_4567efgh",
      "note": "Tarjeta anulada por solicitud del cliente",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "created_at": "2024-01-10T09:00:00Z"
}

La tarjeta deja de funcionar y pierde lo que tenía, como “Anular” en el panel. Anular una tarjeta anulada no cambia nada. Emite gift_card.void. 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.

notestringOptional

Response

La tarjeta anulada

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