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.

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

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

information icon
Important: All contracted products will be shown on this screen and the credential generation is going to be 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. 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.
information icon
Info: If you lose the keys, repeat the step-by-step to generate a new one.

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 document and follow the steps.
information icon
Info: There are other request that can be done to retrive an access token, check the Authentication document to know more about this requests.

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

AttributeTypeDescriptionExample
paymentObjectPayment data.---
payment.currencyStringCurrency code.BRL
payment.amountIntegerPurchase amount in integer format, where the last 2 digits represent the cents.92500
customer.document_typeStringType of the document used to identify the customer.CPF
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
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.sucess_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
information icon
Field filling rules:
  • The epires_atfield accepts values with minimum 15 minutes and maximum 31 days. The field can be filled in with "15m", "2h", "7d" or "1d12h30m" and 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.
  • Spain only the value on the document_type field, must be dni or passport.
  • 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.
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) WebCheckout, 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:

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.

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