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.

More detailed information about these fields can be found in our API specification which can be found at: https://dev.na.bambora.com/docs/references/payment_APIs/v1-0-5/

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 Bambora 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

Request Headers

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.

Authentication

All requests to the Settlement 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.

Parameters

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).

Note: Both of these values are required on all requests to the Settlement Report API

Both parameters accept a date, and will restrict settlement records to the date range specified (inclusive). More details are in the formal specification at https://dev.na.bambora.com/docs/references/payment_APIs/v1-0-5/

Example

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'

Replace <YOUR API ACCESS PASSCODE> with your API passcode.

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
            }
        ]
    ]
}