This website uses cookies so that we can provide you with the best user experience possible. Cookie information is stored in your browser and performs functions such as recognising you when you return to our website and helping our team to understand which sections of the website you find most interesting and useful.
Transaction handling
The transaction handling API is used to get information on a specific ongoing or completed transaction. This API is also used to create withdrawals. The Brite API has a timeout of 60 seconds. Therefore, anyone who implements the Brite API should make sure to have a longer timeout value, for example, 65 seconds.
Note!
The system is not idempotent. Hence, calling the Brite API will always create a new transaction in the system. To add extra security, before re-triggering a transaction, make sure to call the transaction.get_by_merchantreference endpoint to search for the transaction in the Brite system. If it does not exist, it’s safe to create a new one. This approach only works if the merchant_reference used is unique.
Transaction states
The Get Transaction State API call is used to get the current state of an ongoing transaction. Once the transaction state reaches settled, merchants can with certainty assume that the funds will be transferred.
| Name | Id | Deposits | Withdrawals |
|---|---|---|---|
| STATE_CREATED | 0 | The first state of a deposit transaction. Transaction is created after the user has completed the KYC and selected the account to be debited. | The first state a withdrawal gets aftercreate_withdrawal is called. |
| STATE_PENDING | 1 | Occurs after merchant approval (ifapproval_required is set) and Brite risk engine (customer age, merchant blocklist, Brite blacklist) has been passed. | Automatically after the transaction has been created or after merchant approval (if approval_required is set) or depending on the withdrawal rules set in Backoffice. |
| STATE_ABORTED | 2 | The deposit has been aborted for a known reason, e.g. the customer entered the payment flow but later decided to cancel, or because of a misconfiguration in the customer bank. Please note: The transaction can still be settled at a later stage, so callbacks should still be listened to. | The withdrawal has been aborted for a known reason, e.g. the recipient account is invalid. Considered a final state. |
| STATE_FAILED | 3 | The deposit failed for an unknown reason (or was manually failed by Brite). Please note: The transaction can still be settled at a later stage, so callbacks should still be listened to. | The withdrawal failed for an unknown reason (or was manually failed by Brite). Considered a final state. |
| STATE_COMPLETED | 4 | The deposit flow has finished without errors in the customer bank. | The withdrawal flow has finished without errors in Brite’s bank. |
| STATE_CREDIT | 5 | Funds have not yet been settled, but the transaction was successful and a credit callback is sent from Brite. When the credit callback is received, the end user should be credited by the merchant. The transaction receives the state credit immediately after the state completed, unless the transaction amount exceeds the exposure limit (set in the Brite Backoffice, see Backoffice Guide) – then the credit callback will be sent just before the state Settled. | Occurs just before Settled state. |
| STATE_SETTLED | 6 | Deposit funds have arrived in the Brite bank account. The final state for a deposit. | Withdrawal funds have left the Brite bank account. Considered a final state. |
| STATE_DEBIT | 7 | When a deposit has been stuck in STATE_CREDIT for more than 15 days,the state will change to STATE_DEBIT and a deposit callback will be sent. | Not applicable for Withdrawals. |
Refunds
There are two ways to make a refund. Either in Brite BackOffice or through the API.
/api/transaction.create_refund is used when doing a refund through the API.
// example request
{
"callbacks": [
{
"url": "string", // required
"transaction_state": 1 // required
}
],
"amount": 0, // required
"merchant_reference": "string",
"transaction_id": "string" // required
}