Pre-Authorization: Create and Capture

This guide walks through creating a pre-authorization (reserve funds on the card) and then capturing that amount in a second step. Behaviour is the same across USB and Network connections. It also covers retrieving pending pre-authorizations. The Modify and Remove operations follow the same request structure as Confirm, changing only the Operation value.

What is pre-authorization

Pre-authorization reserves funds on the customer’s card without capturing them. You send a Create request; the POS returns an authorization code and reservation data. You then confirm the pre-authorization with that data to capture the amount. This two-step flow is useful when the final amount or capture time is not known at the moment of authorization.

Before you begin

Before starting:

• A Connector must be created and validated using Polling
• Integrated POS Mode must be active
• The terminal and card brand must support pre-authorization

Step 1: Create the pre-authorization

Create the pre-authorization by calling the Pre-authorization operation with Operation = Create. Send the amount and, optionally, installments or plan. The POS will run the card flow and return data you need for Step 2.

This example creates a pre-authorization for 500.00:

var createRequest = new PreAuthRequest
{
    Operation = PreAuthOperation.Create,
    Amount = 50000
};

var createResult = connector.PreAuthAsync(createRequest);

The POS runs the card flow (insert/tap, etc.). When the request succeeds, the response contains the data needed to capture later.

When the pre-authorization is successfully created, the POS returns a structured response containing all transaction details. Below is an example of a complete response object:

{
  "Code": 0,
  "Message": "APPROVED",
  "AuthorizationCode": "551437",
  "Amount": 50000,
  "OriginalAmount": 50000,
  "Last4Digits": "1234",
  "CardBrand": "Mastercard",
  "CardType": "Credit",
  "AccountingDate": "2025-08-25T16:11:23.0000000Z",
  "RealDate": "2025-08-25T13:11:50.8570000-03:00",
  "ReservationId": "RES-001",
  "CommerceCode": "1234567890",
  "TerminalId": "GET00123",
  "CardBin": "84168075",
  "CallerId": "123456-789000"
}

This response provides a comprehensive set of fields that describe the state and origin of the reservation. The following table details the most relevant fields returned in this phase:

To successfully capture the funds in the next step, you must store specific values from this response. These fields are required to identify the transaction during the confirmation phase:

• AuthorizationCode: Used to identify the approved reserve.
• AccountingDate: Used as the OriginalTransactionDate parameter.
• ReservationId: Used as ReservationCode (optional but recommended if available).

After storing these values, you can proceed to the confirmation step.

Step 2: Capture the pre-authorization (confirm)

To capture the reserved amount, call the Pre-authorization operation again with Operation = Confirm, passing the AuthorizationCode and OriginalTransactionDate (and optionally ReservationCode) from the Create response.

Here is an example of how to capture the pre-authorization:

// Using data from the Create response
var confirmRequest = new PreAuthRequest
{
    Operation = PreAuthOperation.Confirm,
    AuthorizationCode = createResponse.AuthorizationCode,  // e.g. "551437"
    OriginalTransactionDate = createResponse.AccountingDate,
    ReservationCode = createResponse.ReservationId  // optional
};

var confirmResult = connector.PreAuthAsync(confirmRequest);

The response includes Code, Message, AuthorizationCode, and optionally Amount, CommerceCode, TerminalId, ReceiptContent, etc. Check Code for success. Returns are standardized for all pre-authorization operations.

Retrieve pending pre-authorizations

To list pending pre-authorizations, call the Pre-authorization operation with Operation = Retrieve. The POS returns up to 30 of the most recent pending pre-authorizations. Only the RealDate and PendingPreAuthorizations fields are populated in the response.

The Filters object is required for the Retrieve operation; its individual filter fields below are optional and narrow the results:

This example retrieves pending pre-authorizations created in a date range for any brand:

var retrieveRequest = new PreAuthRequest
{
    Operation = PreAuthOperation.Retrieve,
    Filters = new PreAuthFilters
    {
        InitialDate = new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero),
        FinalDate = new DateTimeOffset(2026, 1, 2, 0, 0, 0, TimeSpan.Zero),
        CardBrand = 0
    }
};

var retrieveResult = connector.PreAuthAsync(retrieveRequest);

Each item in the PendingPreAuthorizations list includes AuthorizationCode, TransactionDate, Amount, Last4Digits, EntryMode, CommerceCode, TerminalId, DateLimit (expiration), ReceiptCode, and ReservationId. Use these values to identify a pre-authorization for a later Confirm, Modify, or Remove. For the full field list, see Methods and Parameters.

Next steps

• For standard payment processing without authorization holds, see the Single-Step Payment guide.
• To reverse or cancel completed transactions, refer to the Refund guide.