Skip to main content

​
Overview

The ConsultaParcelamento API allows you to retrieve available installment options for a specific payment method and transaction amount. This is essential for displaying installment choices to customers during checkout.

​
Querying Installment Options

​
Basic Usage

Use the Consulta class to retrieve installment options: 
using Akatus.ConsultaParcelamento;
using Akatus.Enums;

try
{
    Consulta consulta = new Consulta();
    
    // Query installment options for R$ 10.39 on Visa
    Retorno retorno = consulta.consultaParcelamento(10.39m, MeioDePagamento.cartao_visa);
    
    if (retorno != null)
    {
        Console.WriteLine($"Description: {retorno.Descricao}");
        Console.WriteLine($"Merchant-assumed installments: {retorno.ParcelasAssumidas}");
        Console.WriteLine();
        
        foreach (RetornoParcela parcela in retorno.Parcelas)
        {
            Console.WriteLine($"{parcela.Quantidade}x of R$ {parcela.Valor:F2} = R$ {parcela.Total:F2}");
        }
    }
}
catch (Akatus.RestExcepction ex)
{
    Console.WriteLine($"Error: {ex.StatusCode} - {ex.StatusDesciption}");
    foreach (string error in ex.ErrorMessages)
    {
        Console.WriteLine(error);
    }
}

​
Method Signature

public Retorno consultaParcelamento(decimal valor, MeioDePagamento meioDePagamento)

​
Parameters

ParameterTypeDescription
valordecimalTransaction amount in BRL
meioDePagamentoMeioDePagamentoPayment method enum value

​
Supported Payment Methods

Installment plans are available for credit card payment methods:
  • MeioDePagamento.cartao_visa - Visa
  • MeioDePagamento.cartao_master - Mastercard
  • MeioDePagamento.cartao_amex - American Express
  • MeioDePagamento.cartao_elo - Elo
  • MeioDePagamento.cartao_diners - Diners Club
Installment queries are not applicable for boleto, tef_itau, or tef_bradesco payment methods.

​
Response Structure

​
Retorno Object

PropertyTypeDescription
DescricaostringPayment method description
ParcelasAssumidasintNumber of installments with no interest (assumed by merchant)
ParcelasList<RetornoParcela>List of available installment options

​
RetornoParcela Object

PropertyTypeDescription
QuantidadeintNumber of installments
ValordecimalAmount per installment
TotaldecimalTotal amount (including any interest)

​
Complete Example

using System;
using System.Collections.Generic;
using Akatus.ConsultaParcelamento;
using Akatus.Enums;

public class InstallmentService
{
    public Retorno GetInstallmentOptions(decimal amount, MeioDePagamento paymentMethod)
    {
        try
        {
            Consulta consulta = new Consulta();
            Retorno opcoes = consulta.consultaParcelamento(amount, paymentMethod);
            
            if (opcoes != null)
            {
                Console.WriteLine($"\nInstallment options for {opcoes.Descricao}:");
                Console.WriteLine($"Amount: R$ {amount:F2}");
                Console.WriteLine($"Interest-free installments: up to {opcoes.ParcelasAssumidas}x\n");
                
                return opcoes;
            }
            
            return null;
        }
        catch (Akatus.RestExcepction ex)
        {
            Console.WriteLine($"API Error: {ex.StatusCode} - {ex.StatusDesciption}");
            
            foreach (string error in ex.ErrorMessages)
            {
                Console.WriteLine($"  - {error}");
            }
            
            throw;
        }
    }
    
    public void DisplayInstallmentTable(decimal amount, MeioDePagamento paymentMethod)
    {
        var opcoes = GetInstallmentOptions(amount, paymentMethod);
        
        if (opcoes == null || opcoes.Parcelas == null)
        {
            Console.WriteLine("No installment options available");
            return;
        }
        
        Console.WriteLine("{0,-12} {1,-15} {2,-15}", "Installments", "Per Month", "Total");
        Console.WriteLine(new string('-', 42));
        
        foreach (var parcela in opcoes.Parcelas)
        {
            string installmentText = $"{parcela.Quantidade}x";
            string perMonth = $"R$ {parcela.Valor:F2}";
            string total = $"R$ {parcela.Total:F2}";
            
            // Highlight interest-free installments
            if (parcela.Quantidade <= opcoes.ParcelasAssumidas)
            {
                installmentText += " (no interest)";
            }
            
            Console.WriteLine("{0,-12} {1,-15} {2,-15}", installmentText, perMonth, total);
        }
    }
    
