Skip to content

Bank API

Jump to bottom Edit New page
Tyler Hunt edited this page Sep 28, 2021 · 5 revisions

DadeCore Bank API

The DadeCore Bank API allows RESTful access to bank data inside DadeCore.

The overview provides general details on how the API works, while the resources section outlines each of the resource endpoints.

Overview

Authentication

All requests to the API require authentication via an access token which must be included in the HTTP request as a token Authorization header.

Authorization: Token token="<TOKEN>"

Content Type

On POST and PATCH requests, the API accepts JSON-formatted request bodies.

Content-Type: application/json

Fields that are not required may be omitted from the request when creating or updating resources. Unsupported fields will be ignored.

Versioning

All requests to the API should include an Accept header to indicate the requested API version.

Accept: application/vnd.dade.core.v1+json

Pagination

Some endpoints support pagination via the page and per_page parameters. On paginated responses, a Link header will be present. The links in the header should be used to traverse results instead of manually constructing URLs with the required query parameters.

Link: </bank-api/billers?page=1>; rel="first",
  </bank-api/billers?page=10>; rel="last",
  </bank-api/billers?page=4>; rel="previous",
  </bank-api/billers?page=6>; rel="next"

Status Codes

The API makes use of standard HTTP response status codes to indicate success and failure states.

  • 200 OK — success
  • 201 Created — e.g. a new resource has been created
    • the Location response header indicates the new resource URL
  • 401 Unauthorized — e.g. an invalid access token
    • the WWW-Authenticate header indicates the required authentication method
  • 403 Forbidden — e.g. the token is valid but not for the given resource
  • 422 Unprocessable Entity — e.g. validation errors

Resources

Root

GET /bank-api

Returns the API root, which includes the endpoints for the resources. API clients should use this response to lookup the resource URLs instead of hard-coding them into the client.

Example Request
GET /bank-api
Example Response
{
  "billers_url": "/bank-api/billers{?active,name,page,per_page}",
  "cluster_search_url": "/bank-api/clusters{?active,name,page,per_page}",
  "clusters_url": "/bank-api/clusters",
  "fund_import_format_search_url": "/bank-api/fund_import_formats?biller_id={biller_id}{&active,external_key,external_number,name,page,per_page}",
  "fund_import_formats_url": "/bank-api/fund_import_formats",
  "lockbox_import_format_search_url": "/bank-api/lockbox_import_formats?biller_id={biller_id}{&active,external_key,external_number,name,page,per_page}",
  "lockbox_import_formats_url": "/bank-api/lockbox_import_formats"
}

Billers

GET /bank-api/billers{?active,name,page,per_page}

Returns the bank’s billers.

Parameters
  • active — optional filter by active status (true or false)
  • name — optional filter by name
  • page — optional page number (default 1)
  • per_page — optional results per page (default 30; maximum 100)
