Crear un pago con preautorización

Este documento aplica a los siguientes países:

Brasil	Chile	México	España	Uruguay

En el Web Checkout de Getnet, la preautorización permite al Merchant reservar temporalmente un importe en la tarjeta de crédito del cliente durante el proceso de pago. La transacción permanece pendiente hasta que el Merchant confirma (captura) el pago, momento en el que el importe se cobra efectivamente. Este mecanismo es útil en escenarios donde el importe final de la compra puede variar o necesita confirmarse posteriormente.

Para comprender las reglas de cada país, consulta el documento Pre-authorization and Availability.

Cómo funciona

Usa la preautorización cuando quieras reservar un importe en la tarjeta de crédito del cliente durante el proceso de pago y confirmarlo (capturarlo) más adelante. Es útil cuando el importe final de la compra puede variar o necesita confirmarse en un momento posterior. Características clave:

Flujo en dos pasos: la transacción se divide en una autorización que reserva los fondos y una captura que los cobra. El importe no se captura de inmediato.
Misma página de Checkout: la experiencia del comprador es idéntica al flujo de pago estándar; solo cambia el momento de la captura.
Reserva y luego cobro: la autorización valida los datos de la tarjeta del cliente y retiene los fondos con el emisor de la tarjeta, pero aún no los transfiere.
Captura ajustable: en la captura, el importe puede ser igual o inferior al importe autorizado.
Vinculado por payment_id: el payment_id que devuelve la autorización identifica la transacción en cada paso posterior. Se obtiene mediante webhook después de que el pago se autoriza.

El flujo completo involucra al comprador, la página de Checkout y la Getnet WebCheckout / Regional API:

Requisitos

Antes de seguir los pasos, necesitas:

Configurar tu Web Checkout mediante Portal o mediante API (dependiendo de tu ubicación).
Generar tu token siguiendo el documento de Authentication.

Payment intent con preautorización

La página de Checkout es la misma que en el flujo de pago estándar; sin embargo, el importe no se captura de inmediato, ya que la transacción se realiza como una preautorización.

Para completar el cobro, el Merchant debe recuperar el payment_id enviado mediante webhook después de autorizar el pago, y usar los endpoints de captura y ajuste de preautorización de la Regional API para capturar o modificar el importe previamente autorizado.

Para pasar por la preautorización, estos parámetros deben enviarse en el payment intent.

Endpoint
`POST /payment-intent`

Campos requeridos

Atributo	Tipo	Descripción	Ejemplo
`configurations`	Object	Conjunto de opciones de pago.	—
`preauthorization`	Boolean	Indica si es un pago de tipo preautorizado.	`true`
`card_verification`	Boolean	Indica si es un pago de tipo verificación de tarjeta.	`false`
`3ds`	Boolean	Indica si es un pago de tipo 3DS.	`false`

El siguiente bloque de código muestra los campos que debes enviar en el payment intent endpoint.

"configurations": {
        "preauthorization": true,
        "card_verification": false,
        "3ds": false
    }

Argentina: card_verification y preauthorization no están disponibles para Argentina.

Paso 1: Autorizar el pago

Un pago en dos pasos comienza con la autorización. Este paso valida los datos de pago del cliente y realiza una retención de fondos con el emisor de la tarjeta, pero aún no los transfiere. Usa el Create - Authorize endpoint para iniciar la transacción.

Algunos países y esquemas de tarjetas imponen límites específicos de preautorización, reglas de ajuste y ventanas de captura. Consulta la pre-authorization reference para conocer los requisitos de cada país.

Para el flujo en dos pasos, debes establecer el atributo data.payment.payment_method de tu solicitud como CREDIT_PRE_AUTHORIZATION. Esto garantiza que los fondos solo se reserven y no se capturen de inmediato. La siguiente tabla muestra los campos mínimos que debes enviar:

Atributo	Descripción	Requerido
`idempotency_key`	Identificador único para evitar cargos duplicados.	Sí
`order_id`	ID de referencia del Merchant utilizado para conciliación.	Sí
`request_id`	Identificador de trazabilidad para auditorías de idempotencia y seguimiento de soporte.	Recomendado
`data.amount`	Importe de la transacción en centavos.	Sí
`data.currency`	Código de moneda ISO utilizado en la transacción.	Sí
`data.customer`	Datos del cliente (nombre, email, teléfono, documento, dirección de facturación completa). Obligatorio en producción para evitar bloqueos antifraude.	Sí
`data.payment.payment_method`	Debe ser `CREDIT_PRE_AUTHORIZATION` para un flujo en dos pasos.	Sí
`data.payment.transaction_type`	Define cómo se procesa la transacción (`FULL`, `INSTALL_NO_INTEREST`, `INSTALL_WITH_INTEREST`).	Sí
`data.payment.number_installments`	Número de cuotas (usa `1` para un pago único).	Sí
`data.payment.card`	Conjunto de datos de la tarjeta (`number`, `brand`, `expiration_month`, `expiration_year`, `security_code`, `cardholder_name`).	Sí
`data.additional_data.device`	Información de huella del dispositivo (`ip_address`, `device_id`, `finger_print`) para análisis antifraude.	Requerido en producción

