Desarrolladores
Errores

Errores

La API usa códigos HTTP estándar. Los errores llegan con esta forma:

{
  "message": "name, amount e id_currency son requeridos",
  "error": "Bad Request",
  "statusCode": 400
}

Códigos HTTP

CódigoSignificado
200 / 201OK. Ojo: GET /status/:reference devuelve 200 con {"status":"NOT_FOUND"} si no existe.
400Petición inválida: faltan campos, regla de negocio violada, o error del gateway.
401Autenticación: falta la key o el sistema está inactivo/suspendido.
404Recurso no encontrado (transacción, tarjeta, suscripción).
429Rate limit excedido — espera Retry-After segundos.
500Error interno — reintenta con backoff; si persiste, contáctanos.

Mensajes por endpoint

Autenticación (todos los endpoints con key)

HTTPMensaje
401Se requiere el header x-wpay-key
401Clave inválida o sistema inactivo
429Rate limit excedido (+ campo retryAfter y header Retry-After)

/payment/init

HTTPMensaje
400name, amount e id_currency son requeridos

/payment/auth-setup

HTTPMensaje
400reference y card son requeridos
404Transacción no encontrada
400Error en authentication setup (o mensaje del gateway)

/payment/process

HTTPMensaje
400reference, card, billing y personal son requeridos
404Transacción no encontrada
400Tarjeta bloqueada por política antifraude
400Error en autenticación 3DS
400Error al procesar el pago

/payment/charge-saved

HTTPMensaje
400card_key y amount son requeridos
404Tarjeta no encontrada
400La tarjeta no tiene token de cobro
400Tarjeta bloqueada por política antifraude
400Error al procesar el cobro

/payment/pending/:reference (DELETE)

HTTPMensaje
404Transacción no encontrada
400No se puede eliminar una transacción en estado {ESTADO}

/payment/refund

HTTPMensaje
400id_transaction, amount y reason son requeridos
404Transacción no encontrada
400Solo se pueden reembolsar transacciones aprobadas
400La transacción no tiene ID de CyberSource
400El monto de reembolso debe ser entre 0.01 y {monto}
400El monto excede el disponible para reembolso (ya reembolsado: {suma})
400Error al procesar el reembolso en CyberSource

/qr/generate

HTTPMensaje
400amount es requerido
400Mensaje del gateway QR

/cards/:key (PUT)

HTTPMensaje
404Tarjeta no encontrada

Suscripciones

HTTPMensaje
400card_key, plan_name y amount son requeridos
404Tarjeta no encontrada
400La tarjeta no tiene token de cobro
400reference es requerido
404Suscripción no encontrada

Recomendaciones de manejo

  • 400 del gateway: muéstrale al cliente un mensaje genérico ("No pudimos procesar tu pago, intenta con otra tarjeta") — el message técnico es para tus logs.
  • 429: backoff usando Retry-After.
  • Timeout de red en /payment/process: ¡no reintentes a ciegas! Consulta GET /status/:reference para saber si el cobro llegó a ejecutarse.
WebhooksPruebas y simulador