Quickstart: Create a 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

After your account is activated, you receive your Test Account and API keys, which let you start the integration.

information icon
Important: Step 1 is only available for Argentina, Chile, and Mexico.

To generate the credential, follow these steps in the Getnet Merchant Portal:

information icon
Important: This screen shows all contracted products. Credential generation is enabled by solution.

  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. The portal creates your credential. Save it, because the portal can't show it again.
  6. Copy and paste the Client ID.
  7. Copy and paste the Client Secret.
  8. Click Continue.
information icon
Info: If you lose the keys, repeat these steps to generate a new credential.

Step 2: Get an access token

First, get an access token. To request it, you need your Client ID and Client Secret.
information icon
Info: You can also retrieve an access token with other requests. To learn more about these requests, see the Authentication document.

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

After you get an access token, create a payment intent each time the customer starts the checkout process. The customer starts checkout 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.

A payment intent ensures that the customer is charged the exact amount you set when you create it. You generate the payment intent on the backend, so the amount stays the same throughout the payment flow. No one can change it from the frontend, either accidentally or maliciously.

To create a payment intent, send an HTTP POST request with the access_token you got earlier in the Authorization header. A successful response returns the payment intent ID and redirect URL. Your frontend implementation requires these values, depending on the integration method you choose.

For more details, see the API reference.

Endpoint
POST /payment-intent
Required fields
FieldTypeDescriptionExample
payment.currencyStringCurrency code.BRL
payment.amountIntegerPurchase 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_idStringWe recommend the customer's document number. Use only letters and numbers, without special characters, separators, or spaces.12345678912
customer.first_nameStringCustomer's first name.John
customer.last_nameStringCustomer's last name.Doe Smith
customer.nameStringCustomer's full name.John Doe Smith
customer.emailStringCustomer's email address.customer@email.com.br
customer.document_typeStringType of the document used to identify the customer. Check the Field Values table to see the accepted values.CPF
customer.document_numberStringDocument number used to identify the customer.12345678912
customer.billing_address.streetStringName of a street.Av. Brasil
customer.billing_address.numberStringNumber that identifies the position of a building on a street.1000
customer.billing_address.countryStringCountry code. Check the Field Values table to see the accepted values.BR
customer.billing_address.postal_codeStringPostal or ZIP code.90230060
Conditional fields (Uruguay only)
FieldTypeDescriptionExample
additional_dataObjectAdditional data for regional regulations and tax requirements. Required for Uruguay.---
additional_data.ratesArrayTax rates applied to the transaction.---
additional_data.rates.keyString(Uruguay only). Type of tax or rate being applied.IVA
additional_data.rates.valueNumber(Uruguay only). Tax amount in integer format (cents).123
additional_data.regional_regulation_codeString(Uruguay only). Regional fiscal or regulatory code required by local authorities. Used for SEP submissions in Uruguay.17934
Optional fields
FieldTypeDescriptionExample
configurationsObjectAdditional configurations for the payment intent.---
configurations.3dsBooleanControls 3D Secure authentication.true or false
configurations.preauthorizationBooleanIndicates if the payment is a pre-authorization.true or false
configurations.card_verificationBooleanIndicates if this is a card verification flow.true or false
configurations.success_urlStringRedirect URL in case of successful payment.https://www.mystore.com/checkout/success
configurations.error_urlStringRedirect URL in case of an error during payment.https://www.mystore.com/checkout/error
expires_atStringPayment intent expiration.3d4h15m
Field Values
FieldArgentinaBrazilColombiaChileEuropeMexicoUruguay
currencyARSBRLCOPCLPEURMXNUYU or USD
document_typeDNICPF, CNPJ or passportCC, PP, RC, DE, CE, TI, NIT, IDC or CELRUTDNI, INE or passportRFCuyci
countryARBRCOCLPT and ESMXUY
key------IVA

Field filling rules

The following rules apply to some of the fields above.

  • The expires_at field accepts a duration value (for example, 15m, 2h, 7d, or 1d12h30m). The API applies this duration regardless of the merchant's timezone. The expiration timestamp returned by the API is always formatted in GMT+0 (UTC). If you provide no value, the payment intent does not expire.
  • When you provide success_url and error_url in the payment intent request, they override the values configured in the seller's technical configuration.
  • Uruguay: You can create payment intents in either UYU (Uruguayan Peso) or USD. For payments in UYU, the additional_data object is required. It must include additional_data.rates.key with the IVA rate key and 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: Integrate the frontend

After you complete your backend integration, a successful payment intent creation returns two key properties: redirect_url and payment_intent_id. You need them to integrate Getnet’s Web Checkout into your frontend.

The property you use depends on the integration format you choose, implemented with JavaScript or React.

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

Import the Getnet loader

The loader initializes the secure Getnet Checkout application. Invoke it after you create a payment intent. The customer can then safely enter their payment details and proceed with the transaction.
To consume the APIs, use the following DNS values for host_getnet_web:

Then, add the following code:

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

Add the checkout script

The checkout script connects the loader and the user. It also lets you select the integration option that best fits your needs.

To do so, add the following code. Replace the paymentIntentId value with the payment_intent_id you received earlier. Set the checkoutType value to lightbox or iframe, depending on your selection:
<script> const config = { "paymentIntentId": ${payment_intent_id}, "checkoutType": "lightbox" }; const checkoutButton = () => { loader.init(config) }; </script>

Add the checkout button

The button runs the checkout script from the previous step. Add the following code to your HTML:

For JavaScript:
JSON
<button onclick="checkoutButton()"> Go to Payment </button>
If you use React, initialize the Getnet loader in this step:
JSON
useEffect(() => { ... window.loader.init(config); }, []);
The final code for React looks like this:
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 appears as the last element of the page by default. 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

A payment goes through the following steps.

  1. The payment process begins when the buyer clicks the designated payment button.
  2. The checkout screen displays the payment intent value and the available payment methods, based on your Merchant Portal or API configuration.
  3. For credit or debit card payments, the buyer enters their card details. If the card brand and type support installment payments, a transparent query is sent to Getnet's Installments API. This query retrieves the available installment options for this checkout.
  4. The installments offered are based on your agreements with Getnet and on your Merchant Portal or API configurations. In those configurations, you choose whether to offer installments with or without interest. You also set a limit on the number of installments.
  5. When the buyer clicks the button, the payment authorization process starts.

Payment authorization process in 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 end of this process, the Web Checkout client application receives a response indicating either Success or Failure:
  • Failure: If the payment is declined or an issue is detected during the process, the buyer sees an error message. A webhook or notification is also sent with the payment details and the transaction status.
  • Success: If the payment is authorized, the buyer sees a confirmation message. A webhook or notification is also sent with the authorization data and transaction status. At this stage, the payment_id is generated. You can use it for cancellation or refund operations. For details, see the Modifying Payments documentation.
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" }

On this page

Quickstart: Create a payment