Skip to main content

​
Overview

The ConsultaStatus API allows you to retrieve the current status of a transaction using its unique transaction ID. This is essential for tracking payment progress and updating order status in your system.

​
Querying Transaction Status

​
Basic Usage

Use the Consulta class to check a transaction’s status: 
using Akatus.ConsultaStatus;

try
{
    Consulta consulta = new Consulta();
    
    // Query transaction status by ID
    string transactionId = "00000000-0000-0000-0000-0000000000";
    Retorno retorno = consulta.consultaStatusTransacao(transactionId);
    
    if (retorno != null)
    {
        Console.WriteLine($"Status: {retorno.Status}");
        Console.WriteLine($"Created: {retorno.DataCriacao}");
        Console.WriteLine($"Last Updated: {retorno.DataStatusAtual}");
        Console.WriteLine($"Reference: {retorno.Referencia}");
        Console.WriteLine($"Amount: {retorno.Valor:C}");
    }
}
catch (Akatus.RestExcepction ex)
{
    Console.WriteLine($"Error: {ex.StatusCode} - {ex.StatusDesciption}");
    foreach (string error in ex.ErrorMessages)
    {
        Console.WriteLine(error);
    }
}

​
Method Signature

public Retorno consultaStatusTransacao(string transacaoId)

​
Parameters

ParameterTypeDescription
transacaoIdstringUnique transaction ID (UUID format)
The transaction ID is returned in the Transacao property when you process a transaction using carrinho.processaTransacao().

​
Response Structure

The Retorno object contains:
PropertyTypeDescription
StatusStatusTransacaoCurrent transaction status (enum)
DataCriacaoDateTimeDate and time when transaction was created
DataStatusAtualDateTimeDate and time of last status update
ReferenciastringYour reference code for the transaction
ValordecimalTransaction amount

​
Transaction Status Values

The Akatus.Enums.StatusTransacao enum defines the following status values:
Awaiting PaymentThe transaction was created but payment has not been received yet. This is common for:
  • Boleto payments (waiting for customer to pay the slip)
  • Bank transfers (waiting for transfer completion)
if (retorno.Status == StatusTransacao.aguardandoPagamento)
{
    Console.WriteLine("Waiting for customer payment...");
}
Under AnalysisThe payment is being analyzed for fraud prevention or other security checks.
if (retorno.Status == StatusTransacao.emAnalise)
{
    Console.WriteLine("Payment is under analysis");
}
ApprovedThe payment has been approved but not yet completed. The transaction is in progress.
if (retorno.Status == StatusTransacao.aprovado)
{
    Console.WriteLine("Payment approved!");
    // Update order status, prepare for shipping
}
CanceledThe transaction was canceled before completion.
if (retorno.Status == StatusTransacao.cancelado)
{
    Console.WriteLine("Transaction canceled");
    // Release reserved inventory
}
ProcessingThe payment is currently being processed by the payment gateway.
if (retorno.Status == StatusTransacao.processando)
{
    Console.WriteLine("Processing payment...");
}
CompleteThe transaction has been successfully completed and the payment received.
if (retorno.Status == StatusTransacao.completo)
{
    Console.WriteLine("Payment complete!");
    // Finalize order, send confirmation email
}
RefundedThe payment was refunded to the customer.
if (retorno.Status == StatusTransacao.devolvido)
{
    Console.WriteLine("Payment refunded");
    // Update accounting records
}
ReversedThe transaction was reversed (similar to a refund).
if (retorno.Status == StatusTransacao.estornado)
{
    Console.WriteLine("Payment reversed");
    // Handle reversal in your system
}
ChargebackThe customer disputed the payment through their bank/card issuer.
if (retorno.Status == StatusTransacao.chargeback)
{
    Console.WriteLine("Chargeback initiated");
    // Alert fraud prevention team
}

​
Complete Example

using System;
using Akatus.ConsultaStatus;
using Akatus.Enums;

public class TransactionStatusService
{
    public Retorno CheckTransactionStatus(string transactionId)
    {
        try
        {
            Consulta consulta = new Consulta();
            Retorno status = consulta.consultaStatusTransacao(transactionId);
            
            if (status != null)
            {
                LogTransactionStatus(status);
                return status;
            }
            
            Console.WriteLine("No status data returned");
            return null;
        }
        catch (Akatus.RestExcepction ex)
        {
            Console.WriteLine($"API Error: {ex.StatusCode} - {ex.StatusDesciption}");
            
            foreach (string error in ex.ErrorMessages)
            {
                Console.WriteLine($"  - {error}");
            }
            
            throw;
        }
    }
    
    private void LogTransactionStatus(Retorno status)
    {
        Console.WriteLine("\n=== Transaction Status ===");
        Console.WriteLine($"Status: {GetStatusDescription(status.Status)}");
        Console.WriteLine($"Reference: {status.Referencia}");
        Console.WriteLine($"Amount: {status.Valor:C}");
        Console.WriteLine($"Created: {status.DataCriacao:yyyy-MM-dd HH:mm:ss}");
        Console.WriteLine($"Last Update: {status.DataStatusAtual:yyyy-MM-dd HH:mm:ss}");
        
        TimeSpan elapsed = status.DataStatusAtual - status.DataCriacao;
        Console.WriteLine($"Elapsed Time: {elapsed.TotalMinutes:F1} minutes");
    }
    
