Saltar al contenido principal
Migo Docs

Preautorización y captura

Un cobro normal mueve el dinero de una vez. El flujo de dos pasos lo parte: primero reservas fondos en la tarjeta, y después decidís si cobrás lo reservado —todo o menos— o si liberás la reserva.

Sirve cuando el monto final no se conoce al momento de la compra: un consumo que se ajusta, un depósito en garantía, un pedido que puede salir incompleto, o una validación que necesitás hacer antes de cobrar.

Cómo se habilita​

No cambia tu integración. Seguís llamando al mismo endpoint de pago que ya usás; lo que cambia es que, en vez de cobrar, reserva.

Se habilita por configuración de tu cuenta de comercio y lo activa Migo. No es un campo que mandes en el request. Coordinalo con tu canal de operaciones indicando qué procesador y qué comercio querés habilitar.

Activarlo no afecta a nadie más

La configuración es por comercio y por procesador. Habilitarla en una cuenta no altera el comportamiento de ninguna otra, y una cuenta sin la configuración sigue cobrando de inmediato como hasta ahora.

El flujo​

1 · Pago
→
AUTHORIZED
fondos reservados, aún no cobrados
└─
2a · Capturar
→
APPROVED
cobrado (total o menos)
└─
2b · Cancelar
→
CANCELLED
reserva liberada

2a y 2b son excluyentes. Una reserva termina capturada o cancelada, nunca las dos: una vez que capturaste, cancelar responde 4014.

Por defecto la reserva admite una sola captura. Si tu cuenta tiene habilitada la captura múltiple, podés cobrarla en partes —varias capturas sucesivas— hasta completar el monto reservado. Se habilita igual que el flujo de dos pasos: por configuración de tu cuenta, no por un campo del request.

Su disponibilidad depende del procesador de tu cuenta, así que consultanos antes de construir sobre ella. Si tu cuenta no la tiene habilitada, una segunda captura sobre la misma reserva responde 4011.

La transacción permanece en AUTHORIZED hasta que mandes una solicitud válida o hasta que venza su ventana de captura. Ningún proceso automático la cobra.

La ventana de captura​

Una reserva tiene una ventana de captura que empieza cuando se crea la transacción. Por defecto es de 24 horas y se puede ajustar por cuenta al habilitar el flujo.

Cuando la ventana vence sin que hayas capturado, Migo libera la reserva por vos: le pide al procesador que suelte los fondos y, si lo confirma, la transacción pasa a CANCELLED y recibís el mismo aviso de cancelled que cuando cancelás vos. La liberación corre en pasadas periódicas, así que puede ocurrir algunas horas después del vencimiento: no cuentes con poder capturar pasada la ventana.

Si el procesador no confirma la liberación, la transacción queda en AUTHORIZED pero ya no se puede capturar ni cancelar, y los fondos quedan retenidos al tarjetahabiente hasta que el emisor los suelte por su cuenta. Por eso conviene que captures o canceles siempre dentro de la ventana, sin esperar a la liberación automática.

Endpoints​

MétodoRutaQué hace
POST/pay/capture/{trxUid}Cobra la reserva, total o por un monto menor
POST/pay/cancel/{trxUid}Libera la reserva

Se autentican con tu merchant token en el header Authorization, igual que el resto de la API.

AmbienteHost
Sandboxhttps://sb-mw.migopayments.com
Producciónhttps://mw.migopayments.com

El detalle completo de esquemas está en la referencia interactiva.

Capturar​

El monto va en el campo totalCapture del cuerpo, y es obligatorio.

curl -X POST https://sb-mw.migopayments.com/pay/capture/<trx-uid> \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>' \
-d '{ "totalCapture": 60.00 }'
Respuesta
{
"transaction": {
"uid": "<trx-uid>",
"status": "approved",
"total": 100.00,
"totalCapture": 60.00
}
}

Reglas del monto:

  • Debe ser mayor que cero.
  • Debe ser menor o igual al saldo sin capturar: el monto reservado menos lo que ya capturaste.
  • Fuera de ese rango se rechaza con el código 2003, y la solicitud no llega al procesador.
  • Si omitís el campo, la respuesta es el código 5000.

Lo efectivamente cobrado queda en totalCapture de la transacción —acumulado, si capturaste en partes— y es lo que reflejan el comprobante y la información transaccional. Con una sola captura, si cobraste 60 de una reserva de 100 el cobro es de 60 y el resto no queda pendiente.

Una captura que no recibió respuesta no debe repetirse sin verificar antes el estado de la transacción. Si quedó en approved con el totalCapture esperado, el cobro se realizó aunque la respuesta no haya llegado.

Serializá las capturas de una misma reserva: dos solicitudes simultáneas pueden llegar las dos al procesador.

