close
    Contents

    Merchant Report

    Report Overview

    The Merchant Report is intended for our Partners to obtain an overview of their merchants as they progress through the boarding process. Partners can get information relating to merchants in their portfolio, including the account status, batch limits, as well as cards and features enabled.

    Report Columns

    The response will be a JSON-formatted response which will consist of a collection of Merchant records. The fields of each Merchant are summarized in the table below.

    Field Description
    merchant_id The id of the merchant
    merchant_name The name of the merchant
    street_address Street address
    postal Postal code
    province Province
    country Country
    website The merchant's website
    status The merchant account status
    state The merchant account state
    live_date The date the merchant was set to live
    created_date The date the merchant was created
    authorized_date The date the merchant was set to authorized
    temp_disabled_date The date the merchant was temporarily disbaled if applicable
    last_enabled_date The date the merchant was last set to enabled
    disabled_date The date the merchant was last set to disabled
    processor_name Processor name
    currency_code The currency code of the merchant
    credit_lag The merchant's credit lag
    eft_credit_lag The merchant's eft credit lag
    batch_limit The merchant's batch limit
    batch_line_limit The merchant's batch line limit
    mastercard_enabled Is the merchant set up to process mastercard
    visa_enabled Is the merchant set up to process visa
    amex_enabled Is the merchant set up to process amex
    discover_enabled Is the merchant set up to process disover
    diners_enabled Is the merchant set up to process diners
    jcb_enabled Is the merchant set up to process jcb
    mastercard_debit_enabled Is the merchant set up to process mastercard debit
    visa_debit_enabled Is the merchant set up to process visa debit
    checkout_enabled Does the merchant have checkout enabled
    payment_profile_enabled Does the merchant have payment profiles enabled
    recurring_billing_enabled Does the merchant have recurring billing enabled
    credit_card_batch_enabled Does the merchant have credit card batch enabled
    eft/ach_batch_enabled Does the merchant have eft/ach batch enabled
    interac_online_enabled The Interac Online feature has been decommissioned. The field is included in the response for backwards compatibility.
    visa_src_enabled Does the merchant have visa checkout enabled

    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 Merchant Report API is accessed via the URL https://api.na.bambora.com/v1/reports/merchants

    In addition, you will need to use your Merchant ID and Reporting API Access Passcode from your Bambora Channel Partner account. See the "Authentication" section below for more details on how to generate your access passcode to use in the request to the Merchant Report API.

    API Requests

    Request Headers

    Requests to the merchant 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 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 Merchant Report API.

    Alternatively, for convenience, you can also use the form which does the 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 Merchant Report can accept one parameter to control the data returned by the endpoint: merchants, which is supplied as part of the URL

    If not passed the data returned will be for all the sub-merchants of the Channel Partner requesting the report. If a sub-merchant is passed in then only data for that sub-merchant will be returned

    Example

    An example request to get sub-merchant details is illustrated below.

    Request

    curl --location --request GET 'https://api.na.bambora.com/v1/reports/merchants/{merchant_id}' \
    --header 'Authorization: Passcode <YOUR API ACCESS PASSCODE>' \
    --header 'Content-Type: application/json'
    

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

    If you wish to retrieve information for all of your sub-merchants then the request would be:

    curl --location --request GET 'https://api.na.bambora.com/v1/reports/merchants' \
    --header 'Authorization: Passcode <YOUR API ACCESS PASSCODE>' \
    --header 'Content-Type: application/json'
    

    Response

    {
        "data": [
            [
                {
                    "merchant_id": 100000000,
                    "merchant_name": "My merchant name",
                    "website": "http://www.merchant.com",
                    "address": {
                        "street_address": "1675 Douglas St",
                        "province": "British Columbia",
                        "country": "Canada",
                        "postal_code": "V8W 2K4"
                    },
                    "merchant_status": {
                        "status": "Active",
                        "state": "Approved",
                        "live_date": "2020-01-01",
                        "created_date": "2020-01-01",
                        "authorized_date": "2020-01-01",
                        "temp_disabled_date": "2020-06-01",
                        "last_enabled_date": "2020-06-15",
                        "disabled_date": "2012-07-22"
                    },
                    "processor": {
                        "processor_name": "BAM Emulator",
                        "currency": "CAD"
                    },
                    "batch": {
                        "batch_limit": 1000000.00,
                        "batch_line_limit": 10000.00,
                        "eft_credit_lag": 1
                    },
                    "settlement": {
                        "credit_lag": 1
                    },
                    "cards": {
                        "mastercard_enabled": true,
                        "visa_enabled": true,
                        "amex_enabled": true,
                        "discover_enabled": false,
                        "diners_enabled": false,
                        "jcb_enabled": false,
                        "mastercard_debit_enabled": false,
                        "visa_debit_enabled": false
                    },
                    "features": {
                        "checkout_enabled": false,
                        "payment_profile_enabled": false,
                        "recurring_billing_enabled": false,
                        "credit_card_batch_enabled": true,
                        "eft_ach_enabled": true,
                        "interac_online_enabled": false,
                        "visa_src_enabled": false
                    }
                }
            ]
        ]
    }