Referência de Webhooks

Esta referência fornece uma visão geral do sistema de Webhook da Getnet, incluindo métodos de autenticação, tipos de eventos disponíveis, endpoints da API e estruturas de payload de Webhook. Para a documentação detalhada dos endpoints da API com schemas de request/response, parâmetros e exemplos, consulte a documentação de API Reference.

A Getnet envia notificações de Webhook como solicitações HTTP POST com payloads JSON. Todos os timestamps usam o formato ISO 8601, e os valores monetários estão na menor unidade de moeda (centavos para BRL).

Autenticação

Ao criar uma assinatura de Webhook, você deve especificar como a Getnet deve se autenticar ao fazer o post para o seu endpoint. A Webhook Management API suporta três métodos de autenticação:

1. Credenciais de Usuário (Basic Auth)

Use este método quando o endpoint do seu Webhook validar solicitações usando HTTP Basic Authentication. A Getnet incluirá um cabeçalho Authorization: Basic padrão composto pelas credenciais que você fornecer.

Configuração:

{
  "authentication_type": "user_credentials",
  "authentication_data": {
    "user": "your_client_id",
    "password": "your_client_secret"
  }
}

Quando a Getnet enviar Webhooks para o seu endpoint, ela incluirá:

Authorization: Basic {base64_encoded_user:password}

2. OAuth 2.0

Use este método quando o endpoint do seu Webhook esperar Bearer tokens OAuth 2.0. A Getnet executará o fluxo completo de client credentials do OAuth 2.0 em seu nome antes de cada entrega de Webhook.

Configuração:

{
  "authentication_type": "oauth",
  "authentication_data": {
    "oauth_url": "https://auth.provider.com/token",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "credentials_location": "basic_auth_header",
    "token_key_name": "access_token"
  }
}

Campos de configuração:

Quando a Getnet enviar Webhooks, ela irá:

1. Solicitar um token do seu servidor OAuth usando as credenciais fornecidas
2. Extrair o token da resposta usando token_key_name
3. Incluí-lo na solicitação do Webhook: Authorization: Bearer {token}

3. Token (Bearer Token)

Use este método quando quiser que a Getnet use um Bearer token obtido da Getnet Authentication API. Este token é o mesmo que você usa para autenticar solicitações de API para a Getnet.

Configuração:

{
  "authentication_type": "token",
  "authentication_data": {
    "token": "your_bearer_token_from_getnet_auth_api"
  }
}

Quando a Getnet enviar Webhooks, ela incluirá:

Authorization: Bearer {token}

Tipos de Eventos

Os Webhooks da Getnet suportam os seguintes tipos de eventos. Cada tipo de evento corresponde a um estado ou ação de transação específica:

Ao criar uma assinatura de Webhook, você especifica qual(is) tipo(s) de evento você deseja receber. Você pode criar várias assinaturas para diferentes tipos de eventos ou lidar com todos os eventos em um único endpoint.

Visão Geral da Webhook Management API

A Webhook Management API fornece endpoints para gerenciar suas assinaturas de Webhook de forma programática. Para a documentação completa dos endpoints, incluindo schemas de request/response, parâmetros, códigos de erro e exemplos, consulte a API Reference.

Endpoints Disponíveis

URL Base

Todos os endpoints de gerenciamento de Webhook estão disponíveis em:

https://api.gettech.com/dpm/webhooks/v1

Para obter informações detalhadas sobre cada endpoint, incluindo:

• Schemas de request e response
• Parâmetros obrigatórios e opcionais
• Query parameters e paginação
• Respostas de erro e códigos de status
• Exemplos de requests e responses

Consulte a documentação de API Reference.

Payloads de Eventos de Webhook

Quando ocorre um evento inscrito, a Getnet envia uma solicitação HTTP POST para a sua callback_url com um payload JSON contendo os dados do evento. A estrutura do payload varia dependendo do tipo de evento.

APPROVED_TRANSACTIONS

Enviado quando uma transação de pagamento foi aprovada com sucesso.

Exemplo de Payload:

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "9406df6c-3100-49ba-b4df-d81c1ad8a62b",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "payment_id": "2c341d28-491b-4cf8-aec7-eeb60136b7a5",
  "order_id": "ORDER-10187383",
  "amount": "11870",
  "currency": "BRL",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2025-11-13T14:30:00.000Z",
  "transaction_id": "123456789012",
  "original_transaction_id": null,
  "authorized_at": "2025-11-13T14:30:00.000Z",
  "reason_code": "00",
  "reason_message": "TRANSACTION EXECUTED SUCCESSFULLY",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA",
  "brand": "Visa",
  "authorization_code": "123456",
  "acquirer_transaction_id": "987654321",
  "eci": "05",
  "payment_received_timestamp": "2025-11-13T14:30:00.000Z",
  "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58",
  "merchant_advice_code": null,
  "additional_data": {}
}

Descrições dos Campos:

REJECTED_TRANSACTIONS

