Return Rates
Request URL
POST /transfer-to/ach/return-rates
Description
This endpoint will retrieve the return rates data for the specified reporting date (YYYY-MM-DD format). If no date is included, up to a maximum of 1000 return rates records will be returned for the currently logged in client, sorted in descending order by maxDate. When originating ACH debits, customers are responsible for monitoring their compliance with NACHA's "ACH Network Risk and Enforcement Rule". This rule specifies that unauthorized return rates should remain below 0.5%, administrative return rates should remain below 3.0%, and the overall return rates should be below 15.0%. This response contains these return rates, as well as the number of days that any such rates have been out of compliance (if applicable). Return rates are calculated daily for a rolling 60-day period. This means that the data used to calculate the return rates for a specified reporting date would come from the 60 days prior to the requested date. If return rates exceed the allowed threshold, then a remediation plan may need to be provided, including updated processes/procedures and the timeline for when the return rates will be in good standing again.
- Unauthorized Return Rate - the rate at which an Originator's or Third-Party Sender's debit entries are returned on the basis that they were unauthorized.
- Administrative Return Rate - the rate at which an Originator’s or Third-Party Sender’s debit entries are returned for administrative reasons
- Overall Return Rate - the rate at which an Originator’s or Third-Party Sender’s debit entries, excluding RCK Entries, are returned, regardless of reason, as calculated in accordance with Subsection 2.17.2.4(d) (ODFI Return Rate Reporting Regarding an Originator’s or Third-Party Sender’s Administrative Return Rate or Overall Return Rate) (NACHA Guidelines, Section 8.71 “Overall Return Rate”)
Schema
Property table for transfer-to/ach/return-rates
| Property | Description | Required | Schema |
|---|---|---|---|
| date | date | No | { "type": "string", "format": "dateISO", "pattern": "^\d{4}-\d{2}-\d{2}$", "description": "common-dateOnly" } |
| numberOfRecords | The maximum number of desired records to return | No | { "type": "integer", "minimum": 1, "nullable": true, "description": "common-numberOfRecords" } |
| skipRecords | The number of records to skip when returning results | No | { "type": "integer", "minimum": 0, "nullable": true, "description": "common-skipRecords" } |
Request Body
Snippet Examples
javascript
const axios = require('axios');
const data = {
"date": "2023-09-12"
};
const config = {
method: 'POST',
url: '${CONNECTFI_BASE_URL}/transfer-to/ach/return-rates',
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/ach/return-rates" --data "{\"date\":\"2023-09-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/ACH/RETURN-RATES 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
RESPONSE BODY
{
"code": "0",
"data": {
"total": {
"skipRecords": 0,
"numberOfRecords": 1,
"more": false
},
"items": [
{
"notes": [
"The administrative returns rate has been out of compliance for 14 days. The adminRate = 42.86 and adminAmountRate = 43.58.",
"The total returns rate has been out of compliance for 39 days. The totalRate = 92.86 and totalAmountRate = 94.38."
],
"returnRates": {
"cFiAggregatorId": "CLIENTID",
"maxDate": "2023-09-13",
"adminAmountRate": 43.58,
"adminDaysOver": 14,
"adminRate": 42.86,
"adminReturns": 6,
"adminReturnsAmount": 33548.36,
"dtsCreatedAt": "2023-09-14T00:13:39.016Z",
"fedDR": 14,
"fedDRAmount": 76978.46,
"fileName": "Return Rates PGACH 20230913094101.json",
"minDate": "2023-07-12",
"nsfReturns": 7,
"nsfReturnsAmount": 39103,
"totalAmountRate": 94.38,
"totalDaysOver": 39,
"totalRate": 92.86,
"totalReturns": 13,
"totalReturnsAmount": 72651.36,
"unAuthorizedAmountRate": 0,
"unAuthorizedDaysOver": 0,
"unAuthorizedRate": 0,
"unAuthorizedReturns": 0,
"unAuthorizedReturnsAmount": 0,
"updatedAt": "2023-09-25T00:16:47.555Z"
}
}
]
},
"requestId": "ec9dfbe079a711eeb5658f28ab5fe311"
}
200 TRANSFER-TO/ACH/RETURN-RATES SUCCESSFUL RESPONSE NO RETURN RATES DATA FOR GIVEN DATE
HEADERS
| Header | Value |
|---|---|
| Content-Type | application/json |
| x-connectfi-token | A long random string token received from /auth/get-token request |
REQUEST BODY
RESPONSE BODY
{
"code": "0",
"data": {
"total": {
"skipRecords": 0,
"numberOfRecords": 0,
"more": false
},
"items": []
},
"requestId": "00b6ca3079a811eeb5658f28ab5fe311"
}
200 TRANSFER-TO/ACH/RETURN-RATES SUCCESSFUL RESPONSE ALL RETURN RATES REPORTS FOR LOGGED IN AGGREGATOR
HEADERS
| Header | Value |
|---|---|
| Content-Type | application/json |
| x-connectfi-token | A long random string token received from /auth/get-token request |
REQUEST BODY
RESPONSE BODY
{
"code": "0",
"data": {
"total": {
"skipRecords": 0,
"numberOfRecords": 9,
"more": false
},
"items": [
{
"notes": [],
"returnRates": {
"cFiAggregatorId": "CLIENTID",
"maxDate": "2023-09-22",
"adminAmountRate": 0.13,
"adminDaysOver": 0,
"adminRate": 0.12,
"adminReturns": 82,
"adminReturnsAmount": 23082.9,
"dtsCreatedAt": "2023-09-24T00:13:39.016Z",
"fedDR": 67018,
"fedDRAmount": 18063493.26,
"fileName": "Return Rates PGACH 20230922094101.json",
"minDate": "2023-07-21",
"nsfReturns": 1155,
"nsfReturnsAmount": 359550.5,
"totalAmountRate": 2.18,
"totalDaysOver": 0,
"totalRate": 1.88,
"totalReturns": 1260,
"totalReturnsAmount": 394295.76,
"unAuthorizedAmountRate": 0.06,
"unAuthorizedDaysOver": 0,
"unAuthorizedRate": 0.03,
"unAuthorizedReturns": 23,
"unAuthorizedReturnsAmount": 11662.36,
"updatedAt": "2023-09-25T00:16:47.555Z"
}
},
{
"notes": [],
"returnRates": {
"cFiAggregatorId": "CLIENTID",
"maxDate": "2023-09-21",
"adminAmountRate": 0.13,
"adminDaysOver": 0,
"adminRate": 0.12,
"adminReturns": 82,
"adminReturnsAmount": 23082.9,
"dtsCreatedAt": "2023-09-24T18:21:01.799Z",
"fedDR": 67018,
"fedDRAmount": 18063493.26,
"fileName": "Return Rates PGACH 20230921094101.json",
"minDate": "2023-07-20",
"nsfReturns": 1155,
"nsfReturnsAmount": 359550.5,
"totalAmountRate": 2.18,
"totalDaysOver": 0,
"totalRate": 1.88,
"totalReturns": 1260,
"totalReturnsAmount": 394295.76,
"unAuthorizedAmountRate": 0.06,
"unAuthorizedDaysOver": 0,
"unAuthorizedRate": 0.03,
"unAuthorizedReturns": 23,
"unAuthorizedReturnsAmount": 11662.36,
"updatedAt": "2023-09-25T18:21:01.799Z"
}
},
{
"notes": [
"The administrative returns rate has been out of compliance for 0 days. The adminRate = 4.04 and adminAmountRate = 3.53.",
"The total returns rate has been out of compliance for 0 days. The totalRate = 12.96 and totalAmountRate = 15.53."
],
"returnRates": {
"cFiAggregatorId": "CLIENTID",
"maxDate": "2023-09-20",
"adminAmountRate": 3.53,
"adminDaysOver": 0,
"adminRate": 4.04,
"adminReturns": 586,
"adminReturnsAmount": 80825.63,
"dtsCreatedAt": "2023-09-23T00:13:39.016Z",
"fedDR": 14503,
"fedDRAmount": 2286700.9,
"fileName": "Return Rates PGACH 20230920094101.json",
"minDate": "2023-07-19",
"nsfReturns": 1263,
"nsfReturnsAmount": 273024.61,
"totalAmountRate": 15.53,
"totalDaysOver": 0,
"totalRate": 12.96,
"totalReturns": 1879,
"totalReturnsAmount": 355170.43,
"unAuthorizedAmountRate": 0.06,
"unAuthorizedDaysOver": 0,
"unAuthorizedRate": 0.21,
"unAuthorizedReturns": 30,
"unAuthorizedReturnsAmount": 1320.19,
"updatedAt": "2023-09-25T00:16:47.555Z"
}
},
{
"notes": [],
"returnRates": {
"cFiAggregatorId": "CLIENTID",
"maxDate": "2023-09-15",
"adminAmountRate": 0.96,
"adminDaysOver": 0,
"adminRate": 1.4,
"adminReturns": 258,
"adminReturnsAmount": 53884.26,
"dtsCreatedAt": "2023-09-16T00:13:39.016Z",
"fedDR": 18431,
"fedDRAmount": 5626232.39,
"fileName": "Return Rates PGACH 20230915094101.json",
"minDate": "2023-07-14",
"nsfReturns": 644,
"nsfReturnsAmount": 103674.14,
"totalAmountRate": 2.8,
"totalDaysOver": 0,
"totalRate": 4.89,
"totalReturns": 902,
"totalReturnsAmount": 157558.4,
"unAuthorizedAmountRate": 0,
"unAuthorizedDaysOver": 0,
"unAuthorizedRate": 0,
"unAuthorizedReturns": 0,
"unAuthorizedReturnsAmount": 0,
"updatedAt": "2023-09-25T00:16:47.555Z"
}
},
{
"notes": [
"The unAuthorized returns rate has been out of compliance for 147 days. The unAuthorizedRate = 0.58 and unAuthorizedAmountRate = 0.85."
],
"returnRates": {
"cFiAggregatorId": "CLIENTID",
"maxDate": "2023-09-14",
"adminAmountRate": 0.03,
"adminDaysOver": 0,
"adminRate": 1.22,
"adminReturns": 21,
"adminReturnsAmount": 4242.93,
"dtsCreatedAt": "2023-09-15T00:13:39.016Z",
"fedDR": 1720,
"fedDRAmount": 15100800.89,
"fileName": "Return Rates PGACH 20230914094101.json",
"minDate": "2023-07-13",
"nsfReturns": 37,
"nsfReturnsAmount": 18846.16,
"totalAmountRate": 1,
"totalDaysOver": 0,
"totalRate": 3.95,
"totalReturns": 68,
"totalReturnsAmount": 151520.36,
"unAuthorizedAmountRate": 0.85,
"unAuthorizedDaysOver": 147,
"unAuthorizedRate": 0.58,
"unAuthorizedReturns": 10,
"unAuthorizedReturnsAmount": 128431.27,
"updatedAt": "2023-09-25T00:16:47.555Z"
}
},
{
"notes": [
"The administrative returns rate has been out of compliance for 14 days. The adminRate = 42.86 and adminAmountRate = 43.58.",
"The total returns rate has been out of compliance for 39 days. The totalRate = 92.86 and totalAmountRate = 94.38."
],
"returnRates": {
"cFiAggregatorId": "CLIENTID",
"maxDate": "2023-09-13",
"adminAmountRate": 43.58,
"adminDaysOver": 14,
"adminRate": 42.86,
"adminReturns": 6,
"adminReturnsAmount": 33548.36,
"dtsCreatedAt": "2023-09-14T00:13:39.016Z",
"fedDR": 14,
"fedDRAmount": 76978.46,
"fileName": "Return Rates PGACH 20230913094101.json",
"minDate": "2023-07-12",
"nsfReturns": 7,
"nsfReturnsAmount": 39103,
"totalAmountRate": 94.38,
"totalDaysOver": 39,
"totalRate": 92.86,
"totalReturns": 13,
"totalReturnsAmount": 72651.36,
"unAuthorizedAmountRate": 0,
"unAuthorizedDaysOver": 0,
"unAuthorizedRate": 0,
"unAuthorizedReturns": 0,
"unAuthorizedReturnsAmount": 0,
"updatedAt": "2023-09-25T00:16:47.555Z"
}
},
{
"notes": [
"The administrative returns rate has been out of compliance for 45 days. The adminRate = 100 and adminAmountRate = 100.",
"The total returns rate has been out of compliance for 45 days. The totalRate = 100 and totalAmountRate = 100."
],
"returnRates": {
"cFiAggregatorId": "CLIENTID",
"maxDate": "2023-09-12",
"adminAmountRate": 100,
"adminDaysOver": 45,
"adminRate": 100,
"adminReturns": 1,
"adminReturnsAmount": 5252,
"dtsCreatedAt": "2023-09-23T00:13:39.016Z",
"fedDR": 1,
"fedDRAmount": 5252,
"fileName": "Return Rates PGACH 20230912094101.json",
"minDate": "2023-07-11",
"nsfReturns": 0,
"nsfReturnsAmount": 0,
"totalAmountRate": 100,
"totalDaysOver": 45,
"totalRate": 100,
"totalReturns": 1,
"totalReturnsAmount": 5252,
"unAuthorizedAmountRate": 0,
"unAuthorizedDaysOver": 0,
"unAuthorizedRate": 0,
"unAuthorizedReturns": 0,
"unAuthorizedReturnsAmount": 0,
"updatedAt": "2023-09-25T00:16:47.555Z"
}
},
{
"notes": [
"The unAuthorized returns rate has been out of compliance for 13 days. The unAuthorizedRate = 0.68 and unAuthorizedAmountRate = 0.88."
],
"returnRates": {
"cFiAggregatorId": "CLIENTID",
"maxDate": "2023-09-11",
"adminAmountRate": 0.03,
"adminDaysOver": 0,
"adminRate": 0.11,
"adminReturns": 1,
"adminReturnsAmount": 10,
"dtsCreatedAt": "2023-09-23T00:13:39.016Z",
"fedDR": 884,
"fedDRAmount": 30210,
"fileName": "Return Rates PGACH 20230911094101.json",
"minDate": "2023-07-10",
"nsfReturns": 33,
"nsfReturnsAmount": 2285,
"totalAmountRate": 8.47,
"totalDaysOver": 0,
"totalRate": 4.52,
"totalReturns": 40,
"totalReturnsAmount": 2560,
"unAuthorizedAmountRate": 0.88,
"unAuthorizedDaysOver": 13,
"unAuthorizedRate": 0.68,
"unAuthorizedReturns": 6,
"unAuthorizedReturnsAmount": 265,
"updatedAt": "2023-09-25T00:16:47.555Z"
}
},
{
"notes": [
"The administrative returns rate has been out of compliance for 0 days. The adminRate = 2.82 and adminAmountRate = 29.",
"The total returns rate has been out of compliance for 0 days. The totalRate = 5.63 and totalAmountRate = 30.62."
],
"returnRates": {
"cFiAggregatorId": "CLIENTID",
"maxDate": "2023-09-08",
"adminAmountRate": 29,
"adminDaysOver": 0,
"adminRate": 2.82,
"adminReturns": 2,
"adminReturnsAmount": 14300,
"dtsCreatedAt": "2023-09-09T00:13:39.016Z",
"fedDR": 71,
"fedDRAmount": 49318.41,
"fileName": "Return Rates PGACH 20230908094101.json",
"minDate": "2023-07-07",
"nsfReturns": 2,
"nsfReturnsAmount": 800,
"totalAmountRate": 30.62,
"totalDaysOver": 0,
"totalRate": 5.63,
"totalReturns": 4,
"totalReturnsAmount": 15100,
"unAuthorizedAmountRate": 0,
"unAuthorizedDaysOver": 0,
"unAuthorizedRate": 0,
"unAuthorizedReturns": 0,
"unAuthorizedReturnsAmount": 0,
"updatedAt": "2023-09-25T00:16:47.555Z"
}
}
]
},
"requestId": "116914f079a811eeb5658f28ab5fe311"
}