Flujos: compra, preautorización, reverso y devolución

Próximamente

Sin sandbox ni servidor público todavía. Los ejemplos usan el contrato v1 con datos ficticios; las cabeceras de firma se omiten por brevedad (ver Autenticación).

Todas las operaciones siguen el mismo patrón: tú envías JSON con una Idempotency-Key; el autorizador registra la solicitud en su libro antes de enviarla, la traduce a ISO 8583, espera la respuesta del emisor como máximo el plazo configurado (2.500 ms por defecto) y te responde con un resultado.

Compra (0200)

curl https://autorizador.example.com/v1/authorizations \
  --cert cliente.crt --key cliente.key \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: PED-2026-000123-v1' \
  -H "X-Finora-Fecha: $FECHA" -H "X-Finora-Nonce: $NONCE" -H "X-Finora-Firma: $FIRMA" \
  --data-binary '{
    "version": "2026-10",
    "operacion": "COMPRA",
    "monto": { "valor": "1250.00", "moneda": "928" },
    "medio": { "tipo": "CREDENCIAL_FPW1", "credencial": "FPW1.9919000000000012345.1792512000.3f9a1c0e7b2d4a68" },
    "comercio": { "codigo": "000000000012345", "mcc": "5411" },
    "entrada": { "modo": "BILLETERA" },
    "opciones": { "cuotas": 3, "aprobacionParcial": true, "referenciaTasa": true },
    "referenciaCliente": "PED-2026-000123"
  }'

Respuesta (200):

{
  "idAutorizacion": "01JBX3A7K2M4N6P8R0S2T4V6W8",
  "operacion": "COMPRA",
  "resultado": "APROBADA",
  "estado": "RESPONDIDA",
  "codigoRespuesta": "00",
  "mensaje": "Aprobada",
  "codigoAutorizacion": "A1B2C3",
  "rrn": "629300000123",
  "stan": "000457",
  "monto": { "solicitado": "1250.00", "aprobado": "1250.00", "moneda": "928", "devuelto": null },
  "referenciaTasa": { "moneda": "840", "tasa": "36.50000000", "monto": "34.25" },
  "reverso": null,
  "referenciaCliente": "PED-2026-000123",
  "iso": { "mtiRespuesta": "0210" },
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "latenciaMs": 41
}

Guarda idAutorizacion: lo necesitas para reversar, capturar, devolver o consultar.

Preautorización (0100) y captura (0220)

La preautorización retiene el importe; la captura lo convierte en cargo. Solo se admite una captura por preautorización, por un importe menor o igual a monto.aprobado y en la misma moneda.

curl https://autorizador.example.com/v1/authorizations/01JBX3A7K2M4N6P8R0S2T4V6W8/captures \
  --cert cliente.crt --key cliente.key \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: MESA-12-2026-10-20-C1' \
  -H "X-Finora-Fecha: $FECHA" -H "X-Finora-Nonce: $NONCE" -H "X-Finora-Firma: $FIRMA" \
  --data-binary '{"version":"2026-10","monto":{"valor":"280.00","moneda":"928"},"referenciaCliente":"MESA-12-2026-10-20-C"}'

La captura no lleva el medio de pago: el emisor localiza la retención por el RRN y el código de autorización de la 0100. Una segunda captura responde 409 ORIGINAL_NO_ADMITE_OPERACION; un importe mayor que el aprobado, 422 MONTO_EXCEDE_ORIGINAL. La consulta de la preautorización muestra monto.capturado.

Reverso (0400)

Pide un reverso para deshacer una operación aprobada (compra, preautorización, captura o devolución). El reverso repite el RRN y el terminal (TID) de la original, lleva su propio STAN y referencia la original en el DE 90 (MTI + STAN + DE 7 de la original).

curl https://autorizador.example.com/v1/authorizations/01JBX3A7K2M4N6P8R0S2T4V6W8/reversals \
  --cert cliente.crt --key cliente.key \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: PED-2026-000123-R1' \
  -H "X-Finora-Fecha: $FECHA" -H "X-Finora-Nonce: $NONCE" -H "X-Finora-Firma: $FIRMA" \
  --data-binary '{"version":"2026-10","motivo":"CANCELACION_CLIENTE","referenciaCliente":"PED-2026-000123-R"}'

Respuesta (200):

{
  "idAutorizacion": "01JBX3F2G4H6J8K0M2N4P6R8S0",
  "operacion": "REVERSO",
  "resultado": "APROBADA",
  "estado": "REVERSO_RESPONDIDO",
  "codigoRespuesta": "00",
  "mensaje": "Reverso respondido; pendiente de confirmar contra el libro",
  "codigoAutorizacion": null,
  "rrn": "629300000123",
  "stan": "000458",
  "monto": { "solicitado": "1250.00", "aprobado": "1250.00", "moneda": "928" },
  "referenciaTasa": null,
  "reverso": null,
  "referenciaCliente": "PED-2026-000123-R",
  "iso": { "mtiRespuesta": "0410" },
  "traceId": "0af7651916cd43dd8448eb211c80319c",
  "latenciaMs": 38
}