Enviado quando uma transação de pagamento foi rejeitada ou negada.

Exemplo de Payload:

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "9406df6c-3100-49ba-b4df-d81c1ad8a62b",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "payment_id": "2c341d28-491b-4cf8-aec7-eeb60136b7a5",
  "order_id": "ORDER-10187383",
  "amount": "11870",
  "currency": "BRL",
  "status": "REJECTED",
  "payment_method": "CREDIT",
  "received_at": "2025-11-13T14:30:00.000Z",
  "transaction_id": "123456789012",
  "original_transaction_id": null,
  "authorized_at": null,
  "reason_code": "51",
  "reason_message": "INSUFFICIENT FUNDS",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA",
  "brand": "Visa",
  "authorization_code": null,
  "acquirer_transaction_id": null,
  "eci": null,
  "payment_received_timestamp": "2025-11-13T14:30:00.000Z",
  "card_id": null,
  "merchant_advice_code": null,
  "additional_data": {}
}

Descrições dos Campos:

REFUNDED_TRANSACTIONS

Enviado quando uma transação foi reembolsada.

Exemplo de Payload:

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "9406df6c-3100-49ba-b4df-d81c1ad8a62b",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "payment_id": "2c341d28-491b-4cf8-aec7-eeb60136b7a5",
  "order_id": "ORDER-10187383",
  "amount": 8900,
  "currency": "BRL",
  "status": "REFUNDED",
  "reason_code": "00",
  "reason_message": "TRANSACTION EXECUTED SUCCESSFULLY",
  "canceled_at": "2025-11-13T15:30:00.000Z",
  "custom_key": "20200630-8900"
}

Descrições dos Campos:

CANCELLED_TRANSACTIONS

Enviado quando uma transação foi cancelada.

Exemplo de Payload:

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "9406df6c-3100-49ba-b4df-d81c1ad8a62b",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "payment_id": "2c341d28-491b-4cf8-aec7-eeb60136b7a5",
  "order_id": "ORDER-10187383",
  "amount": 8900,
  "currency": "BRL",
  "status": "CANCELLED",
  "reason_code": "00",
  "reason_message": "TRANSACTION CANCELLED SUCCESSFULLY",
  "canceled_at": "2025-11-13T15:30:00.000Z",
  "custom_key": "20200630-8900"
}

Descrições dos Campos:

CAPTURED_TRANSACTIONS

Enviado quando um pagamento pré-autorizado foi capturado.

Exemplo de Payload:

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "9406df6c-3100-49ba-b4df-d81c1ad8a62b",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "payment_id": "2c341d28-491b-4cf8-aec7-eeb60136b7a5",
  "order_id": "ORDER-10187383",
  "amount": 8900,
  "currency": "BRL",
  "status": "CAPTURED",
  "reason_code": "00",
  "reason_message": "TRANSACTION EXECUTED SUCCESSFULLY",
  "captured_at": "2025-11-13T16:00:00.000Z"
}

Descrições dos Campos:

CARD_UPDATE

Enviado quando os detalhes do cartão são atualizados via serviços de Network Token ou Account Updater.

Exemplo de Payload:

{
  "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58",
  "last_four_digits": "1212",
  "bin": "121212",
  "expiration_month": 12,
  "expiration_year": 28,
  "brand": "Mastercard",
  "cardholder_name": "JOAO DA SILVA",
  "customer_id": "customer_21081826",
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
  "used_at": "2017-04-19T16:30:30Z",
  "created_at": "2017-04-19T16:30:30Z",
  "updated_at": "2017-04-19T16:30:30Z",
  "status": "active",
  "transaction_id": "123456"
}

Descrições dos Campos:

Requisitos de Resposta

O endpoint do seu Webhook deve:

• Aceitar solicitações HTTP POST
• Usar HTTPS com um certificado SSL válido
• Responder com o código de status HTTP 204 (No Content) para confirmar o recebimento bem-sucedido
• Lidar com a autenticação conforme configurado em sua assinatura

Se o seu endpoint retornar qualquer código de status diferente de 204, a Getnet considerará a entrega falha e poderá tentar reenviar a entrega do Webhook.

Notas Importantes

1. Idempotência: Todos os payloads de Webhook incluem uma idempotency_key. Seu endpoint deve ser idempotente e lidar com entregas duplicadas de forma adequada.

2. Código de Resposta: O endpoint do seu Webhook deve responder com HTTP 204 (No Content) para confirmar o recebimento bem-sucedido. Qualquer outro código de status será considerado uma falha.

3. Timestamps: Todos os timestamps estão no formato ISO 8601 (ex: 2025-11-13T14:30:00.000Z).

4. Valores: Os valores monetários são representados na menor unidade monetária (centavos para BRL).

5. Campos Opcionais: Alguns campos podem ser null ou omitidos dependendo do tipo de transação e do método de pagamento.

6. Lógica de Retentativa: Se o seu endpoint não responder com 204, a Getnet tentará reenviar a entrega do Webhook.