Pagos

Crear pago

POST /api/v1/payments

{
  "order_id": "uuid",
  "gateway": "stripe",
  "amount": 9800,
  "currency": "PEN",
  "payment_method_id": "pm_stripe_xxxx"
}

Pasarelas disponibles

Gateway	Provider ID	Monedas	Campos requeridos
Stripe	stripe	USD, PEN, EUR, +135	payment_method_id (token de Stripe Elements)
Culqi	culqi	PEN, USD	token_id (token de Culqi JS), email
MercadoPago	mercadopago	PEN, ARS, BRL, +18	token (token de MP.js), installments, payment_method_id
Niubiz	niubiz	PEN	session_key, transaction_token (flujo 3 pasos)
Izipay	izipay	PEN	kr_answer (token de Izipay), transaction_id
PayMe	payme	PEN	charge_id (token de PayMe Flex v2)
PayPal	paypal	USD, EUR, +20	order_id (PayPal Order ID desde SDK)

Campos por gateway

Stripe

{
  "order_id": "uuid",
  "gateway": "stripe",
  "amount": 9800,
  "currency": "PEN",
  "payment_method_id": "pm_1N5kQ2abc123"
}

Culqi

{
  "order_id": "uuid",
  "gateway": "culqi",
  "amount": 9800,
  "currency": "PEN",
  "token_id": "tkn_live_abc123",
  "email": "[email protected]"
}

MercadoPago

{
  "order_id": "uuid",
  "gateway": "mercadopago",
  "amount": 9800,
  "currency": "PEN",
  "token": "abc123-token-mp",
  "payment_method_id": "visa",
  "installments": 3
}

Niubiz

{
  "order_id": "uuid",
  "gateway": "niubiz",
  "amount": 9800,
  "currency": "PEN",
  "session_key": "session_abc123",
  "transaction_token": "token_abc123"
}

Izipay

{
  "order_id": "uuid",
  "gateway": "izipay",
  "amount": 9800,
  "currency": "PEN",
  "kr_answer": "kr_answer_token_abc123",
  "transaction_id": "tx_123"
}

PayMe

{
  "order_id": "uuid",
  "gateway": "payme",
  "amount": 9800,
  "currency": "PEN",
  "charge_id": "ch_abc123"
}

PayPal

{
  "order_id": "uuid",
  "gateway": "paypal",
  "amount": 9800,
  "currency": "USD",
  "paypal_order_id": "PAYID-abc123"
}

Estados

Estado	Descripción
pending	Iniciado, esperando confirmación del gateway
processing	En proceso en la pasarela
paid	Capturado exitosamente
failed	Fallido
partially_refunded	Reembolso parcial aplicado
refunded	Reembolsado totalmente

Transiciones de estado

pending ──→ processing ──→ paid ──→ refunded
    │           │            │
    │           └──→ failed  └──→ partially_refunded ──→ refunded
    └──→ failed

Webhooks de pasarelas

OmniBuy recibe notificaciones automáticas de las pasarelas para confirmar pagos sin polling. Cada webhook verifica la firma antes de procesar.

Pasarela	Endpoint	Método de verificación
Stripe	POST /webhooks/stripe	Firma HMAC-SHA256 (Stripe signature)
Culqi	POST /webhooks/culqi	Firma HMAC-SHA256
MercadoPago	POST /webhooks/mp	Firma HMAC (x-signature header)
Niubiz	POST /webhooks/niubiz	Redirect callback (flujo 3 pasos)
Izipay	POST /webhooks/izipay	Firma HMAC-SHA256
PayMe	POST /webhooks/payme	Firma RSA-SHA512
PayPal	N/A (IPN / Polling)	Verificación IPN HMAC-SHA1 o polling vía GET /api/v1/payments/:id

Los endpoints de webhook no requieren autenticación de tenant. La seguridad se basa en la verificación de firma de cada pasarela.

Eventos que procesan los webhooks

• Pago confirmado: transiciona el pago a paid y confirma la orden asociada
• Pago fallido: transiciona el pago a failed

Endpoints

Obtener pago

GET /api/v1/payments/:id

Reembolsar pago

POST /api/v1/payments/:id/refund

{
  "amount": 9800,
  "reason": "requested_by_customer"
}

Campo	Tipo	Requerido	Descripción
amount	int64	Sí	Monto a reembolsar en centavos. 0 = reembolso total
reason	string	No	duplicate, fraudulent, requested_by_customer, other

Reglas de negocio:

• Solo se puede reembolsar un pago en estado paid o partially_refunded
• El monto total de reembolsos no puede exceder el monto original del pago
• Un reembolso parcial cambia el estado a partially_refunded
• Un reembolso total (monto = restante) cambia el estado a refunded
• El reembolso se procesa en la misma pasarela que el pago original

Respuestas:

• 201: Reembolso creado exitosamente
• 409: El pago no se puede reembolsar (estado inválido o monto excede el límite)

Estados del reembolso

Estado	Descripción
pending	Reembolso creado, pendiente de procesamiento
processing	En proceso en la pasarela
refunded	Reembolso completado
failed	Reembolso fallido