Webhooks Reference

This reference provides an overview of the Getnet Webhook system, including authentication methods, available event types, API endpoints, and webhook payload structures. For detailed API endpoint documentation with request/response schemas, parameters, and examples, refer to the API Reference documentation.

Getnet sends webhook notifications as HTTP POST requests with JSON payloads. All timestamps use ISO 8601 format, and monetary amounts are in the smallest currency unit (cents for BRL).

Authentication

When creating a webhook subscription, you must specify how Getnet should authenticate when posting to your endpoint. The Webhook Management API supports three authentication methods:

1. User Credentials (Basic Auth)

Use this method when your webhook endpoint validates requests using HTTP Basic Authentication. Getnet will include a standard Authorization: Basic header composed of the credentials you provide.

Configuration:

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

When Getnet sends webhooks to your endpoint, it will include:

Authorization: Basic {base64_encoded_user:password}

2. OAuth 2.0

Use this method when your webhook endpoint expects OAuth 2.0 Bearer tokens. Getnet will execute the full OAuth 2.0 client credentials flow on your behalf before each webhook delivery.

Configuration:

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

Configuration fields:

Field	Type	Required	Description
`oauth_url`	string	Yes	OAuth token endpoint URL
`client_id`	string	Yes	OAuth client ID
`client_secret`	string	Yes	OAuth client secret
`credentials_location`	string	No	Where to send credentials: `basic_auth_header` (default) or `body`
`token_key_name`	string	No	Key name in token response (default: `access_token`)

When Getnet sends webhooks, it will:

Request a token from your OAuth server using the provided credentials
Extract the token from the response using token_key_name
Include it in the webhook request: Authorization: Bearer {token}

3. Token (Bearer Token)

Use this method when you want Getnet to use a Bearer token obtained from the Getnet Authentication API. This token is the same one you use to authenticate API requests to Getnet.

Configuration:

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

The token is obtained from the Getnet Authentication API endpoint (/authentication/oauth2/access_token) using your client_id and client_secret. This is the same token you use for other Getnet API requests. See the Authentication documentation for details on obtaining tokens from the authentication endpoint.

When Getnet sends webhooks, it will include:

Authorization: Bearer {token}

Event Types

Getnet webhooks support the following event types. Each event type corresponds to a specific transaction state or action:

Event Type	Description
`APPROVED_TRANSACTIONS`	Payment transaction has been successfully approved
`REJECTED_TRANSACTIONS`	Payment transaction was rejected or denied
`CAPTURED_TRANSACTIONS`	Pre-authorized payment has been captured
`CANCELLED_TRANSACTIONS`	Transaction has been cancelled
`REVERSED_TRANSACTIONS`	Card Present authorization has been reversed before capture
`REFUNDED_TRANSACTIONS`	Transaction has been refunded
`CARD_UPDATE`	Card details updated via Network Token or Account Updater
`CARD_UPDATED_TRANSACTIONS`	Card details updated on a transaction via Network Token or Account Updater
`PENDING_TRANSACTIONS`	Transaction is pending processing
`PIX_UPDATED_TRANSACTIONS`	PIX transaction status has been updated
`BOLETO_UPDATED_TRANSACTIONS`	Boleto transaction status has been updated
`BOLETO_PAID_TRANSACTIONS`	Boleto has been paid
`PROCESSING_TRANSACTIONS`	Transaction is being processed
`FAILED_TRANSACTIONS`	Transaction processing has failed
`EXPIRED_TRANSACTIONS`	Transaction has expired
`AUTHORIZED_TRANSACTIONS`	Transaction has been authorized

When creating a webhook subscription, you specify which event type(s) you want to receive. You can create multiple subscriptions for different event types or handle all events at a single endpoint.

Webhook Management API Overview

The Webhook Management API provides endpoints to manage your webhook subscriptions programmatically. For complete endpoint documentation including request/response schemas, parameters, error codes, and examples, see the API Reference.

Available Endpoints

Endpoint	Method	Description
`POST /subscriptions`	POST	Create a new webhook subscription
`GET /subscriptions/{event_name}`	GET	Retrieve webhook subscriptions for a specific event name
`DELETE /subscriptions/{event_name}`	DELETE	Delete a webhook subscription
`GET /subscriptions/{event_name}/events`	GET	List event messages for a subscription with pagination
`PATCH /subscriptions/{event_name}/events/{event_id}`	PATCH	Resend a specific webhook event message
`GET /subscriptions-events`	GET	List all events you are currently subscribed to

Base URL

All webhook management endpoints are available at:

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

For detailed information about each endpoint, including:

Request and response schemas
Required and optional parameters
Query parameters and pagination
Error responses and status codes
Example requests and responses

Refer to the API Reference documentation.

Webhook Event Payloads

When a subscribed event occurs, Getnet sends an HTTP POST request to your callback_url with a JSON payload containing the event data. The payload structure varies depending on the event type.

APPROVED_TRANSACTIONS

Sent when a payment transaction has been successfully approved.

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

Field Descriptions:

