Point-of-sale icon

Pré-autorização

Pré-autorize um pagamento, ajuste o valor autorizado e capture o pagamento.

Em um fluxo de pagamento básico, o valor a pagar da sua solicitação de pagamento é autorizado e capturado. Mas, às vezes, você pode alterar o valor ou estender a duração da autorização antes que o pagamento seja capturado. Você pode fazer isso usando pré-autorização. Nesse fluxo de pagamento, você pode aumentar ou diminuir o valor autorizado posteriormente e capturar o pagamento. Tais alterações em um pagamento pré-autorizado são chamadas de ajustes de autorização.

No momento, o ajuste de autorização está disponível para Discover, Mastercard e Visa. Em última análise, o suporte depende do emissor.

Casos de uso

Existem vários casos de uso para ajustar uma quantidade pré-autorizada:

  • Hospitalidade. Por exemplo, em um hotel

    1. No momento do check-in, o hotel pré-autoriza o pagamento do quarto que o hóspede reservou. Ao mesmo tempo, o hotel cria um token de reconhecimento do comprador, para poder aplicar cobranças em atraso quando necessário.
    2. Durante a estadia, o hóspede incorre em despesas nas instalações do hotel. O hotel adiciona essas despesas ao valor pré-autorizado, ajustando a autorização.
    3. No momento do check-out, o hotel captura o valor final ou cancela o pagamento se o hóspede preferir pagar a conta com uma forma de pagamento diferente.
    4. Se necessário, o hotel cobra do hóspede após a partida, usando o token de reconhecimento do comprador para um novo pagamento.
  • Gorjeta em regiões e indústrias em que é habitual que o hóspede adicione uma dica no recibo após a apresentação do cartão.

Ajuste assíncrono ou síncrono

Existem duas maneiras de implementar a pré-autorização:

  • Com o ajuste de autorização assíncrona, você se refere a um pagamento usando a referência PSP que você recebeu na resposta à sua solicitação de pré-autorização. Em cada solicitação de ajuste de autorização e na solicitação de captura final, você só precisa especificar esta primeira referência PSP.

    O ajuste assíncrono é mais fácil de implementar, mas não fica claro imediatamente se o ajuste foi bem-sucedido. Você precisa configurar as notificações do webhook para receber atualizações e saber se o valor final foi autorizado antes de capturar o pagamento.

  • Com o ajuste de autorização síncrona, você passa um blob adjustAuthorisationData de um ajuste de autorização para o próximo, para nos permitir acompanhar o valor mais recente. Você recebe o primeiro blob na resposta à sua solicitação de pré-autorização. Na sua primeira solicitação de ajuste de autorização, você especifica o blob recebido para a pré-autorização e recebe um novo blob na resposta. No seu próximo ajuste, você especifica o blob que você recebeu na resposta do ajuste anterior e assim por diante.

    O ajuste síncrono requer uma etapa adicional para implementar, porque você precisa acompanhar o blob mais recente. A vantagem é que você recebe o resultado do ajuste de forma síncrona. Dessa forma, você saberá imediatamente se o valor final foi autorizado antes de capturar o pagamento.

    Se, em algum momento, você não conseguir passar no blob, o fluxo retornará ao ajuste assíncrono e não será mais possível retornar ao ajuste síncrono para esse pagamento.

Antes de você começar

Antes de configurar e usar a pré-autorização, certifique-se de:

  • Ler e entender nossos fundamentos da API de terminais.
  • Criar uma integração capaz de efetuar um pagamento.
  • Configurar as notificações de webhook. Você precisará confiar nas notificações para saber se a captura foi bem-sucedida. Se você usar o ajuste de autorização assíncrono, também precisará confiar em notificações para o resultado do ajuste de autorização.

Lembre-se também de que você precisa implementar a lógica do seu lado, por exemplo, para decidir quando usar o fluxo de pré-autorização e calcular a quantia ao fazer um ajuste de autorização.

Etapa 1 (opcional): configure sua conta

