Quickstart: Crear pago

Esta guía le ayuda a crear su primera transacción de pago exitosa. Se autenticará con la API, enviará una solicitud de pago y verificará el estado de la transacción.

Paso 1: Obtener una credencial

Una vez que su cuenta esté activada, recibirá su Test Account y las claves de la API que le permitirán comenzar con la integración.

El paso 1 solo está disponible para Argentina, Chile y México.

Para generar la credencial, en el Getnet Merchant Portal, siga los pasos a continuación:

Todos los productos contratados se mostrarán en esta pantalla y la generación de credenciales se habilitará por solución.

Seleccione Digital Products.
En el menú desplegable, seleccione Integrations.
Haga clic en Generate credentials.
En la ventana emergente de advertencia, haga clic en Generate credentials.
Su credencial se ha creado. Guarde su credencial, ya que no podrá volver a mostrarse.
Copie y pegue el Client ID.
Copie y pegue el Client Secret.
Haga clic en Continue.

Si pierde las claves, repita el paso a paso para generar una nueva.

Paso 2: Recuperar el access token

Primero debe obtener un access token. Esto requiere su Client ID y Client Secret. Para recuperar sus credenciales, acceda al documento Credentials y siga los pasos.

Existen otras solicitudes que puede realizar para obtener un access token. Consulte el documento Authentication para obtener más información sobre estas solicitudes.

Ejemplo de solicitud

curl --location '{{host_getnet_api}}/authentication/oauth2/access_token' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--header 'Accept: application/json' 
--data-urlencode 'grant_type=client_credentials' 
--data-urlencode 'client_id={{PUT_YOUR_CLIENT_ID_HERE}}' 
--data-urlencode 'client_secret={{PUT_YOUR_CLIENT_SECRET_HERE}}'

Ejemplo de respuesta

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiI1amhLMy9xK0ZpK0tTRkIrRUwwN3VhMFYwdGM9Ii...",
    "scope": "name-scope:r",
    "token_type": "Bearer",
    "expires_in": 3599
}

Paso 3: Crear un Payment Intent

Una vez que haya obtenido un access token, debe crear un payment intent cada vez que el cliente inicie el proceso de checkout al hacer clic en el botón de pago de su tienda web.

El payment intent permite que el frontend cargue la interfaz de Checkout y continúe con la transacción de forma segura.

El uso de un payment intent garantiza que se cobre al cliente el importe exacto especificado durante su creación. Como el payment intent se genera en el backend, el importe definido se mantiene constante durante todo el flujo de pago. No se puede modificar, ni accidental ni maliciosamente, desde el frontend.

Para crear un payment intent, envíe una solicitud HTTP POST e incluya el access_token obtenido previamente en el encabezado Authorization. Una respuesta exitosa devuelve el payment intent ID y la redirect URL, necesarios para la implementación del frontend, según el método de integración elegido.

Para más detalles, consulte la referencia de la API

Endpoint
`POST /payment-intent`

Campos obligatorios

Campo	Tipo	Descripción	Ejemplo
`payment.currency`	String	Código de moneda.	`BRL`
`payment.amount`	Integer	Importe de la compra en formato entero, donde los últimos 2 dígitos representan los centavos. Para países donde no aplican los centavos, complete el importe con 2 ceros a la derecha.	`92500`
`customer.customer_id`	String	Se recomienda usar el número de documento del cliente, solo letras y números, sin caracteres especiales, separadores ni espacios.	`12345678912`
`customer.first_name`	String	Nombre del cliente.	`John`
`customer.last_name`	String	Apellido del cliente.	`Doe Smith`
`customer.name`	String	Nombre completo del cliente.	`John Doe Smith`
`customer.email`	String	Dirección de correo electrónico del cliente.	`[email protected]`
`customer.document_type`	String	Tipo de documento usado para identificar al cliente. Consulte la tabla Valores de campo para ver los valores aceptados.	`CPF`
`customer.document_number`	String	Número de documento usado para identificar al cliente.	`12345678912`
`customer.billing_address.street`	String	Nombre de la calle.	`Av. Brasil`
`customer.billing_address.number`	String	Número que identifica la posición de un edificio en una calle.	`1000`
`customer.billing_address.country`	String	Código de país. Consulte la tabla Valores de campo para ver los valores aceptados.	`BR`
`customer.billing_address.postal_code`	String	Código postal.	`90230060`

