ACH Settlements
Retrieve information for daily ACH settlement funds. The date range for results defaults to the current date, to change the default date range use the filter request field.
| API end-point |
|---|
GET "/api/v1/settlements" |
Requires: Authorization header
Request fields
| Field | Required | Description |
|---|---|---|
| filter | Optional | Filter results based on the given criteria. Filter request are accepted in JSON format. |
| limit | Optional | Max number of results to return per page. Defaults to: 25 |
Filtering Results
Results can be be filtered using the filter request field. Currently, the following fields are recognized:
| Field | Description |
|---|---|
| settleDate | A specific date to look for settlement results. This field defaults to the current date. Supports expressions. Format: YYYYMMDD |
| transaction | OmniFund assigned transaction ID. Note: When the transaction filter is set the default settleDate is removed, returning results regardless of date. If desired, you will need to include a specific settleDate, startDate or endDate. Supports expressions. |
| startDate | The earliest date to retrieve settlement data. If startDate is given, but no endDate is given. endDate will default to +30 days from the given startDate. Format: YYYYMMDD. |
| endDate | The last date to retrieve settlement data. If endDate is given, but no startDate is given. startDate will default to -30 days from the given endDate. Format: YYYYMMDD |
Additionally, expressions can be applied to the transaction filter. The following expressions are supported. See examples for usage.
- >
- >=
- <
- <=
Response fields
| Field | Description |
|---|---|
| items | Array of settlement items |
| total | Total number of items in the requested results |
| count | Number of items in the current page of results |
| filters | Echo of filters given, if any. Not present if no filters are passed. |
| recordCount | Number of items processed in the results |
| recordAmount | SUM of items processed in the results |
| returnCount | Number items that have returned |
| returnAmount | SUM items that have returned |
| netAmount | Net amount for total result set. This is the amount of funds to be settled to the merchant bank account. Record Amount - Return Amount = Net Amount. |
| _links | Result set paging links.
|
Item fields
| Field | Description |
|---|---|
| id | OmniFund ID of the settlement record. |
| type | Type of item: SETTLE, RETURN |
| name | Customer name |
| account | Masked version of the customer's bank account |
| checkNumber | Serial number of the paper check |
| processDate | Original process date of the transaction. |
| settleDate | Date of the settlement record. |
| referenceId | Merchant provided reference ID identifying the transaction |
| netAmount | Net settlement amount. This is the amount of funds to be deposited/withdrawn. |
| returnCode | The R code of the return. Only available on RETURN. |
| returnCodeText | Textual description of the returnCode. Only available on RETURN |
| _links | Result set paging links.
|
Examples
Retrieve settlement data for current date
GET /api/v1/settlements
Filter by a specific date
GET /api/v1/settlements?filter={"settleDate":20180501}
Filter based on settleDate and expression
GET /api/v1/settlements?filter={"settleDate;>=":20180501}
Filter by a specific date range
GET /api/v1/settlements?filter={"startDate":20180501,"endDate":20180531}
Filter for a specific transaction
GET /api/v1/settlements?filter={"transaction":123456}
Filter for all transactions after a specific transaction
GET /api/v1/settlements?filter={"transaction;>":123456}
Response
{
"items": [
{
"id": 3975404,
"type": "SETTLE",
"name": "Test Customer",
"account": "11xx33",
"checkNumber": "",
"amount": "1.00",
"processDate": 20180503,
"settleDate": 20180503,
"netAmount": "1.00",
"transaction": {
"id": 9799753,
"type": "ACH",
"action": "debit",
"amount": 1.0,
"customer": {
"id": 6412957,
"name": "Test Customer",
"company": "",
"email": "",
"custRef": "19991234"
},
"account": {
"id": 7442715,
"type": "ACH",
"number": "11xx33"
},
"processDate": "2021-03-02",
"referenceId": "44444",
"createdAt": "2021-03-02 05:35:01",
"status": "settled",
"statusText": ""
},
"_links": {
"transaction": "/api/v1/transactions/9799753"
}
},
{
"id": 3975405,
"type": "RETURN",
"name": "Test Company",
"account": "31xx22",
"checkNumber": "",
"amount": "6.02",
"processDate": 20180515,
"settleDate": 20180515,
"netAmount": 0,
"returnCode": "R02",
"returnCodeText": "Invalid or Account closed",
"transaction": {
"id": 9799754,
"type": "ACH",
"action": "debit",
"amount": 1.0,
"customer": {
"id": 6412959,
"name": "",
"company": "Test Company",
"email": "",
"custRef": "1254-5484"
},
"account": {
"id": 7442685,
"type": "ACH",
"number": "31xx22"
},
"processDate": "2018-05-15",
"referenceId": "44444",
"createdAt": "2018-03-02 05:35:01",
"status": "returned",
"statusText": ""
},
"_links": {
"transaction": "/api/v1/transactions/9799754"
}
}
],
"total": 3,
"count": 3,
"recordCount": 2,
"recordAmount": "-5.02",
"returnCount": 1,
"returnAmount": "6.02",
"netAmount": "1.00",
"filters": {
"startDate": "20180501",
"endDate": "20180527"
},
"_links": {
"self": "/api/v1/settlements?page=1",
"first": "/api/v1/settlements?page=1",
"last": "/api/v1/settlements?page=1"
}
}