Skip to content

Settlement Summary

Request URL

POST /transfer-to/bills/summary

Description

This endpoint will return an activity summary for a specified date, along with transactions, exceptions associated with transactions, and extra exceptions (exceptions not associated with transactions). This report will be helpful when reconciling daily RPPS activity.

Since RPPS settlement occurs within the same or next business day of transaction execution, it is not recommended to pull this report for the current day. It is recommended to request this report only once per day for a previous day's date.

A notes array will also be returned containing any messages obtained while generating the summary. For each transaction, the originally requested transaction amount will be compared to the settled amount. A similar reconciliation will occur for each exception and descrepancies will be recorded in the notes array as well.

The summary report may include, but is not limited to, the following items:

disburse - This field is commonly used and refers to bill payment request transactions and amounts (requests to debit the merchant's settlement account in order to make a bill payment to a biller).

purchase - This field is rarely used and can refer to bill payment reversal request transactions and amounts (requests to credit the merchant's settlement account in order to reverse a previously settled bill payment).

adjustments - This field contains the sum of any adjustments that occur. For example, when a request results in an exception and is declined, the adjusted amount would be included in this field. Exceptions may occur for both bill payment requests and bill payment reversal requests.

fees - Fees include items such as network fees, processing fees, and convenience fees.

Schema

Property table for transfer-to/bills/summary

Property Description Required Schema
date date Yes {
  "type": "string",
  "format": "dateISO",
  "pattern": "^\d{4}-\d{2}-\d{2}$",
  "$id": "common-dateOnly"
}

Request Body

{
    "date": "2023-10-12"
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
    "date": "2023-10-12"
};
const config = {
  method: 'POST',
  url: '${CONNECTFI_BASE_URL}/transfer-to/bills/summary',
  headers: {
    'Content-Type': "application/json",
    'x-connectfi-token': "A long random string token received from /auth/get-token request"
  },
  data
};

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/summary" --data "{\"date\":\"2023-10-12\"}" --header "Content-Type: application/json" --header "x-connectfi-token: A long random string token received from /auth/get-token request" 

Successful Response Examples

200 TRANSFER-TO/BILLS/SUMMARY SUCCESSFUL RESPONSE

HEADERS

Header Value
Content-Type application/json
x-connectfi-token A long random string token received from /auth/get-token request

REQUEST BODY

{
    "date": "2023-10-12"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiAggregatorId": "CLIENTID",
        "date": "2023-10-12",
        "summary": {
            "cFiAggregatorId": "CLIENTID",
            "merchantId": "10000001",
            "date": "2023-10-12",
            "fileName": "3113_0001_20231012_summary_v2-5.csv",
            "purchase": {
                "transactions": 0,
                "amount": 0,
                "currency": "USD"
            },
            "convenienceFees": {
                "transactions": 0,
                "amount": 0,
                "currency": "USD"
            },
            "credits": {
                "transactions": 0,
                "amount": 0,
                "currency": "USD"
            },
            "refunds": {
                "transactions": 0,
                "amount": 0,
                "currency": "USD"
            },
            "disburse": {
                "transactions": 7,
                "amount": -154,
                "currency": "USD"
            },
            "chargebacks": {
                "transactions": 0,
                "amount": 0,
                "currency": "USD"
            },
            "adjustments": {
                "transactions": 1,
                "amount": 10,
                "currency": "USD"
            },
            "reserve": {
                "transactions": 0,
                "amount": 0,
                "currency": "USD"
            },
            "totals": {
                "transactions": 8,
                "amount": -144,
                "currency": "USD"
            },
            "indicativeInterchange": {
                "transactions": 7,
                "amount": 0,
                "currency": "USD"
            },
            "actualInterchangeDifference": {
                "transactions": 0,
                "amount": 0,
                "currency": "USD"
            },
            "networkFees": {
                "transactions": 7,
                "amount": -0.42,
                "currency": "USD"
            },
            "processingFees": {
                "transactions": 6,
                "amount": -0.45,
                "currency": "USD"
            },
            "dtsCreatedAt": "2023-10-20T12:35:36.027Z",
            "updatedAt": "2023-10-20T12:35:36.027Z"
        },
        "transactions": [
            {
                "reference": "extBillIdY0bHq",
                "cFiTransactionId": "CLIENTID_VwquJtbXM1ajWvhu",
                "merchantId": "10000001",
                "cFiTraceNumber": "000000000002491",
                "status": "Declined",
                "amount": 10,
                "currency": "USD",
                "dtsCreated": "2023-10-20T12:35:36.027Z",
                "dtsSent": "2023-10-12T00:00:00.000Z",
                "processing": {
                    "status": "Completed",
                    "dateProcessed": "2023-10-12",
                    "isReversal": false,
                    "responseCode": "",
                    "remarks": "",
                    "_id": "65327418eab09a197ba02975"
                },
                "dateSettled": "2023-10-12",
                "settled": {
                    "id": "RPPS15787921369",
                    "networkFee": -0.06,
                    "settledAmount": -10,
                    "status": "Complete",
                    "settlementDate": "2023-10-12"
                },
                "dateException": "2023-10-12",
                "exception": {
                    "id": "RPPS15787921369",
                    "exceptionAmount": 10,
                    "exceptionCurrency": "USD",
                    "networkFee": 0,
                    "exceptionCode": "R02",
                    "exceptionDescription": "Customer account closed-Merchant paid",
                    "exceptionDate": "2023-10-12"
                }
            },
            {
                "reference": "extBillIdfRYIl",
                "cFiTransactionId": "CLIENTID_MR6Cn31Gw3ESrlib",
                "merchantId": "10000001",
                "cFiTraceNumber": "000000000002490",
                "status": "Settled",
                "amount": 28,
                "currency": "USD",
                "dtsCreated": "2023-10-20T12:35:36.018Z",
                "dtsSent": "2023-10-12T00:00:00.000Z",
                "processing": {
                    "status": "Completed",
                    "dateProcessed": "2023-10-12",
                    "isReversal": false,
                    "responseCode": "",
                    "remarks": "",
                    "_id": "65327418eab09a197ba02970"
                },
                "dateSettled": "2023-10-12",
                "settled": {
                    "id": "RPPS51753435317",
                    "networkFee": -0.06,
                    "settledAmount": -28,
                    "status": "Complete",
                    "settlementDate": "2023-10-12"
                }
            },
            {
                "reference": "extBillIdxNtYd",
                "cFiTransactionId": "CLIENTID_iOytXrRkuHruxuef",
                "merchantId": "10000001",
                "cFiTraceNumber": "000000000002489",
                "status": "Settled",
                "amount": 28,
                "currency": "USD",
                "dtsCreated": "2023-10-20T12:35:36.011Z",
                "dtsSent": "2023-10-12T00:00:00.000Z",
                "processing": {
                    "status": "Completed",
                    "dateProcessed": "2023-10-12",
                    "isReversal": false,
                    "responseCode": "",
                    "remarks": "",
                    "_id": "65327418eab09a197ba0296b"
                },
                "dateSettled": "2023-10-12",
                "settled": {
                    "id": "RPPS77808043754",
                    "networkFee": -0.06,
                    "settledAmount": -28,
                    "status": "Complete",
                    "settlementDate": "2023-10-12"
                }
            },
            {
                "reference": "extBillIdfB0ya",
                "cFiTransactionId": "CLIENTID_346yAcrHz2ASAVHM",
                "merchantId": "10000001",
                "cFiTraceNumber": "000000000002488",
                "status": "Settled",
                "amount": 26,
                "currency": "USD",
                "dtsCreated": "2023-10-20T12:35:36.005Z",
                "dtsSent": "2023-10-12T00:00:00.000Z",
                "processing": {
                    "status": "Completed",
                    "dateProcessed": "2023-10-12",
                    "isReversal": false,
                    "responseCode": "",
                    "remarks": "",
                    "_id": "65327418eab09a197ba02966"
                },
                "dateSettled": "2023-10-12",
                "settled": {
                    "id": "RPPS37519632739",
                    "networkFee": -0.06,
                    "settledAmount": -26,
                    "status": "Complete",
                    "settlementDate": "2023-10-12"
                }
            },
            {
                "reference": "extBillIdSmnGv",
                "cFiTransactionId": "CLIENTID_EqUUF5FckkSC5zqo",
                "merchantId": "10000001",
                "cFiTraceNumber": "000000000002487",
                "status": "Settled",
                "amount": 16,
                "currency": "USD",
                "dtsCreated": "2023-10-20T12:35:35.998Z",
                "dtsSent": "2023-10-12T00:00:00.000Z",
                "processing": {
                    "status": "Completed",
                    "dateProcessed": "2023-10-12",
                    "isReversal": false,
                    "responseCode": "",
                    "remarks": "",
                    "_id": "65327417eab09a197ba02961"
                },
                "dateSettled": "2023-10-12",
                "settled": {
                    "id": "RPPS06444669607",
                    "networkFee": -0.06,
                    "settledAmount": -16,
                    "status": "Complete",
                    "settlementDate": "2023-10-12"
                }
            },
            {
                "reference": "extBillId4n0yL",
                "cFiTransactionId": "CLIENTID_DMXmd5w61NcFgq6b",
                "merchantId": "10000001",
                "cFiTraceNumber": "000000000002486",
                "status": "Settled",
                "amount": 18,
                "currency": "USD",
                "dtsCreated": "2023-10-20T12:35:35.991Z",
                "dtsSent": "2023-10-12T00:00:00.000Z",
                "processing": {
                    "status": "Completed",
                    "dateProcessed": "2023-10-12",
                    "isReversal": false,
                    "responseCode": "",
                    "remarks": "",
                    "_id": "65327417eab09a197ba0295c"
                },
                "dateSettled": "2023-10-12",
                "settled": {
                    "id": "RPPS82103840084",
                    "networkFee": -0.06,
                    "settledAmount": -18,
                    "status": "Complete",
                    "settlementDate": "2023-10-12"
                }
            },
            {
                "reference": "extBillIdWJnPr",
                "cFiTransactionId": "CLIENTID_PyzmtLsI2qmI77IT",
                "merchantId": "10000001",
                "cFiTraceNumber": "000000000002485",
                "status": "Settled",
                "amount": 28,
                "currency": "USD",
                "dtsCreated": "2023-10-20T12:35:35.985Z",
                "dtsSent": "2023-10-12T00:00:00.000Z",
                "processing": {
                    "status": "Completed",
                    "dateProcessed": "2023-10-12",
                    "isReversal": false,
                    "responseCode": "",
                    "remarks": "",
                    "_id": "65327417eab09a197ba02957"
                },
                "dateSettled": "2023-10-12",
                "settled": {
                    "id": "RPPS28119154491",
                    "networkFee": -0.06,
                    "settledAmount": -28,
                    "status": "Complete",
                    "settlementDate": "2023-10-12"
                }
            }
        ],
        "exceptions": [
            {
                "reference": "extBillIdY0bHq",
                "cFiTransactionId": "CLIENTID_VwquJtbXM1ajWvhu",
                "merchantId": "10000001",
                "cFiTraceNumber": "000000000002491",
                "status": "Declined",
                "amount": 10,
                "currency": "USD",
                "dtsCreated": "2023-10-20T12:35:36.027Z",
                "dtsSent": "2023-10-12T00:00:00.000Z",
                "processing": {
                    "status": "Completed",
                    "dateProcessed": "2023-10-12",
                    "isReversal": false,
                    "responseCode": "",
                    "remarks": ""
                },
                "dateSettled": "2023-10-12",
                "settled": {
                    "id": "RPPS15787921369",
                    "networkFee": -0.06,
                    "settledAmount": -10,
                    "status": "Complete",
                    "settlementDate": "2023-10-12"
                },
                "dateException": "2023-10-12",
                "exception": {
                    "id": "RPPS15787921369",
                    "exceptionAmount": 10,
                    "exceptionCurrency": "USD",
                    "networkFee": 0,
                    "exceptionCode": "R02",
                    "exceptionDescription": "Customer account closed-Merchant paid",
                    "exceptionDate": "2023-10-12"
                }
            }
        ],
        "extraExceptions": [],
        "notes": []
    },
    "requestId": "c6bfd7e0797511eeb5658f28ab5fe311"
}

200 TRANSFER-TO/BILLS/SUMMARY SUCCESSFUL RESPONSE NO SUMMARY AVAILABLE

HEADERS

Header Value
Content-Type application/json
x-connectfi-token A long random string token received from /auth/get-token request

REQUEST BODY

{
    "date": "2023-10-21"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiAggregatorId": "CLIENTID",
        "date": "2023-10-21",
        "transactions": [],
        "exceptions": [],
        "extraExceptions": [],
        "notes": []
    },
    "requestId": "b7985660797611eeb5658f28ab5fe311"
}