Campos condicionales (solo Uruguay)

Campo	Tipo	Descripción	Ejemplo
`additional_data`	Object	Datos adicionales para regulaciones regionales y requisitos fiscales. Obligatorio para Uruguay.	---
`additional_data.rates`	Array	Tasas de impuestos aplicadas a la transacción.	---
`additional_data.rates.key`	String	(Solo Uruguay). Tipo de impuesto o tasa que se aplica.	`IVA`
`additional_data.rates.value`	Number	(Solo Uruguay). Importe del impuesto en formato entero (centavos)	`123`
`additional_data.regional_regulation_code`	String	(Solo Uruguay). Código fiscal o regulatorio regional exigido por las autoridades locales. Se usa para los envíos SEP en Uruguay.	`17934`

Campos opcionales

Campo	Tipo	Descripción	Ejemplo
`configurations`	Object	Configuraciones adicionales para el payment intent	---
`configurations.3ds`	Boolean	Controla la autenticación 3D Secure.	`true` o `false`
`configurations.preauthorization`	Boolean	Indica si el pago es una preautorización.	`true` o `false`
`configurations.card_verification`	Boolean	Indica si se trata de un flujo de verificación de tarjeta.	`true` o `false`
`configurations.success_url`	String	URL de redirección en caso de pago exitoso.	`https://www.mystore.com/checkout/success`
`configurations.error_url`	String	URL de redirección en caso de error durante el pago.	`https://www.mystore.com/checkout/error`
`expires_at`	String	Vencimiento del payment intent.	`3d4h15m`

Valores de campo

Campo	Argentina	Brasil	Chile	España	México	Uruguay
`currency`	`ARS`	`BRL`	`CLP`	`EUR`	`MXN`	`UYU` o `USD`
`document_type`	`DNI`	`CPF`, `CNPJ` o `passport`	`RUT`	`DNI`, `INE` o `passport`	`RFC`	`uyci`
`country`	`AR`	`BR`	`CH`	`ES`	`MX`	`UY`
`key`	-	-	-	-	-	`IVA`

Reglas de llenado de campos:

El campo expires_at acepta un valor de duración (por ejemplo, 15m, 2h, 7d o 1d12h30m). Esta duración se aplica sin importar la zona horaria del comercio. La marca de tiempo de vencimiento que devuelve la API siempre tiene formato GMT+0 (UTC). Si no se proporciona ningún valor, el payment intent no vence.
Cuando se proporcionan success_url y error_url en la solicitud del payment intent, estos valores anulan la configuración técnica del comercio.
Uruguay: Los comercios pueden crear payment intents en UYU (peso uruguayo) o en USD. Al pagar en UYU, el objeto additional_data es obligatorio y debe incluir additional_data.rates.key con la clave de tasa IVA y regional_regulation_code para cumplir con SEP.
Argentina: card_verification y preauthorization no están disponibles para Argentina.

Ejemplo de solicitud

{
  "mode": "instant",
  "order_id": "ORDER_UY_97531",
  "configurations": {
    "3ds": true,
    "preauthorization": false,
    "card_verification": false,
    "success_url": "https://www.mystore.com/checkout/success",
    "error_url": "https://www.mystore.com/checkout/error"
  },
  "payment": {
    "currency": "UYU",
    "amount": 120000
  },
  "product": [
    {
      "product_type": "service",
      "title": "Curso de inglés online",
      "description": "Curso completo de 6 meses",
      "value": 120000,
      "quantity": 1
    }
  ],
  "customer": {
    "customer_id": "customer_uy_005",
    "first_name": "Laura",
    "last_name": "Fernández Rodríguez",
    "name": "Laura Fernández Rodríguez",
    "email": "[email protected]",
    "document_type": "ci",
    "document_number": "45678912",
    "phone_number": "59899123456",
    "gender": "Female",
    "checked_email": true,
    "billing_address": {
      "street": "Av. 18 de Julio",
      "number": "1234",
      "complement": "Apto 601",
      "district": "Centro",
      "city": "Montevideo",
      "state": "Montevideo",
      "country": "UY",
      "postal_code": "11200",
      "reference": "Entre Río Branco y Convención"
    }
  },
  "shipping": {
    "first_name": "Laura",
    "last_name": "Fernández Rodríguez",
    "name": "Laura Fernández Rodríguez",
    "phone_number": "59899123456",
    "shipping_amount": 0,
    "address": {
      "street": "Av. 18 de Julio",
      "number": "1234",
      "complement": "Apto 601",
      "district": "Centro",
      "city": "Montevideo",
      "state": "Montevideo",
      "country": "UY",
      "postal_code": "11200",
      "reference": "Entre Río Branco y Convención"
    }
  },
  "pickup_store": false,
  "shipping_method": "UES",
  "soft_descriptor": "Tienda UY",
  "additional_data": {
    "rates": [
      {
        "key": "Iva",
        "value": 22
      }
    ],
    "regional_regulation_code": ["17934"]
  },
  "expires_at": "1h"
}

