Tarifas

Algumas operações podem gerar uma tarifa. A API sempre informa o valor cobrado em centavos, e você não precisa calcular nada: a plataforma aplica a tarifa configurada para a sua conta e devolve o valor efetivamente cobrado no status da transação.

Onde a tarifa aparece

O campo fee no status da transação (GET /transfers/:id para TED e o status do PIX) traz a tarifa cobrada por aquela operação, em centavos. Quando não há tarifa, o valor é 0.

Como a tarifa é cobrada

• Unidade: centavos, igual a todos os valores da API. Uma tarifa de R$ 5,00 chega como 500.
• Momento: a tarifa é cobrada quando a operação se conclui. No PIX de saída ela é lançada de forma assíncrona, logo após a liquidação, então o campo fee pode aparecer como 0 numa primeira consulta e passar a refletir o valor cobrado numa consulta seguinte.
• Fonte da verdade: o fee do status é a soma do que foi efetivamente lançado no razão de tarifas para aquela transação. É esse valor que você deve usar para conciliar.
• Limite: a tarifa nunca consome a transação inteira. O valor cobrado é sempre menor do que o montante da operação.
• Débito: a tarifa é debitada da conta que originou a operação, além do valor transferido.

Consultando a tarifa de um PIX

GET /api/partner/v1/pix/{transactionId}
Authorization: Bearer {{access_token}}

Resposta 200:

{
  "transactionId": "PIX20260711a1b2c3d4e5f6",
  "type": "pix_out",
  "status": "settled",
  "amount": 25000,
  "fee": 4,
  "recipientKey": "cliente@empresa.com.br",
  "endToEndId": "E9999900820260711100000abcdef123",
  "errorReason": null,
  "createdAt": "2026-07-11T10:00:00Z",
  "completedAt": "2026-07-11T10:00:02Z"
}

Neste exemplo a operação de R$ 250,00 (amount: 25000) teve uma tarifa de R$ 0,04 (fee: 4). O valor debitado da conta foi a soma dos dois.

Consultando a tarifa de uma TED

GET /api/partner/v1/transfers/{transactionId}
Authorization: Bearer {{access_token}}

O status da TED também expõe o campo fee em centavos, preenchido quando a TED liquida.

Catálogo de tarifas

Lista as tarifas ativas aplicáveis às suas contas. A gestão da tabela (valores e ativação) é feita pela VULCI Banco; a API é somente leitura.

GET /api/partner/v1/fees
Authorization: Bearer {{access_token}}

• Escopo: fee:read

Resposta 200:

{
  "data": [
    {
      "feeType": "ted_out",
      "clientType": "pf",
      "subType": null,
      "fixedAmount": 500,
      "percent": "0",
      "minAmount": 100,
      "maxAmount": 900,
      "chargingModel": "immediate",
      "freeTransactionsPerMonth": 0,
      "effectiveFrom": "2026-07-14",
      "effectiveUntil": null,
      "scope": "global"
    }
  ]
}

Os valores monetários (fixedAmount, minAmount, maxAmount) estão em centavos; percent é a parcela percentual da tarifa. scope indica a abrangência da regra: global (todas as contas), customer (um cliente) ou account (uma conta específica). effectiveFrom e effectiveUntil delimitam a vigência.

Tarifas cobradas

Lista as tarifas efetivamente cobradas das contas do parceiro, com a correlação para a transação que originou cada cobrança.

GET /api/partner/v1/fees/charges?account_id=10024270&from=2026-07-01&to=2026-07-14&page=1&per_page=50
Authorization: Bearer {{access_token}}

• Escopo: fee:read · Filtros opcionais na query string: account_id, origin_transaction_id, from, to, page, per_page (máximo 200).

Resposta 200:

{
  "data": [
    {
      "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
      "feeType": "pix_out_transfer",
      "amount": 350,
      "originTransactionId": "E9999900820260714210000aabbccdd0",
      "originTransactionType": "pix",
      "originAmount": 10000,
      "status": "posted",
      "accountId": 10024270,
      "chargedAt": "2026-07-14T21:00:00Z"
    }
  ]
}

status é posted quando a tarifa está lançada e reversed quando ela foi estornada. originTransactionId, originTransactionType e originAmount apontam para a transação principal e o valor dela.

Tarifa no extrato

A tarifa é sempre um lançamento separado da transação principal. No extrato (GET /accounts/{id}/statement), os lançamentos de tarifa têm type: "fee" e carregam dois campos de correlação: feeTransactionId, o identificador da cobrança (o mesmo id da listagem de tarifas cobradas), e originTransactionId, a transação que originou a tarifa.

Evento fee.charged

Se preferir ser notificado em vez de consultar, assine o evento de webhook fee.charged, entregue quando uma tarifa é cobrada:

{
  "feeTransactionId": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
  "accountId": 10024270,
  "feeType": "ted_out",
  "amount": 500,
  "originTransactionId": "E9999900820260714210000aabbccdd0",
  "originTransactionType": "ted",
  "originalAmount": 150075,
  "status": "posted",
  "chargedAt": "2026-07-14T21:00:00Z"
}

O formato da entrega e a validação de assinatura estão em Webhooks.

Operações sem tarifa

Alguns tipos de operação são gratuitos por exigência regulatória e sempre chegam com fee: 0, independentemente da configuração da conta:

• PIX de pessoa física, na condição de pagador ou recebedor, conforme a Resolução BCB nº 19/2020.
• Devolução de PIX.
• Serviços essenciais de conta de pagamento previstos na regulação vigente.

Quando há tarifa

As operações que podem gerar tarifa incluem, entre outras, PIX de saída de pessoa jurídica e TED. Os valores aplicados à sua conta são definidos no seu contrato com a VULCI Banco e podem ser consultados no catálogo de tarifas desta página. O resultado de cada cobrança chega no campo fee, na listagem de tarifas cobradas e nos lançamentos type: "fee" do extrato. Se precisar de uma condição diferente da vigente, fale com o seu contato comercial.

Boletos

A emissão e a liquidação de boletos ainda não estão disponíveis na Partner API. Quando forem liberadas, seguirão o mesmo modelo desta página: a tarifa da operação será informada em centavos no campo fee do status, sem que você precise calcular nada. O planejamento dessa funcionalidade está em andamento.