# Pré-autorização: criar e capturar

Este guia mostra como criar uma pré-autorização (reservar fundos no cartão) e depois capturar esse valor em uma segunda etapa. O comportamento é o mesmo nas conexões USB e Rede. O guia também cobre a recuperação de pré-autorizações pendentes. As operações Modify e Remove seguem a mesma estrutura de requisição do Confirm, alterando somente o valor de `Operation`.

## O que é pré-autorização

A pré-autorização reserva fundos no cartão do cliente sem capturá-los. Você envia uma requisição **Create**; o POS retorna um código de autorização e os dados da reserva. Depois, você confirma a pré-autorização com esses dados para capturar o valor. Esse fluxo de duas etapas é útil quando o valor final ou o momento da captura não é conhecido no instante da autorização.

## Antes de começar

Antes de iniciar:

* Um Connector deve ser criado e validado com `Polling`
* O Modo POS Integrado deve estar ativo
* O terminal e a bandeira do cartão devem suportar pré-autorização

## Passo 1: Criar a pré-autorização

Crie a pré-autorização chamando a operação Pre-authorization com **Operation** = **Create**. Envie o valor e, opcionalmente, as parcelas ou o plano. O POS executa o fluxo do cartão e retorna os dados necessários para o Passo 2.

| Parâmetro | Tipo | Obrigatório | Descrição |
| :--- | :--- | :--- | :--- |
| `Operation` | Enum | Sim | Defina como `Create`. |
| `Amount` | Long | Não | Valor na moeda local, com os dois últimos dígitos como decimais (máx. 9 dígitos). Se omitido, o POS solicita o valor. |
| `PlanId` | String | Não | Plano de parcelamento (por exemplo, Argentina). Consulte [Planos de Parcelamento e Plan Ids](/pt/integrated-pos/reference/installment-plans). |
| `Installments` | Int | Não | Número de parcelas. |
| `SkipReceipt` | Bool | Não | Se `true`, o recibo do cliente não é impresso. |
| `SkipConfirmation` | Bool | Não | Se `true`, ignora a tela de confirmação. |
| `PrintOnPos` | Boolean | Não | Se `true`, o recibo é impresso no POS; se `false`, os dados são retornados na resposta. |
| `CallerId` | String | Não | Id gerado pelo sistema de automação, necessário para consultar depois uma transação `Create` com o Check Status. Não use caracteres especiais nem Unicode. |

Este exemplo cria uma pré-autorização de 500,00:

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

