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" |
Info |
---|
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
Code Block | ||
---|---|---|
| ||
GET /api/v1/settlements |
Filter by a specific date
Code Block | ||
---|---|---|
| ||
GET /api/v1/settlements?filter={"settleDate":20180501} |
Filter based on settleDate and expression
Code Block | ||
---|---|---|
| ||
GET /api/v1/settlements?filter={"settleDate;>=":20180501} |
Filter by a specific date range
Code Block | ||
---|---|---|
| ||
GET /api/v1/settlements?filter={"startDate":20180501,"endDate":20180531} |
Filter for a specific transaction
Code Block | ||
---|---|---|
| ||
GET /api/v1/settlements?filter={"transaction":123456} |
Filter for all transactions after a specific transaction
Code Block | ||
---|---|---|
| ||
GET /api/v1/settlements?filter={"transaction;>":123456} |
Response
Code Block |
---|
{ "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" } } |