Ejemplo de respuesta

{
  "payment_intent_id": "f6ee8bc7-229d-4d9d-bced-7dd2371a1f57",
  "trade_name": "GetNet Store",
  "redirect_url": "https://www.globalgetnet.com/hosted-web-checkout/eyJraWQiOiJQQUdPTlhUL..."
}

Paso 4: Integración del frontend

Una vez que su integración de backend esté completa, la creación exitosa de un payment intent devuelve dos propiedades clave (redirect_url y payment_intent_id) necesarias para integrar el Web Checkout de Getnet en su frontend.

La propiedad que use depende del formato de integración elegido, que puede ser una implementación en JavaScript o en React.

Para el Web Checkout de tipo Redirect (alojado por Getnet), use la URL de la propiedad redirect_url para abrir una nueva página para el comprador.
Para las opciones de Web Checkout con formato Iframe o Lightbox, extraiga el payment_intent_id de la respuesta y siga los pasos correspondientes para incrustar la interfaz de Checkout en la página de pago de su tienda web.

Importar el loader de Getnet

El loader se encarga de inicializar la aplicación segura de Getnet Checkout. Debe invocarse después de crear un payment intent para que el cliente pueda ingresar sus datos de pago de forma segura y continuar con la transacción.

Para consumir las APIs, use los siguientes valores de DNS para host_getnet_web:

https://www.pre.globalgetnet.com (entorno de homologación)
https://www.globalgetnet.com (entorno de producción)

Luego, agregue el siguiente código:

Para JavaScript:

<script src="${host_getnet_web}/digital-checkout/loader.js" />

Para React:

useEffect(() => {
const script = document.createElement("script");
script.src = "${host_getnet_web}/digital-checkout/loader.js";
script.async = true; 
script.setAttribute("data-testid", "digital-checkout");
script.setAttribute("id", "digital-checkout");
document.body.appendChild(script);
}, []);

Agregar el script de checkout

El script de checkout conecta el loader con el usuario y también le permite seleccionar la opción de integración que mejor se adapte a sus necesidades.

Para ello, agregue el siguiente código. Reemplace el valor paymentIntentId con el payment_intent_id recibido previamente y modifique el valor checkoutType con lightbox o iframe según su selección:

Para JavaScript:

<script> 
const config = { "paymentIntentId": ${payment_intent_id}, "checkoutType": "lightbox" }; 
const checkoutButton = () => { loader.init(config) }; 
</script>

Para React:

useEffect(() => { ... 
const config = { paymentIntentId: ${payment_intent_id}, checkoutType: "lightbox" };
}, []);

Agregar el botón de checkout

El botón se encarga de ejecutar el script de checkout mostrado en el paso anterior. Agregue el siguiente código a su HTML:

Para JavaScript:

<button onclick="checkoutButton()"> Go to Payment </button>

Si usa React, en este paso debe iniciar el loader de Getnet:

useEffect(() => { ...
window.loader.init(config);
}, []);

Este será el código final para React:

useEffect(() => { 
const script = document.createElement("script"); 
script.src = "${host_getnet_web}/digital-checkout/loader.js"; 
script.async = true; 
script.setAttribute("data-testid", "digital-checkout"); 
script.setAttribute("id", "digital-checkout"); 
document.body.appendChild(script);
const config = { paymentIntentId: ${payment_intent_id}, checkoutType: "lightbox" };
window.loader.init(config);
}, []);

Cambiar la posición del iFrame

