RCLON Integration Guide

Overview

RCLON is an API that Publishers use to provide Card-linked Offer services for their members.
This Integration Guide is intended to help you integrate your application with our rclon-client-sdk.

Terminology

  • Affiliate: A client partner system or entity that uses RCLON services
  • Publisher: A website or digital media service that presents RCLON Offers to their members
  • PCN: The Payment Card Network that the cardholder is using.. currently only VISA and AMEX are supported.
  • Cardholder: The Publisher's card carrying end-user.
  • PaymentCard: A credit card that has been registered with the system. To receive a reward it must be a "credit card", rather than a "debit" card.
  • Merchant: A vendor that offers goods and services.
  • Offer: A temporary in-store offering from the Merchant that a Cardholder can link their card to.
  • LinkedOffer A link between an Offer and a PaymentCard.
  • ShoppingCategory A category or group of categories that a merchant can be associated with.

API

  • See the 8197355832 for a full reference of all endpoints and models.

Version

The most currently supported version is v2. The version is present in the baseURL of the API endpoint. If you are migrating from v1 to v2, see Upgrate Guide to V2

Stages

RCLON is deployed in 4 stages:

  • DEV: The most up-to-date developer codebase - /dev-api.rclon.com/v1
  • QA: A release candidate area that contains recently added features and is currently being tested by the QA Team - 269-483-9611
  • QA2: The latest stable (QA Approved) build that is used as a pre-staging area just before releasing to production. - /qa2-api.rclon.com/v1
  • STATIC A stable static integration environment that does not interact with the PCNs- /static-api.rclon.com/v1
  • PROD The production environment - /api.rclon.com/v1

HTTP Verbs

RCLON supports the following HTTP verbs for each action:

Verb Description
OPTIONS Used to describe communication options for a given endpoint
GET Used for retrieving resources.
POST Used for creating resources.
PUT Used for updating resources state. Provide all first-level fields, any that are omitted will be set to null.
DELETE Used for deleting existing resources. Warning: All deletes are hard-deletes and are not reversible

HTTP Headers

There only 2 required headers:

  1. Authorization. See: Authentication.
  2. Content-Type. Should be set to application/json.
  3. X-Device-Info. See: Device-Info Header.

Error Handling

A Typical error response looks like this:

{
  "timestamp": 1465339637896,
  "status": 400,
  "error": "Bad Request",
  "exception": "com.ebates.rclon.service.core.exceptions.MandatoryFieldValidationException",
  "message": "Value expected for field entry when requesting to create a Cardholder. The firstName field should be provided in the request'",
  "path": "/v1/users"
}

When using the Client SDK, and an exception occurs, the SDK will throw either a ClientException or a ServerException which both have a base class of a RestException. A ClientException indicates that you have submitted a Bad Request, whereas a ServerException indicates that a server-side error has occurred. If a ServerException occurs please contact your RCLON Administrator.

Having all client errors extend from the same base class, RestException, allows for ease of coding and handling errors programatically. Both the ClientException and ServerException should be caught, and then can be dealt with generically. The member variables on both types of exception, which belong to the RestException class are as follows:

 private Data timestamp - the time at which the error occured.
 private int status - represents a status code of the exception.
 private String error - a description of the error itself.
 private String exception - the underlying exception that was thrown on the server.
 private String message - a human readable message describing the error (suitable for client display).
 private String path -

These are all accessible via standard Java "get" methods:

  public Date getTimeStamp()
  public int getStatus()
  public String getError()
  public String getException()
  public String getMessage()
  public String getPath()

POST and PUT Responses

Whenever a resource is created or updated, the response payload that is returned is the updated state of that resource.

Sorting

When querying for a list of resources you can specify a sortBy query parameter. Sorting by direction and multiple fields is supported. The default sort direction is asc. For example, if you need to retrieve Cardholders sorted by lastName ascending and firstName descending you could use the following URI:

GET /cardholders?sortBy=lastName,firstName.dir:desc

Query Metadata and Pagination

When doing a GET request that returns a collection of resources, a ResourceQueryResponse object is returned which contains metadata. The metadata object consists of summary and pagination information. A typical query response looks like this:

{
  "metadata": {
    "page": 0,
    "pageSize": 500,
    "totalRecords": 14,
    "totalPages": 1,
    "isCached": false
  },
  "records": [
   /the collection of resources
  ],
  "errors": []
}
  • The default pageSize is 500. You can override this by adding a ?pageSize query parameter.
  • The page numbering system is 0-indexed, so if you wish to see the first page of results, set the ?page=0 query parameter.
  • If isCached is true, this indicates that the record set did not hit the database, rather it was found in the service cache.
  • To bypass caching you can add a ?disableCache=true query parameter on when caching is used to retrieve a set of resources that supports caching.

Fetch Parameter

To request for embedded resources or child resources you can use the fetch query parameter. For example if you wish to retrieve cardholders with their cards array, use /cardholders?fetch=cards rather than /cardholders.

Timestamps

By default, all timestamps are returned in ISO 8601 format and contain milliseconds and are in the UTC (+0000) TimeZone:

yyyy-MM-dd'T'HH:mm:ss.SSSZ

Example: 2016-06-10T10:30:55.529+0000