Planos de taxas das organizações filhas

Esta página só se aplica a contas com o produto Chargefy for Platforms habilitado. Nesse produto, uma plataforma opera pagamentos para suas organizações filhas.

Um plano de taxas define quanto uma organização filha paga em cada venda: um percentual e um valor fixo para cada condição de pagamento (método, bandeira e número de parcelas). Sua plataforma pode ter vários planos. Um deles é o padrão, e cada organização filha segue o padrão ou usa um plano fixado. Você cria e edita os planos no painel da plataforma, em Configurações da plataforma → Planos de taxas. Pela API, você consulta os planos e escolhe qual deles cada organização paga.

A taxa da plataforma e a sua margem

Cada venda de uma organização filha paga uma taxa só: a do plano dela. Dessa taxa sai o custo contratado com a Chargefy para a mesma condição, e o restante é a margem da sua plataforma. Exemplo fictício, numa venda de R$ 100,00 no Visa 1x:

Parte	Condição	Valor
Taxa do plano, paga pela organização	3,99%	R$ 3,99
Custo contratado	2,99%	R$ 2,99
Margem da plataforma	—	R$ 1,00

A organização filha vê só a taxa do plano no extrato dela (platform_fee). A divisão entre custo e margem aparece apenas para a plataforma. Veja o objeto transaction. Nenhuma condição pode ficar abaixo do custo contratado. Ao editar um plano, o painel mostra o valor mínimo de cada condição e não aceita valores menores. O prazo de recebimento (settlement_days) e a antecipação (prepaid) também vêm do que foi contratado e não são editáveis no plano.

O plano Padrão e a etapa Defina sua taxa

Quando as condições da sua plataforma são liberadas, a Chargefy cria o plano Padrão com cada condição no custo contratado, sem margem, e o marca como padrão. As organizações filhas que seguem o padrão passam a pagar esse plano. Enquanto a taxa da plataforma não é definida:

o painel abre a etapa Defina sua taxa para quem administra a plataforma; os demais membros veem um aviso;
as vendas funcionam normalmente, com a taxa igual ao custo e margem zero;
se o custo contratado mudar, as condições do Padrão mudam junto, e você recebe fee.plan.updated.

A etapa termina quando você salva o Padrão, mesmo sem alterar valores, ou escolhe outro plano como padrão. A partir daí, as condições dos seus planos só mudam quando você as edita. Antes de as condições serem liberadas, a plataforma não tem planos: GET /v1/fee-plans devolve uma lista vazia, e as organizações filhas criadas nesse período ficam com fee_plan: "default". Elas passam a seguir o Padrão assim que ele é criado.

Qual plano cada organização paga

O campo fee_plan da organização mostra a escolha:

`fee_plan`	O que a organização paga	Quando você troca o plano padrão
`"default"`	As taxas do plano padrão atual.	Passa a pagar o novo padrão na próxima cobrança.
`"plan_k6F3mqMZ"`	As taxas desse plano.	Nada muda.

Para escolher pelo painel, abra a organização filha, vá à aba Taxas e use Trocar plano de taxas. Pela API, envie fee_plan ao criar ou atualizar a organização:

omitido: na criação, a organização segue o padrão; na atualização, o valor atual é mantido;
null ou "default": a organização segue o padrão;
ID de um plano da sua plataforma: a organização passa a usar esse plano.

A organização filha e o plano dela são os mesmos em teste e em produção, e o plano define o preço das vendas reais. Por isso fee_plan só é aceito com a chave de produção da plataforma (ch_live_...). Com chave de teste, omita o campo: a organização criada segue o padrão, e a atualizada mantém o plano atual. Enviar fee_plan em teste, mesmo null ou "default", retorna 400 livemode_mismatch. Para fixar um plano numa organização criada em teste, atualize-a com a chave de produção: repetir o create com o mesmo documento devolve a organização existente sem trocar o plano. Fixar um plano:

curl -X POST "https://api.chargefy.io/v1/organizations/org_Wq3zL8rTnV5kPm2X" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "fee_plan": "plan_k6F3mqMZ"
  }'

Voltar a seguir o padrão:

