# 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.

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `Operation` | Enum | Yes | Set to `Create`. |
| `Amount` | Long | No | Value in local currency, last two digits as decimals (max 9 digits). If omitted, the POS asks for it. |
| `PlanId` | String | No | Installment plan (e.g. Argentina). See [Installment Plans and Plan Ids](/en/integrated-pos/reference/installment-plans). |
| `Installments` | Int | No | Number of installments. |
| `SkipReceipt` | Bool | No | If `true`, client receipt is not printed. |
| `SkipConfirmation` | Bool | No | If `true`, skips the confirmation screen. |
| `PrintOnPos` | Boolean | No | If `true`, receipt is printed on the POS; if `false`, data is returned in the response. |
| `CallerId` | String | No | ID generated by the automation system, required to later query a `Create` transaction with Check Status. No special or Unicode characters. |

This example creates a pre-authorization for 500.00:

```csharp
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.

<Callout type="note">

`ReservationCode` (named `reservationId` in the SDK) is optional, but it **must be unique** when you send it. The automation system is responsible for ensuring uniqueness.

</Callout>

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:

```json
{
  "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:

| Field | Type | Description |
| :--- | :--- | :--- |
| `Code` | int | Response code; `0` indicates success. |
| `Message` | String | Descriptive result message. |
| `AuthorizationCode` | String | Unique transaction authorization code. |
| `ReservationId` | String | Identifier assigned to the reserve. |
| `Amount` | long | The authorized amount in local currency. |
| `OriginalAmount` | long | The original amount before adjustments. |
| `AccountingDate` | Date | Transaction date and time (GMT). |
| `RealDate` | Date | Transaction date and time (Local). |
| `CommerceCode` | String | Unique branch code. |
| `TerminalId` | String | Identifier of the POS terminal. |
| `CardBin` | String | First eight digits of the customer's card (max 8). |
| `CallerId` | String | ID generated by the automation system. |

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.

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `Operation` | Enum | Yes | Set to `Confirm`. |
| `AuthorizationCode` | String (6) | Yes | From the Create response. |
| `OriginalTransactionDate` | Date | Yes | From the Create response. |
| `ReservationCode` | String (5) | No | From the Create response `ReservationCode`, if available. |
| `Amount` | Long | No | Final amount to capture, if different from the authorized amount. |
| `PlanId` | String | No | Installment plan to apply at capture. |
| `Installments` | Int | No | Number of installments to apply at capture. |
| `SkipReceipt` | Bool | No | If `true`, client receipt is not printed. |
| `SkipConfirmation` | Bool | No | If `true`, skips the screen asking the cardholder to confirm the updated amount. |
| `PrintOnPos` | Boolean | No | If `true`, receipt is printed on the POS. |

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

```csharp
// 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:

| Filter | Type | Description |
| :--- | :--- | :--- |
| `InitialDate` | Date | Start of the date range, in ISO8601 format with time zone (default: current date). Cannot be after the current date or after `FinalDate`. |
| `FinalDate` | Date | End of the date range, in ISO8601 format with time zone (default: current date). Cannot be after the current date or before `InitialDate`. |
| `AuthorizationCode` | String | Filter by authorization code (6 digits). |
| `ReservationCode` | String | Filter by reservation code (max 5 characters). |
| `Last4CardDigits` | String | Filter by the last four digits of the card. |
| `CardBrand` | Int | Filter by brand: `0` = ALL (default), `1` = Visa, `2` = MasterCard, `3` = Amex. |

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

```csharp
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](/en/integrated-pos/reference/methods-parameters).

## Next steps

* For standard payment processing without authorization holds, see the [Single-Step Payment](/en/integrated-pos/pos-payment-guides/single-step-payment) guide.
* To reverse or cancel completed transactions, refer to the [Refund](/en/integrated-pos/pos-payment-guides/refund-payment) guide.