VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pagamentos

Parcelas

Opções de parcelamento da loja e simulador de parcelas Pagar.me.

Cartão de crédito no Brasil costuma ser parcelado. Estas duas rotas públicas calculam as opções para mostrar ao cliente: uma com a configuração da loja e outra como simulador do Pagar.me. Valores sempre em centavos.

Parcelas da loja

Calcula as opções de parcelamento de um valor usando a configuração da loja: máximo de parcelas, parcela mínima, quantas são sem juros e a taxa de juros. É a rota que mostra "3x sem juros" na página do produto e no carrinho.

GET/api/v1/storefront/installmentsPública

Opções de parcelamento conforme a configuração da loja

Parâmetros de consulta

amountintegerobrigatório
Valor em centavos, maior que zero.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/installments?amount=29900"

Resposta

200Opções de parcelamento
json
{
  "amount": 29900,
  "installments": [
    {
      "installments": 1,
      "value": 29900,
      "total": 29900,
      "interest_free": true
    },
    {
      "installments": 2,
      "value": 14950,
      "total": 29900,
      "interest_free": true
    },
    {
      "installments": 3,
      "value": 9967,
      "total": 29900,
      "interest_free": true
    },
    {
      "installments": 4,
      "value": 7475,
      "total": 29900,
      "interest_free": false
    }
  ]
}

Campos da resposta

amountinteger
O valor consultado, em centavos.
installmentsarray

Uma opção por número de parcelas.

installmentsinteger
Número de parcelas.
valueinteger
Valor de cada parcela, em centavos (arredondado para cima).
totalinteger
Total pago, em centavos. Maior que amount quando há juros.
interest_freeboolean
true quando a opção não tem juros.

Erros

StatusQuandoCorpo de exemplo
400amount ausente.{"error":"amount query parameter is required"}
400amount não é um inteiro positivo.{"error":"amount must be a positive integer (centavos)"}
A lista para quando a parcela fica pequena

Se a parcela mínima da loja (R$ 5,00 por padrão) não for atingida, as opções maiores nem aparecem. A taxa é composta por mês sobre o valor; sem taxa configurada, total é igual a amount mesmo nas opções com interest_free: false.

Simulador de parcelas Pagar.me

Calculadora de parcelas pela tabela Price (juros compostos, parcelas iguais). Ao contrário da rota da loja, os parâmetros vêm da consulta e, quando você não os envia, de padrões fixos (12x, 3 sem juros, 2,49% ao mês); ela não lê a configuração da loja. Exige o módulo pagarme.

GET/api/v1/storefront/pagarme/installmentsPública

Simula parcelas com a tabela Price e parâmetros da consulta

Parâmetros de consulta

amountintegerobrigatório
Valor em centavos, maior que zero.
max_installmentsintegerpadrão: 12
Máximo de parcelas, de 1 a 12. Fora disso vale 12.
interest_freeintegerpadrão: 3
Quantas parcelas sem juros (a partir de 1x). 0 equivale a 1.
interest_ratenumberpadrão: 2.49
Juros ao mês, em %. 0 volta ao padrão 2.49: não dá para simular "sem juros" por aqui.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/pagarme/installments?amount=29900&max_installments=4"

Resposta

200Simulação
json
{
  "installments": [
    {
      "number": 1,
      "installment_value": 29900,
      "total_value": 29900,
      "interest_amount": 0,
      "interest_rate": 0,
      "interest_free": true,
      "label": "1x de R$ 299,00"
    },
    {
      "number": 4,
      "installment_value": 7947,
      "total_value": 31788,
      "interest_amount": 1888,
      "interest_rate": 2.49,
      "interest_free": false,
      "label": "4x de R$ 79,47 com juros"
    }
  ],
  "total": 2
}

Campos da resposta

installmentsarray

Uma opção por número de parcelas viável.

numberinteger
Número de parcelas.
installment_valueinteger
Valor de cada parcela, em centavos.
total_valueinteger
Total pago, em centavos.
interest_amountinteger
Juros totais, em centavos.
interest_ratenumber
Juros ao mês, em %; 0 nas sem juros.
interest_freeboolean
true se sem juros.
labelstring
Texto pronto em português, por exemplo 3x de R$ 99,66 sem juros.
totalinteger
Quantidade de opções devolvidas.

Erros

StatusQuandoCorpo de exemplo
400amount ausente.{"error":"amount query parameter is required"}
400amount inválido.{"error":"amount must be a positive integer (centavos)"}
403O módulo pagarme está desligado nesta loja.{"error":"module_disabled","module":"pagarme"}
Não use como fonte do preço final

A cobrança de cartão no Pagar.me usa o valor do pedido. Se a sua tela mostrar parcelas desta rota com taxas diferentes das que a loja cobra, o cliente vê um número e paga outro. Prefira a rota da loja ou envie exatamente as taxas da loja.

Veja também

  • Formas de pagamento
  • Cobrança no Pagar.me
Anterior
Formas de pagamento
Próxima
Cobrar um pedido
Nesta página
  • Parcelas da loja
  • Simulador de parcelas Pagar.me
  • Veja também