Example Request
GET /bank-api/billers?per_page=10`
Example Response
[
  {
    "active": true,
    "cluster": {
      "id": "1",
      "name": "Cluster 1"
    },
    "external_key": "eb1",
    "fund_import_format_search_url": "/bank-api/fund_import_formats?biller_id=83{&active,external_key,external_number,name,page,per_page}",
    "id": "83",
    "lockbox_import_format_search_url": "/bank-api/lockbox_import_formats?biller_id=83{&active,external_key,external_number,name,page,per_page}",
    "name": "Example Biller 1"
  }
]

POST /bank-api/billers

Creates a new biller.

Fields
  • active — optional (default true)
  • cluster — optional
    • id — required
  • external_key — required
  • name — required
Example Request
POST /bank-api/billers

{
  "active": true,
  "cluster": {
    "id": "1"
  },
  "external_key": "eb1",
  "name": "Example Biller 1"
}
Example Response
{
  "active": true,
  "cluster": {
    "id": "1",
    "name": "Cluster 1"
  },
  "external_key": "eb1",
  "fund_import_format_search_url": "/bank-api/fund_import_formats?biller_id=83{&active,external_key,external_number,name,page,per_page}",
  "id": "83",
  "lockbox_import_format_search_url": "/bank-api/lockbox_import_formats?biller_id=83{&active,external_key,external_number,name,page,per_page}",
  "name": "Example Biller 1"
}

PATCH /bank-api/billers/{id}

Updates a biller.

Fields
  • active — optional
  • cluster — optional
    • id — required
  • external_key — optional
  • name — optional
Example Request
PATCH /bank-api/billers/83

{
  "active": false,
  "cluster": {
    "id": "2"
  },
  "external_key": "eb2"
}
Example Response
{
  "active": false,
  "cluster": {
    "id": "2",
    "name": "Cluster 2"
  },
  "external_key": "eb2",
  "fund_import_format_search_url": "/bank-api/fund_import_formats?biller_id=83{&active,external_key,external_number,name,page,per_page}",
  "id": "83",
  "lockbox_import_format_search_url": "/bank-api/lockbox_import_formats?biller_id=83{&active,external_key,external_number,name,page,per_page}",
  "name": "Example Biller 1"
}

Clusters

GET /bank-api/clusters{?active,name,page,per_page}

Returns the bank’s clusters, which can be used to group together billers.

Parameters
  • active — optional filter by active status (true or false)
  • name — optional filter by name
  • page — optional page number (default 1)
  • per_page — optional results per page (default 30; maximum 100)
Example Request
GET /bank-api/clusters?per_page=10
Example Response
[
  {
    "active": true,
    "id": "3",
    "name": "Cluster 1"
  }
]

POST /bank-api/clusters

Creates a new cluster.

Fields
  • active — optional (default true)
  • name — required
Example Request
POST /bank-api/clusters

{
  "name": "Cluster 1"
}
Example Response
{
  "active": true,
  "id": "3",
  "name": "Cluster 1"
}

PATCH /bank-api/clusters/{id}

Updates a cluster.

Fields
  • active — optional
  • name — optional
Example Request
PATCH /bank-api/clusters/3

{
  "active": false,
}
Example Response
{
  "active": false,
  "id": "3",
  "name": "Cluster 1"
}

Fund Import Formats

GET /bank-api/fund_import_formats?biller_id={biller_id}{&active,external_key,external_number,name,page,per_page}

Returns a biller’s fund import formats.

Parameters
  • active — optional filter by active status (true or false)
  • biller_id — required
  • external_key — optional filter by external key
  • external_number — optional filter by external number
  • name — optional filter by name
  • page — optional page number (default 1)
  • per_page — optional results per page (default 30; maximum 100)
Example Request
GET /bank-api/fund_import_formats?active=true&biller_id=83
Example Response
[
  {
    "active": true,
    "biller": {
      "id": "83"
    },
    "external_key": "ach1",
    "external_number": "1234124522",
    "id": "12",
    "name": "ACH Import 1"
  }
]

POST /bank-api/fund_import_formats

Creates a new fund import format for the given biller.

Fields
  • active — optional (default true)
  • biller — required
    • id — required
  • external_key — required
  • external_number — required
  • name — required
Example Request
POST /bank-api/fund_import_formats

{
  "active": true,
  "biller": {
    "id": "83"
  },
  "external_key": "ach1",
  "external_number": "1234124522",
  "name": "ACH Import 1"
}
Example Response
{
  "active": true,
  "biller": {
    "id": "83"
  },
  "external_key": "ach1",
  "external_number": "1234124522",
  "id": "12",
  "name": "ACH Import 1"
}

PATCH /bank-api/fund_import_formats/{id}

Updates a biller fund import format.

Fields
  • active — optional
  • external_key — optional
  • external_number — optional
  • name — optional
Example Request
PATCH /bank-api/fund_import_formats/12

{
  "active": false,
  "external_key": "ach1",
  "external_number": "1234124522",
  "id": "12",
  "name": "ACH Import 1"
}
Example Response
{
  "active": false,
  "biller": {
    "id": "83"
  },
  "external_key": "ach1",
  "external_number": "1234124522",
  "id": "12",
  "name": "ACH Import 1"
}

Images

GET /bank-api/images/{id}/front

GET /bank-api/images/{id}/rear

Returns a check or coupon image. These URLs should not be generated directly, but instead they should be taken from the payments response.

Example Request
GET /bank-api/images/173/front
Example Response

The response is binary date with the image contents, typically with a content type of image/png.

Lockbox Import Formats

GET /bank-api/lockbox_import_formats?biller_id={biller_id}{&active,external_key,external_number,name,page,per_page}

Returns a biller’s lockbox import formats.

Parameters
  • active — optional filter by active status (true or false)
  • biller_id — required
  • external_key — optional filter by external key
  • external_number — optional filter by external number
  • name — optional filter by name
  • page — optional page number (default 1)
  • per_page — optional results per page (default 30; maximum 100)
Example Request
GET /bank-api/lockbox_import_formats?active=true&biller_id=83
Example Response
[
  {
    "active": true,
    "biller": {
      "id": "83"
    },
    "external_key": "lbx1",
    "external_number": "512",
    "id": "12",
    "name": "Lockbox 1"
  }
]

POST /bank-api/lockbox_import_formats

Creates a new biller lockbox import format.

Fields
  • active — optional (default true)
  • biller — required
    • id — required
  • external_key — required
  • external_number — required
  • name — required
Example Request
POST /bank-api/lockbox_import_formats

{
  "active": true,
  "biller": {
    "id": "83"
  },
  "external_key": "lbx1",
  "external_number": "512",
  "name": "Lockbox 1"
}
Example Response
{
  "active": true,
  "biller": {
    "id": "83"
  },
  "external_key": "lbx1",
  "external_number": "512",
  "id": "12",
  "name": "Lockbox 1"
}

PATCH /bank-api/lockbox_import_formats/{id}

Updates a biller lockbox import format.

Fields
  • active — optional
  • external_key — optional
  • external_number — optional
  • name — optional
Example Request
PATCH /bank-api/lockbox_import_formats/12

{
  "active": false,
  "external_key": "lbx2",
  "name": "Lockbox 2"
}
Example Response
{
  "active": false,
  "biller": {
    "id": "83"
  },
  "external_key": "lbx2",
  "external_number": "512",
  "id": "12",
  "name": "Lockbox 2"
}

Payments

GET /bank-api/payments/{id}

Returns a bank payment.

Example Request
GET /bank-api/payments/728
Example Response
{
  "checks": [
    {
      "amount": "3984.36",
      "front_image_url": "/bank-api/images/173/front",
      "number": "4169",
      "rear_image_url": "/bank-api/images/173/rear"
    }
  ],
  "coupons": [
    {
      "front_image_url": "/bank-api/images/174/front"
    }
  ],
  "id": "728",
  "posted_date": "2019-02-15",
  "total": "3984.36",
  "type": "lockbox"
}
Add a custom footer
Add a custom sidebar

Clone this wiki locally