# 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.

<Callout type="warning">

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

</Callout>

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

<Callout type="warning">

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

</Callout>

![](https://static-devportal-ux.sensedia-eng.com/Pagonxt/staging/documentations/wbc-credentials-1770648262379-rrshzhvs.gif)

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

<Callout type="info">

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

</Callout>

## 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](https://docs.globalgetnet.com/es/products/online-payments/web-checkout?doc=credential-wbc) y siga los pasos.

<Callout type="info">

Existen otras solicitudes que puede realizar para obtener un access token. Consulte el documento [Authentication](/es/web-checkout/first-steps-wbc/authentication-token-wbc) para obtener más información sobre estas solicitudes.

</Callout>

Ejemplo de solicitud

```json
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

```json
{
    "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](https://docs.globalgetnet.com/en/products/online-payments/web-checkout/swagger#tag/payment-intent/POST/payment-intent)

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.| `customer@email.com.br`  |
|`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**

```json
{
  "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": "laura.fernandez@example.com.uy",
    "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
```json
{
  "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**](https://www.pre.globalgetnet.com) (entorno de homologación)
* [**https://www.globalgetnet.com**](https://www.globalgetnet.com) (entorno de producción)

Luego, agregue el siguiente código:

Para **JavaScript**:
```json
<script src="${host_getnet_web}/digital-checkout/loader.js" />
```

Para **React**:
```json
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**:
```json
<script> 
const config = { "paymentIntentId": ${payment_intent_id}, "checkoutType": "lightbox" }; 
const checkoutButton = () => { loader.init(config) }; 
</script>
```

Para **React**:
```json
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**:
```json
<button onclick="checkoutButton()"> Go to Payment </button>
```

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

```json
useEffect(() => { ...
window.loader.init(config);
}, []);
```
Este será el código final para **React**:

```json
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
```json
<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.

1. El proceso de pago comienza cuando el comprador hace clic en el botón de pago designado.
2. 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.
3. 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.
4. 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.
5. Al hacer clic en el botón, el comprador inicia el proceso de autorización del pago.

![](https://static-devportal-ux.sensedia-eng.com/Pagonxt/production/images/webcheckout-payment-1784580432558-3q7u6fh8.gif)

### 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:

1. **Captura de Device Fingerprint**: recopila información del dispositivo para respaldar el análisis de fraude.  
2. **Autenticación 3D Secure (3DS)**: se aplica cuando lo admite el país de origen, la marca, el emisor y el tipo de tarjeta.  
3. **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.  
4. **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.  
5. **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.  
6. **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**:

```json
    {
  "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": "johndoe@emailtest.com",
    "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**:

```json
    {
  "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": "johndoe@emailtest.com",
    "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"
}
```