In-depth Knowledge

Settlements and reconciliation

Welcome to our guide on retrieving your reconciliation / settlement files! These files are crucial for keeping your records aligned with your payment transactions. We understand that accessing this data needs to be straightforward, so we’ve provided two convenient options: a simple download from our Back Office and a powerful API for automated retrieval. This guide will walk you through each method, ensuring you can easily access and understand your reconciliation data.

Back Office

You can easily download the reconciliation files directly from the Back Office. By setting specific filters you can narrow down the content of the exported CSV file to the timeframe / market you need.

All filter options are described in the Back Office Manual. The output of the export is a CSV File. Further down this page you find an explaination of the file contents (fields) and the structure and how to interpret this data properly.

Export via API

Our Export API enables you to automate the retrieval of reconciliation files, facilitating seamless integration with existing systems. This section provides the necessary information for utilizing the API effectively.

In order to retrieve the files via API you have to follow a two-step approach.

Initiate an export with specific filters
POST /api/merchant.authorize POST /api/transaction.csv_export
Retrieve the exported file
POST /api/export_task.get

You can find a swimlane for the full process of exporting and retrieving the reconciliation files via API.

Merchant authorisation

POST /api/merchant.authorize

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

Authorization: Bearer <access_token>

Initiate an export

POST /api/transaction.csv_export

With this API call you initiate the export of the reconciliation file. There are several filters you can send in to limit the content of the file to the transactions you need.

Requesting Transactions at 00:00 UTC We advise you to run this request at around 00:00 UTC for transactions from the previous day(s). With that you ensure that our day-end booking processes have been run successfully and all transactions have the right status for reconciliation purposes.

				
					POST /api/transaction.csv_export HTTP/1.1
Host: sandbox.britepaymentgroup.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>
    
{
    "settled_from": 1721772000,
    "settled_to": 1721858399,
    "states": ["6"],
    "country_ids": ["DE","BE"],
    "types": ["0","1"]
}

Here we highlight some parameters. For a full list of all parameters check out the API reference.

settled_from / settled_to - UNIX timestamp in seconds

With the fields settled_from and settled_to you define the timeframe of the transactions you want to have in your reconciliation export file.

states For reconciliation purposes only the settled transactions are relevant. Therefore the field states should be set to 6, which is the state for STATE_SETTLED. For a full list of states check out our transaction states.

types In this field you can define the types of transactions you want to reconcile. If you leave it empty, you’ll simply get all transaction types which have been settled in the selected timeframe. Nevertheless we want to point out a few fields in particular:

`type`	Type name	What is it for?
`0`	`TYPE_DEPOSIT`	This is a deposit or payment
`1`	`TYPE_WITHDRAWAL`	This is a withdrawal or payout
`4`	`TYPE_MERCHANT_DEPOSIT`	This is a merchant deposit to top up your Brite balance
`5`	`TYPE_MERCHANT_WITHDRAWAL`	This is a merchant withdrawal where you paid our funds from the Brite Balance to your own bank account

For a full list of types check out our transaction types.

100,000 Transaction File Limit The API export has a limit of 100.000 transactions per file! If you expect more transactions in one export, please make sure to use the limit and offset fields described in the API reference.

				
					{
    "task_id": "974285d4-2e7b-46a7-a0c5-760ae8969f15"
}

The response contains a task_id which is the unique identifier of this export task. You need that one to retrieve the actual file in the next step of the process.

Retrieve the file

POST /api/export_task.get

In order to retrieve the file, you have to send a request by using the previously received export task_id.

				
					POST /api/export_task.get HTTP/1.1
Host: sandbox.britepaymentgroup.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>
{
    "id": "974285d4-2e7b-46a7-a0c5-760ae8969f15"
}

				
					{
    "state": 4,
    "artifact_url": "https://storage.../csv-exports-.../376332f5b35ef5f....csv",
    "id": "65b7483e-0be2-457f-9fd0-83e3e2e15155"
}

state

The state describes the status of the export. The following table explains the different states and give an indication on how to act on those.