Há dois aspectos da sua conta que você pode querer configurar para pré-autorização:

  • Ajuste de autorização síncrona: para receber os resultados do ajuste de autorização de forma síncrona, peça à nossa Support Team para ativar isso.

  • Tipo de autorização padrão: geralmente o tipo de autorização padrão é Final, o que significa que o pagamento é capturado automaticamente quando autorizado. Como esse é o padrão, você não precisa especificá-lo em seus pedidos de pagamento. No entanto, com a pré-autorização, você precisa especificar um tipo de autorização de PreAuth na sua solicitação de pagamento. Se você fizer apenas solicitações de pagamento com pré-autorização, poderá solicitar à nossa Support Team que defina seu tipo de autorização padrão como PreAuth para que você não precise especificá-lo nas solicitações de pagamento.

    Se você deseja fazer solicitações de pagamento com pré-autorização e solicitações de pagamento normais, recomendamos que você especifique o tipo de autorização em todas as solicitações de pagamento.

Etapa 2: pré-autorizar um pagamento

Para iniciar o fluxo de pagamento de pré-autorização, faça um PaymentRequest com um tipo de autorização de PreAuth:

  1. Faça uma solicitação POST para um endpoint da API de terminais, especificando:

    • MessageHeader: Segue a estrutura MessageHeader padrão, explicada nos fundamentos da API de terminais, que incluem:

      • ProtocolVersion: 3.0
      • MessageClass: Service
      • MessageCategory: Payment.
      • MessageType: Request
      • SaleID: Seu ID exclusivo para a caixa registradora.
      • ServiceID: Seu ID exclusivo para esta tentativa de transação, consistindo em 1 a 10 caracteres alfanuméricos. Esse valor precisa ser exclusivo nas últimas 48 horas.
      • POIID: : ID exclusivo do terminal. Isso indica para qual terminal o pagamento será roteado.
    • PaymentRequest: O corpo da solicitação da solicitação de pré-autorização deve incluir:

      • SaleData.SaleTransactionID.TransactionID: Sua referência exclusiva para esta solicitação de pagamento.
      • SaleData.SaleTransactionID.TimeStamp: Data e hora da solicitação de pagamento, no formato UTC.
      • SaleData.SaleToAcquirerData:
        • authorisationType=PreAuth: indica que esta é uma solicitação de pré-autorização.
        • Quaisquer outros pares de valores-chave que você deseja passar, por exemplo, para fins de reconhecimento de clientes purposes.
      • PaymentTransaction.AmountsReq.Currency: A moeda da transação.
      • PaymentTransaction.AmountsReq.RequestedAmount: O valor da transação.

    O exemplo a seguir mostra como você iniciaria a pré-autorização para um pagamento de EUR 150,00.

    Para obter mais informações sobre a estrutura de solicitação da API de terminais, consulte os fundamentos da API de terminais.

    O cliente apresenta seu cartão no terminal de pagamento. O terminal coleta os detalhes do pagamento e envia a solicitação do valor original à plataforma de pagamentos da Adyen para processamento

    Se a pré-autorização for bem sucedida:

    • Approved é exibido no visor do terminal.
    • O resultado do pagamento contém:

      • POIData.POITransactionID.TransactionID: Identificador de transação para o pagamento, no formato Tender_reference.PSP_reference.

      • PaymentResult: Payment method data including:

        • AmountsResp: O AuthorizedAmount e Currency do pagamento pré-autorizado.

      • Response.Result: Success

      • Response.AdditionalResponse: Uma sequência base64. Quando decodificado, este é um objeto JSON com dados de transação adicionais. Isso inclui:

        • posadditionalamounts.originalAmountValue: OMontante original em unidades menores.
        • authorisedAmountValue: Quantidade autorizada em unidades menores, que nesta fase é igual à quantidade original.
        • pspReference: A referência PSP da sua solicitação de pré-autorização.
        • adjustAuthorisationData: Um blob codificado em URL.

    O exemplo a seguir mostra a resposta a uma solicitação de autorização de EUR 150,00.

  2. Armazene o arquivo pspReference da AdditionalResponse para uso posterior ao ajustar a autorização ou ao capturar o pagamento.

  3. Se você estiver usando o ajuste de autorização síncrona, decodifique o URL blob adjustAuthorisationData e o armazene.

