Biller API

DadeCore Biller API

The DadeCore Biller API allows RESTful access to biller 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
• Content Type
• Versioning
• Pagination
• Status Codes

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: </biller-api/payments?page=1>; rel="first",
  </biller-api/payments?page=10>; rel="last",
  </biller-api/payments?page=4>; rel="previous",
  </biller-api/payments?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
• Images
• Payments
• Portal Payers

Root

GET /biller-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 /biller-api

Example Response

{
  "payments_url": "/biller-api/payments{?page,per_page,posted_date,type}",
}

Images

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

GET /biller-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 /biller-api/images/173/front

Example Response

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

Payments

GET /biller-api/payments{?page,per_page,posted_date,type}

Returns the biller’s payments.

Parameters

• page — optional page number (default 1)
• per_page — optional results per page (default 30; maximum 100)
• posted_date — optional filter by posted date (ISO 8601 date)
• type — optional filter by payment type (ach, credit_card, debit_card, deposit, document, eca, electronic_check, external, lockbox, or portal)

Example Request

GET /biller-api/payments?per_page=10

Example Response

[
  {
    "checks": [
      {
        "amount": "3984.36",
        "front_image_url": "/biller-api/images/173/front",
        "number": "4169",
        "rear_image_url": "/biller-api/images/173/rear"
      }
    ],
    "coupons": [
      {
        "front_image_url": "/biller-api/images/174/front"
      }
    ],
    "id": "728",
    "posted_date": "2019-02-15",
    "total": "3984.36",
    "type": "lockbox"
  }
]

GET /biller-api/payments/{id}

Returns a biller payment.

Example Request

GET /biller-api/payments/728

Example Response

{
  "checks": [
    {
      "amount": "3984.36",
      "front_image_url": "/biller-api/images/173/front",
      "number": "4169",
      "rear_image_url": "/biller-api/images/173/rear"
    }
  ],
  "coupons": [
    {
      "front_image_url": "/biller-api/images/174/front"
    }
  ],
  "id": "728",
  "posted_date": "2019-02-15",
  "total": "3984.36",
  "type": "lockbox"
}

Portal Payers

GET /biller-api/portal-payers?external_key={external_key}

Returns the biller’s portal payers.

Parameters

• external_key — required payer identifier (e.g. customer number)

Example Request

GET /biller-api/portal-payers?external_key=8759728845

Example Response

[
  {
    "external_key": "1936685091",
    "id": "86",
    "pay_methods": [
      {
        "active": true,
        "receivable_accounts": [
          {
            "external_key": "884488"
          }
        ],
        "recurrence_type": "bill",
        "type": "credit_card"
      }
    ]
  }
]