Transaction states

Payments

Payments state flow

Example of a transaction_state notification posted to the callbacks.url

POST [url] // EXAMPLE: POST /callback/?order_id=ORD-12345-ABC
user-agent: Brite Callback
content-type: application/json
accept-encoding: gzip, deflate
{
    "merchant_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSCE1lcmNoYW50GICAgID4woQKDA",
    "transaction_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uGJX6itYBDA",
    "transaction_state": 6 // STATE_SETTLED
}

You should store the transaction_id alongside the order in your system.

transaction_state*	Transaction state name	Description	What to do?	Notification?
0	STATE_CREATED	Payment created in Brite’s system The first state of a deposit transaction. Transaction is created after the user has completed the KYC and selected the account to be debited.	-	-
1	STATE_PENDING	Payment ready for authorisation Occurs after merchant approval (if approval_required is set) and Brite risk engine (customer age, merchant blocklist, Brite blacklist) has been passed.	-	-
2	STATE_ABORTED	Payment failed with a reason. Please note: The transaction can still be settled at a later stage, so callbacks should still be listened to.	Return to the payment selection view.	Yes
3	STATE_FAILED	Payment failed unknown. Please note: The transaction can still be settled at a later stage, so callbacks should still be listened to.	Return to the payment selection view.	Yes
4	STATE_COMPLETED	Authorisation completed The customer has completed all required steps to authorise the payment. At this point, the bank needs to further process the payment.	Confirm the order / purchase to the customer.	Yes
5	STATE_CREDIT	Payment processed for sending The payment is now fully processed for sending. If the payment amount is equal or below the configured exposure limit in your merchant configuration, this state will trigger together with state 4.	Ship goods / credit the player.	Yes
6	STATE_SETTLED	Payment arrived (fully settled) - final state The payment was received in full and the funds are now scheduled to be paid to the merchant.	Ship goods / credit the player (if not already done before)	Yes
7	STATE_DEBIT	Payment lost - final state This can happen in rare cases, most often due to technical or other reasons. If the payment wasn’t received within a certain number of days, Brite will automatically declare the payment failed.	Reach out to the customer to pay again.	Yes

* only the numerical transaction_state is shared in the notification.

You can reduce the risk to payment failure to virtually zero if you wait for state 6 (STATE_SETTLED) to ship goods or credit the player.

While state 5 indicates that payment was sent, 6 means that the payment has arrived in full and it can’t be returned anymore. This, however, can take a couple more minutes or even to hours.

Unexpected successful payments

In rare cases a bank might label a payment wrongly as failed. Brite then sets the payment into the state 2 or 3 (STATE_ABORTED or STATE_FAILED) to then actually still receive the payment. This means that the customer actually paid successful and Brite received the funds. As a result, this payment is then updated to first to state 5 (STATE_CREDITED) and then 6 (STATE_SETTLED), meaning you still receive those notifications for this payment.

While Brite has systems to minimize these issues, we advise adding your own handling logic. Consider:

• Initiating a refund if the customer has made a duplicate payment.

• Contacting the customer to confirm how they wish to proceed with the funds.

Payouts and refunds

Payouts and refunds state flow

transaction_state	Transaction state name	Description	What to do?	Notification?
0	STATE_CREATED	Payout/refund created in Brite’s system The first state of a deposit transaction. Transaction is created after the user has completed the KYC and selected the account to be debited.	-	-
1	STATE_PENDING	Payout/refund ready for authorisation Occurs after merchant approval (if approval_required is set) and Brite risk engine (customer age, merchant blocklist, Brite blacklist) has been passed.	-	-
2	STATE_ABORTED	Payout/refund failed with a reason - final state	-	Yes
3	STATE_FAILED	Payout/refund failed unknown - final state	-	Yes
4	STATE_COMPLETED	Payout/refund completed Brite completed all required steps to send the payouts/refunds. At this point, the bank needs to further process the payment.	Confirm the payout / refund to the customer.	Yes
5	STATE_CREDIT	Payout/refund processed for sending The payment is now fully processed for sending.	-	Yes
6	STATE_SETTLED	Payout/refund was sent - final state The payout/refund was sent and is now expected to arrive on the customer’s bank account. This typically take only couple of seconds or minutes but Brite has no way to	Mark the payout/refund as completed (if not already done before)	Yes
-	-	Payout/refund failed - final state The payout/refund failed and the funds were returned back to Brite. Your merchant balance was updated. See returned funds This is not part of the regular notification and funds flow. Please see GUIDE TO CONFIGURE RETURNED FUNDS NOTIFICATION.	Reach out to the customer to choose another bank account or contact their bank.	Yes

Special handling in Sweden

In exceptional rare cases, payouts in Sweden can remain in STATE_PENDING = 1 for longer than anticipated. To avoid unnecessary delay, you should subscribe to STATE_COMPLETED = 4 , meaning that the payout has passed the STATE_PENDING and giving you a way to identify the remaining payouts.

 

Returned Funds Notification

If a refund or payout bounces back to Brite due to a rejection at the receiving bank even though it was initially successfully executed, Brite will create a returned funds transaction to pay these funds back to the merchant’s balance. This means the merchant has those funds available again but the customer didn’t receive their payout or refund.

In case funds are returned Brite sends a notification to the URL configured in Brite’s Back Office.

Example of the returned funds notification

POST [back_office_configured_url]
user-agent: Brite Callback
content-type: application/json
accept-encoding: gzip, deflate
{
    "merchant_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSCE1lcmNoYW50GICAgID4woQKDA",
    "transaction_id": "ag9ofmFib25lYS0xNzYyMTNyFAsSB1Nlc3Npb24YgICAjeqInQgM",
    "original_transaction_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uGJX6itYBDA",
    "notification_type": "RETURNED_TRANSACTION",
    "country_id": "se",
    "amount": 299.95
}

What to do with returned funds?

If you get a notification about returned funds, it means the refund or payouts failed and the customer didn’t receive their funds. The id of the failed refund or payout is provided in original_transaction_id. This way you can label the original refund or payout as failed and highlight it your system.

There are different reasons for that, and while Brite is most often not informed about the actual reason, some examples are:

• Bank account does not exist

• Bank account closed or blocked

• Format of the bank account number is not correct

• Other unknown reasons

However, even though it is defined, a retry is unlikely to succeed. As a result we recommend:

1. Asking the customer to choose another bank account or

2. Asking the customer to reach out to their bank.

If there is an issue with the bank account, it is only the customer who is able to resolve it. Brite has no right to request further details from the bank, let alone...