SWSPERU — Puente de pagos: referencia de la API

Esta es la referencia de la API del puente de pagos: la superficie HTTP que tu sistema puede usar para cobrar a tus propios clientes (tarjeta, PayPal, transferencia bancaria) usando tus propias credenciales de Izipay/PayPal/Culqi/Niubiz, sin construir tu propio módulo de pagos.

Este es un servicio independiente de la API de facturación electrónica — comparten la misma cuenta (tenant) y el mismo mecanismo de API key, pero cada servicio se activa por separado. Si tu cuenta todavía no tiene el puente de pagos habilitado, contacta a tu proveedor.

Los ejemplos de este documento reflejan el shape exacto de la respuesta, pero no son una prueba en vivo contra Izipay/PayPal/Culqi/Niubiz. Antes de ir a producción, prueba tu integración de punta a punta con tus credenciales de prueba reales.

1. Conceptos básicos

Base URL: https://<tu-dominio-facturador>/api/v1/external — la misma base que la API de facturación.
Autenticación: la misma API key (Authorization: Bearer sak_...) que usas para facturación — ver sección 2 de la Referencia de la API.
Un tenant = una cuenta: nunca vas a poder ver ni afectar cobros de otra organización con tu key.
reference, no un id numérico: cada cobro se identifica por un UUID (reference), nunca por un contador — no revela cuántos cobros procesa la plataforma en total.
Tú traes tus propias credenciales: este servicio no cobra con las credenciales de SWSPERU — cada pasarela que quieras usar necesita que primero registres tus propias llaves (sección 3).

2. Habilitar el servicio

Tu cuenta empieza con el puente de pagos desactivado. Pide a tu proveedor que lo active — una vez activo, ya puedes registrar credenciales y crear cobros.

3. Registrar tus credenciales de pasarela

PUT /portal/environments/{environment}/payment-gateway-credentials/{provider} (requiere sesión del portal, no la API key — es una acción de configuración, no de operación diaria).

{environment}: beta o produccion. {provider}: izipay, paypal, culqi o niubiz.

Body (credentials envuelve los campos, varían por proveedor):

Proveedor	Campos de `credentials`
`izipay`	`merchant_code`, `public_key`, `hash_key`
`paypal`	`mode` (`sandbox`/`live`), `client_id`, `client_secret`
`culqi`	`public_key`, `secret_key`
`niubiz`	`mode` (`sandbox`/`live`), `merchant_id`, `user`, `password`

{
  "credentials": {
    "merchant_code": "tu-merchant-code",
    "public_key": "tu-public-key",
    "hash_key": "tu-hash-key"
  }
}

Respuesta 200:

{ "provider": "izipay", "configured": true }

Por seguridad, GET .../payment-gateway-credentials/{provider} nunca devuelve los valores reales de vuelta — solo si ya está configurado.

4. Crear un cobro

POST /payments/charges

Headers: Authorization: Bearer <api_key>, Content-Type: application/json

Body:

Campo	Tipo	Requerido	Notas
`provider`	string	Sí	`izipay`, `paypal`, `culqi`, `niubiz` o `manual_transfer`
`amount`	number	Sí	Monto en la unidad de la moneda (ej. `49.90`, no centavos)
`currency`	string	No	ISO de 3 letras, default `PEN`
`email`	string	No	Email del cliente final
`customer_name`	string	No	Nombre del cliente final
`culqi_token`	string	Solo `culqi`	Token de tarjeta ya tokenizada (widget Culqi Checkout JS en tu frontend)
`return_url`	string (url)	Solo `paypal`	Base de tu propia app — el puente arma `return_url`/`cancel_url` sobre esto
`support_email`	string	No	Se usa en el mensaje de instrucciones de `manual_transfer`

Ejemplo (Izipay) — 201:

{
  "reference": "a3f1e2b0-...-uuid",
  "status": "pending",
  "provider": "izipay",
  "payment": {
    "success": true,
    "form_token": "token-123",
    "public_key": "mc123:pk123",
    "order_id": "a3f1e2b0-...-uuid",
    "transaction_reference": "a3f1e2b0-...-uuid"
  }
}

Con el form_token, embebe el widget Krypton de Izipay en tu frontend (kr-payment-form.min.js, provisto por Izipay) — cuando el cliente completa el pago, reenvía kr-answer/kr-hash a la sección 5.

Culqi resuelve el cobro en el mismo request (sin paso de confirmación posterior) — el status de la respuesta ya viene paid o el request falla con 422 payment_initiation_failed si la tarjeta fue rechazada.

Errores posibles: 422 payments_disabled (servicio no habilitado), 422 payment_gateway_not_configured (no registraste credenciales de ese proveedor todavía, sección 3), 422 payment_initiation_failed, 422 validation_failed, 429 rate_limit_exceeded (20/min).

5. Confirmar un cobro (webhook)

POST /payments/webhooks/{gateway} — sin autenticación por API key (tu propio backend, o el servidor de la pasarela, llama esto directamente). Límite de 60 solicitudes por minuto por IP (no afecta el flujo normal de confirmar un cobro, ver sección 7). El reference que recibiste en la sección 4 va siempre en el body, además de los campos propios de cada pasarela:

`{gateway}`	Campos adicionales del body
`izipay`	`kr-answer`, `kr-hash` (los entrega el widget Krypton)
`paypal`	`paypal_order_id` (o `token`, el que llega en el redirect de PayPal)
`niubiz`	`transaction_token` (lo entrega el callback `culqi()`/`complete` del widget)

culqi y manual_transfer no usan este endpoint — Culqi ya resuelve en la sección 4, y la confirmación de una transferencia bancaria es manual entre tú y tu cliente (no automatizada en esta versión).

Ejemplo (Izipay) — 200:

{ "reference": "a3f1e2b0-...-uuid", "status": "paid" }

Es seguro exponer este endpoint sin autenticación: la confirmación real no depende de quién llama, sino de que la firma/credencial de la pasarela se valide correctamente contra tus credenciales reales (sección 3) — nadie puede marcar como pagado un cobro ajeno con solo adivinar un reference.

Errores posibles: 422 payment_verification_failed (firma inválida, reference inexistente, o no pertenece a ese {gateway}).

6. Consultar el estado de un cobro

GET /payments/charges/{reference}

{
  "reference": "a3f1e2b0-...-uuid",
  "provider": "izipay",
  "amount": 49.9,
  "currency": "PEN",
  "status": "paid",
  "paid_at": "2026-09-09T20:00:00+00:00",
  "created_at": "2026-09-09T19:58:00+00:00"
}

status: pending, paid, failed o expired.

Errores posibles: 404 (no existe, o es de otra cuenta).

7. Errores y límites

Mismo formato único que la API de facturación — {"error": {"code", "message", "details"?}} — ver sección 3 de la Referencia de la API. Límites de tasa propios de este servicio: 20 solicitudes por minuto por cuenta para POST /payments/charges (distinto del límite general de 60/min del resto de la API), y 60 solicitudes por minuto por IP para POST /payments/webhooks/{gateway}.