Create a Pre-authorized Payment

This document applies to the following countries:

In Getnet’s Web Checkout, pre-authorization allows the merchant to temporarily reserve an amount on the customer’s credit card during the payment process. The transaction remains pending until the merchant confirms (captures) the payment, at which point the amount is effectively charged. This mechanism is useful in scenarios where the final purchase amount may vary or needs to be confirmed later.

To understand the rules for each country check the Pre-authorization and Availability document.

How it works

Use pre-authorization when you want to reserve an amount on the customer’s credit card during the payment process and confirm (capture) it later — useful when the final purchase amount may vary or needs to be confirmed at a later point. Key characteristics:

• Two-step flow: the transaction is split into an authorization that reserves the funds and a capture that charges them. The amount is not captured immediately.
• Same Checkout page: the buyer experience is identical to the standard payment flow; only the capture timing differs.
• Reserve, then charge: authorization validates the customer’s card details and places a hold on the funds with the card issuer, but does not transfer them yet.
• Adjustable capture: at capture, the amount can be equal to or lower than the authorized amount.
• Linked by payment_id: the payment_id returned by the authorization identifies the transaction in every later step. It is retrieved via webhook after the payment is authorized.

The end-to-end flow involves the buyer, the Checkout page, and the Getnet WebCheckout / Regional API:

Before you start

Before following the steps, you need to:

• Configuring your Web Chekout by Portal or by API (depending on your location).
• Generate your token following the Authentication document.

Payment intent with pre-authorization

The Checkout page is the same as the standard payment flow, however, the amount is not captured immediately, as the transaction is performed as a pre-authorization.

To complete the charge, the Merchant must retrieve the payment_id sent via webhook, after authorize the payment, and use the capture and pre-authorization adjustment endpoints of the Regional API to capture or modify the previously authorized amount.

To pass through the Pre-Authorization, these parameters must be send on the payment intent.

Required fields

The following code block shows the fields that must be send in the payment intent endpoint.

"configurations": {
        "preauthorization": true,
        "card_verification": false,
        "3ds": false
    }

Argentina: card_verification and preauthorization are not available for Argentina.

Step 1: Authorize the Payment

A two-step payment starts with authorization. This step validates the customer’s payment details and places a hold on the funds with the card issuer, but it does not transfer them yet. Use the Create - Authorize endpoint to initiate the transaction.

Some countries and card schemes impose specific pre-authorization limits, adjustment rules, and capture windows. Review the pre-authorization reference for country-by-country requirements.

For the two-step process, you must set the data.payment.payment_method attribute in your request to CREDIT_PRE_AUTHORIZATION. This ensures the funds are only reserved and not immediately captured. The table below lists the minimum fields you need to send:

At the end of a successful authorization, you will receive a payment_id, which is used to identify this transaction in the next step.

The following code block shows an example of a request and response to authorize a payment:

Example of request:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "order123",
  "data": {
    "amount": 118708,
    "currency": "BRL",
    "customer_id": "test",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "12345678900",
      "phone_number": "+5511999999999",
      "billing_address": {
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Apto 101",
        "district": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "postal_code": "01310-100"
      }
    },
    "payment": {
      "payment_method": "CREDIT_PRE_AUTHORIZATION",
      "save_card_data": false,
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "LOJA*TESTE*COMPRA-123",
      "dynamic_mcc": 1799,
      "card": {
        "number": "5155901222260000",
        "expiration_month": "05",
        "expiration_year": "25",
        "cardholder_name": "CARD HOLDER",
        "security_code": "282"
      }
    },
    "additional_data": {
      "device": {
        "ip_address": "192.168.1.1",
        "device_id": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
        "finger_print": "1a2b3c4d5e6f7g8h9i0j"
      }
    }
  }
}'

Example of response

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "order_id": "order123",
  "amount": 118708,
  "currency": "BRL",
  "status": "AUTHORIZED",
  "payment_method": "CREDIT_PRE_AUTHORIZATION",
  "received_at": "2025-08-12T20:46:26.713Z",
  "transaction_id": "MCC30105G5020",
  "original_transaction_id": "MCC30105G5020",
  "authorized_at": "2025-08-12T20:46:26.713Z",
  "reason_code": "00",
  "reason_message": "authorized",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA-123",
  "brand": "MASTERCARD",
  "authorization_code": "604020",
  "acquirer_transaction_id": "204050301040206020503010"
}

Getnet provides a list of test cards that can be used in the Stage environment to simulate various transaction scenarios.

Step 2: Capture the Payment

After a successful authorization, you must capture the funds to finalize the transaction. Use the Capture endpoint to transfer the previously authorized funds to your account.

When calling the capture endpoint, you must provide the payment_id from the authorization step and the idempotency_key. If you send the amount, it must be equal to or lower than the authorized amount.

To confirm the capture was successful, verify that the API response returns an HTTP 200 OK status and that the status field in the response body is CAPTURED.

The following code block shows an example of a request and response to capture a payment:

Example of request:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/capture \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --data '{
  "idempotency_key": "11c7f8ee-51a6-470d-bb76-ef762b62bfb1",
  "payment_id": "a36887d0-53ec-4c36-b731-9bbeca18fcd2"
}'

Example of response

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "idempotency_key": "11c7f8ee-51a6-470d-bb76-ef762b62bfb1",
  "order_id": "order123",
  "amount": 118708,
  "currency": "BRL",
  "status": "CAPTURED",
  "reason_code": "00",
  "reason_message": "captured",
  "captured_at": "2025-08-12T20:47:52.166Z"
}

Step 3: Check the Payment Status (Optional)

The initial authorization response will show the status as AUTHORIZED. After you complete the capture step, this status will change to CAPTURED.

Because some payments are processed asynchronously, the status can change over time. To get the latest status of a transaction, use the Get Transaction endpoint.

For real-time updates without polling, it is recommended to use Webhooks to receive notifications for every status change.

See also

You can explore more payments of the Getnet Web Checkout API:

• Learn how to create a payment with card verification.
• Learn how to create a payment with 3DS.