# Quickstart: Create Payment

This guide helps you create your first successful payment transaction. You'll authenticate with the API, submit a payment request, and verify the transaction status.

## Step 1: Get a credential

Once your account is activated, you will receive your Test Account and API keys that will enable you to start with the integration.

<Callout type="warning">

Step 1 is only available for 
**Argentina**, **Chile** and **Mexico**.

</Callout>

To generate the credential, at the Getnet Merchant Portal, follow the steps below:

<Callout type="warning">

All contracted products will be shown on this screen and the credential generation is going to be enabled by solution.

</Callout>

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

1. Select **Digital Products**.
2. In the dropdown menu, select **Integrations**.
3. Click **Generate credentials**.
4. In the pop up warning, click **Generate credentials**.
5. Your credential is created. Please save your credential as it will not be able to show it again.
6. Copy and paste the Client ID.
7. Copy and paste the Client Secret.
8. Click **Continue**.

<Callout type="info">

If you lose the keys, repeat the step-by-step to generate a new one.

</Callout>

## Step 2: Retrieving Access token

You must first obtain an **access token**. This requires your **Client ID** and **Client Secret**.
To retrieve your credentials access [Credentials](https://docs.globalgetnet.com/en/products/online-payments/web-checkout?doc=credential-wbc) document and follow the steps.

<Callout type="info">

There are other request that can be done to retrive an access token, check the [Authentication](/en/web-checkout/first-steps-wbc/authentication-token-wbc) document to know more about this requests.

</Callout>

Request example

```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}}'
```

Response example

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

## Step 3: Create a Payment Intent

Once you have obtained an **access token**, a **payment intent** must be created whenever the customer initiates the checkout process by clicking the payment button on your web store. 

The payment intent allows the frontend to load the Checkout interface and proceed with the transaction securely.

Using a payment intent ensures that the customer is charged the exact amount specified during its creation. Since the payment intent is generated on the backend, the defined amount remains consistent throughout the entire payment flow and cannot be modified, either accidentally or maliciously, from the frontend.

To create a payment intent, send an **HTTP POST** request including the previously obtained `access_token` in the **Authorization** header. A successful response will return the **payment intent ID** and **redirect URL**, which are required for the frontend implementation, depending on the chosen integration method.

For more details, see the [API reference](https://docs.globalgetnet.com/en/products/online-payments/web-checkout/swagger#tag/payment-intent/POST/payment-intent)

Endpoint|
---|
`POST /payment-intent`|

**Required fields**
| Field | Type | Description | Example |
|---|---|---|---|
|`payment.currency`| String | Currency code. | `BRL`|
|`payment.amount`| Integer | Purchase amount in integer format, where the last 2 digits represent the cents. For countries where cents do not apply, fill in the amount with 2 zeros to the right. |`92500`|
|`customer.customer_id`| String | Recommend using the customer's document number, only letters and numbers, without any special characters, separators or spaces.| `12345678912`  |
|`customer.first_name`| String | Customer's first name.| `John`  |
|`customer.last_name`| String | Customer's last name.| `Doe Smith`  |
|`customer.name`| String | Customer's full name.| `John Doe Smith`  |
|`customer.email`| String | Customer's email address.| `customer@email.com.br`  |
|`customer.document_type`| String | Type of the document used to identify the customer. Check the **Field Values** table to see the accepted values. | `CPF`  |
|`customer.document_number`| String | Document number used to identify the customer.| `12345678912`  |
|`customer.billing_address.street`| String | Name of a street.| `Av. Brasil`  |
|`customer.billing_address.number`| String | Number that identifies the position of a building on a street.| `1000`  |
|`customer.billing_address.country`| String | Country code. Check the **Field Values** table to see the accepted values.| `BR` |
|`customer.billing_address.postal_code`| String | Postal or ZIP code.| `90230060`  |

**Conditional fields (Uruguay only)**
| Field | Type | Description | Example |
|---|---|---|---|
|`additional_data`| Object | Additional data for regional regulations and tax requirements. Required for Uruguay. | --- |
|`additional_data.rates`| Array | Tax rates applied to the transaction.| --- |
|`additional_data.rates.key`| String | (Uruguay only). Type of tax or rate being applied. | `IVA`|
|`additional_data.rates.value`| Number | (Uruguay only). Tax amount in integer format (cents)| `123`|
|`additional_data.regional_regulation_code`| String | (Uruguay only). Regional fiscal or regulatory code required by local authorities. Used for SEP submissions in Uruguay. | `17934`|

**Optional fields**
| Field | Type | Description | Example |
|---|---|---|---|
|`configurations`| Object | Additional configurations for the payment intent | --- |
|`configurations.3ds`| Boolean | Controls 3D Secure authentication. | `true` or `false`|
|`configurations.preauthorization`| Boolean | Indicates if the payment is a pre-authorization. | `true` or `false`|
|`configurations.card_verification`| Boolean | Indicates if this is a card verification flow. | `true` or `false`|
|`configurations.success_url`| String | Redirect URL in case of successful payment. |`https://www.mystore.com/checkout/success`|
|`configurations.error_url`| String | Redirect URL in case of an error during payment. |`https://www.mystore.com/checkout/error`|
|`expires_at`| String | Payment intent expiration. | `3d4h15m`|

**Field Values**
| Field         | Argentina |       Brazil                | Chile |       Espanha              | Mexico | Uruguay         |
|:-------------:|:---------:|:---------------------------:|:-----:|:--------------------------:|:------:|:---------------:|
|`currency`     |   `ARS`   |               `BRL`         | `CLP` |  `EUR`                     |  `MXN` | `UYU` or  `USD` |
|`document_type`|   `DNI`   | `CPF`, `CNPJ` or `passport` | `RUT` | `DNI`, `INE` or `passport` |  `RFC` |     `uyci`      |
|`country`      |    `AR`   |             `BR`            |  `CH` |             `ES`           |  `MX`  |      `UY`       |
|`key`          |    -      |             -               |   -   |             -              |    -   |       `IVA`     |

#### Field filling rules:

* The `expires_at` field accepts a duration value (for example, 15m, 2h, 7d, or 1d12h30m). This duration is applied regardless of the merchant's timezone. The expiration timestamp returned by the API is always formatted in GMT+0 (UTC). If **no value** is provided, the payment intent **does not expire**.
* When `success_url` and `error_url` is provided in the payment intent request, it will overrides the value configured in the seller's technical configuration.
* **Uruguay**: Sellers can create payment intents in either UYU (Uruguayan Peso) or USD. When paying in UYU, the `additional_data` object is required and must include the `additional_data.rates.key` with **IVA** rate key and the `regional_regulation_code` for SEP compliance.
* **Argentina**: `card_verification` and `preauthorization` are **not available** for Argentina.

**Request example**

```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"
}
```

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

## Step 4: Frontend integration

Once your backend integration is complete, a successful **payment intent** creation will return two keys properties required (`redirect_url` and `payment_intent_id`) to integrate Getnet’s Web Checkout into your frontend. 

The property you use depends on the chosen integration format, that can be by JavaScript or React implementation.

- For the **Redirect** (Getnet-hosted) Web Checkout, use the URL provided in the `redirect_url` property to open a new page for the shopper.  
- For Web Checkout options using **Iframe** or **Lightbox** formats, extract the `payment_intent_id` from the response and follow the corresponding steps to embed the Checkout interface on your web store’s payment page.

### Import the Getnet loader

The loader is responsible for initializing the secure Getnet Checkout application. It must be invoked **after a payment intent has been created** to allow the customer to safely enter their payment details and proceed with the transaction.

To consume the APIs use the following DNS values for the `host_getnet_web`:

* [**https://www.pre.globalgetnet.com**](https://www.pre.globalgetnet.com) (homologation environment)
* [**https://www.globalgetnet.com**](https://www.globalgetnet.com) (production environment)

Then, add the following code:

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

For **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);
}, []);
```

### Add the checkout script

The checkout script will make a connection between the loader and the user, and also allow you to select the integration option that better fits your needs.

To do so, add the following code and replace the `paymentIntentId` value with the `payment_intent_id` previously received, and modify the `checkoutType` value with `lightbox` or `iframe` depending on your selection:

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

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

### Add the checkout button

The button is responsible for running the checkout script shown in the previous step. Add the following code to your html:

For **JavaScript**:
```json
<button onclick="checkoutButton()"> Go to Payment </button>
```

If you are using **React**, in this step you have to initiate the Getnet loader:

```json
useEffect(() => { ...
window.loader.init(config);
}, []);
```
This will be the final code for **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);
}, []);
```

## Change the position of the iFrame

If you choose the **iFrame** format for your checkout integration, the iFrame is inserted by default as the last element of the page. You can adjust its position by manipulating the element within the DOM to better fit your layout and design requirements.

The example below shows how to create the iFrame with an identifier and manipulate it in the 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>
```

## Transaction Flow

Follow the steps to process a payment.

1. The payment process begins when the buyer clicks the designated payment button.
2. The checkout screen will display the payment intention value, as well as the available payment methods depending on Merchant Portal or API's configuration.
3. For payments made by credit or debit card, the buyer will enter their card details. If the brand and type of card provided support installment payments, a transparent query will be sent to Getnet's Installments API to retrieve the available installment options for this checkout.
4. The installments offered are based on the agreements contracted with Getnet and the pre-configurations made in the merchant's portal or API configurations, where you determine whether to offer installments with or without interest and set a limit on the number of installments.
5. By clicking the button, the buyer will start the payment authorization process.

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

### Payment Authorization Process – Getnet Web Checkout

The authorization process for each payment involves several critical steps designed to ensure the **security, integrity, and compliance** of every transaction:

1. **Device Fingerprint Capture**: Collects device information to support fraud analysis.  
2. **3D Secure Authentication (3DS)**: Applied when supported by the card’s country of origin, brand, issuer, and type.  
3. **Card Tokenization**: In compliance with **PCI DSS** standards, sensitive card data is neither transmitted nor stored during the authorization process. Instead, the card is tokenized at the start of the flow, and only the generated token is transmitted between internal APIs.  
4. **Payment Method Validation**: Verifies that the selected payment method, card brand, and installment plan are compatible with the products and services contracted by the merchant.  
5. **Fraud Analysis**: Conducted via Getnet’s AntiFraud API, based on rules defined by the relevant Getnet team in each country.  
6. **Payment Authorization**: The final step, where the transaction is authorized through communication with the appropriate financial institutions.  

At the conclusion of this process, the Web Checkout client application receives a response indicating either **Success** or **Failure**:

- **Failure**: If the payment is declined or any issue is detected during the process, an error message is displayed to the buyer. Additionally, a **webhook or notification** is sent containing the payment details and the transaction status.  
- **Success**: If the payment is authorized, a confirmation message is displayed to the buyer. A **webhook or notification** is also sent with the authorization data and transaction status. At this stage, the **payment_id** is generated, which can be used for **cancellation or refund operations** (refer to the *Modifying Payments* documentation for further details).

Example of an **AUTHORIZED** transaction payload:

```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"
}
```

Example of a **DENIED** transaction payload:

```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"
}
```