close
    Contents

    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 Bambora reserve account
    reserves_released Amount released from the reserve account during the current statement period
    reserves_forward Total amount that Bambora 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 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
                }
            ]
        ]
    }