Referencia de Webhooks

Esta referencia proporciona una visión general del sistema de Webhook de Getnet, incluyendo métodos de autenticación, tipos de eventos disponibles, endpoints de la API y estructuras de payload del Webhook. Para obtener la documentación detallada de los endpoints de la API con esquemas de request/response, parámetros y ejemplos, consulte la documentación de la API Reference.

Getnet envía notificaciones de Webhook como peticiones HTTP POST con payloads JSON. Todas las marcas de tiempo (timestamps) utilizan el formato ISO 8601, y los importes monetarios están en la unidad de divisa más pequeña (céntimos para BRL).

Autenticación

Al crear una suscripción de Webhook, debe especificar cómo debe autenticarse Getnet al enviar peticiones (post) a su endpoint. La Webhook Management API soporta tres métodos de autenticación:

1. Credenciales de Usuario (Basic Auth)

Utilice este método cuando el endpoint de su Webhook valide las peticiones utilizando HTTP Basic Authentication. Getnet incluirá una cabecera Authorization: Basic estándar compuesta por las credenciales que usted proporcione.

Configuración:

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

Cuando Getnet envíe Webhooks a su endpoint, incluirá:

Authorization: Basic {base64_encoded_user:password}

2. OAuth 2.0

Utilice este método cuando el endpoint de su Webhook espere Bearer tokens de OAuth 2.0. Getnet ejecutará el flujo completo de client credentials de OAuth 2.0 en su nombre antes de cada entrega de Webhook.

Configuración:

{
  "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 configuración:

Cuando Getnet envíe Webhooks, realizará lo siguiente:

1. Solicitar un token a su servidor OAuth utilizando las credenciales proporcionadas
2. Extraer el token de la respuesta utilizando token_key_name
3. Incluirlo en la petición del Webhook: Authorization: Bearer {token}

3. Token (Bearer Token)

Utilice este método cuando desee que Getnet utilice un Bearer token obtenido de la Getnet Authentication API. Este token es el mismo que usted utiliza para autenticar peticiones de API a Getnet.

Configuración:

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

Cuando Getnet envíe Webhooks, incluirá:

Authorization: Bearer {token}

Tipos de Eventos

Los Webhooks de Getnet soportan los siguientes tipos de eventos. Cada tipo de evento corresponde a un estado o acción de transacción específica:

Al crear una suscripción de Webhook, usted especifica qué tipo(s) de evento desea recibir. Puede crear múltiples suscripciones para diferentes tipos de eventos o gestionar todos los eventos en un solo endpoint.

Visión General de la Webhook Management API

La Webhook Management API proporciona endpoints para gestionar sus suscripciones de Webhook de forma programática. Para obtener la documentación completa de los endpoints, incluyendo esquemas de request/response, parámetros, códigos de error y ejemplos, consulte la API Reference.

Endpoints Disponibles

URL Base

Todos los endpoints de gestión de Webhooks están disponibles en:

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

Para obtener información detallada sobre cada endpoint, incluyendo:

• Esquemas de request y response
• Parámetros obligatorios y opcionales
• Query parameters y paginación
• Respuestas de error y códigos de estado
• Ejemplos de requests y responses

Consulte la documentación de la API Reference.

Payloads de Eventos de Webhook

Cuando ocurre un evento suscrito, Getnet envía una petición HTTP POST a su callback_url con un payload JSON que contiene los datos del evento. La estructura del payload varía dependiendo del tipo de evento.

APPROVED_TRANSACTIONS

Se envía cuando una transacción de pago ha sido aprobada con éxito.

Ejemplo 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": {}
}

Descripciones de los Campos:

REJECTED_TRANSACTIONS

Se envía cuando una transacción de pago ha sido rechazada o denegada.

Ejemplo 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": {}
}

Descripciones de los Campos:

REFUNDED_TRANSACTIONS

Se envía cuando una transacción ha sido reembolsada.

Ejemplo 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"
}

Descripciones de los Campos:

CANCELLED_TRANSACTIONS

Se envía cuando una transacción ha sido cancelada.

Ejemplo 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"
}

Descripciones de los Campos:

CAPTURED_TRANSACTIONS

Se envía cuando un pago preautorizado ha sido capturado.

Ejemplo 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"
}

Descripciones de los Campos:

CARD_UPDATE

Se envía cuando los detalles de la tarjeta se actualizan a través de los servicios de Network Token o Account Updater.

Ejemplo 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"
}

Descripciones de los Campos:

Requisitos de Respuesta

El endpoint de su Webhook debe:

• Aceptar peticiones HTTP POST
• Utilizar HTTPS con un certificado SSL válido
• Responder con el código de estado HTTP 204 (No Content) para confirmar la recepción exitosa
• Gestionar la autenticación tal como está configurada en su suscripción

Si su endpoint devuelve cualquier código de estado distinto de 204, Getnet considerará que la entrega ha fallado y puede volver a intentar la entrega del Webhook.

Notas Importantes

1. Idempotencia: Todos los payloads de Webhook incluyen una idempotency_key. Su endpoint debe ser idempotente y gestionar las entregas duplicadas de forma correcta.

2. Código de Respuesta: El endpoint de su Webhook debe responder con HTTP 204 (No Content) para confirmar la recepción exitosa. Cualquier otro código de estado se considerará un fallo.

3. Marcas de tiempo (Timestamps): Todas las marcas de tiempo están en formato ISO 8601 (ej., 2025-11-13T14:30:00.000Z).

4. Importes: Los importes monetarios se representan en la unidad de divisa más pequeña (céntimos para BRL).

5. Campos Opcionales: Algunos campos pueden ser null u omitirse dependiendo del tipo de transacción y del método de pago.

6. Lógica de Reintento: Si su endpoint no responde con 204, Getnet volverá a intentar la entrega del Webhook.