Si elige el formato iFrame para su integración de checkout, el iFrame se inserta de forma predeterminada como el último elemento de la página. Puede ajustar su posición manipulando el elemento dentro del DOM para adaptarlo mejor a sus requisitos de diseño y maquetación.

El siguiente ejemplo muestra cómo crear el iFrame con un identificador y manipularlo en el DOM.

JavaScript

<div id="iframe-section"></div>

<script>
const config = {
    "paymentIntentId": "PAYMENT_INTENT_ID_HERE",
    "checkoutType": "iframe"
};
const checkoutButton = () => {
    loader.init(config);

    const iframeSection = document.getElementById("iframe-section");
    const iframe = document.querySelector("iframe");
    iframeSection.appendChild(iframe);
};
</script>

Flujo de la transacción

Siga estos pasos para procesar un pago.

El proceso de pago comienza cuando el comprador hace clic en el botón de pago designado.
La pantalla de checkout muestra el importe del payment intent, así como los métodos de pago disponibles según la configuración del Merchant Portal o de la API.
Para los pagos con tarjeta de crédito o débito, el comprador ingresa los datos de su tarjeta. Si la marca y el tipo de tarjeta admiten pagos en cuotas, se envía una consulta transparente a la API de Installments de Getnet para obtener las opciones de cuotas disponibles para este checkout.
Las cuotas ofrecidas se basan en los acuerdos contratados con Getnet y en las preconfiguraciones del Merchant Portal o de la API. Ahí usted determina si ofrece cuotas con o sin interés y establece un límite en la cantidad de cuotas.
Al hacer clic en el botón, el comprador inicia el proceso de autorización del pago.

Proceso de autorización de pago – Web Checkout de Getnet

El proceso de autorización de cada pago incluye varios pasos críticos diseñados para garantizar la seguridad, la integridad y el cumplimiento de cada transacción:

Captura de Device Fingerprint: recopila información del dispositivo para respaldar el análisis de fraude.
Autenticación 3D Secure (3DS): se aplica cuando lo admite el país de origen, la marca, el emisor y el tipo de tarjeta.
Tokenización de la tarjeta: en cumplimiento de los estándares PCI DSS, los datos sensibles de la tarjeta no se transmiten ni se almacenan durante el proceso de autorización. En su lugar, la tarjeta se tokeniza al inicio del flujo y solo se transmite el token generado entre las APIs internas.
Validación del método de pago: verifica que el método de pago seleccionado, la marca de tarjeta y el plan de cuotas sean compatibles con los productos y servicios contratados por el comercio.
Análisis de fraude: se realiza a través de la API Antifraude de Getnet, según las reglas definidas por el equipo correspondiente de Getnet en cada país.
Autorización de pago: el paso final, donde la transacción se autoriza mediante comunicación con las instituciones financieras correspondientes.

Al concluir este proceso, la aplicación cliente del Web Checkout recibe una respuesta que indica Success o Failure:

Failure: Si el pago es rechazado o se detecta cualquier problema durante el proceso, se muestra un mensaje de error al comprador. Además, se envía un webhook o notificación con los detalles del pago y el estado de la transacción.
Success: Si el pago es autorizado, se muestra un mensaje de confirmación al comprador. También se envía un webhook o notificación con los datos de autorización y el estado de la transacción. En esta etapa se genera el payment_id, que puede usarse para operaciones de cancelación o reembolso (consulte la documentación Modifying Payments para más detalles).

