Pagos

La API integra dos pasarelas de pago: Transbank (WebpayPlus, para Chile) y MercadoPago (para Latinoamérica). Ambas siguen el mismo patrón: crear la orden + iniciar el pago en un solo paso, luego confirmar mediante un callback.

Consultar métodos disponibles

GET /api/v1/payments/methods

Retorna las pasarelas de pago activas para la tienda autenticada.

Respuesta 200 OK

{
  "methods": [
    { "provider": "transbank", "name": "Webpay Plus" },
    { "provider": "mercadopago", "name": "MercadoPago" }
  ],
  "defaultProvider": "transbank"
}

Transbank — WebpayPlus

Iniciar pago con Transbank

POST /api/v1/payments/transbank

Crea la orden y genera una transacción Webpay. El cuerpo de la petición es idéntico al de POST /orders.

Respuesta 201 Created

{
  "message": "Transacción creada. Completa el pago en la URL de Transbank.",
  "token": "01ab7f3c...",
  "url": "https://webpay3g.transbank.cl/webpayserver/initTransaction",
  "buyOrder": "BUI-1042",
  "orderId": "uuid",
  "amount": 19980
}

Flujo recomendado en el frontend:

1. Hacer POST /payments/transbank con los datos de la orden.
2. Redirigir al usuario a url incluyendo el token como parámetro.
3. Transbank redirigirá al usuario a tu returnUrl configurada.
4. El sistema confirma el pago automáticamente (ver callback).

Confirmar pago Transbank

GET /api/v1/payments/transbank/confirm

Ruta pública — no requiere x-api-token. Es el callback al que Transbank redirige al usuario después del pago.

Parámetros de consulta (enviados por Transbank)

Respuesta 200 OK

{
  "paid": true,
  "orderId": "uuid",
  "transactionId": "01ab7f3c...",
  "result": { /* datos completos de la transacción Transbank */ }
}

Si el pago fue rechazado o cancelado:

{
  "paid": false,
  "result": { /* datos de la transacción */ }
}

MercadoPago

Iniciar pago con MercadoPago

POST /api/v1/payments/mercadopago

Crea la orden y genera una preferencia de pago en MercadoPago. El cuerpo es idéntico al de POST /orders.

Respuesta 201 Created

{
  "message": "Preferencia creada. Redirige al usuario a la URL de MercadoPago.",
  "preferenceId": "1234567890-abc",
  "initPoint": "https://www.mercadopago.cl/checkout/v1/redirect?pref_id=...",
  "sandboxUrl": "https://sandbox.mercadopago.cl/checkout/v1/redirect?pref_id=...",
  "orderId": "uuid",
  "amount": 19980
}

Flujo recomendado en el frontend:

1. Hacer POST /payments/mercadopago con los datos de la orden.
2. En producción, redirigir al usuario a initPoint; en desarrollo, usar sandboxUrl.
3. MercadoPago redirigirá al usuario a tu URL de retorno configurada.

Confirmar pago MercadoPago

GET /api/v1/payments/mercadopago/confirm

Ruta pública — no requiere x-api-token. MercadoPago redirige aquí después del pago.

Parámetros de consulta (enviados por MercadoPago)

Respuesta 200 OK

{
  "paid": true,
  "orderId": "uuid",
  "transactionId": "MP-987654321"
}

Webhook MercadoPago

POST /api/v1/payments/mercadopago/confirm/webhook

Ruta pública — recibe notificaciones asíncronas de MercadoPago (IPN).

MercadoPago envía notificaciones payment a este endpoint cuando cambia el estado de un pago. La API valida el tipo de notificación y marca la orden como pagada si corresponde.

Respuesta 200 OK

{ "received": true }

Credenciales de pasarela

Las credenciales (API keys, secrets) de cada pasarela se almacenan encriptadas con AES-256-GCM en la base de datos y son desencriptadas en tiempo de ejecución por el servicio GatewayCryptoService. Nunca se exponen en las respuestas de la API.