var createResult = connector.PreAuthAsync(createRequest);
```

O POS executa o fluxo do cartão (inserir, aproximar, etc.). Quando a requisição é bem-sucedida, a resposta contém os dados necessários para a captura posterior.

<Callout type="note">

`ReservationCode` (chamado `reservationId` no SDK) é opcional, mas **deve ser único** quando você o envia. O sistema de automação é responsável por garantir essa unicidade.

</Callout>

Quando a pré-autorização é criada com sucesso, o POS retorna uma resposta estruturada com todos os detalhes da transação. Veja abaixo um exemplo de objeto de resposta completo:

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

Essa resposta traz um conjunto abrangente de campos que descrevem o estado e a origem da reserva. A tabela a seguir detalha os campos mais relevantes retornados nesta fase:

| Campo | Tipo | Descrição |
| :--- | :--- | :--- |
| `Code` | int | Código de resposta; `0` indica sucesso. |
| `Message` | String | Mensagem descritiva do resultado. |
| `AuthorizationCode` | String | Código de autorização único da transação. |
| `ReservationId` | String | Identificador atribuído à reserva. |
| `Amount` | long | Valor autorizado na moeda local. |
| `OriginalAmount` | long | Valor original antes de ajustes. |
| `AccountingDate` | Date | Data e hora da transação (GMT). |
| `RealDate` | Date | Data e hora da transação (local). |
| `CommerceCode` | String | Código único da filial. |
| `TerminalId` | String | Identificador do terminal POS. |
| `CardBin` | String | Oito primeiros dígitos do cartão do cliente (máx. 8). |
| `CallerId` | String | Id gerado pelo sistema de automação. |

Para capturar os fundos com sucesso na próxima etapa, você precisa armazenar valores específicos dessa resposta. Esses campos são obrigatórios para identificar a transação na fase de confirmação:

* **`AuthorizationCode`**: Usado para identificar a reserva aprovada.
* **`AccountingDate`**: Usado como o parâmetro `OriginalTransactionDate`.
* **`ReservationId`**: Usado como `ReservationCode` (opcional, mas recomendado se disponível).

Depois de armazenar esses valores, você pode seguir para o passo de confirmação.

## Passo 2: Capturar a pré-autorização (confirm)

Para capturar o valor reservado, chame a operação Pre-authorization novamente com **Operation** = **Confirm**, informando o **AuthorizationCode** e a **OriginalTransactionDate** (e, opcionalmente, o **ReservationCode**) da resposta do Create.

| Parâmetro | Tipo | Obrigatório | Descrição |
| :--- | :--- | :--- | :--- |
| `Operation` | Enum | Sim | Defina como `Confirm`. |
| `AuthorizationCode` | String (6) | Sim | Da resposta do Create. |
| `OriginalTransactionDate` | Date | Sim | Da resposta do Create. |
| `ReservationCode` | String (5) | Não | Do campo `ReservationCode` da resposta do Create, se disponível. |
| `Amount` | Long | Não | Valor final a capturar, se for diferente do valor autorizado. |
| `PlanId` | String | Não | Plano de parcelamento a aplicar na captura. |
| `Installments` | Int | Não | Número de parcelas a aplicar na captura. |
| `SkipReceipt` | Bool | Não | Se `true`, o recibo do cliente não é impresso. |
| `SkipConfirmation` | Bool | Não | Se `true`, ignora a tela que pede ao portador do cartão para confirmar o valor atualizado. |
| `PrintOnPos` | Boolean | Não | Se `true`, o recibo é impresso no POS. |

Veja um exemplo de como capturar a pré-autorização:

```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);
```

A resposta inclui **Code**, **Message**, **AuthorizationCode** e, opcionalmente, **Amount**, **CommerceCode**, **TerminalId**, **ReceiptContent**, entre outros. Verifique o **Code** para confirmar o sucesso. Os retornos são padronizados para todas as operações de pré-autorização.

## Recuperar pré-autorizações pendentes

Para listar as pré-autorizações pendentes, chame a operação Pre-authorization com **Operation** = **Retrieve**. O POS retorna até 30 das pré-autorizações pendentes mais recentes. Na resposta, somente os campos `RealDate` e `PendingPreAuthorizations` são preenchidos.

O objeto `Filters` é **obrigatório na operação Retrieve**. Os campos de filtro listados abaixo são opcionais e restringem os resultados:

| Filtro | Tipo | Descrição |
| :--- | :--- | :--- |
| `InitialDate` | Date | Início do intervalo de datas, no formato ISO8601 com fuso horário (padrão: data atual). Não pode ser posterior à data atual nem posterior a `FinalDate`. |
| `FinalDate` | Date | Fim do intervalo de datas, no formato ISO8601 com fuso horário (padrão: data atual). Não pode ser posterior à data atual nem anterior a `InitialDate`. |
| `AuthorizationCode` | String | Filtra pelo código de autorização (6 dígitos). |
| `ReservationCode` | String | Filtra pelo código de reserva (máx. 5 caracteres). |
| `Last4CardDigits` | String | Filtra pelos últimos quatro dígitos do cartão. |
| `CardBrand` | Int | Filtra pela bandeira: `0` = ALL (padrão), `1` = Visa, `2` = MasterCard, `3` = Amex. |

Este exemplo recupera as pré-autorizações pendentes criadas em um intervalo de datas, para qualquer bandeira:

```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);
```

Cada item da lista `PendingPreAuthorizations` inclui `AuthorizationCode`, `TransactionDate`, `Amount`, `Last4Digits`, `EntryMode`, `CommerceCode`, `TerminalId`, `DateLimit` (expiração), `ReceiptCode` e `ReservationId`. Use esses valores para identificar uma pré-autorização em um Confirm, Modify ou Remove posterior. Para a lista completa de campos, consulte [Métodos e Parâmetros](/pt/integrated-pos/reference/methods-parameters).

## Próximos passos

* Para o processamento de pagamentos padrão, sem retenção de autorização, consulte o guia [Pagamento em Passo Único](/pt/integrated-pos/pos-payment-guides/single-step-payment).
* Para reverter ou cancelar transações concluídas, consulte o guia [Reembolso](/pt/integrated-pos/pos-payment-guides/refund-payment).