Create a Pre-authorized Card Payment

Process a complete two-step payment transaction by first authorizing it to reserve funds, and then capturing it to finalize the charge. This guide walks you through every step of using the Getnet Regional API for this common e-commerce flow.

Requirements

Before following the steps, you need to:

• Create your account by contacting the Integration Support team to get your API credentials client_id and client_secret.
• Generate your token with your credentials using the Authentication endpoint.

Getnet provides a Postman Collection to help you to replicate these use cases locally. You can also test the API in sandbox using the API Reference available in the documentation.

Use Cases Specifics

When integrating any Getnet solution, market-specific requirements apply. Be sure to review the resources below before you go live:

• Currency codes
• Document types
• Local taxes and regulations

You can also use test cards to simulate specific scenarios. More information about specific requirements for each country can be found in the Developer Resources section of the Getnet documentation.

Two-Step Payment Process

To help visualize the two-step payment process, the following sequence diagram illustrates the interactions between your system and the Getnet Regional API. It covers the initial authorization, the subsequent capture, and the two methods for verifying the final status.

Getnet also supports creating and capturing payments in one step. For more details, see the Create Single-Step Payments guide.

Tokenize Card Data (Optional)

Instead of sending the raw card number in your payment request, you can use tokenization to enhance security and reduce PCI DSS compliance scope. To use a tokenized card:

1. Tokenize the card by calling the Card Tokenization endpoint with the card_number and customer_id.
2. In your payment request, replace the card.number field with card.number_token using the token value received from the tokenization endpoint.

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.

The antifraud payload must also include the following fields:

Antifraud data is mandatory for production environments. Transactions missing device fingerprint or customer information will be automatically blocked by antifraud teams to prevent fraud. See the Antifraud documentation for complete implementation details.

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

curl --request POST \
  --url https://api-sbx.pre.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": "john.doe@example.com",
      "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_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": "13c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "order_id": "123order2",
  "amount": 118708,
  "currency": "CLP",
  "status": "AUTHORIZED",
  "payment_method": "CREDIT_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.

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

curl --request POST \
  --url https://api-sbx.pre.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": "13c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "order_id": "123order2",
  "amount": 118708,
  "currency": "CLP",
  "status": "CAPTURED",
  "reason_code": "00",
  "reason_message": "captured",
  "captured_at": "2025-08-12T20:47:52.166Z"
}

Step 3: Check the Payment Status (Optional)

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.

Next Steps

Now that you have successfully created a two-step payment, you can explore more features of the Getnet Regional API:

• Create a Single-Step Payment.
• Learn more about 3DS Payments.