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 nameRequired?Additional Information
eventYesCan be one of:
- authorization
- authorization_reversal
- authorization_dry_run
- settlement
- refund
typeYesThe type of the payment, today it's only allowed card and transaction_reversal.

For more info check out Types of Payments.
assetYesThe asset code that you want to authorize (for example BRLP).
amountYesThe amount(in string) to be blocked in the authorization. For example "20.00".
walletIdYesThe ID of the source wallet of the authorization.
transactionIdNo*Is required for events settlement, authorization_reversal and refund
transitoryAccountTypeNoIn 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
additionalDataNoAn 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:

578

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:

597

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:

555

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:

581

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 TypeReasonAdditional Information
INSUFICCIENT_BALANCEInsufficient balance
PENDING_TRANSACTIONSInsufficient balance due to pending transaction(s)The user has balance but it's already authorized for another transaction
TRANSACTION_NOT_FOUNDTransaction not foundThe transaction sent in the authorization request was not valid
NON_REVERSIBLE_STATETransaction is not in a reversible stateThe transaction can't be reversed.
NOT_AUTHORIZEDTransaction must be authorized in order to be settledThe transaction can't be settled.
NON_REFUNDABLE_STATETransaction is in a non-refundable stateThe transaction can't be refunded.
INTERNAL_ERRORAuthorization failed due to internal errorInternal error in the system.
FSM_ERRORCould not perform state transition to executedSome error in the FSM did not let the transaction state transition be performed.
WALLET_NOT_READYWallet is not in the required status for this operationThe wallet is not in the ready state.
USER_NOT_READYUser is not in the required status for this operationThe user is not in the active state.
CONSUMER_NOT_READYConsumer is not in the required status for this operationThe consumer is not in the ready state.
EXCEEDS_DAILY_LIMITTransaction exceeds daily limitThe transaction exceeds the user's daily limits.
CURRENCY_NOT_SUPPORTEDBilling currency is not supportedThe asset configured in the Billing Services
ASSET_NOT_FOUNDAsset is not authorizableThe asset inputed was not found.
ASSET_NOT_AUTHORIZABLEAsset is not authorizableThe asset is not authorizable (required to be configured, in this case open a ticket in our help desk).