Crear un Pago Preautorizado con Tarjeta

Procese una transacción de pago completa de dos pasos autorizándola primero para reservar los fondos y, a continuación, capturándola para finalizar el cargo. Esta guía le orienta en cada paso del uso de la Global API de Getnet para este flujo común de e-commerce.

Requisitos

Antes de seguir los pasos, necesita:

Crear su cuenta poniéndose en contacto con el equipo de Soporte de Integración para obtener sus credenciales de la API client_id y client_secret.
Generar su token con sus credenciales utilizando el endpoint de Authentication.

Getnet proporciona una Postman Collection para ayudarle a replicar estos casos de uso localmente. También puede probar la API en el entorno sandbox utilizando la API Reference disponible en la documentación.

Especificidades de los Casos de Uso

Al integrar cualquier solución de Getnet, se aplican requisitos específicos del mercado. Asegúrese de revisar los recursos a continuación antes de pasar a producción:

También puede utilizar tarjetas de prueba para simular escenarios específicos. Puede encontrar más información sobre los requisitos específicos para cada país en la sección de Developer Resources de la documentación de Getnet.

Proceso de Pago en Dos Pasos

Para ayudar a visualizar el proceso de pago de dos pasos, el siguiente diagrama de secuencia ilustra las interacciones entre su sistema y la Global API de Getnet. Cubre la autorización inicial, la captura posterior y los dos métodos para verificar el estado final.

Getnet también soporta la creación y captura de pagos en un solo paso. Para más detalles, consulte la guía Crear Pagos en un Solo Paso.

Tokenizar los Datos de la Tarjeta (Opcional)

En lugar de enviar el número de la tarjeta en formato original (raw) en su petición de pago, puede utilizar la tokenización para mejorar la seguridad y reducir el alcance del cumplimiento del PCI DSS. Para utilizar una tarjeta tokenizada:

Tokenice la tarjeta llamando al endpoint de Card Tokenization con el card_number y el customer_id.
En su petición de pago, reemplace el campo card.number por card.number_token utilizando el valor del token recibido del endpoint de tokenización.

Al utilizar number_token, debe excluir la propiedad card.number de la petición. Para obtener todos los detalles sobre la tokenización, consulte la documentación de Tokenización y Vault.

Paso 1: Autorizar el Pago

Un pago en dos pasos comienza con la autorización. Este paso valida los detalles de pago del cliente y retiene los fondos con el emisor de la tarjeta, pero aún no los transfiere. Utilice el endpoint de Create - Authorize 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. Revise la referencia de preautorización para conocer los requisitos de cada país.

Para el proceso de dos pasos, debe establecer el atributo data.payment.payment_method de su petición en CREDIT_AUTHORIZATION. Esto garantiza que los fondos solo se reserven y no se capturen de inmediato.

Requisitos específicos del país: Algunos mercados pueden requerir campos obligatorios adicionales. En Uruguay debe incluir un array rates y proporcionar un regional_regulation_code. El regional_regulation_code es un array donde cada entrada tiene un code y un invoice. El invoice acepta hasta 9 caracteres alfanuméricos. Recomendamos usar solo números. Revise la referencia de Taxes and Regulations para obtener más información.

La siguiente tabla enumera los campos mínimos que necesita enviar:

Atributo	Descripción	Requerido
`idempotency_key`	Identificador único para evitar cargos duplicados.	Sí
`order_id`	ID de referencia del comercio utilizado para la conciliación.	Sí
`request_id`	Identificador de rastreo para auditorías de idempotencia y seguimiento de soporte.	Recomendado
`data.amount`	Importe de la transacción en céntimos.	Sí
`data.currency`	Código de la divisa ISO utilizado en la transacción.	Sí
`data.customer`	Detalles del cliente (nombre, correo electrónico, teléfono, documento, dirección de facturación completa). Obligatorio en producción para evitar bloqueos del antifraude.	Sí
`data.payment.payment_method`	Debe ser `CREDIT_AUTHORIZATION` para un flujo de 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 plazos (utilice `1` para un solo pago).	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 fingerprint del dispositivo (`ip_address`, `device_id`, `finger_print`) para análisis de antifraude.	Obligatorio en producción

El payload de antifraude también debe incluir los siguientes campos:

Objeto / Campo	Descripción
`customer.first_name`	Nombre del cliente
`customer.last_name`	Apellido del cliente
`customer.email`	Dirección de correo electrónico del cliente
`customer.phone_number`	Número de teléfono (formato internacional)
`customer.document_type`	Tipo de documento (ej., CPF, DNI, etc.)
`customer.document_number`	Número de documento (sin puntuación)
`customer.billing_address.street`	Nombre de la calle
`customer.billing_address.number`	Número de la dirección
`customer.billing_address.district`	Distrito o barrio
`customer.billing_address.city`	Ciudad
`customer.billing_address.state`	Estado o provincia
`customer.billing_address.country`	Código del país (ISO)
`customer.billing_address.postal_code`	Código postal
`additional_data.device.ip_address`	Dirección IP del cliente
`additional_data.device.device_id`	ID de la sesión del fingerprint del dispositivo (UUIDv4)
`additional_data.device.finger_print`	Hash del fingerprint generado por el script de antifraude

Los datos de antifraude son obligatorios para entornos de producción. Las transacciones que carezcan del fingerprint del dispositivo o de la información del cliente serán bloqueadas automáticamente por los equipos de antifraude para prevenir el fraude. Consulte la documentación de Antifraude para obtener detalles completos sobre la implementación.

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

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

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_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": "13c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "order_id": "123order2",
  "amount": 118708,
  "currency": "CLP",
  "status": "AUTHORIZED",
  "payment_method": "CREDIT_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 tarjetas de prueba que se pueden utilizar en el entorno de Homologación (Stage) para simular diversos escenarios de transacción.

Paso 2: Capturar el Pago

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

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

Para confirmar que la captura fue exitosa, verifique 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 una petición y respuesta para capturar un pago:

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": "13c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "order_id": "123order2",
  "amount": 118708,
  "currency": "CLP",
  "status": "CAPTURED",
  "reason_code": "00",
  "reason_message": "captured",
  "captured_at": "2025-08-12T20:47:52.166Z"
}

Paso 3: Comprobar el Estado del Pago (Opcional)

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

Debido a que 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, utilice el endpoint de Get Transaction.

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

Próximos Pasos

Ahora que ha creado con éxito un pago de dos pasos, puede explorar más funciones de la Global API de Getnet:

Crear un Pago de un Solo Paso.
Obtener más información sobre los Pagos con 3DS.