Integrate

Brite Instant Payouts

This guide explains how to integrate Brite’s Instant Payouts API to send funds directly to your customers’ bank accounts.

Overview

Instant Payouts allow merchants to programmatically initiate transfers to customer bank accounts via the Brite API. The process involves authorising, creating a bank account if not available, requesting a payout to a known bank account and handling notifications about the payout's status. This means the integration consists of 4 or 5 steps depending if you pay out to a new bank account or already have a Brite bank account id (bank_account_id).

Merchant authorization
POST /api/merchant.authorize
Create a Bank Account (if you don’t have a bank account id already)
POST /api/bank_account.create or POST /api/session.create_bank_account_selection
Initiate a Payout
POST /api/transaction.create_withdrawal
Handle Callback Notifications
POST [callbacks[...].url] POST /api/transaction.get
Handle Returned Funds Notifications

Prerequisites: Bank Account ID

To initiate a payout, you need a bank_account_id representing the customer's registered bank account.

How to get a bank_account_id?

There are three ways to obtain a bank_account_id:

From a previous payment:
If the customer has previously made a payment using Brite, you can retrieve their bank_account_id by fetching the transaction details using POST /transaction.get.
Create a bank account via API:
You can create a new bank account record directly via the API if you have all the required bank account details available.
Create a bank account via the Brite Client:
Guide the user through the Brite Client to select or add their bank account using session.create_bank_account_selection (link to relevant documentation page).

Here we focus on the 2nd option, creating a bank account via the API.

Payout Process

Step 1: Merchant authorisation

POST /api/merchant.authorize

You need to authorise your access to Brite’s APIs. For that follow the steps outlined in Authorisation. As a result, you have an access_token which you add to your requests to the Brite APIs.

Authorization: Bearer <access_token>

Step 2: Create a Bank Account

Create a Bank Account via API

If you don't have a bank_account_id for the customer and choose not to use the session flow, you must first create one using the POST /bank_account.create endpoint.

Request: POST /bank_account.create


POST /bank_account.create HTTP/1.1
hostname: sandbox.britepayments.com
Authorization: Bearer 
{
  "country_id": "de",
  "iban": "DE89370400440532013000",
  "holder_firstname": "Hans",
  "holder_lastname": "Schmidt",
  "holder_dob": "1978-03-22",
  "holder_address": {
    "city": "Berlin",
    "postal_code": "10115",
    "street_address": "Musterstraße 1",
    "country": "Germany"
  }
}

For a full list of all parameters check out the API reference.

Importance of Customer Data

When creating a bank account via the API, providing accurate customer details (holder_firstname, holder_lastname, holder_dob, holder_address) is crucial for every request.

Compliance: Supplying this data helps meet Know Your Customer (KYC) requirements.
Payout Success: Accurate holder information can reduce the risk of payouts being rejected or delayed by the receiving bank.

Ensure you collect and provide the most accurate and complete customer information available when using this endpoint.

Understanding BBAN (for Sweden & Denmark)

The bban (Basic Bank Account Number) parameter is used instead of iban when country_id is "se" (Sweden) or "dk" (Denmark).

Format in Sweden:

The bban must be a concatenation of the Clearing Number and the Account Number, with no spaces or separators.

Clearing Number (Clearingnummer): Typically 4 digits (sometimes 5 for Swedbank).
Account Number (Kontonummer): Variable length, usually 7-10 digits.

Example (Sweden):

If Clearing Number is 8327 and Account Number is 991234567 the bban value should be: "8327991234567"

Format in Denmark:

The bban should be the standard Danish BBAN (often referred to as Reg.nr + Kontonummer, but provided as a single BBAN string according to Danish standards). No special concatenation is required by Brite beyond the standard format.

Response:

{
  "id": "ag9ofmFib25lYS0xNzYyMTNyFAsSB1Nlc3Npb24YgICAtevC9wOM"
}

The API will respond with the id of the newly created bank account.

Create Bank Account via Session (Brite Client)

If you don't have a bank_account_id for the customer and choose to use the Brite Client to retrieve one from your customer, you must use the POST /session.create_bank_account_selection endpoint. This approach initiates a session using the Brite Client where the user can select their bank and consent to sharing their account details. Upon successful completion, Brite provides the resulting bank_account_id, which you can then use for payouts. This method simplifies the process for you as Brite handles the bank selection UI and account detail retrieval directly from the user.

For detailed instructions on implementing this flow, please refer to the Data Solutions - Bank Account Selection guide.

Step 3: Initiate a Payout