Etapa 3 (opcional): ajuste a pré-autorização

Para modificar o valor pré-autorizado, faça uma solicitação de ajuste de autorização.

  1. Faça uma solicitação POST para o endpoint do /payments/{paymentPspReference}/amountUpdates, especificando:

    • paymentPspReference: O pspReference da solicitação de pré-autorização. Você recebeu isso na resposta à sua solicitação de pré-autorização
    • amount: A currency e value da nova quantia em minor units. Esta é a soma do valor pré-autorizado e do valor adicional. Se este não for o primeiro ajuste de autorização, é a soma do valor pré-autorizado mais todos os valores adicionais.
    • reference: Sua referência a esta modificação de pagamento para uso em seu processo de reconciliação.
    • reason: DelayedCharge
    • merchantAccount: O nome da sua merchant account usada para processar o pagamento.

    O exemplo a seguir mostra como você adicionaria uma cobrança de EUR 64,15 a um valor pré-autorizado de EUR 150,00.

    A resposta /adjustAuthorisation contém:

    • pspReference: TA referência do PSP associada a solicitação /adjustAuthorisation. Observe que esta é diferente da referência do PSP associada à solicitação de pré-autorização
    • status: received
  2. Aguarde a notificação assíncrona. Isso informa se o novo valor foi autorizado.

Etapa 4: finalize o pagamento pré-autorizado

Quando você fiezer seu último ajuste de autorização, precisará capturar manualmente o pagamento para garantir que os fundos reservados sejam transferidos para sua conta:

Sempre verifique se você concluiu todos os ajustes de autorização para o pagamento antes de capturá-lo. As capturas são feitas de forma assíncrona, portanto, pode parecer que o pagamento ainda não foi capturado e ainda é possível ajustar a autorização

    1. Decida se você está pronto para capturar o pagamento:
    • Existem cobranças adicionais a serem feitas?
      Se sim, ajuste a autorização primeiro (consulte a Etapa 3).

    • O cliente deseja liquidar a fatura usando um método de pagamento diferente daquele usado para a pré-autorização?
      Se sim, não capture o pagamento. Em vez disso, cancele a pré-autorização:

  1. Quando você estiver pronto para capturar o pagamento, faça uma solicitação POST para o endpoint do /payments/{paymentPspReference}/captures , especificando:

    • paymentPspReference: A pspReference da pré-autorização original. Você recebeu isso na resposta à sua solicitação de pré-autorização
    • amount: A currency e value do valor final em minor units. Essa é a soma do valor original pré-autorizado e de todos os ajustes posteriores.
    • reference: Sua referência a esta modificação de pagamento para uso em seu processo de reconciliação.
    • merchantAccount: O nome da sua conta de comerciante usada para processar o pagamento.
  2. Ao receber a resposta da captura, observe o seguinte:

    • pspReference: A referência PSP associada a esta solicitação de captura. Observe que esta é diferente da referência PSP associada à solicitação de pré-autorização.
    • status: received.
    • reference: Sua referência a esta modificação de pagamento para uso em seu processo de reconciliação.
    1. Aguarde a notificação assíncrona. Isso informa se o valor final foi capturado.
      Se a captura for bem sucedida, esta notificação conterá:
      • eventCode: CAPTURE
      • originalReference: O pspReference da pré-autorização.
      • pspReference: A referência do PSP associada a esta solicitação de captura.
      • success: true

    Se success for false, então sua solicitação de captura falhou. Revise o reason que você recebeu na notificação, corrija o problema e envie a solicitação de captura novamente.

Se você precisar cobrar do hóspede uma quantia adicional após a partida e tiver criado um token de reconhecimento de cliente com sua solicitação de pré-autorização, poderá aplicar essas cobranças em atraso em uma solicitação de pagamento normal usando o token. Consulte Reconhecimento do cliente.

Veja também