`state`	State name	What to do?
`1`	`CREATED`	The export task has been created. This does NOT mean it is completed!
`2`	`QUEUED`	The export is in the processing queue and will be processed shortly
`3`	`STARTED`	The export has been started to be processed
`4`	`COMPLETED`	The export is completed and the file is ready to be downloaded
`5`	`FAILED`	The export failed

artifact_url

The artifact_url is only part of the response if the state has reached the status 4, which means the export reached the status COMPLETED. This is the link to the export file, which you show download and store on your end.

Available 24 hours Generated files are available for 24 hours and then deleted.

File content & structure

The structure of the exported file is fixed and can’t be changed. The following fields are part of the export (not necessarily in this order).

fieldname	Description	Example
`id`	Unique Brite transaction identifier	ag9ofmFib25iYS0yNDkwMTRYFqSsC1RtyYW5zYWN0AW9uGlgdjWTM
`type`	Transaction type (see here)	Deposit
`merchant_reference`	Merchant generated reference number	Order09876521
`message`	Brite generated reference number	RF45000000002087512940
`amount`	Amount of transaction	199.99
`fee`	Fee amount for this transaction	0.56
`currency_id`	ISO Currency Code (3 digits)	EUR
`country_id`	ISO Country Code (2 digits)	DE
`customer_bank`	Customers bank name (optional)	Sparkasse
`customer_first_name`	Name of the customer (optional)	Max
`customer_last_name`	Name of the customer (optional)	Muster
`created`	UTC time when the transaction has been created	2024-07-02 13:08:04+00:00
`approved`	UTC time when the transaction has been approved	2024-07-02 13:08:04+00:00
`completed`	UTC time when the transaction has been completed	2024-07-02 13:10:41+00:00
`settled`	UTC time when the transaction has been settled	2024-07-02 13:12:57+00:00
`session_id`	Unique session identifier	ag9ofmFib15iYS0yNDkwMTRYFasSC1RtyYW5zYWN0AW9uGL6My2iX
`customer_id`	Brite generated unique customer identifier	ag9ofmFib25iYS0yNDkwMTRYFAsgB1Nic3Npb24yYGlCAis6MpdoM
`fee_id`	Unique fee identifier for all fees combined for a given time period. This refers to a transaction type called fee	ag9ofmFib25iYS0yNSkwMTRYFqSsCEN1c36vbWVyGlCAGJDT2JcJWA
`fail_reason`	Reason why a transaction has been failing (optional)	-

No negative sign All amount values are always shown are expressed in absolute terms without a positive or negative sign.

Example File

Here you can download an example file with random data to show the format and content of the file. We recommend creating a few test transactions and export your own files with your own merchant_reference fields to make sure you can process them correctly. Please note, that not all types in this example file might apply for you.

Download example .csv

Good to know

Fee handling

There are several ways to get to the fees which Brite charges.

Typically every transaction has a fee associated and this fee is shown in the line of the transaction.
We also collect all fees from one booking period (1 day) and combin them together in a fee_id, which you can find in the line of a transaction. Additionally we show a combined fee line with all fees added from that fee_id.
In some cases we might do a fee correction at the end of the month. If that is the case you'll see a “Fee Correction” in your export with the corrected amount. In case you get fees back, you'll see a line with the type "Fee Correction Deposit"; in case you have to pay more fees, you’ll see a line "Fee Correction Withdrawal".

PDF invoices

Typically at the end of the month we generate PDF invoices which contain your fees for the last month. These PDF files are sent via email to your finance contact and are not part of the API or Back Office functionality.

Merchant Reference

We highly recommend sending in a merchant_reference in the Payments or Payouts requests. By doing that you can send one identifier from your system into Brites system, which we’ll pass back to you in the reconciliation files which helps you to identify the related transaction in your system by using your very own numbers.

Export other transactions

You can use the above mentioned process to also generate any kind of transaction report for your purposes. You do that by adjusting the filters of the POST /api/transaction.csv_export API request.