GuidesAPI ReferenceCommunity
GuidesCommunityLog In

Authorization API

Enable external services and partners to authorize their transactions inside enterprise instances of the Bit Capital Platform.


Experimental API

This feature is still in the experimental phase. It is only supported in SaaS and may change with time. For enabling the permissions for your credentials, ask us in our help desk.

When you are using other services outside BT Core that needs to be integrated with your users balances, it can be difficult to use the traditional GET /wallets/:id and POST /payments, for many reasons, for example:

  • In cases of card transactions, for example, it needs to have a really low response time(usually around 500ms for good UX), using more than one method call and loading a lot of unused data may consume milliseconds that you don't have.
  • In case of PIX transactions, that needs to have a lot of account checks on receiving and sending instant payments, you need a quick way to integrate it in our core banking.

For that, we provide an API focused on quick and reliable transaction authorizations, that inclused two-step authorizations (settlement flow is separated from the authorization one) and it's reversals (refunds and authorization reversals).

How to use?

For start using the authorization API, you simply need to send a request to POST /transactions/authorize with the given values:

Field name


Additional Information



Can be one of:

  • authorization
  • authorization_reversal
  • authorization_dry_run
  • settlement
  • refund



The type of the payment, today it's only allowed card and transaction_reversal.

For more info check out Types of Payments.



The asset code that you want to authorize (for example BRLP).



The amount(in string) to be blocked in the authorization. For example "20.00".



The ID of the source wallet of the authorization.



Is required for events settlement, authorization_reversal and refund



In case you want to send the amount of the transaction to a explicit transitory account, can be one of:

  • boleto_payment
  • card_transaction
  • service_fee



An optional field for non-structured data about the transaction.

For examples of requests and responses, check out our docs.

Transitory Accounts

For using the Authorization API it's really important to understand how a transitory account works in it. Basically, in every authorization, the balance authorized is sent to a transitory wallet in the system which will hold this "authorized balances" for future settlement with the external provider. Every type of payment type can have it's own transitory account, but if you wish you can explicitly tell which transitory account to be used with the transitoryAccountType field.

It's also important to say that, currently, you can only have one transitory account for each type of payment in the system.

For creating a new transitory account, you'll need to open a ticket in our help desk.

Dry Running

A dry run is a testing process where the effects of a possible failure are intentionally mitigated. For example, an aerospace company may conduct a "dry run" test of a jet's new pilot ejection seat while the jet is parked on the ground, rather than while it is in flight. In case of our Authorization API when testing something in production you may want to avoid actually authorizing something, for that we have a dry run mode, it accepts the same fields as the authorization API but it's in the route /transaction/authorize/dry-run. In this case the system will replicate all it's validations for the specified flow but won't create any transactions.


The authorization flow is the first step in the authorizer API, it creates a new transaction in a AUTHORIZED state, following the diagram below:

Authorization flow diagramAuthorization flow diagram

Authorization flow diagram

For examples of request and responses for this flow, check out our docs.

Authorization Reversal

The authorization_reversal flow is for when you have authorized a transaction previously, and *did not settled it but needs to revert it. The reversal flow follows this diagram:

Authorization reversal flowAuthorization reversal flow

Authorization reversal flow

For examples of request and responses for this flow, check out our docs.


The settlement method gets a transaction that was previously authorized and moves it to a settled state(executed).
After the settlement, the transaction cannot be reversed anymore and the only way to revert it is using the refund flow. It's also important to notice that when a transaction is settled, the destination wallet can use the balance from this authorization freely and the system can no longer guarantee that the amount will be available for future refunds.
The settlement flow follows this diagram:

Settlement flowSettlement flow

Settlement flow

For examples of request and responses for this flow, check out our docs.


The refund flow is used for when you already have settled a transaction, but it needs to refund it for some reason. In this case is important to notice that if the transitory account does not have the available balance the refund authorization will be rejected.
The refund flow follows this diagram:

For examples of request and responses for this flow, check out our docs.

Handling authorization responses

The Authorization API, different from other services in BT Core has a single structure response in successful and failed requests, that follows the structure bellow:
in success cases:

  "transactionId": "c5dbbf84-e243-4d02-beb3-3890ec702391", // The transaction referenced by this authorization
  "authorized": true // The result of the authorization

In error cases:

// 200 OK
// Requests that don't result in request error will return HTTP CODE 200
  "reason": [
    "Transaction is in a non-refundable state" // reason of the error
  "authorized": false // result of the authorization

Below, we describe the different types of erros the authorization API can answer:

Error Type


Additional Information


Insufficient balance


Insufficient balance due to pending transaction(s)

The user has balance but it's already authorized for another transaction


Transaction not found

The transaction sent in the authorization request was not valid


Transaction is not in a reversible state

The transaction can't be reversed.


Transaction must be authorized in order to be settled

The transaction can't be settled.


Transaction is in a non-refundable state

The transaction can't be refunded.


Authorization failed due to internal error

Internal error in the system.


Could not perform state transition to executed

Some error in the FSM did not let the transaction state transition be performed.


Wallet is not in the required status for this operation

The wallet is not in the ready state.


User is not in the required status for this operation

The user is not in the active state.


Consumer is not in the required status for this operation

The consumer is not in the ready state.


Transaction exceeds daily limit

The transaction exceeds the user's daily limits.


Billing currency is not supported

The asset configured in the Billing Services


Asset is not authorizable

The asset inputed was not found.


Asset is not authorizable

The asset is not authorizable (required to be configured, in this case open a ticket in our help desk).

Did this page help you?