    public string GetStatusDescription(StatusTransacao status)
    {
        switch (status)
        {
            case StatusTransacao.aguardandoPagamento:
                return "Awaiting Payment";
            case StatusTransacao.emAnalise:
                return "Under Analysis";
            case StatusTransacao.aprovado:
                return "Approved";
            case StatusTransacao.cancelado:
                return "Canceled";
            case StatusTransacao.processando:
                return "Processing";
            case StatusTransacao.completo:
                return "Complete";
            case StatusTransacao.devolvido:
                return "Refunded";
            case StatusTransacao.estornado:
                return "Reversed";
            case StatusTransacao.chargeback:
                return "Chargeback";
            default:
                return "Unknown";
        }
    }
    
    public bool IsPaymentComplete(string transactionId)
    {
        var status = CheckTransactionStatus(transactionId);
        
        if (status == null)
            return false;
        
        return status.Status == StatusTransacao.completo || 
               status.Status == StatusTransacao.aprovado;
    }
    
    public bool IsPaymentFailed(string transactionId)
    {
        var status = CheckTransactionStatus(transactionId);
        
        if (status == null)
            return true;
        
        return status.Status == StatusTransacao.cancelado || 
               status.Status == StatusTransacao.estornado ||
               status.Status == StatusTransacao.chargeback;
    }
}

​
Polling for Status Updates

For scenarios where you need to wait for a status change: 
using System.Threading;

public class TransactionMonitor
{
    private readonly TransactionStatusService _statusService;
    
    public TransactionMonitor()
    {
        _statusService = new TransactionStatusService();
    }
    
    public Retorno WaitForCompletion(string transactionId, int timeoutSeconds = 300)
    {
        DateTime startTime = DateTime.Now;
        TimeSpan timeout = TimeSpan.FromSeconds(timeoutSeconds);
        
        while (DateTime.Now - startTime < timeout)
        {
            try
            {
                var status = _statusService.CheckTransactionStatus(transactionId);
                
                if (status != null)
                {
                    // Check for terminal states
                    if (status.Status == StatusTransacao.completo)
                    {
                        Console.WriteLine("Payment completed successfully!");
                        return status;
                    }
                    
                    if (_statusService.IsPaymentFailed(transactionId))
                    {
                        Console.WriteLine($"Payment failed with status: {status.Status}");
                        return status;
                    }
                    
                    // Still processing, wait before checking again
                    Console.WriteLine($"Status: {status.Status}, checking again in 5 seconds...");
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error checking status: {ex.Message}");
            }
            
            Thread.Sleep(5000); // Wait 5 seconds
        }
        
        Console.WriteLine("Timeout waiting for transaction completion");
        return null;
    }
}

​
Web Application Example

using System;
using System.Web.UI;
using Akatus.ConsultaStatus;
using Akatus.Enums;

public partial class OrderStatus : Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        string transactionId = Request.QueryString["tid"];
        
        if (!string.IsNullOrEmpty(transactionId))
        {
            DisplayTransactionStatus(transactionId);
        }
    }
    
    private void DisplayTransactionStatus(string transactionId)
    {
        try
        {
            Consulta consulta = new Consulta();
            Retorno status = consulta.consultaStatusTransacao(transactionId);
            
            if (status != null)
            {
                lblReference.Text = status.Referencia;
                lblAmount.Text = status.Valor.ToString("C");
                lblCreated.Text = status.DataCriacao.ToString("dd/MM/yyyy HH:mm");
                lblUpdated.Text = status.DataStatusAtual.ToString("dd/MM/yyyy HH:mm");
                
                // Update UI based on status
                UpdateStatusUI(status.Status);
            }
        }
        catch (Akatus.RestExcepction ex)
        {
            pnlError.Visible = true;
            lblError.Text = $"Error: {ex.StatusDesciption}";
        }
    }
    
    private void UpdateStatusUI(StatusTransacao status)
    {
        switch (status)
        {
            case StatusTransacao.completo:
                pnlSuccess.Visible = true;
                lblStatusMessage.Text = "Payment completed successfully!";
                break;
                
            case StatusTransacao.aguardandoPagamento:
                pnlWaiting.Visible = true;
                lblStatusMessage.Text = "Waiting for payment confirmation...";
                // Add auto-refresh meta tag
                break;
                
            case StatusTransacao.cancelado:
            case StatusTransacao.estornado:
                pnlCanceled.Visible = true;
                lblStatusMessage.Text = "Payment was canceled";
                break;
                
            default:
                pnlProcessing.Visible = true;
                lblStatusMessage.Text = "Processing payment...";
                break;
        }
    }
}

​
Best Practices

Don’t poll the status API too frequently. Implement reasonable delays (5-10 seconds) between status checks to avoid rate limiting.
Use Payment Notifications (NIP) for real-time status updates instead of continuous polling. Query status only when you need to verify the current state.
Store the transaction ID from processaTransacao() in your database immediately. You’ll need it to query status later.

​
Next Steps

Payment Notifications

Receive real-time status updates via webhooks

Processing Transactions

Learn how to create transactions

Error Handling

Handle API errors properly

Build docs developers (and LLMs) love

Get started for freeTalk to us