Al final de una autorización exitosa, recibirás un payment_id, que se usa para identificar esta transacción en el siguiente paso.

El siguiente bloque de código muestra un ejemplo de solicitud y respuesta para autorizar un pago:

Ejemplo de solicitud:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "order123",
  "data": {
    "amount": 118708,
    "currency": "BRL",
    "customer_id": "test",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "12345678900",
      "phone_number": "+5511999999999",
      "billing_address": {
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Apto 101",
        "district": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "postal_code": "01310-100"
      }
    },
    "payment": {
      "payment_method": "CREDIT_PRE_AUTHORIZATION",
      "save_card_data": false,
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "LOJA*TESTE*COMPRA-123",
      "dynamic_mcc": 1799,
      "card": {
        "number": "5155901222260000",
        "expiration_month": "05",
        "expiration_year": "25",
        "cardholder_name": "CARD HOLDER",
        "security_code": "282"
      }
    },
    "additional_data": {
      "device": {
        "ip_address": "192.168.1.1",
        "device_id": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
        "finger_print": "1a2b3c4d5e6f7g8h9i0j"
      }
    }
  }
}'

Ejemplo de respuesta

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "order_id": "order123",
  "amount": 118708,
  "currency": "BRL",
  "status": "AUTHORIZED",
  "payment_method": "CREDIT_PRE_AUTHORIZATION",
  "received_at": "2025-08-12T20:46:26.713Z",
  "transaction_id": "MCC30105G5020",
  "original_transaction_id": "MCC30105G5020",
  "authorized_at": "2025-08-12T20:46:26.713Z",
  "reason_code": "00",
  "reason_message": "authorized",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA-123",
  "brand": "MASTERCARD",
  "authorization_code": "604020",
  "acquirer_transaction_id": "204050301040206020503010"
}

Getnet proporciona una lista de test cards que puedes usar en el entorno Stage para simular distintos escenarios de transacción.

Paso 2: Capturar el pago

Después de una autorización exitosa, debes capturar los fondos para finalizar la transacción. Usa el Capture endpoint para transferir los fondos previamente autorizados a tu cuenta.

Al llamar al endpoint de captura, debes proporcionar el payment_id del paso de autorización y el idempotency_key. Si envías el importe, debe ser igual o inferior al importe autorizado.

Para confirmar que la captura se realizó correctamente, verifica que la respuesta de la API devuelva un estado HTTP 200 OK y que el campo status en el cuerpo de la respuesta sea CAPTURED.

El siguiente bloque de código muestra un ejemplo de solicitud y respuesta para capturar un pago:

Ejemplo de solicitud:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/capture \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --data '{
  "idempotency_key": "11c7f8ee-51a6-470d-bb76-ef762b62bfb1",
  "payment_id": "a36887d0-53ec-4c36-b731-9bbeca18fcd2"
}'

Ejemplo de respuesta

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "idempotency_key": "11c7f8ee-51a6-470d-bb76-ef762b62bfb1",
  "order_id": "order123",
  "amount": 118708,
  "currency": "BRL",
  "status": "CAPTURED",
  "reason_code": "00",
  "reason_message": "captured",
  "captured_at": "2025-08-12T20:47:52.166Z"
}

Paso 3: Consultar el estado del pago (Opcional)

La respuesta inicial de autorización mostrará el estado como AUTHORIZED. Después de completar el paso de captura, este estado cambiará a CAPTURED.

Como algunos pagos se procesan de forma asíncrona, el estado puede cambiar con el tiempo. Para obtener el estado más reciente de una transacción, usa el Get Transaction endpoint.

Para recibir actualizaciones en tiempo real sin necesidad de polling, se recomienda usar Webhooks para recibir notificaciones en cada cambio de estado.

Ver también

Puedes explorar más pagos de la API de Getnet Web Checkout:

Aprende cómo crear un pago con verificación de tarjeta.
Aprende cómo crear un pago con 3DS.