Bit Capital

The Bit Capital Developer Hub

Welcome to the Bit Capital developer hub. You'll find comprehensive guides and documentation to help you start working with the platform as quickly as possible, as well as support if you get stuck. Let's jump right in!

Guides    Community

Overview

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.


Plans

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:

FieldDescription
itemsAn array of entries that include informations about each "billable service" in the plan.
billingSettingsConfigurations about how this plan will work
billingSettings.invoiceClosingThis configuration lets the mediator control how the invoice closing flow will work.
billingSettings.invoiceClosing.periodicityThis field lets you control the periodicity of the invoice closing process.
Can be monthly, weekly or daily.
billingSettings.invoiceClosing.dayOfMonthIf the periodicity is set to monthly, you can use this field to set which day of the month the invoice will close.
billingSettings.invoiceClosing.dayOfWeekIf 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).
billingSettings.settlementTriggerWhen the settlement will be made on the plan, can be:
invoice_closing(default)
period_closing
domainThe ID of the domain associated with the plan
validFromThe starting date that the plan will be valid from
defaultFlag to define if this will be the default plan for the domain

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


Services

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:

FieldDescription
nameA friendly name for this entry. It'll appear on the invoice.
priceThe price of the tariff associated with the service.
billingTriggerWhen the billing of this entry will be charged, the possible fields are:
transaction
period_closing
* invoice_closing
freeUntillHow many free entries the consumer will have before starting to charge.
entryClazzType of the entry, the possible fields are:
service_charge (default)
commission
progressive_discount
incentive
penalty
tax
serviceIdThe 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.


Subscription

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

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.

Updated 2 months ago


What's Next

Services

Overview


Overview of the billing system and how it works.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.