Capturar en partes​

Con captura múltiple habilitada cada llamada cobra un incremento y la transacción va acumulando:

curl -X POST https://sb-mw.migopayments.com/pay/capture/<trx-uid> \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>' \
-d '{ "totalCapture": 30 }'

Sobre una reserva de 100, tres llamadas de 30, 30 y 40 dejan la transacción en totalCapture 100. Cualquier llamada que exceda el saldo sin capturar se rechaza con 2003 y no llega al procesador.

La transacción pasa a approved ya en la primera captura, y ahí deja de poder cancelarse: el saldo que no captures simplemente no se cobra.

Cancelar​

curl -X POST https://sb-mw.migopayments.com/pay/cancel/<trx-uid> \
-H 'Authorization: <merchant-token>'

Libera la reserva y la transacción queda en CANCELLED. Una transacción ya capturada no se cancela por esta vía: responde 4014.

Para deshacer un cobro que ya ocurrió usá el flujo de anulaciones y reembolsos, que es un camino distinto y no el de cancelación. Dos cosas que conviene saber antes de prometerle algo al tarjetahabiente: deshacer el cobro de una reserva no es lo mismo que liberar una reserva sin cobrar, y según el riel puede haber un límite de tiempo —a veces el mismo día— para deshacerlo. Confirmá con nosotros qué aplica a tu procesador.

Estados​

EstadoSignificaQué podés hacer
AUTHORIZEDFondos reservados, aún no cobradosCapturar o cancelar
APPROVEDCobrado, total o parcialmenteAnular o reembolsar; capturar otra vez si tenés captura múltiple y queda saldo
CANCELLEDReserva liberada, por tu cancelación o porque venció la ventana de capturaNada: la transacción está cerrada
DENIEDEl procesador rechazó la reservaIniciar un pago nuevo
Un rechazo no cambia el estado

Si el procesador rechaza tu captura o tu cancelación, la transacción sigue en AUTHORIZED. Podés reintentar o cancelar. El estado interno sólo avanza con una aprobación explícita del procesador, así que nunca vas a ver una transacción marcada como cobrada sin que el cobro haya ocurrido.

Qué combinaciones soporta​

CapacidadSoportada
PreautorizaciónSí
Captura por el monto totalSí
Captura por un monto menorSí
Captura en partes (varias capturas)Sí, con captura múltiple habilitada
Preautorización + 3D SecureDepende del procesador
Preautorización + tarjeta tokenizadaDepende del procesador
Preautorización + cuotasDepende del procesador

Las tres últimas no dependen de Migo sino del procesador de tu cuenta: algunos las admiten y otros no. Se resuelven al configurar la cuenta, no en tiempo de ejecución, así que si necesitás alguna coordinala antes de habilitar el flujo.

Lo que aplica con Serfinsa​

Con ese procesador, las tres combinaciones no están disponibles, y el motivo es del protocolo del riel:

CombinaciónPor qué
Preautorización + 3D SecureLa autenticación corre sobre una API distinta, que cobra de inmediato y no expone reserva
Preautorización + tarjeta tokenizadaLa reserva exige el número de tarjeta completo, que una tarjeta guardada no provee
Preautorización + cuotasEl mensaje de reserva no tiene campo para el plazo

En los tres casos la solicitud se rechaza sin llegar al procesador, para que nunca termine en un cobro que no pediste.

Con Serfinsa, una reserva ya capturada se puede deshacer con la anulación: la transacción pasa a reversed. Una reserva que todavía no capturaste no se anula: se libera con /pay/cancel.

Errores​

CódigoSignifica
2000La transacción no existe
2003Monto inválido: cero, negativo, no numérico o mayor al saldo sin capturar
4011La transacción no está en un estado que permita capturar
4013El procesador de esa transacción no admite captura, o no confirmó la captura solicitada
4014La transacción no está en un estado que permita cancelar — típicamente porque ya se capturó
4015El procesador de esa transacción no admite cancelación
5000Faltan parámetros: típicamente el monto de la captura
5001 / 5004No se pudo resolver la configuración de tu cuenta o del procesador

El resultado de una captura viaja en el cuerpo de la respuesta. Para confirmar el cobro, leé status de la transacción: sólo approved significa cobrado. Una captura que el procesador no confirma responde con el código 4013 y sin transacción en el cuerpo.

El aviso de la reserva​

El aviso de authorized no se envía por defecto: se habilita en la configuración de tu cuenta. Si no declarás una lista de estados en tu callback, recibís todos los que lo disparen. Si la declarás, cada estado debe coincidir exactamente con el nombre del estado real; uno que no coincida no se envía.

Después de habilitar el aviso de la reserva, verificá con una transacción de prueba que llega a tu backend.

Relacionados​