Visão geral

Os webhooks, também conhecidos como HTTP Callbacks, permitem que você se inscreva para receber notificações em uma URL específica de sua escolha.

Sempre que ocorre uma alteração no estado de um recurso nas plataformas da Paytime — como a criação bem-sucedida de uma transação ou o estorno de uma transação — um evento correspondente é gerado e enviado para os webhooks cadastrados.

Como cadastrar os webhooks

Para utilizar a notificação de eventos por webhooks você precisa:

Implementar o seu sistema de recebimento de notificações via webhook.

Cadastrar as URLs do seu sistema na Paytime, através do seu Gestor:

1. Vá até o menu "Integração";
2. Informe e chave de integração e clique no botão "Consultar";
3. Clique na aba "Eventos";
4. Clique no Botão "Adicionar Eventos";
5. Selecione o evento que deseja receber;
   1. Preencha o campo correspondente com a URL do seu sistema;
   2. Clique no botão "Adicionar evento";

Pronto, webhook cadastrado!

Conteúdo do evento

Sempre que um evento webhook é disparado enviaremos um objeto JSON, conforme padrão abaixo.
Exemplo de evento: new-sub-transaction

{
   "event":"new-sub-transaction",
   "event_date":"2025-04-30T17:05:53.107Z",
   "data":{
      "_id":"681258717903c84441e0e823",
      "status":"PENDING",
      "amount":1005,
      "original_amount":1017,
      "fees":12,
      "type":"CREDIT",
      "gateway_key":"849c88d8-8599-449d-8b0e-598036c6f014",
      "gateway_authorization":"PAYTIME",
      "card":{
         "brand_name":"MASTERCARD",
         "first4_digits":"5200",
         "last4_digits":"1005",
         "expiration_month":"12",
         "expiration_year":"2026",
         "holder_name":"JOÃO DA SILVA",
         "_id":"681258707903c84441e0e80b"
      },
      "installments":1,
      "customer":{
         "first_name":"João",
         "last_name":"da Silva",
         "document":"10068114004",
         "phone":"31992831124",
         "email":"[email protected]",
         "address":{
            "street":"Rua Maria dos Desenvolvedores",
            "number":"0101",
            "complement":"Debug",
            "neighborhood":"Bairro Deploy",
            "city":"Vitória",
            "state":"ES",
            "zip_code":"29000000"
         },
         "_id":"681258707903c84441e0e80c"
      },
      "antifraud":[
         {
            "analyse_status":"NO_ANALYSED",
            "_id":"681258717903c84441e0e820"
         }
      ],
      "point_of_sale":{
         "type":"ONLINE",
         "identification_type":"API"
      },
      "acquirer":{
         "name":"PAGSEGURO",
         "acquirer_nsu":123456789123,
         "gateway_key":"354F9DD8-39AB-417D-B543-558126B347E9",
         "mid":"100000000000002",
         "_id":"681258717903c84441e0e822"
      },
      "created_at":"2025-04-30T17:05:52.924Z",
      "pix":null
   }
}

• event: é o nome do evento que está sendo enviado, sua aplicação precisa estar preparada para identificar o tipo de evento;
• event_date: é a data que o evento foi enviado;
• data: É objeto JSON que contém as informações do webhook cadastrado, seguindo o padrão de resposta dos endpoints de criação, edição e atualização.

Nome dos eventos disponíveis na integração da plataforma

Como funcionam os envios

Envio dos webhooks

Quando um evento é gerado e existem webhooks cadastrados para recebê-lo, o envio é realizado após a sua criação.

A URL do seu webhook deve ser única e estar publicamente acessível na internet, garantindo que a plataforma da Paytime possa alcançá-la e enviar os eventos corretamente.

Fluxo de tentativas de envios

Uma vez que a primeira tentativa de entrega não obtém sucesso, a Paytime efetuará novos disparos dentro de poucos instantes. Após um número máximo de 3 tentativas sem sucesso, o evento entra em estado de falha na entrega.

Timeout

Durante o disparo de um evento para um de seus webhook, a Paytime espera receber uma resposta em até 1 segundo. Caso esse tempo expire, fechamos a conexão e a Paytime irá tentar novamente o envio.

Orientação Múltiplos Destinos

Caso seja necessário distribuir o mesmo evento para múltiplos destinos, recomenda-se implementar um orquestrador do lado do integrador.

• Nesse cenário:
  • A Paytime envia o webhook para uma única URL configurada
  • Essa URL atua como ponto central de processamento
  • O integrador redistribui o evento para outros serviços conforme sua regra de negócio

⚠️

Importante

Recomendamos que você realize um tratamento no seu sistema, garantindo que os eventos disparados em duplicidade sejam considerados apenas uma vez.

🔁Idempotência

Recomendamos que o parceiro implemente um mecanismo de idempotência e sincronização de eventos para o processamento dos webhooks recebidos.

Ao receber um webhook, o sistema deve identificar a transação através do identificador único retornado pela Paytime e validar se o evento recebido representa uma alteração de estado já processada anteriormente.

A atualização da transação deve ocorrer apenas quando houver mudança efetiva de status ou alteração relevante nos dados da operação. Caso o evento recebido já tenha sido processado ou não represente mudança no estado atual da transação, o processamento deve ser ignorado.

Essa estratégia reduz riscos de processamento duplicado, múltiplas baixas financeiras, inconsistências de conciliação e problemas causados por reenvio de eventos, retentativas automáticas ou processamento concorrente de webhooks