GuidesAPI ReferenceCommunity
GuidesCommunityLog In


Overview of the billing system and how it works.

The Bit Capital platform has built-in features for Mediators to setup fees to their consumers. This enable positive financial results for the operation, without a huge overload of software implementation.

Services and theirs fees are configured using APIs and can be changed at runtime.

For example, these are a sample of types of fees that can be charged to one or more consumers:

  • Fixed amounts: For example: 1.00 BRL for emitting deposit boletos.
  • Percentage amounts: For example: 0.05 (5%) for withdrawals using TEDs.

How it works

The big picture is that consumers are charged for the usage of services. These fees are charges that will be on the consumer's invoices.


A plan is a set of configuration and contain a list of services, each one with their fee and way of charge, that can be charged on monthly, weekly or daily basis.
You can have multiple plans and associate each one of them with specific customers to create billing tiers with your users.
Each plan has the following fields:




An array of entries that include informations about each "billable service" in the plan.


Configurations about how this plan will work


This configuration lets the mediator control how the invoice closing flow will work.


This field lets you control the periodicity of the invoice closing process.
Can be monthly, weekly or daily.


If the periodicity is set to monthly, you can use this field to set which day of the month the invoice will close.


If the periodicity is set to weekly, you can use this field to set which day of the month the invoice will close. The value must be between 0 (Sunday) and 6 (Saturday).


When the settlement will be made on the plan, can be:

  • invoice_closing(default)
  • period_closing


The ID of the domain associated with the plan


The starting date that the plan will be valid from


Flag to define if this will be the default plan for the domain

You can check out how to create a plan in our docs.


One service is described as the chargeable usage item on platform. Each consumer can use a service and be charged (or not) for their usage.
Configuration of one or more services can be setup differently in each plan.
You can check out more detailed informations about which services exist in the system in the Services section.

Service Entries

An entry is a registration of some service consumed by some user in a certain time. They're used to reference how to charge a consumer in a certain plan. Here are the possible fields:




A friendly name for this entry. It'll appear on the invoice.


The price of the tariff associated with the service.


When the billing of this entry will be charged, the possible fields are:

  • transaction
  • period_closing
  • invoice_closing


How many free entries the consumer will have before starting to charge.


Type of the entry, the possible fields are:

  • service_charge (default)
  • commission
  • progressive_discount
  • incentive
  • penalty
  • tax


The ID of the service which will trigger this service entry. You can retrieve the possible services in this endpoint.

You can always edit the service entries in a plan using the API. When edited the newly created transactions will be billed with the new value.


A subscription is the association of a consumer to a specific plan. We have two types of subscription:

  • Pre-paid: All invoice entries are billed in the act of consuming a specific service. If the user does not have enough balance for the entry and the transaction the system will reject the transaction with a Not Enough Balance error.
  • Post-paid: Invoice entries are generated on every transaction but not billed. You can check the consolidated amount to be billed manually in the invoice closure.
    You can check how to subscribe to a specific plan in our docs.

Migration from one subscription to another

If you wish to migrate a user to another plan, just use the sabe subscription endpoint with the new plan but with the flag force set to true, the system will automatically end the current subscription and subscribe the user in the new one.


Invoices are the usage overview of a customer for a specific period. They're are closed automatically when configured the periodicity on a plan. You can also force close one using this endpoint.

What’s Next
Did this page help you?