Pular para o conteúdo principal
As taxas do Z2Pay têm dois componentes que se somam: um percentual (o famoso MDR) e uma parcela fixa em centavos. Cada método de pagamento (Pix, boleto, cartão por parcela) tem sua própria taxa, além de taxas para saque, reembolso e chargeback.
Esta página é conceitual + referência do endpoint de consulta. Para entender como a taxa de plataforma entra na divisão de valores, veja Split.

​
Como a taxa é composta

Toda taxa é descrita por dois campos:
​
percentage
number
Percentual da taxa. Exemplo: 3.99 significa 3,99% sobre o valor da transação. Use 0 quando não há componente percentual.
​
fixed
number
Parcela fixa em centavos (inteiro). Exemplo: 350 significa R$ 3,50. Use 0 quando não há componente fixo.
Os dois componentes se somam. Uma taxa de cartão com percentage: 3.99 e fixed: 0 cobra apenas 3,99% do valor. Uma taxa de boleto com percentage: 0 e fixed: 350 cobra R$ 3,50 fixos por boleto, independente do valor.
Valores monetários são sempre inteiros em centavos. fixed: 350 = R3,50,nuncaR 3,50, nunca R 350,00. Veja Convenções.

​
Taxas resolvidas por conta

A tabela retornada pela API entrega o valor efetivo já resolvido para a sua conta. Você consulta a taxa final que se aplica às suas transações — sem precisar saber de onde ela vem nem combinar regras.
  • Quando uma taxa específica não está configurada, ela cai em 0 (percentual e fixo).
  • A taxa é por moeda (ISO 4217: BRL, USD…). Sem o parâmetro currency, a API usa a moeda padrão da sua conta.

​
A taxa de plataforma no split

Quando você usa Split para dividir o valor de uma transação entre recebedores, é possível injetar uma taxa de plataforma como um item do split. No payload de configuração do split, cada item tem um campo type:
​
type
string
Tipo do item de split. Valores possíveis: sale (venda — padrão), interest (juros) e platform_fee (taxa de plataforma).
Um item com type: "platform_fee" representa a parcela que vai para a conta da plataforma, separada das parcelas de venda dos recebedores. Isso é o que permite à plataforma reter sua margem sobre cada transação dividida.
As taxas do endpoint GET /fees são as taxas do PSP sobre a sua conta (Pix, boleto, cartão, saque, refund, chargeback). A platform_fee do split é uma divisão que você define dentro de uma transação. São conceitos distintos — não confunda. A mecânica completa de divisão, incluindo as regras de processingFee e liable, está em Split.

​
Endpoints

MétodoRotaDescrição
GET/feesRetorna a tabela de taxas resolvida da sua conta

​
Consultar a tabela de taxas

GET /fees Retorna as taxas resolvidas da sua conta: Pix, boleto, cartão de 1x a 12x, saque, reembolso e chargeback (taxa + multa). Cada taxa vem com percentage e fixed (centavos). A autenticação usa o header x-api-key (veja Autenticação).

​
Parâmetros de query

​
currency
string
Código da moeda em ISO 4217, com exatamente 3 letras (ex: BRL, USD). É convertido para maiúsculas automaticamente. Opcional — sem ele, a API usa a moeda padrão configurada na sua conta.

​
Exemplo de requisição

curl https://api.sandbox.z2pay.com/fees \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Filtrando por moeda: 
curl "https://api.sandbox.z2pay.com/fees?currency=BRL" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

​
Resposta 200 OK

{
  "currency": "BRL",
  "pix": { "percentage": 0.99, "fixed": 0 },
  "boleto": { "percentage": 0, "fixed": 350 },
  "creditCard": [
    { "installments": 1, "percentage": 3.99, "fixed": 0 },
    { "installments": 2, "percentage": 4.49, "fixed": 0 },
    { "installments": 3, "percentage": 4.99, "fixed": 0 },
    { "installments": 4, "percentage": 5.49, "fixed": 0 },
    { "installments": 5, "percentage": 5.99, "fixed": 0 },
    { "installments": 6, "percentage": 6.49, "fixed": 0 },
    { "installments": 7, "percentage": 6.69, "fixed": 0 },
    { "installments": 8, "percentage": 6.79, "fixed": 0 },
    { "installments": 9, "percentage": 6.89, "fixed": 0 },
    { "installments": 10, "percentage": 6.99, "fixed": 0 },
    { "installments": 11, "percentage": 6.99, "fixed": 0 },
    { "installments": 12, "percentage": 6.99, "fixed": 0 }
  ],
  "withdrawal": { "percentage": 0, "fixed": 367 },
  "refund": { "percentage": 0, "fixed": 0 },
  "chargeback": {
    "fee": { "percentage": 0, "fixed": 0 },
    "penalty": { "percentage": 0, "fixed": 0 }
  }
}
Os números acima são exemplos. As taxas reais da sua conta podem ser diferentes — a resposta sempre reflete o que está configurado para a sua company.

​
Campos da resposta

​
currency
string
Moeda das taxas retornadas (ISO 4217). Se você não passou currency na query, é a moeda padrão da conta.
​
pix
object
Taxa do método Pix. Objeto com percentage e fixed.
​
boleto
object
Taxa do método boleto. Objeto com percentage e fixed.
​
creditCard
array
Array com uma entrada por número de parcelas, de 1x a 12x (sempre 12 itens). Cada entrada tem installments (número de parcelas), percentage e fixed.
​
withdrawal
object
Taxa de saque/payout. Objeto com percentage e fixed.
​
refund
object
Taxa de reembolso. Objeto com percentage e fixed.
​
chargeback
object
Taxas relacionadas a chargeback. Contém dois sub-objetos: fee (taxa de chargeback) e penalty (multa de chargeback), cada um com percentage e fixed.
Taxas não configuradas vêm com percentage: 0 e fixed: 0. No exemplo acima, refund e chargeback estão zerados — isso significa que sua conta não tem cobrança configurada para esses casos.

​
Erros

O endpoint retorna 200 OK no caminho feliz. Erros de autenticação (chave inválida ou ausente) seguem o formato padrão da API. Veja Erros para a lista de status codes e o formato de resposta.

​
Veja também

Referência: Fees

Detalhe técnico do endpoint de taxas na Core API.

Split

Como dividir valores entre recebedores e injetar a taxa de plataforma.

Visão geral de valores

Como o Z2Pay calcula taxas, splits e liquidação.

Liquidação

Quando e como os valores líquidos caem na sua carteira.