Ejemplo de un payload de transacción AUTHORIZED:

    {
  "payment_intent_id": "1f9f47ed-65cc-4fbf-a407-0f17df9a2e2c",
  "checkout_id": "5ab15d1e-ea8b-4560-84d2-fb3d02179537",
  "order_id": "YOUR_ORDER_ID",
  "mode": "instant",
  "seller": {
    "id": "716d899e-9091-4577-a12f-8a77ec4d1e0b",
    "trade_name": "GetNet Shop",
    "merchant_document": "00000000000",
    "settings": {
      "notification_url_configured": true
    }
  },
  "customer": {
    "customer_id": "c129d793-d204-4610-8819-b8fb720a8552",
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "document_type": "dni",
    "document_number": "1111111111111",
    "checked_email": false,
    "billing_address": {
      "street": "South Rockledge St",
      "number": "00",
      "complement": "Rockville",
      "country": "AR",
      "postal_code": "00000000"
    }
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "address": {
      "street": "South Rockledge St",
      "number": "00",
      "complement": "Rockville",
      "country": "AR",
      "postal_code": "00000000"
    }
  },
  "payment": {
    "method": "credit",
    "amount": 14100,
    "currency": "ARS",
    "installment": {
      "quote_id": "f054ce63-0475-406f-8eca-25aea5dae6a8",
      "schema": "plan_name",
      "type": "with_interest",
      "number": 6
    },
    "payment_method": {
      "token_id": "e327bae6-286e-4920-addb-5f4b10315b4e"
    },
    "result": {
      "payment_id": "3a76acae-d9c0-421c-91e0-cf5ce8aca098",
      "status": "Authorized",
      "authorization_code": "999999",
      "transaction_datetime": "2024-01-01T12:00:00.000Z"
    }
  },
  "pickup_store": false,
  "product": [
    {
      "product_type": "cash_carry",
      "title": "Look Fashion Leather Boot",
      "value": 5300,
      "quantity": 1
    },
    {
      "product_type": "cash_carry",
      "title": "Look Fashion Blazer",
      "value": 8800,
      "quantity": 1
    }
  ],
  "frontend": {
    "link": "https://www.globalgetnet.com/",
    "time_page": 39,
    "sales_channel": "WEB",
    "application_version": "0.0.0",
    "card_pasted": true,
    "ip": "000.000.00.00",
    "timezone": "America/Sao_Paulo",
    "locale": "en-US"
  },
  "created_at": "2024-01-01T12:00:00.000Z",
  "updated_at": "2024-01-01T12:00:00.000Z"
}

Ejemplo de un payload de transacción DENIED:

    {
  "payment_intent_id": "1f9f47ed-65cc-4fbf-a407-0f17df9a2e2c",
  "checkout_id": "5ab15d1e-ea8b-4560-84d2-fb3d02179537",
  "order_id": "YOUR_ORDER_ID",
  "mode": "instant",
  "seller": {
    "id": "716d899e-9091-4577-a12f-8a77ec4d1e0b",
    "trade_name": "GetNet Shop",
    "merchant_document": "00000000000",
    "settings": {
      "notification_url_configured": true
    }
  },
  "customer": {
    "customer_id": "c129d793-d204-4610-8819-b8fb720a8552",
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "document_type": "dni",
    "document_number": "1111111111111",
    "checked_email": false,
    "billing_address": {
      "street": "South Rockledge St",
      "number": "00",
      "complement": "Rockville",
      "country": "AR",
      "postal_code": "00000000"
    }
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "address": {
      "street": "South Rockledge St",
      "number": "00",
      "complement": "Rockville",
      "country": "AR",
      "postal_code": "00000000"
    }
  },
  "payment": {
    "method": "credit",
    "amount": 14100,
    "currency": "ARS",
    "installment": {
      "quote_id": "f054ce63-0475-406f-8eca-25aea5dae6a8",
      "schema": "plan_name",
      "type": "with_interest",
      "number": 6
    },
    "payment_method": {
      "token_id": "e327bae6-286e-4920-addb-5f4b10315b4e"
    },
    "result": {
      "payment_id": "3a76acae-d9c0-421c-91e0-cf5ce8aca098",
      "status": "Denied",
      "return_message": "Card not accepted for this operation",
      "transaction_datetime": "2024-01-01T12:00:00.000Z"
    }
  },
  "pickup_store": false,
  "product": [
    {
      "product_type": "cash_carry",
      "title": "Look Fashion Leather Boot",
      "value": 5300,
      "quantity": 1
    },
    {
      "product_type": "cash_carry",
      "title": "Look Fashion Blazer",
      "value": 8800,
      "quantity": 1
    }
  ],
  "frontend": {
    "link": "https://www.globalgetnet.com/",
    "time_page": 39,
    "sales_channel": "WEB",
    "application_version": "0.0.0",
    "card_pasted": true,
    "ip": "000.000.00.00",
    "timezone": "America/Sao_Paulo",
    "locale": "en-US"
  },
  "created_at": "2024-01-01T12:00:00.000Z",
  "updated_at": "2024-01-01T12:00:00.000Z"
}