curl -X POST "https://api.chargefy.io/v1/organizations/org_Wq3zL8rTnV5kPm2X" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "fee_plan": "default"
  }'

Enviar o ID do plano que hoje é o padrão fixa esse plano: a organização não acompanha trocas futuras do padrão. Cada troca gera organization.updated com previous_attributes.fee_plan.

Status	`code`	Quando
`400`	`invalid_request`	`fee_plan` não é `null`, `"default"` nem um ID no formato `plan_*`.
`400`	`livemode_mismatch`	`fee_plan` foi enviado com chave de teste. Em teste, omita o campo.
`404`	`resource_missing`	Não existe plano com esse ID na sua plataforma.
`422`	`fee_plan_incompatible`	O recebimento já definido para o CPF/CNPJ da organização é diferente do recebimento dos planos da sua plataforma. Fale com o suporte.

Quando a taxa vale

A taxa de uma venda é a condição ativa do plano da organização no momento da cobrança. Exemplo:

Às 10h, o comprador abre um checkout. O Visa 1x do plano está em 3,99%.
Às 11h, você edita o plano e o Visa 1x passa para 4,29%.
Às 12h, o comprador paga. A cobrança usa 4,29%.

Cobranças já processadas não mudam. Renovações de assinatura e novas tentativas de pagamento usam a taxa em vigor no momento de cada cobrança.

Editar um plano

Editar uma condição cria uma condição nova, com id novo, no lugar da anterior. O plano mantém o seu id, e todas as organizações que pagam esse plano, fixado ou pelo padrão, pagam as condições novas a partir da próxima cobrança. Antes de salvar, o painel mostra quantas organizações serão afetadas e o que muda em cada condição. Para manter o preço negociado com parte das organizações, crie outro plano e fixe-o nelas antes de editar. Planos não são apagados.

Consultar pela API

Use a API key da plataforma, sem o header Organization. Para descobrir o plano padrão atual:

curl -X GET "https://api.chargefy.io/v1/fee-plans?is_default=true" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}"

{
  "object": "list",
  "data": [
    {
      "id": "plan_nVTh3XtU",
      "object": "fee_plan",
      "...": "demais campos do fee_plan",
      "is_default": true,
      "name": "Padrão"
    }
  ],
  "has_more": false,
  "url": "/v1/fee-plans"
}

Para saber quanto uma organização paga, leia organization.fee_plan. Com "default", use o plano com is_default: true; com um ID, consulte GET /v1/fee-plans/{id}. As condições ficam em rates, com fee_rate em pontos-base (399 = 3,99%) e fixed_fee_amount em centavos. O formato completo está no objeto fee_plan.

Eventos

Evento	Quando acontece
`fee.plan.created`	Um plano foi criado no painel, ou a Chargefy criou o Padrão.
`fee.plan.updated`	Nome, descrição, condições ou plano padrão mudaram, inclusive quando o Padrão acompanha o custo contratado antes de a taxa ser definida.
`organization.updated`	O `fee_plan` de uma organização filha mudou. Trocar o plano padrão não gera este evento.

Os eventos fee.plan.* chegam aos endpoints com events_from: "platform", um por modo (teste e produção). Neles, o campo top-level organization é a organização da sua plataforma.

Visão geral

Ativação de organizações

Planos de taxas

Marca e domínio próprio

Modelo de negócio

Planos de taxas das organizações filhas

A taxa da plataforma e a sua margem

O plano Padrão e a etapa Defina sua taxa

Qual plano cada organização paga

Quando a taxa vale

Editar um plano

Consultar pela API

Eventos

Próximos passos

Objeto fee_plan

Operar organizações conectadas

​A taxa da plataforma e a sua margem

​O plano Padrão e a etapa Defina sua taxa

​Qual plano cada organização paga

​Quando a taxa vale

​Editar um plano

​Consultar pela API

​Eventos

​Próximos passos

Objeto fee_plan

Operar organizações conectadas

A taxa da plataforma e a sua margem

O plano Padrão e a etapa Defina sua taxa

Qual plano cada organização paga

Quando a taxa vale

Editar um plano

Consultar pela API

Eventos

Próximos passos