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

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

Required?

Additional Information

event

Yes

Can be one of:

  • authorization
  • authorization_reversal
  • authorization_dry_run
  • settlement
  • refund

type

Yes

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

For more info check out Types of Payments.

asset

Yes

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

amount

Yes

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

walletId

Yes

The ID of the source wallet of the authorization.

transactionId

No*

Is required for events settlement, authorization_reversal and refund

transitoryAccountType

No

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

additionalData

No

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.

Authorization

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 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 flow

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

Settlement

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 flow

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

Refund

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

Reason

Additional Information

INSUFICCIENT_BALANCE

Insufficient balance

PENDING_TRANSACTIONS

Insufficient balance due to pending transaction(s)

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

TRANSACTION_NOT_FOUND

Transaction not found

The transaction sent in the authorization request was not valid

NON_REVERSIBLE_STATE

Transaction is not in a reversible state

The transaction can't be reversed.

NOT_AUTHORIZED

Transaction must be authorized in order to be settled

The transaction can't be settled.

NON_REFUNDABLE_STATE

Transaction is in a non-refundable state

The transaction can't be refunded.

INTERNAL_ERROR

Authorization failed due to internal error

Internal error in the system.

FSM_ERROR

Could not perform state transition to executed

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

WALLET_NOT_READY

Wallet is not in the required status for this operation

The wallet is not in the ready state.

USER_NOT_READY

User is not in the required status for this operation

The user is not in the active state.

CONSUMER_NOT_READY

Consumer is not in the required status for this operation

The consumer is not in the ready state.

EXCEEDS_DAILY_LIMIT

Transaction exceeds daily limit

The transaction exceeds the user's daily limits.

CURRENCY_NOT_SUPPORTED

Billing currency is not supported

The asset configured in the Billing Services

ASSET_NOT_FOUND

Asset is not authorizable

The asset inputed was not found.

ASSET_NOT_AUTHORIZABLE

Asset is not authorizable

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

Updated 4 months ago


Authorization API


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

Suggested Edits are limited on API Reference Pages

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