Pré-autorização

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.

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.

   Pedido de pré-autorização

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
     "SaleToPOIRequest":{
       "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "MessageType":"Request",
         "SaleID":"POSSystemID12345",
         "ServiceID":"0207111104",
         "POIID":"P400Plus-275688710"
       },
       "PaymentRequest":{
         "SaleData":{
           "SaleTransactionID":{
             "TransactionID":"27908",
             "TimeStamp":"2019-03-07T10:11:04+00:00"
           },
           "SaleToAcquirerData":"authorisationType=PreAuth"
         },
         "PaymentTransaction":{
           "AmountsReq":{
             "Currency":"EUR",
             "RequestedAmount":150.00
           }
         }
       }
     }
   }

   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.

   Resposta de pré-autorização

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
       "SaleToPOIResponse": {
           "PaymentResponse": {
               "POIData":
                   "POITransactionID": {
                       "TimeStamp": "2019-12-04T13:56:26.000Z",
                       "TransactionID": "8ha5001575467786000.8815754678001083"
                      }
                   {...},
               "SaleData": {...},
               "PaymentReceipt": [...],
               "PaymentResult": {
                   "AuthenticationMethod": [...],
                   "OnlineFlag": true,
                   "PaymentAcquirerData": {...},
                   "PaymentInstrumentData": {...},
                   "AmountsResp": {
                       "AuthorizedAmount": 150.00,
                       "Currency": "EUR"
                   }
               },
               "Response": {
                   "Result": "Success",
                   "AdditionalResponse": "...adjustAuthorisationData=BQABAQA+fbc==..."
               }
           },
           "MessageHeader": {...}
       }
   }

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.

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:

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

     • Faça uma solicitação /payments/{paymentPspReference}/cancels especificando a pspReference da pré-autorização original. Consulte Cancelar autorização para obter mais detalhes.

2. 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.
   Pedido de captura

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
       "amount":{
           "currency":"EUR",
           "value":21415
       },
       "reference":"YOUR_MODIFICATION_REFERENCE",
       "merchantAccount":"ADYEN_MERCHANT_ACCOUNT"
   }

3. 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.
   Resposta da captura

   Expand view

   Copy link to code block

   Copy code

   Copy code

   {
       "reference": "YOUR_MODIFICATION_REFERENCE",
       "pspReference": "8815762358979809",
       "status": "received"
   }

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

Veja também