fee_plan reúne as taxas por venda e exatamente uma tabela de juros de parcelamento. Nos planos criados no painel, as taxas e a tabela ficam fixas na criação. Vários planos podem reutilizar a mesma tabela. Para oferecer outra combinação, crie outro plano no painel. Planos especiais de repasse integral concedidos à plataforma acompanham a condição contratada e deixam os juros com a organização.
Nome e descrição podem ser editados. A API consulta os planos e permite atribuí-los às organizações filhas. O catálogo é compartilhado entre teste e produção; livemode indica o modo da consulta ou do evento.
Qual plano cada organização paga
organization.fee_plan identifica o plano atribuído. A organização permanece nele até uma troca explícita. O padrão (is_default: true) é usado ao criar organizações sem escolha de plano.
Ao criar ou atualizar uma organização, fee_plan: "default" ou null escolhe e fixa o padrão atual. Trocar o padrão posteriormente não altera as organizações existentes. Antes de haver um plano configurado, a organização pode retornar fee_plan: "default".
Exemplo: duas organizações recebem o plano de 3,99%. A plataforma cria um plano de 4,29% e o define como padrão. As duas mantêm 3,99%; uma organização criada depois recebe 4,29%.
Quando a taxa vale
Cada nova cobrança usa o plano atribuído à organização naquele momento, inclusive renovações e novas tentativas de pagamento. Cobranças já criadas mantêm suas condições. Mudar o nome de um plano não muda o valor pago.Editar um plano
Edite o nome e a descrição. Para mudar as taxas ou os juros, crie outro plano e atribua-o às organizações desejadas. Planos não são apagados.string
ID da tabela de juros fixada na criação, como
"00199". Vários planos podem compartilhar essa tabela.Taxas e recebimento
rates lista as condições ativas do plano, uma por combinação de método,
bandeira e parcelas, sempre na mesma ordem: método (boleto, credit_card,
pix), bandeira (null primeiro, depois amex, elo, mastercard e visa)
e parcelas. Hoje um plano tem 62 condições: 12 parcelas de crédito para cada
uma das cinco curvas de bandeira, Pix e boleto. Trate a quantidade como
variável.
fee_rateusa pontos-base:399significa 3,99%.fixed_fee_amountusa centavos:99significa R$ 0,99.- No crédito,
card_brand: nullvale para as demais bandeiras aceitas. Ela não substitui a condição de Visa, Mastercard, American Express ou Elo. Em Pix e boleto,card_brandé semprenull.
prepaid e settlement_days vêm do recebimento contratado e não são editáveis
no plano. No crédito, prepaid: false mantém o recebimento no fluxo das
parcelas; true indica recebimento antecipado. Consulte os dois campos: o
prazo sozinho não define o fluxo de recebimento.
Somente leitura
A API só consulta planos: listar e consultar. Criar e editar acontece no painel da plataforma.POST e DELETE em /v1/fee-plans respondem 405.
Eventos
Os eventos
fee.plan.* chegam só aos endpoints com events_from: "platform",
um por modo (teste e produção). O campo top-level organization é a
organização da sua plataforma.
Data Object
string
Identificador público do plano. Usa o prefixo
plan_* e não muda quando as
condições são editadas.string
Sempre
"fee_plan".string
Criação do plano, em ISO 8601.
string | null
Descrição definida no painel. Vem
null quando não foi informada.string
Sobre qual valor o percentual incide. Os planos criados pela plataforma usam
chargeable. Planos especiais de repasse integral podem usar total.boolean
true no plano padrão da plataforma. Existe um único padrão por vez.boolean
Modo da consulta ou do evento. O plano é o mesmo nos dois modos.
object
Sempre
{}: os planos são criados e editados no painel.string
Nome do plano, definido no painel.
boolean
true quando o recebimento do crédito é antecipado; false quando segue o
fluxo das parcelas.array
Condições ativas do plano, em ordem estável.
string
Última mudança de nome, descrição, condições ou
is_default, em ISO 8601.