Preautorización & Captura
Preautorización
La preautorización, también conocida como "autorización previa" o "bloqueo de fondos", es una etapa crucial en el procesamiento de transacciones. Durante esta fase, se verifica la disponibilidad de fondos en la cuenta del titular de la tarjeta antes de completar la transacción. Su objetivo principal es reservar una cierta cantidad de fondos en la cuenta del titular para asegurarse de que haya suficiente saldo disponible para cubrir la transacción futura.
La preautorización se utiliza ampliamente en situaciones en las que es necesario garantizar la disponibilidad de fondos antes de entregar un producto o servicio. Por ejemplo, en el comercio electrónico, se puede utilizar para asegurarse de que el saldo de la tarjeta sea suficiente antes de realizar un envío o realizar una reserva.
Implementación de la Preautorización
Requisitos previos
Antes de comenzar con la implementación de la preautorización, asegúrate de contar con los siguientes requisitos:
Paso 1. Genera un token de aceptación.
Paso 2. Tokeniza el medio de pago (Tarjeta).
Paso 3. Antes de crear la preautorización, tener en cuenta lo siguiente:
-
Podemos crear una fuente de pago para que los datos del tarjetahabiente queden listos para preautorizaciones o pagos futuros. Ver proceso.
-
Omitir la creación de la fuente de pago e ir directamente a crear la preautorización. Ver proceso.
Paso 4. Recuerda que para crear la preautorizacion se requiere el uso de tu llave privada el cual debes enviar como Bearer token:
- Si quieres crear una preautorización con una fuente de pago, debes generar nuevamente un token de aceptación y hacer una petición
POST /payment_sourcescon el siguiente cuerpo JSON:
{
"type": "CARD",
"payment_source_id": 297, // ID de la fuente de pago
"customer_email": "prueba@test.com", // Email del tarjetahabiente
"financial_operation": "PREAUTHORIZATION",
"acceptance_token": "acceptance_token", // Token de aceptación
"data": {
"amount_in_cents": 100, // Monto de la preautorización
"currency": "USD"
}
}
- Si por el contrario quieres crear una preautorización directamente deberás hacer una petición
POST /payment_sourcescon el siguiente cuerpo JSON:
{
"type": "CARD",
"customer_email": "prueba@test.com", // Email del tarjetahabiente
"financial_operation": "PREAUTHORIZATION",
"token": "token_card", // ID de la tarjeta que tokenizaste
"acceptance_token": "acceptance_token", // Token de aceptacion
"data": {
"amount_in_cents": 100, // Monto de la preautorización
"currency": "USD"
}
}
Obtendremos de vuelta el siguiente JSON:
{
"data": {
"id": 335,
"public_data": {
"type": "CARD",
"financial_operation": "PREAUTHORIZATION",
"amount_in_cents": 100,
"number_of_installments": 1,
"currency": "USD"
},
"token": "tok_devtest_196_8A7308f20c2d236f42252972390b4eb1",
"type": "CARD",
"status": "PROCESSING",
"customer_email": "prueba@test.com"
}
}
Paso 5. Realizar consultas periódicas para verificar el estado de la preautorización y asegurarnos de su correcta ejecución:
Para consultar la preautorización debemos hacer una petición GET /payment_sources/:id sin olvidarnos de enviar la llave privada como Bearer token. Tendremos de vuelta el siguiente JSON:
{
"data": {
"id": 335,
"public_data": {
"type": "CARD",
"financial_operation": "PREAUTHORIZATION",
"amount_in_cents": 100,
"number_of_installments": 1,
"currency": "USD"
},
"token": "tok_devtest_196_8A7308f20c2d236f42252972390b4eb1",
"type": "CARD",
"status": "PENDING",
"customer_email": "jmtm141097@gmail.com",
"extra": {
"three_ds_auth": {
"current_step": "BROWSER_INFO", // Hace referencia al tipo de autenticación: (BROWSER_INFO - CHALLENGE)
"current_step_status": "PENDING",
"three_ds_method_data": "<iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" style="visibility: hidden; width: 1px; height: 1px;" xmlns="http://www.w3.org/1999/xhtml"><!--.--></iframe><form id="tdsMmethodForm" name="tdsMmethodForm" action="https://api-sandbox.pa.dev.wompi.dev/v1/webhook_events/acs_response?order_id=PAYMENT_SOURCE-335" method="post" target="tdsMmethodTgtFrame" xmlns="http://www.w3.org/1999/xhtml"><input type="hidden" name="operation" value="CHALLENGE_IFRAME_BIN" /><script type="text/javascript">document.getElementById("tdsMmethodForm").submit();</script></form>"
}
}
}
}
Paso 6. Renderizar el IFRAME para continuar con el proceso de autenticación:
Observaremos que en la preautorizacion, la clave extra contiene información adicional relevante. Específicamente, nos centraremos en la clave three_ds_method_data, que incluye un fragmento de código HTML. Este es un bloque IFRAME que debe ser integrado y mostrado en la página para llevar a cabo de manera segura el proceso de autenticación de la tarjeta. Además, también encontraremos la clave current_step, que indica el estado actual de la autenticación y puede hacer referencia al tipo espec ífico de autenticación necesario para verificar la identidad del titular de la tarjeta.
Paso 7. No te olvides de realizar consultas periódicas de la preautorización
Así luce una preautorización exitosa y lista para ser capturada:
{
"data": {
"id": 335,
"public_data": {
"type": "CARD",
"financial_operation": "PREAUTHORIZATION",
"amount_in_cents": 100,
"number_of_installments": 1,
"currency": "USD"
},
"token": "tok_devtest_196_8A7308f20c2d236f42252972390b4eb1",
"type": "CARD",
"status": "AVAILABLE",
"customer_email": "jmtm141097@gmail.com",
"extra": {
"three_ds_auth": {
"current_step": "AUTHENTICATION",
"current_step_status": "COMPLETED"
}
}
}
}
Captura
Es la etapa en la que se realiza el cobro o la transferencia final de los fondos reservados durante la preautorización. Una vez que se completa la transacción o se cumple la condición acordada, se envía una solicitud de captura para obtener los fondos reservados durante la preautorización. Esto resulta en la transferencia de los fondos desde la cuenta del titular de la tarjeta al comerciante o proveedor de servicios. La captura es fundamental para finalizar la transacción y asegurar que el comerciante reciba el pago correspondiente.
Implementación de la Captura
Requisitos previos
Antes de realizar una captura, asegúrate de contar con los siguientes requisitos:
-
Contar con una preautorización en estado
AVAILABLE.
Paso 1. Crea una transacción.
Para avanzar con el proceso de captura, debemos enviar una solicitud POST /transactions. En los headers, debemos incluir la llave privada de nuestro comercio como un Bearer token. Además, debemos enviar el siguiente JSON como cuerpo de la solicitud:
{
"amount_in_cents": 100, // Monto de la captura (no debe superar el monto preautorizado)
"public_key": "pub_prod_ffhas23932", // Llave publica del comercio
"currency": "USD",
"customer_email": "prueba@test.com",
"reference": "TEST34502", // Referencia unica de la transacción
"payment_source_id": 298 // ID de la fuente de pago (preautorización)
}
Paso 2. Realizar consultas periódicas de la transacción para verificar el estado y asegurarnos de su correcta ejecución.
Así luce una captura que se ha realizado exitosamente:
{
"data": {
"id": "1196-1689602000-65841",
"created_at": "2023-07-17T13:53:24.308Z",
"amount_in_cents": 100,
"reference": "TEST34502",
"currency": "USD",
"payment_method_type": "CARD",
"payment_method": {
"type": "CARD",
"extra": {
"name": "VISA-0031",
"type": "CAPTURE", // Indica que la transacción es de tipo captura
"brand": "VISA",
"last_four": "0031",
"is_three_ds": false,
"three_ds_auth": null,
"external_identifier": "QtcGZjh9nX",
"processor_response_code": "00"
}
},
"redirect_url": null,
"status": "APPROVED", // Estado final de la transacción
"status_message": null,
"merchant": {
"name": "Pruebas SandBox",
"legal_name": "Pruebas SandBox",
"contact_name": "Pepito Perez",
"phone_number": "+50732345634",
"logo_url": null,
"legal_id_type": "RUC",
"email": "prueba@test.com",
"legal_id": "2452345-5"
},
"taxes": []
}
}
