List of Billers

Request URL

GET /transfer-to/bills/billers/download

Description

Requests to this endpoint return a large JSON file with all of the billers available for Mastercard RPPS. It is recommended that this file be downloaded no more than once per day.

Successful response example

200 (HTTP response status code) -- Success, a list of billers and associated data is returned

{
    [   //Very large list of billers in JSON format
        {
            "recordType": "0",
            "billerKey": "458909", 
            "record_effective_date": "2022-08-25",
            "biller_id": "0011460198",
            "live_date": "2022-05-31",
            "routing_number": "",
            "biller_name": "Clear Lake CWAHC WCID 161",
            "biller_class": "Electric / Gas / Power / Water",
            "biller_type": "Core",
            "line_of_business": "RB",
            "file_format": "",
            "accepts_prenotes": "N",
            "accepts_guaranteed_payments_only": "Y",
            "accepts_DMP_prenotes": "",
            "accepts_DMP_payments_only": "",
            "average_response_time": "",
            "accept_CDP_prenotes": "",
            "accept_CDV_prenotes": "",
            "accept_CDD_prenotes": "",
            "accept_CDF_prenotes": "",
            "accept_CDN_prenotes": "",
            "accept_FBD_prenotes": "",
            "accept_FBC_prenotes": "",
            "return_CDR": "",
            "return_CDT": "",
            "return_CDA": "",
            "return_CDV": "",
            "return_CDC": "",
            "return_CDM": "",
            "require_addenda_with_reversals": "N",
            "country_code": "USA",
            "state_code": "TX",
            "check_digit_routine": "N",
            "currency_code": "840", 
            "territory_code": "Regional",
            "previous_biller_name": "",
            "note": "",
            "accepts_exception_payments": "N",
            "total_addresses": "1",
            "total_masks": "8",
            "total_AKAs": "8",
            "total_contacts": "5",
            "addresses": [ //Array of biller address objects (example below)
            ],
            "masks": [ //Array of mask objects (examples and explanation below)
            ],
            "akas": [ //Array of aka objects, names (A.K.A) that the biller may use (example below)
            ],
            "contacts": [ //Array of biller contact objects (example below)
            ],
            "phones": [ //Array of biller phone objects (example below)
            ]
        },
        // List of billers continued....
    ]
}

Biller address object example

{
    "recordType": "1",
    "address_key": "182059",
    "record_effective_date": "2022-05-31",
    "address_type": "Standard",
    "address_line1": "900 Bay Area Blvd",
    "address_line2": "",
    "city": "Houston",
    "state": "TX",
    "country_code": "USA",
    "postal_code": "77058-2604"
}

Biller mask object example

Some records may contain input masks for customer's account in biller's system.
In this example, account numbers a biller can accept are 15 characters long, will start with 960315,and be followed by 9 Numeric digits.

*=Alpha, #=Numeric, @=Alpha or Numeric, !=Special Character

{
    "recordType": "2",
    "mask_key": "851880",
    "record_effective_date": "2022-08-01",
    "mask_length": "15",
    "mask": "960315#########",
    "exception_mask": "N"
}

Masks explained

*=Alpha, #=Numeric, @=Alpha or Numeric, !=Special Character

Mask	Explanation	Example accountNumber
"mask": "@#######"	1 alphanumeric character, followed by 7 numeric digits	"a1234567"
"mask": "#####"	5 numeric digits	"12345"
"mask": "@@#######"	2 alphanumeric character, followed by 7 numeric digits	"ab1234567"
"mask": "A#########"	The letter A, followed by 9 numeric digits	"A123456789"
"mask": "#######-##"	7 numeric digits, followed by a dash and two more digits	"1234567-12"
"mask": "@@@@@@@@"	8 alphanumeric characters	"a1b2c3d4"
"mask": "####**"	4 numeric digits, followed by 2 alpha characters	"1234ab"
"mask": "###!####"	3 numeric digits, followed by a special character and then 4 more digits	"123!1234"
"mask": "*\###!@@@"	3 alpha characters, followed by 3 numeric digits, then a special character, and 3 alphanumeric characters	"abc123!a1b"

Biller aka object example

{
    "recordType": "4",
    "aka_key": "295758",
    "record_effective_date": "2022-05-31",
    "AKA_name": "Water" //Names the biller may go by
}

Biller contact object example

{
    "recordType": "5",
    "contact_key": "171582",
    "record_effective_date": "2022-05-31",
    "contact_type": "Scrub File",
    "organization_name": "Harris County WCID #161",
    "courtesy_title": "",
    "fist_name": "Jennifer",
    "last_name": "Morrow",
    "title": "",
    "address_line1": "900 Bay Area Blvd",
    "address_line2": "",
    "city": "Houston",
    "state": "TX",
    "country_code": "USA",
    "postal_code": "77058-2604",
    "email": "j.morrow@clcwa.org"
}

Biller phone object example

{
    "recordType": "6",
    "phone_key": "166967",
    "record_effective_date": "2022-05-31",
    "phone_type": "Phone",
    "phone_number": "281-488-1146"
}

Snippet Examples

javascript

const axios = require('axios');
const config = {
  method: 'GET',
  url: '${CONNECTFI_BASE_URL}/transfer-to/bills/billers/download',
  headers: {
    'x-connectfi-token': "A long random string token received from /auth/get-token request"
  },
};

let result;
try {
  result = await axios.request(config);
  if (result.status === 200) {
    console.log(JSON.stringify(result.data));
  }
} catch (err) {
  console.log({
    errCode: err.code,
    responseStatus: err.response && err.response.status,
    data: err.response && JSON.stringify(err.response.data)
  });
}

cURL

curl --location "CONNECTFI_BASE_URL/transfer-to/bills/billers/download"  --header "x-connectfi-token: A long random string token received from /auth/get-token request"