Processar Pré-autorizações e Confirmações

O fluxo de Pré-autorização permite que você reserve fundos no cartão de um cliente (Reserva) e os capture posteriormente (Confirmar). Isso é diferente de uma “Venda” (Sale) padrão, onde os fundos são capturados imediatamente.

Este processo envolve duas operações distintas da API:

1. Pré-autorização (/preautorizacion): O terminal verifica o cartão e reserva os fundos.
2. Confirmação (/confirmacion): Você captura explicitamente os fundos (total ou parcialmente) para concluir a transação.

Fase 1: Criar a Pré-autorização

O primeiro passo é iniciar a reserva. Isso se parece muito com uma requisição de pagamento padrão, mas utiliza um endpoint diferente.

• Endpoint: /preautorizacion
• Método: POST

Passo 1.1: Enviar a Requisição

Envie o valor que você deseja reservar. Você deve fornecer uma factura (ID da Fatura) única, que servirá como referência para a futura confirmação.

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timestamp": "20250428 120000",
    "notificacion": {
      "urlNotificacion": "https://your-server.com/api/webhooks/preauth",
      "correoNotificacion": "[email protected]"
    },
    "datosOperacion": {
      "importe": "100.00",
      "factura": "RES-Hotel-001"
    }
  },
  "signature": "YOUR_CALCULATED_SIGNATURE"
}

Passo 1.2: Receber a Notificação

Assim como em um pagamento padrão, a interação com o terminal físico é assíncrona. Você receberá uma notificação na sua urlNotificacion.

• tipoPago: Será PREAUTORIZACION.
• resultado: Procure por Autorizada.
• Ação: Não considere o dinheiro recebido. Considere os fundos apenas como “reservados” (reserved/held).

Fase 2: Confirmar a Transação

Quando você estiver pronto para cobrar o cliente (ex.: check-out de hóspede, devolução de carro alugado), você deve enviar uma requisição de confirmação.

Referências Correspondentes: A factura (ID da Fatura) usada na confirmação deve corresponder à factura usada na pré-autorização original. É assim que o sistema vincula a captura à reserva.

• Endpoint: /confirmacion
• Método: POST

Passo 2.1: Enviar Requisição de Confirmação

Você especifica o valor a ser capturado.

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timestamp": "20250429 080000",
    "datosOperacion": {
      "importe": "100.00",
      "factura": "RES-Hotel-001"
    }
  },
  "signature": "YOUR_CALCULATED_SIGNATURE"
}

Passo 2.2: Tratar a Resposta

Diferente da interação inicial, a Confirmação geralmente é processada de servidor para servidor (server-to-server) sem a necessidade de o portador do cartão inserir novamente seu cartão.

Você receberá uma notificação confirmando a captura:

• tipoPago: Será CONFIRMACION.
• resultado: Autorizada.

Considerações Importantes

• Limites de Tempo: As pré-autorizações normalmente possuem um período de validade (ex.: 7 a 30 dias, dependendo da bandeira do cartão). Se você não confirmar dentro desta janela, a reserva pode expirar.
• Tratamento de Erros: Se você tentar confirmar uma operação que não existe ou que já foi confirmada, poderá receber códigos de erro específicos.
  • TPVPC0094: “No es posible realizar más confirmaciones sobre la preautorización original” (Não é possível realizar mais confirmações sobre a pré-autorização original).

Próximos Passos

• Estornar um Pagamento: Aprenda como devolver fundos se uma confirmação for feita por engano.
• Consultar Histórico de Transações: Verifique o status das suas pré-autorizações se não tiver certeza de que foram confirmadas.