Skip to main content

​
Overview

The Akatus.NotificacaoPagamento.Notificacao class handles NIP (Notificação Instantânea de Pagamento) - Instant Payment Notifications sent by Akatus when a transaction’s payment status changes. This allows your application to receive real-time updates about payment status changes.

​
What is NIP?

NIP (Notificação Instantânea de Pagamento) is Akatus’s webhook system that sends POST requests to your server whenever a transaction’s status changes. This allows you to:
  • Receive real-time payment status updates
  • Update your order system automatically
  • Trigger business processes based on payment events
  • Avoid polling the status API repeatedly

​
Notificacao Class

​
processaRetorno()

Processes and validates a payment notification received from Akatus via webhook. 
public static Akatus.NotificacaoPagamento.Retorno processaRetorno(
    string token, 
    string transacao_id, 
    string status, 
    string referencia
)
​
token
string
required
The NIP token used to validate that the notification was actually sent by Akatus. This must match the token configured in your Akatus account settings.
​
transacao_id
string
required
The transaction ID in Akatus (GUID format)
​
status
string
required
The current payment status as a string. Possible values:
  • “Aguardando Pagamento”
  • “Em Análise”
  • “Aprovado”
  • “Cancelado”
  • “Processando”
  • “Completo”
  • “Devolvido”
  • “Estornado”
  • “Chargeback”
​
referencia
string
Your store’s transaction ID (optional, only if provided during transaction creation)

​
Returns

Returns an Akatus.NotificacaoPagamento.Retorno object containing the validated notification data.

​
Retorno Structure

The Retorno class contains the following properties from the processed notification:
​
TransacaoId
string
The transaction ID from Akatus
​
Status
Akatus.Enums.StatusTransacao
The current payment status as an enum. Possible values:
  • aguardandoPagamento - Awaiting Payment
  • emAnalise - Under Analysis
  • aprovado - Approved
  • cancelado - Canceled
  • processando - Processing
  • completo - Complete
  • devolvido - Refunded
  • estornado - Reversed
  • chargeback - Chargeback
​
Referencia
string
Your store’s transaction ID (if one was provided)

​
Webhook Implementation Example

Create an endpoint in your application to receive POST requests from Akatus: 
// In your ASP.NET page or controller that receives the webhook
protected void Page_Load(object sender, EventArgs e)
{
    // Get parameters posted by Akatus
    string token = Request.Form["token"];
    string transacao_id = Request.Form["transacao_id"];
    string status = Request.Form["status"];
    string referencia = Request.Form["referencia"];
    
    try
    {
        // Process the notification
        Akatus.NotificacaoPagamento.Retorno retorno = 
            Akatus.NotificacaoPagamento.Notificacao.processaRetorno(
                token, 
                transacao_id, 
                status, 
                referencia
            );
        
        // Update your order system based on the status
        UpdateOrder(retorno.TransacaoId, retorno.Status, retorno.Referencia);
        
        // Return success response to Akatus
        Response.StatusCode = 200;
        Response.Write("OK");
    }
    catch (System.ArgumentException ex)
    {
        // Invalid token or missing parameters
        Response.StatusCode = 400;
        Response.Write("Error: " + ex.Message);
    }
    catch (Exception ex)
    {
        // Other errors
        Response.StatusCode = 500;
        Response.Write("Error: " + ex.Message);
    }
}

​
Configuration Requirements

Before processing notifications, ensure you have configured the NIP token in your Web.Config: 
<appSettings>
  <!-- Akatus - Environment ('producao' or 'testes') -->
  <add key="AkatusAmbiente" value="testes"/>
  
  <!-- Akatus - API Key -->
  <add key="AkatusApiKey" value="YOUR-API-KEY"/>
  
  <!-- Akatus - NIP Token -->
  <add key="AkatusTokenNIP" value="YOUR-NIP-TOKEN"/>
  
  <!-- Akatus - Email -->
  <add key="AkatusEmail" value="[email protected]"/>
</appSettings>

​
Security Validation

The processaRetorno() method performs important security validations:
  1. Token Validation: Verifies that the token sent by Akatus matches your configured NIP token. This ensures the notification came from Akatus and not a malicious third party.
  2. Required Parameters: Validates that all required parameters (token, transacao_id, status) are present in the POST request.
  3. Exception Handling: Throws exceptions for invalid tokens or missing parameters.

​
Error Handling

The method throws exceptions in the following scenarios:
  • Invalid token: When the posted token doesn’t match your configured NIP token
  • Missing parameters: When required parameters (token, transacao_id, or status) are not provided
Example error handling: 
try
{
    string token = Request.Form["token"];
    string transacao_id = Request.Form["transacao_id"];
    string status = Request.Form["status"];
    string referencia = Request.Form["referencia"];
    
    Akatus.NotificacaoPagamento.Retorno retorno = 
        Akatus.NotificacaoPagamento.Notificacao.processaRetorno(
            token, 
            transacao_id, 
            status, 
            referencia
        );
}
catch (System.ArgumentException ex)
{
    if (ex.Message.Contains("Tóken inválido"))
    {
        // Security breach attempt - invalid token
        LogSecurityIncident(ex);
    }
    else
    {
        // Missing parameters
        LogError("Missing required POST parameters");
    }
}

​
Best Practices

  1. Respond Quickly: Process the notification and respond to Akatus within a reasonable time to avoid timeouts.
  2. Idempotency: Handle the possibility of receiving the same notification multiple times. Check if you’ve already processed the transaction before updating your system.
  3. Logging: Log all received notifications for debugging and audit purposes.
  4. Status Updates: Update your order/transaction system based on the status received.
  5. Security: Always validate the token before processing any notification data.

​
Status Flow

Typical payment status progression: 
Aguardando Pagamento → Em Análise → Aprovado → Completo
Possible alternative flows:
  • Aguardando Pagamento → Cancelado
  • Aprovado → Devolvido (refund initiated)
  • Completo → Estornado (reversal/chargeback)
  • Completo → Chargeback (dispute filed)

Build docs developers (and LLMs) love

Get started for freeTalk to us