Tokens de pago

Cada pago exitoso crea automáticamente un token reutilizable (pt_…). Esta página cubre los endpoints de lectura + revocación de tokens ya existentes. Para crear un token importando uno de un gateway externo, ver Tokenización.

Tokenize vs Payment Tokens

• POST /tokenize — importa un token existente de un gateway bajo un cliente (lo usan integradores migrando desde otro procesador).
• GET /customers/{external_customer_id}/payment-tokens — lista tarjetas ya guardadas a través de los flujos normales de checkout.
• POST /payment-tokens/{id}/deactivate — revoca un token para que no pueda volver a ser cobrado.

Ninguno de estos endpoints captura una tarjeta desde cero. Una tarjeta nueva siempre se tokeniza a través de una sesión de checkout.

Estados del token

Estado	Significado
active	Apto para POST /charge-token y para suscripciones.
inactive	Revocado por el comercio o el cliente. No se puede cobrar.
expired	Pasado expiry_month / expiry_year. No se puede cobrar.

Un token también pasa a inactivo automáticamente cuando el gateway subyacente lo marca como inutilizable (p. ej. contracargo / bloqueo por fraude).

Listar tarjetas guardadas de un cliente

GET /api/v1/customers/{external_customer_id}/payment-tokens

{external_customer_id} es el id de cliente del lado del comercio (tu wp_users.ID, tu Magento customer_id, tu Shopify customer_gid). Genius Checkout lo mapea en el primer pago — los plugins de tienda lo hacen automáticamente.

Respuesta (200)

{
  "data": [
    {
      "id": "pt_xyz789",
      "brand": "visa",
      "last4": "4242",
      "expiry_month": "12",
      "expiry_year": "2030"
    }
  ]
}

Si el cliente nunca ha pagado a través de Genius Checkout, la respuesta es {"data": []} (200, no 404), de manera que las UIs de tienda pueden renderizar la sección incondicionalmente.

El token cifrado nunca se devuelve — usa el id (pt_…) para referenciar el token en POST /charge-token o en POST /subscriptions.

Desactivar un token

POST /api/v1/payment-tokens/{external_id}/deactivate

Idempotente — llamarlo sobre un token ya inactivo devuelve 200 con el estado actual. Úsalo cuando:

• Un cliente cancela su suscripción del lado del comercio y quieres revocar la tarjeta guardada.
• Una señal de fraude indica que la tarjeta no debería ser cobrada.
• Estás limpiando tras flujos de eliminación de cuenta / derecho al olvido.

Respuesta (200)

{
  "id": "pt_xyz789",
  "status": "inactive",
  "brand": "visa",
  "last4": "4242"
}

Ejemplos de código

# Renderiza un selector de tarjetas guardadas en tu tienda
curl -H "Authorization: Bearer $GC_API_KEY" \
  "https://app.geniuscheckout.com/api/v1/customers/wp_user_42/payment-tokens"

// Node — revocar tras cancelar una suscripción
await fetch(`https://app.geniuscheckout.com/api/v1/payment-tokens/${tokenId}/deactivate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GC_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
})

# Python — listar tarjetas guardadas de un cliente
import requests
r = requests.get(
    f"https://app.geniuscheckout.com/api/v1/customers/{external_id}/payment-tokens",
    headers={"Authorization": f"Bearer {GC_API_KEY}"},
)
cards = r.json()["data"]

Notas de seguridad

• Las claves API están aisladas por comercio. Una solicitud con la clave de un comercio nunca puede ver ni revocar tokens de otro comercio — las consultas cruzadas devuelven data: [] o 404, nunca la existencia del recurso.
• Las tarjetas guardadas nunca se exponen en código del navegador. Los plugins de tienda consultan la lista desde PHP / del servidor y solo renderizan {id, brand, last4, expiry_*}. El token cifrado se queda en la plataforma GC.

Siguiente

• Tokenización — cobra una tarjeta guardada con POST /charge-token
• Suscripciones — asocia un token a un calendario recurrente