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.
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/
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.
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 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.
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/
An example request is illustrated below.
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.
{
"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
}
]
]
}