Field	Type	Description
`idempotency_key`	string	Idempotency key used to control requests
`seller_id`	string	Seller identification
`request_id`	string	Request identifier. Unique for each request
`payment_id`	string	Payment identifier
`order_id`	string	Purchase identification code used by e-commerce
`amount`	string	Transaction amount
`currency`	string	Currency code (e.g., “BRL”, “USD”)
`status`	string	Transaction status (e.g., “APPROVED”)
`payment_method`	string	Payment method used (e.g., “CREDIT”, “DEBIT”)
`received_at`	string	Timestamp when payment was received
`transaction_id`	string	Transaction identifier
`original_transaction_id`	string	Original transaction identifier (for refunds/cancellations)
`authorized_at`	string	Timestamp when transaction was authorized
`reason_code`	string	Return code from the sender or the getnet capture system
`reason_message`	string	Return message from the sender or the getnet capture system
`acquirer`	string	Acquirer name
`soft_descriptor`	string	Soft descriptor shown on card statement
`brand`	string	Card brand (e.g., “Visa”, “Mastercard”)
`authorization_code`	string	Authorization code
`acquirer_transaction_id`	string	Acquirer transaction identifier
`eci`	string	Electronic Commerce Indicator
`payment_received_timestamp`	string	Payment received timestamp
`card_id`	string	Card identifier saved in vault (if applicable)
`boleto`	object	Boleto payment details (if applicable)
`merchant_advice_code`	string	Merchant advice code (if applicable)
`additional_data`	object	Additional data

REJECTED_TRANSACTIONS

Sent when a payment transaction has been rejected or denied.

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

Field Descriptions:

Field	Type	Description
`idempotency_key`	string	Idempotency key used to control requests
`seller_id`	string	Seller identification
`request_id`	string	Request identifier. Unique for each request
`payment_id`	string	Payment identifier
`order_id`	string	Purchase identification code used by e-commerce
`amount`	string	Transaction amount
`currency`	string	Currency code (e.g., “BRL”, “USD”)
`status`	string	Transaction status (e.g., “REJECTED”)
`payment_method`	string	Payment method used (e.g., “CREDIT”, “DEBIT”)
`received_at`	string	Timestamp when payment was received
`transaction_id`	string	Transaction identifier
`original_transaction_id`	string	Original transaction identifier (for refunds/cancellations)
`authorized_at`	string	Timestamp when transaction was authorized (may be null)
`reason_code`	string	Return code from the sender or the getnet capture system
`reason_message`	string	Return message from the sender or the getnet capture system
`acquirer`	string	Acquirer name
`soft_descriptor`	string	Soft descriptor shown on card statement
`brand`	string	Card brand (e.g., “Visa”, “Mastercard”)
`authorization_code`	string	Authorization code (may be null)
`acquirer_transaction_id`	string	Acquirer transaction identifier (may be null)
`eci`	string	Electronic Commerce Indicator (may be null)
`payment_received_timestamp`	string	Payment received timestamp
`card_id`	string	Card identifier saved in vault (if applicable, may be null)
`boleto`	object	Boleto payment details (if applicable)
`merchant_advice_code`	string	Merchant advice code (if applicable, may be null)
`additional_data`	object	Additional data

REFUNDED_TRANSACTIONS

Sent when a transaction has been refunded.

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

Field Descriptions:

Field	Type	Description
`idempotency_key`	string	Idempotency key, used to control requests (1-64 characters)
`seller_id`	string	ECommerce identification code (UUID, 36 characters)
`request_id`	string	Request identifier. Unique for each request (UUID, 36 characters)
`payment_id`	string	Payment identifier (UUID, 36 characters)
`order_id`	string	Purchase identification code used by e-commerce
`amount`	number	Purchase value in cents
`currency`	string	Currency identification (e.g., “BRL”)
`status`	string	Transaction status
`reason_code`	string	Return code from the sender or the getnet capture system (2 chars)
`reason_message`	string	Return message from the sender or the getnet capture system
`canceled_at`	string	Cancellation/refund date (ISO 8601 format)
`custom_key`	string	Customer key used to identify the refund request (3-32 chars)

CANCELLED_TRANSACTIONS

Sent when a transaction has been cancelled.

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

Field Descriptions:

Field	Type	Description
`idempotency_key`	string	Idempotency key, used to control requests (1-64 characters)
`seller_id`	string	ECommerce identification code (UUID, 36 characters)
`request_id`	string	Request identifier. Unique for each request (UUID, 36 characters)
`payment_id`	string	Payment identifier (UUID, 36 characters)
`order_id`	string	Purchase identification code used by e-commerce
`amount`	number	Purchase value in cents
`currency`	string	Currency identification (e.g., “BRL”)
`status`	string	Transaction status
`reason_code`	string	Return code from the sender or the getnet capture system (2 chars)
`reason_message`	string	Return message from the sender or the getnet capture system
`canceled_at`	string	Cancellation date (ISO 8601 format)
`custom_key`	string	Customer key used to identify the cancellation request (3-32 chars)

