API Reference | Blitz Ecom

Autenticacion

Todas las solicitudes a la API requieren un header de autorizacion con tu API key. Las keys de sandbox comienzan con sk_test_ y las de produccion con sk_live_.

Importante

Nunca expongas tus API keys en el codigo del lado del cliente. Usa variables de entorno o un vault seguro.

Header de autenticacion

Authorization: Bearer sk_test_abc123def456ghi789

Crear Pago

POST /payments

Crea un nuevo pago. El sistema de routing seleccionara automaticamente el mejor procesador.

Cuerpo de la solicitud

{
  "amount": 15000,
  "currency": "MXN",
  "method": "card",
  "card": {
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2027,
    "cvc": "123"
  },
  "customer": {
    "email": "cliente@correo.com",
    "name": "Juan Perez"
  },
  "metadata": {
    "order_id": "ORD-2026-001"
  },
  "description": "Pago de ejemplo"
}

Respuesta (201 Created)

{
  "id": "pay_7sK2mN4xR8wQ",
  "object": "payment",
  "status": "requires_action",
  "amount": 15000,
  "currency": "MXN",
  "processor": "stripe",
  "client_secret": "cs_live_...",
  "created_at": "2026-07-10T14:30:00Z",
  "next_action": {
    "type": "redirect",
    "url": "https://checkout.stripe.com/..."
  }
}

Confirmar Pago

POST /payments/{id}/confirm

Confirma un pago que requiere accion adicional (3D Secure, autenticacion biométrica, etc).

Cuerpo de la solicitud

{
  "payment_id": "pay_7sK2mN4xR8wQ",
  "return_url": "https://mitienda.com/pago-exitoso"
}

Respuesta (200 OK)

{
  "id": "pay_7sK2mN4xR8wQ",
  "status": "succeeded",
  "amount": 15000,
  "processor": "stripe",
  "confirmed_at": "2026-07-10T14:32:15Z"
}

Obtener Pago

GET /payments/{id}

Obtiene los detalles completos de un pago por su ID.

Respuesta (200 OK)

{
  "id": "pay_7sK2mN4xR8wQ",
  "object": "payment",
  "status": "succeeded",
  "amount": 15000,
  "currency": "MXN",
  "processor": "stripe",
  "customer": {
    "email": "cliente@correo.com",
    "name": "Juan Perez"
  },
  "metadata": {
    "order_id": "ORD-2026-001"
  },
  "created_at": "2026-07-10T14:30:00Z",
  "updated_at": "2026-07-10T14:32:15Z"
}

Reembolsar Pago

POST /payments/{id}/refund

Realiza un reembolso total o parcial de un pago exitoso.

Cuerpo de la solicitud

{
  "amount": 7500,
  "reason": "customer_request",
  "metadata": {
    "ticket_id": "TK-1234"
  }
}

Respuesta (200 OK)

{
  "id": "ref_9xP3kL5mT2nR",
  "status": "pending",
  "amount": 7500,
  "currency": "MXN",
  "payment_id": "pay_7sK2mN4xR8wQ",
  "created_at": "2026-07-10T15:00:00Z"
}

Errores

La API utiliza codigos de error HTTP estandar. Cada respuesta de error incluye un objeto con el tipo de error y un mensaje descriptivo.

Estructura de error

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "El campo 'amount' es requerido",
    "param": "amount"
  }
}

Rate Limits

Las solicitudes se limitan por API key. Si excedes el limite, recibirás un error 429.

1,000

Solicitudes / minuto (sandbox)

10,000

Solicitudes / minuto (produccion)

100

Webhooks / minuto

Headers de rate limit

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1720636800

Webhooks

Configure URLs de webhook para recibir notificaciones en tiempo real sobre eventos de pago. Los webhooks se firman con HMAC-SHA256 para verificacion.

Payload de webhook

{
  "id": "evt_abc123",
  "type": "payment.succeeded",
  "created_at": "2026-07-10T14:32:15Z",
  "data": {
    "object": {
      "id": "pay_7sK2mN4xR8wQ",
      "status": "succeeded",
      "amount": 15000,
      "currency": "MXN"
    }
  }
}

Eventos disponibles

payment.created        - Pago creado
payment.processing    - Pago en procesamiento
payment.succeeded     - Pago exitoso
payment.failed        - Pago fallido
payment.cancelled     - Pago cancelado
refund.created        - Reembolso iniciado
refund.succeeded      - Reembolso completado