Reglas del reverso en v1:

Total, nunca parcial. El DE 4 lleva el monto.aprobado de la original (en una aprobación parcial, lo aprobado, no lo solicitado) y no se envía DE 95.
motivo es opcional: CANCELACION_CLIENTE, ERROR_ENTREGA o TIEMPO_AGOTADO_CLIENTE.
Un 00 del emisor deja el reverso en REVERSO_RESPONDIDO (provisional). El autorizador lo confirma contra el libro del emisor y entonces pasa a REVERSADA; consúltalo con GET.
Cuando el autorizador no recibe respuesta a tiempo, él mismo envía el reverso: no necesitas pedirlo (ver Idempotencia, plazos y reversos).

Como la compra y sus devoluciones comparten RRN y terminal (igual que la preautorización y su captura), el autorizador impide los reversos que podrían caer sobre otra operación. En esos casos responde 409 ORIGINAL_NO_ADMITE_OPERACION con el motivo en detail:

Situación	Qué hacer
La compra ya tiene devoluciones	Devuelve el saldo restante con otra devolución
La preautorización tiene una captura vigente	Reversa la captura
Quieres reversar una devolución que no es la última de su compra	Reversa primero la última
La operación ya tiene un reverso, o no fue aprobada	Nada: no hay cargo que deshacer

Devolución (0200, DE 3 `200000`)

Devuelve total o parcialmente una compra aprobada. Puedes hacer varias devoluciones; la suma de las aprobadas y en curso más la nueva no puede superar monto.aprobado de la compra.

curl https://autorizador.example.com/v1/authorizations/01JBX3A7K2M4N6P8R0S2T4V6W8/refunds \
  --cert cliente.crt --key cliente.key \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: DEV-2026-000045-v1' \
  -H "X-Finora-Fecha: $FECHA" -H "X-Finora-Nonce: $NONCE" -H "X-Finora-Firma: $FIRMA" \
  --data-binary '{"version":"2026-10","monto":{"valor":"250.00","moneda":"928"},"referenciaCliente":"DEV-2026-000045"}'

Si el importe excede lo disponible, la respuesta es 422 y nada sale hacia el emisor:

{
  "type": "urn:finora:auth-gateway:monto-excede-original",
  "title": "El importe excede lo aprobado en la original",
  "status": 422,
  "codigo": "MONTO_EXCEDE_ORIGINAL",
  "detail": "Aprobado 1250.00; ya usado o en curso 1100.00; disponible 150.00.",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Próximamente: devoluciones

El emisor valida la tarjeta en cada devolución, así que la devolución necesita volver a resolver el medio de la compra. Eso solo es posible con el medio TOKEN, que llega con el servicio de tokenización. Una compra hecha con CREDENCIAL_FPW1 (de un solo uso) no admite devolución por esta API en v1: responde 409 ORIGINAL_NO_ADMITE_OPERACION. Mientras tanto, deshaz una compra con FPW1 mediante un reverso.

Mientras una devolución de la misma compra siga sin resolver, una devolución nueva responde 409; reintenta cuando la anterior termine.

Consulta de saldo (0200, DE 3 `310000`)

--data-binary '{"version":"2026-10","operacion":"CONSULTA_SALDO","medio":{"tipo":"CREDENCIAL_FPW1","credencial":"FPW1.9919000000000012345.1792512000.3f9a1c0e7b2d4a68"},"comercio":{"codigo":"000000000012345","mcc":"5411"},"entrada":{"modo":"BILLETERA"}}'

Va sin monto (o con "valor": "0.00"). En v1 la respuesta trae el resultado, pero no el saldo.

Consultar una autorización

curl "https://autorizador.example.com/v1/authorizations/01JBX3A7K2M4N6P8R0S2T4V6W8" \
  --cert cliente.crt --key cliente.key \
  -H "X-Finora-Fecha: $FECHA" -H "X-Finora-Nonce: $NONCE" -H "X-Finora-Firma: $FIRMA"

Si perdiste el idAutorizacion (por ejemplo, tu sistema se cayó antes de leer la respuesta), busca por tu clave: GET /v1/authorizations?idempotencyKey=PED-2026-000123-v1. Recuerda firmar la ruta con su consulta.

Compra (0200)​

Preautorización (0100) y captura (0220)​

Reverso (0400)​

Devolución (0200, DE 3 200000)​

Consulta de saldo (0200, DE 3 310000)​

Consultar una autorización​