Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

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 POS 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 POS 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 150.00 EUR.

    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
    {
      "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 150,00 EUR.

    Resposta de pré-autorização
    {
        "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.

  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 in 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 64,15 EUR a um valor pré-autorizado de 150,00 EUR.

    Solicitação de ajuste de autorização assíncrona
    curl https://checkout-test.adyen.com/v67/payments/{paymentPspReference}/amountUpdates \
    -H "x-API-key: YOUR_X-API-KEY" \
    -H "content-type: application/json" \
    -d '{
      "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
      "amount": {
        "currency":"EUR",
        "value":21415
      },
      "reason":"DelayedCharge",
      "reference":"YOUR_UNIQUE_REFERENCE"
    }'

    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
    Resposta de ajuste de autorização assíncrona
    {
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
      "paymentPspReference": "8536214160615591",
      "pspReference": "8836226209778195",
      "reference": "YOUR_UNIQUE_REFERENCE",
      "status": "received",
      "amount": {
          "currency": "EUR",
          "value": 2500
      }
    }
  2. Aguarde a notificação assíncrona. Isso informa se o novo valor foi autorizado.
  • Faça uma solicitação POST para o endpoint do /adjustAuthorisation, especificando:

    • originalReference: O pspReference da solicitação de pré-autorização. Você recebeu isso na resposta à sua solicitação de pré-autorização.
    • modificationAmount: A currency e value da nova quantia em in 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.
    • additionalData.adjustAuthorisationData: O blob adjustAuthorisationData anterior, em URL-decoded format. Para o primeiro ajuste, esse é o blob que você recebeu na resposta à solicitação de pré-autorização. Para o segundo ajuste, é o blob que você recebeu na resposta ao primeiro ajuste e assim por diante.

      Sempre use o blob mais recente.

    • merchantAccount: O nome da sua merchant account usada para processar o pagamento.

    Os exemplos a seguir mostram como você adicionaria uma cobrança de 64,15 EUR a um valor pré-autorizado de 150,00 EUR.

    Solicitação de ajuste de autorização síncrona
    {
        "originalReference":"8815754678001083",
        "modificationAmount": {
            "currency":"EUR",
            "value":21415
        },
        "reference":"YOUR_MODIFICATION_REFERENCE",
        "additionalData":{
            "adjustAuthorisationData":"BQABAQA+fbc==..."
        },
        "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
    }

    A resposta /adjustAuthorisation contém:

    • additionalData.adjustAuthorisationData: O novo blob, para a nova quantidade autorizada.
    • merchantReference: Sua referência a esta modificação de pagamento para uso em seu processo de reconciliação.
    • pspReference: TA referência do PSP associada a esta solicitação /adjustAuthorisation. Observe que isso é diferente da referência do PSP associada à solicitação de pré-autorização.
    • response: Authorised. Indica que a nova quantidade está autorizada.
    Resposta de ajuste de autorização síncrona
    {
        "additionalData": {
            "adjustAuthorisationData": "BQABAQArqht7L...",
            "merchantReference": "YOUR_MODIFICATION_REFERENCE"
        },
        "pspReference": "8535762347980628",
        "response": "Authorised"
    }
  • Decodifique pelo URL e amazene o blob adjustAuthorisationData que você recebeu na resposta /adjustAuthorisation. Você precisará disso se posteriormente ajustar a autorização novamente.
  • 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.
      Pedido de captura
      {
          "amount":{
              "currency":"EUR",
              "value":21415
          },
          "reference":"YOUR_MODIFICATION_REFERENCE",
          "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
      }
    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.
      Resposta da captura
      {
          "reference": "YOUR_MODIFICATION_REFERENCE",
          "pspReference": "8815762358979809",
          "status": "received"
      }
      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