REVERSED_TRANSACTIONS

Sent when a Card Present authorization has been reversed before capture. A reversal always covers the full amount, and no money moves.

Example Payload:

{
  "idempotency_key": "b10be7a7-d76e-4cd6-8ebe-4f68b9271d9c",
  "seller_id": "19ffd677-3691-4c4d-88c9-79cc91b95c0d",
  "request_id": "51d212f6-ad05-499c-90a1-e05c3b6ea0db",
  "payment_id": "b0b7851a-e558-4d94-b34e-86d69138de77",
  "order_id": "471994a7-ba22-453e-8afc-f0137d1710c2",
  "amount": 4000,
  "status": "REVERSED",
  "canceled_at": "2026-09-04T18:14:54.057Z",
  "reason_code": "00",
  "reason_message": "Payment successful reversal.",
  "custom_key": "2bc94fa13c8d4df28e52a996912bbab5",
  "authorization_code": "601878",
  "trace_number": 0,
  "complete_cancel": true,
  "callback_url": "https://myserver.com/send/callback/here"
}

Field Descriptions:

Field	Type	Description
`idempotency_key`	string	Idempotency key sent on the reversal request (1-64 characters)
`seller_id`	string	Seller identification (UUID, 36 characters)
`request_id`	string	Request identifier. Unique for each request (UUID, 36 characters)
`payment_id`	string	Identifier of the reversed payment (UUID, 36 characters)
`order_id`	string	Purchase identification code (code or order number)
`amount`	number	Reversed amount in cents. Always the full amount of the original authorization
`status`	string	Transaction status (`REVERSED`)
`canceled_at`	string	Reversal date (ISO 8601 format)
`reason_code`	string	Return code from the sender or the getnet capture system (2 chars)
`reason_message`	string	Return message from the sender or the getnet capture system
`custom_key`	string	Customer key sent on the reversal request (3-32 chars)
`authorization_code`	string	Authorization code
`trace_number`	integer	Trace number of the transaction
`complete_cancel`	boolean	Indicates a full reversal. Always `true` for this event
`callback_url`	string	Webhook URL that received this notification

CAPTURED_TRANSACTIONS

Sent when a pre-authorized payment has been captured.

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

Field Descriptions:

Field	Type	Description
`idempotency_key`	string	Idempotency key, used to control requests (1-64 characters)
`seller_id`	string	ECommerce identification code (UUID, 36 characters)
`request_id`	string	Request identifier. Unique for each request (UUID, 36 characters)
`payment_id`	string	Payment identifier (UUID, 36 characters)
`order_id`	string	Purchase identification code used by e-commerce
`amount`	number	Purchase value in cents
`currency`	string	Currency identification (e.g., “BRL”)
`status`	string	Transaction status
`reason_code`	string	Return code from the sender or the getnet capture system (2 chars)
`reason_message`	string	Return message from the sender or the getnet capture system
`captured_at`	string	Capture date (ISO 8601 format)

CARD_UPDATE

Sent when card details are updated via Network Token or Account Updater services.

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

Field Descriptions:

Field	Type	Description
`card_id`	string	Card identifier saved in the safe (max 36 chars)
`last_four_digits`	string	Last four digits of the card (max 4 chars)
`bin`	string	First six digits of the card (max 6 chars)
`expiration_month`	integer	Two-digit card expiration month (1-12)
`expiration_year`	integer	Two-digit card expiration year
`brand`	string	Card banner (Mastercard, Visa, Amex, Elo, Hipercard)
`cardholder_name`	string	Buyer’s name printed on the card (max 26 chars)
`customer_id`	string	Buyer identifier (max 100 chars)
`number_token`	string	Card token that will be used in transactions (max 128 chars)
`used_at`	string	Date of last use (ISO 8601 format)
`created_at`	string	Creation date (ISO 8601 format)
`updated_at`	string	Update date (ISO 8601 format)
`status`	string	Card status in the safe (active, blocked, canceled, renewed)
`transaction_id`	string	Card Verification Transaction ID (max 32 chars)

Response Requirements

Your webhook endpoint must:

Accept HTTP POST requests
Use HTTPS with a valid SSL certificate
Respond with HTTP status code 204 (No Content) to acknowledge successful receipt
Handle authentication as configured in your subscription

If your endpoint returns any status code other than 204, Getnet will consider the delivery failed and may retry the webhook delivery.

Important Notes

Idempotency: All webhook payloads include an idempotency_key. Your endpoint should be idempotent and handle duplicate deliveries gracefully.
Response Code: Your webhook endpoint must respond with HTTP 204 (No Content) to acknowledge successful receipt. Any other status code will be considered a failure.
Timestamps: All timestamps are in ISO 8601 format (e.g., 2025-11-13T14:30:00.000Z).
Amounts: Monetary amounts are represented in the smallest currency unit (cents for BRL).
Optional Fields: Some fields may be null or omitted depending on the transaction type and payment method.
Retry Logic: If your endpoint doesn’t respond with 204, Getnet will retry the webhook delivery.