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:
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:
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:
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 over 2 years ago