Callbacks

Checkout envía un HTTP POST a tu notification_URL como resultado de cada operación.

Alta del webhook

Para empezar a recibir estas notificaciones hay que comunicarse con el equipo de tech y mandarles la URL del webhook (notification_URL) donde quieran recibir los callbacks.

Eventos que disparan callback

Checkout puede disparar más de un callback para el mismo pago, a medida que avanza por distintos estados:

1. type=redirect, status=success — se dispara cuando el pago llega a la instancia de redirección (ej. cuando se genera el link/cupón de transferencia). Puede llegar duplicado (puede llegar más de una vez con el mismo type/status).
2. type=sale, status=waiting — el cobro está en proceso (esperando que se acredite la transferencia).
3. type=sale, status=success — cuando el pago se acredita y queda settled.

Callbacks duplicados

Checkout puede reenviar el mismo callback (mismo id, type y status) más de una vez. Tu endpoint debería ser idempotente — usá el campo id para detectar si ya procesaste ese evento antes de aplicar cambios en tu sistema.

información

El set de eventos exacto (redirect, sale, u otros) depende del método de pago. Métodos con redirección (transferencia bancaria, efectivo, wallets) van a mandar el callback de redirect antes del de sale; métodos directos (tarjeta) pueden mandar directamente sale.

Estados de transacción

Transaction Status	Descripción
success	Completada exitosamente
fail	Con errores, no validada
waiting	En procesamiento
undefined	Estado incierto por problema con el proveedor

aviso

success no implica necesariamente que el pago tenga estado final exitoso — revisá también order_status (ver tabla de payload abajo).

Payload del callback

Parámetro	Tipo	Descripción
id	string	ID público del pago
order_number	string	Tu order ID
order_amount	float	Monto (XX.XX)
order_currency	string	Código de moneda
order_description	string	Descripción del producto
order_status	string	prepare, settled, pending, redirect, decline, refund, reversal, etc.
type	string	redirect, sale, u otra etapa del pago
status	string	success, fail, waiting, undefined
reason	string	Motivo de rechazo/error (solo si fail)
card	string	Máscara de tarjeta XXXXXX******XXXX
card_expiration_date	string	mm/yyyy
card_token	string	Solo si req_token estuvo habilitado
customer_name, customer_email, customer_country, customer_state, customer_city, customer_address, customer_ip	—	Datos del cliente (customer_ip es requerido)
crypto_network, crypto_address	—	Solo pagos cripto
digital_wallet, pan_type	—	Solo si se usó Google Pay / Apple Pay
exchange_rate, exchange_rate_base, exchange_currency, exchange_amount	—	Solo si hubo conversión de moneda
recurring_init_trans_id, recurring_token, schedule_id	—	Solo si se usó recurring_init
vat_amount	float	Solo si se calculó IVA (vat_calc)
custom_data	object	Eco de lo que enviaste en el request
extended_data*	string	Solo si está configurado "Add Extended Data to Callback"
connector_name, rrn, arn, approval_code, brand, gateway_id, extra_gateway_id, merchant_name, mid_name, issuer_country, issuer_bank*	—	Datos extendidos del conector/adquirente
hash	string	Firma — ver Signature

* Solo se incluyen si está configurado en Configuration → Protocol Mappings.

Reglas de entrega

• Tu endpoint debe responder con HTTP 2xx para confirmar recepción.
• Si no respondés 2xx, el callback no se reintenta automáticamente.

Bloqueo por timeouts

Si se acumulan 5 timeouts en 5 minutos para tu notification_URL, se bloquea por 15 minutos (afecta a todos los merchants que comparten esa URL). El bloqueo se levanta automáticamente, o manualmente desde Configuration → Merchants → Edit Merchant. El contador de timeouts se resetea si hay una respuesta exitosa.

Cascading

Si se dispara cascading para el pedido, en general vas a recibir solo el callback del último intento (donde se determina el estado final: settled o declined). En casos particulares, podés recibir el callback del primer intento si hace falta redirigir al cliente. Los intentos intermedios no generan callback.

Formato real del callback

Formato del callback

El callback llega como application/x-www-form-urlencoded (pares key=value separados por &), no como JSON. Los valores de status y type llegan en minúscula (status=success, type=sale). Los espacios llegan como + y los caracteres especiales (como @, :) van codificados (ej. %40, %3A).

Ejemplo de callback real

Así se ve un callback real (crudo, application/x-www-form-urlencoded) para un método de transferencia bancaria (ARS):

id=****************************&order_number=1&order_amount=150000.00&order_currency=ARS&order_description=Purchase&order_status=redirect&type=sale&status=waiting&date=2026-07-15+15%3A01%3A52&hash=****************************************&customer_name=John+Doe&customer_email=john.doe%40example.com&customer_country=AR&customer_state=Cordoba&customer_city=Cordoba&customer_address=Av+Arequipa+1234&customer_ip=***************