Once you have the bank_account_id, initiate the payout using the POST /transaction.create_withdrawal endpoint.

Request: POST /transaction.create_withdrawal

POST /transaction.create_withdrawal HTTP/1.1
hostname: sandbox.britepayments.com
Authorization: Bearer <YOUR_TOKEN>
{
  "amount": 199.50,
  "bank_account_id": "ag9ofmFib25lYS0xNzYyMTNyFAsSB1Nlc3Npb24YgICAtevC9wOM",
  "merchant_reference": "PAYOUT-REF-45678",
  "statement_reference": "Your payout from Merchant ABC"
  "callbacks": [
    {
      "url": "https://your-merchant-site.com/callbacks/brite?order=45678",
      "transaction_state": 2
    },
    {
      "url": "https://your-merchant-site.com/callbacks/brite?order=45678",
      "transaction_state": 3
    },
    {
      "url": "https://your-merchant-site.com/callbacks/brite?order=45678",
      "transaction_state": 4
    },
    {
      "url": "https://your-merchant-site.com/callbacks/brite?order=45678",
      "transaction_state": 6
    }
  ]
}

Here we highlight some key parameters from the transaction.create_withdrawal request above. For a full list of all parameters, please consult the API reference.

merchant_reference

This is your internal reference for the transaction. While it can be any relevant string, setting it to a unique identifier for each payout attempt (unique per amount) enables idempotency (see Testing section).

statement_reference

This optional field allows you to specify a reference text that appear on the recipient's bank statement. Important: This parameter cannot be used for payouts to Sweden (SE) or Finland (FI).

Response:

{
  "id": "ag9ofmFib25lYS0xNzYyMTNyFAsSB1Nlc3Npb24YgICAjeqInQgM",
  "eta": 1739956658 
}

The API will respond with the id of the newly created payout transaction and an estimated time of arrival (eta).

Step 4: Handle Callback Notifications

Brite sends POST requests to the callback URLs provided in the transaction.create_withdrawal request (see Step 3) when the transaction reaches specific states (STATE_ABORTED, STATE_FAILED, STATE_COMPLETED, STATE_SETTLED).

Detailed information on how to receive, validate, and process these notifications is available in the dedicated callback handling documentation:

Integrate Callback Handling (Covers processing state updates, security, and best practices)

Step 5: Handle Returned Funds Notifications

In some rare cases, a payout might be returned by the bank after initially being settled (e.g. due to incorrect account details). Brite will notify you via a specific callback if you have configured one for returned funds. Note: This callback URL is a static one configured separately in your Brite Back Office settings, not within the API request itself.

Returned Funds Notification Payload:

{
  "transaction_id": "ag9ofmFib25lYS0xNzYyMTNyFAsSB1Nlc3Npb24YgICAjeqInQgM",
  "original_transaction_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uGJX6itYBDA",
  "notification_type": "RETURNED_TRANSACTION",
  "merchant_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSCE1lcmNoYW50GICAgID4woQKDA",
  "country_id": "se",
  "amount": 299.95
}

Action: Handle this notification by reconciling the returned funds and potentially contacting the customer to resolve the issue or find an other way to pay out the customer.

Testing Your Integration

Thorough testing is crucial before going live. Ensure you test the following scenarios in Brite's test environment:

Successful Payout

Create a bank account via API (if applicable).
Initiate a payout using transaction.create_withdrawal.
Receive and correctly process the STATE_SETTLED (6) callback.
Verify transaction details using transaction.get.

Failed Payout

Trigger failure scenarios via the API. See the Integration Test and Verification page for details on the specific test data or parameters to use.
Receive and correctly handle STATE_ABORTED (2) or STATE_FAILED (3) callbacks (as detailed in the Callback Handling guide).

Returned Funds

Trigger returned fund scenarios via the API in the test environment. See the Integration Test and Verification page for details on how to trigger these scenarios.
Receive and correctly process the RETURNED_TRANSACTION notification from the BackOffice-configured URL.

Idempotency

Verify idempotency using the merchant_reference field in transaction.create_withdrawal. The primary benefit is to prevent accidental duplicate payouts if the same request is sent multiple times due to network issues or retries.
If you send a request with a merchant_reference that has been used previously with the same amount, Brite will return the transaction_id of the original transaction instead of creating a new one.
If you send a request with a previously used merchant_reference but with a different amount, Brite will return an error.
Test both scenarios to ensure your system handles them correctly.

This documentation provides a guide based on the information in the supplied files. Remember to consult the full API reference for detailed parameter descriptions, error handling, and additional options.