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

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.

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.

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:

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

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

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.

Próximos passos

Para o processamento de pagamentos padrão, sem retenção de autorização, consulte o guia Pagamento em Passo Único.
Para reverter ou cancelar transações concluídas, consulte o guia Reembolso.