    public RetornoParcela GetBestInstallmentOption(decimal amount, MeioDePagamento paymentMethod)
    {
        var opcoes = GetInstallmentOptions(amount, paymentMethod);
        
        if (opcoes == null || opcoes.Parcelas == null || opcoes.Parcelas.Count == 0)
            return null;
        
        // Return the maximum interest-free installment option
        return opcoes.Parcelas
            .Where(p => p.Quantidade <= opcoes.ParcelasAssumidas)
            .OrderByDescending(p => p.Quantidade)
            .FirstOrDefault();
    }
}

​
Web Application Example

using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using Akatus.ConsultaParcelamento;
using Akatus.Enums;

public partial class CheckoutPage : Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        if (!IsPostBack)
        {
            LoadInstallmentOptions();
        }
    }
    
    private void LoadInstallmentOptions()
    {
        decimal cartTotal = GetCartTotal(); // Your method to calculate cart total
        MeioDePagamento selectedPayment = GetSelectedPaymentMethod();
        
        try
        {
            Consulta consulta = new Consulta();
            Retorno opcoes = consulta.consultaParcelamento(cartTotal, selectedPayment);
            
            if (opcoes != null && opcoes.Parcelas != null)
            {
                // Bind to dropdown
                ddlInstallments.DataSource = opcoes.Parcelas;
                ddlInstallments.DataTextField = "Quantidade";
                ddlInstallments.DataValueField = "Quantidade";
                ddlInstallments.DataBind();
                
                // Add text formatting for each item
                foreach (ListItem item in ddlInstallments.Items)
                {
                    int qty = int.Parse(item.Value);
                    var parcela = opcoes.Parcelas.Find(p => p.Quantidade == qty);
                    
                    if (parcela != null)
                    {
                        string text = $"{qty}x R$ {parcela.Valor:F2}";
                        
                        if (qty <= opcoes.ParcelasAssumidas)
                        {
                            text += " (sem juros)";
                        }
                        else
                        {
                            text += $" = R$ {parcela.Total:F2}";
                        }
                        
                        item.Text = text;
                    }
                }
            }
        }
        catch (Akatus.RestExcepction ex)
        {
            lblError.Text = $"Error loading installments: {ex.StatusDesciption}";
            lblError.Visible = true;
        }
    }
    
    private decimal GetCartTotal()
    {
        // Implementation
        return 299.90m;
    }
    
    private MeioDePagamento GetSelectedPaymentMethod()
    {
        // Implementation
        return MeioDePagamento.cartao_visa;
    }
}

​
Real-World Scenarios

Update installment options when the customer changes payment method or cart total:
protected void ddlPaymentMethod_SelectedIndexChanged(object sender, EventArgs e)
{
    LoadInstallmentOptions();
}

protected void UpdateCartTotal(decimal newTotal)
{
    ViewState["CartTotal"] = newTotal;
    LoadInstallmentOptions();
}
Recommend the best installment option to customers:
var service = new InstallmentService();
var bestOption = service.GetBestInstallmentOption(500.00m, MeioDePagamento.cartao_visa);

if (bestOption != null)
{
    Console.WriteLine($"Recommended: {bestOption.Quantidade}x of R$ {bestOption.Valor:F2} (no interest)");
}
Display interest information to customers:
foreach (var parcela in opcoes.Parcelas)
{
    decimal originalAmount = 299.90m;
    
    if (parcela.Total > originalAmount)
    {
        decimal interest = parcela.Total - originalAmount;
        decimal interestRate = (interest / originalAmount) * 100;
        
        Console.WriteLine($"{parcela.Quantidade}x: +{interestRate:F2}% interest");
    }
}
Filter installment options based on minimum value per installment:
decimal minInstallmentValue = 10.00m;

var validOptions = opcoes.Parcelas
    .Where(p => p.Valor >= minInstallmentValue)
    .ToList();

if (validOptions.Count == 0)
{
    Console.WriteLine("Single payment only (amount below minimum for installments)");
}

​
Best Practices

Always query installment options in real-time before displaying them to customers. Installment configurations can change based on your Akatus account settings.
Cache installment results for a short period (e.g., 5 minutes) to reduce API calls for the same amount and payment method combination.
The ParcelasAssumidas value indicates how many installments have no interest charges. Installments beyond this number may include interest.

​
Next Steps

Processing Transactions

Learn how to process installment payments

Payment Methods

Query available payment methods

Transaction Status

Check transaction status

Error Handling

Handle API errors properly

Build docs developers (and LLMs) love

Get started for freeTalk to us