Settlement Report
Report overview
The Settlement Report provides an overview of transactions and upcoming settlement disbursement. You will be able to view pending settlement, settlement amount, when to expect it, and what fees were removed. With the settlement data, you can spend less time on manual tasks and reconciliation.
Report columns
The response will be a JSON-formatted response which will consist of a collection of CardSettlementRecord records. The fields of each CardSettlementRecord are summarized in the table below.
Field |
Description |
|---|---|
merchant_id |
The id of the merchant. |
transactions_date |
The day the transactions settled. |
currency |
The currency (CAD, USD) of the settlement. |
settlement_net_amount |
Total amount (net) of the settlement. |
settlement_state |
The current state (scheduled, approved, etc.) of the settlement. |
settlement_date |
The day funds are expected to be settled. |
approved_transaction_count |
The total count of transactions that were approved. |
declined_transaction_count |
The total count of transactions that were declined. |
sale_amount_total |
Total amount of sales of the settlement. |
returned_amount_total |
Total amount of returns of the settlement. |
chargebacks_count |
Total count of chargebacks. |
chargebacks_amount_total |
Total amount (i.e. monetary total) of chargebacks. |
card_transaction_approved_rate |
Rate for approved transactions. |
card_transaction_declined_rate |
Rate for declined transactions. |
card_discount_rate |
Credit card discount rate fee (i.e. 3%). |
gst_tax_rate |
GST rate applied to fees. |
approved_transaction_fee_total |
Total fees for approved transactions of the settlement. |
declined_transaction_fee_total |
Total fees for declined transactions of the settlement. |
discount_rate_fee_total |
Total of the per-transaction fees. |
chargeback_fee_total |
Total of the chargeback fees. |
gst_tax_fee_total |
The total GST applied to transaction fees. |
reserves_held |
The amount currently held in a Worldline reserve account. |
reserves_released |
Amount released from the reserve account during the current statement period. |
reserves_forward |
Total amount that Worldline held in a reserve account as of the previous statement period. |
More detailed information about these fields can be found in our API specification which can be found here .
Getting started
The Settlement Report API is accessed via the URL https://api.na.bambora.com/v1/reports/settlement .
In addition, you will need to use your Merchant ID and Reporting API Access Passcode from your Worldline account. See the "Authentication" section below for more details on how to generate your access passcode to use in the request to the Settlement Report API.
API requests
Requests to the settlement endpoint should include two request headers: a Content-type header with the value application/json and a Authorization header which is outlined in the next section.
All requests to the Merchant Report require authentication in the form of an Authorization header. This header contains the value Passcode <YOUR API ACCESS PASSCODE> which is an encoded version of your Merchant ID and your Reporting API Access Passcode. Note that your Reporting API Access Passcode can be found in the Portal under administration > account settings > order settings.
<YOUR API ACCESS PASSCODE> is created by concatenating your Merchant ID to your Reporting API Access Passcode (separated by a colon), and then base 64 encoding the result.
As an example, if your Merchant ID is 123456789, and your Reporting API Passcode is fd36d245a3584434b904096525547f17, then using JavaScript your API Access Passcode could be generated by doing:
merchantID = "123456789";
reportingAPIPasscode = "fd36d245a3584434b904096525547f17";
// base 64 encode the two values concatenated with a colon
yourAPIAccessPassCode = btoa(merchantID + ":" + reportingAPIPasscode);In this example yourAPIAccessPassCode would be MTIzNDU2Nzg5OmZkMzZkMjQ1YTM1ODQ0MzRiOTA0MDk2NTI1NTQ3ZjE3 which is the value used when making a call to the Settlement Report API.
Alternatively, for convenience, you can also use the form which does same calculation.
It is worth noting that while this process obfuscates/obscures your Reporting API Passcode it is not an encrypted value, so this value should be treated with equal sensitivity/security as your Reporting API Passcode itself.
The Settlement Report accepts two parameters to control the data returned by the endpoint: start_date and end_date, both of which are supplied as query string parameters on the HTTP GET request. Both dates are specified in the YYYY-MM-DD format (including leading zeros, so for example, January 1st, 2021 would be specified as 2021-01-01).
Both parameters accept a date, and will restrict settlement records to the date range specified (inclusive). More details are in the formal specification on our Payment API specifications page .
An example request is illustrated below.
Request
curl --location --request GET 'https://api.na.bambora.com/v1/reports/settlement?start_date=2020-12-01&end_date=2021-01-31' \
--header 'Authorization: Passcode <YOUR API ACCESS PASSCODE>' \
--header 'Content-Type: application/json'Response
{
"data": [
[
{
"merchant_id": 123456789,
"currency": "USD",
"transactions_date": "2021-01-10",
"settlement_net_amount": 5213.45,
"settlement_state": "Approved",
"settlement_date": "2021-01-10",
"approved_transaction_count": 10,
"declined_transaction_count": 3,
"sale_amount_total": 6123.00,
"returned_amount_total": 0.00,
"chargebacks_count": 5,
"chargebacks_amount_total": 10.00,
"card_transaction_approved_rate": 0.00,
"card_transaction_declined_rate": 0.00,
"card_discount_rate": 0.00,
"gst_tax_rate": 0.00,
"approved_transaction_fee_total": 0.00,
"declined_transaction_fee_total": 0.00,
"discount_rate_fee_total": 0.00,
"chargeback_fee_total": 0.00,
"gst_tax_fee_total": 0.00,
"reserves_held": 311.15,
"reserves_released": 0.00,
"reserves_forward": 0.00
}
]
]
}