Welcome

Welcome to Clearhaus Merchant API.

General guidelines

Use the link relations provided to interact with the API; don’t rely on URLs (which are not supplied, on purpose)
To query a resource or a collection of resources use GET
To create a resource use POST on a collection link
To update a resource use PATCH on a resource link
To remove a resource use DELETE on a resource link
If you have doubts about what you can do with a given link use OPTIONS
Templated URLs will be provided when appropriate. See URI Template (RFC 6570).

Entrypoints

https://merchant.clearhaus.com       # Production
https://merchant.test.clearhaus.com  # Sandbox

Authentication

Authentication is done via HTTP Bearer scheme.

curl -X GET https://merchant.test.clearhaus.com -H "Authorization: Bearer <access_token>"

The means by which the access_token is obtained follow the OAuth 2.0 Authorization Framework (https://tools.ietf.org/html/rfc6749). See also Client registration and Supported grants.

Client registration

To obtain an access_token and start calling the Merchant API, developers need to register an OAuth Client with Clearhaus to obtain client credentials, client_id and client_secret.

See OAuth Clients to create and manage your Clients.

Client registration can also be done programatically. It follows the OAuth 2.0 Dynamic Client Registration Protocol specification and supports Protected Client Registration (see https://tools.ietf.org/html/rfc7591#appendix-A.1 for information about Open versus Protected Client Registration).

The implementation currently defines the following extension parameter:

name	description
description	Short description of the purpose of the Client

Example request:

curl -X POST https://merchant.test.clearhaus.com/oauth/clients \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
           "client_name": "Transactions collector bot",
           "grant_types": ["client_credentials"],
           "contacts": ["trxbot@example.com"],
           "description": "Collect and process transaction information"
         }'

Example response:

{
  "client_name": "Transactions collector bot",
  "grant_types": ["client_credentials"],
  "contacts": ["trxbot@example.com"],
  "description": "Collect and process transaction information",
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "_links": {
    "self": {
      "href": "https://merchant.test.clearhaus.com/oauth/clients/2c48923c-bcac-482f-b5d7-5506f32bab61"
    },
    "curies": [
      {
        "href": "https://developer.clearhaus.com/rels/{rel}",
        "templated": true,
        "name": "ch"
      }
    ]
  }
}

The only supported client type is confidential:

OAuth defines two client types, based on their ability to
authenticate securely with the authorization server (i.e., ability to
maintain the confidentiality of their client credentials):

   confidential
      Clients capable of maintaining the confidentiality of their
      credentials (e.g., client implemented on a secure server with
      restricted access to the client credentials), or capable of secure
      client authentication using other means.
...

in OAuth 2.0 Authorization Framework: Client Types.

Supported grants

We support the Client Credentials Grant.

Client Credentials Grant

Example request:

curl -X POST https://merchant.test.clearhaus.com/oauth/token \
     -u $CLIENT_ID:$CLIENT_SECRET \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "audience=https://merchant.test.clearhaus.com"    \
     -d "grant_type=client_credentials"

Example response:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 86400,
  "_links": {
    "ch:root": {
      "href": "https://merchant.test.clearhaus.com"
    },
    "curies": [
      {
        "href": "https://developer.clearhaus.com/rels/{rel}",
        "templated": true,
        "name": "ch"
      }
    ]
  }
}

Media types

Request: application/json (https://tools.ietf.org/html/rfc4627)
Response: application/hal+json (https://tools.ietf.org/html/draft-kelly-json-hal-08)
Error response: application/problem+json (https://tools.ietf.org/html/rfc7807)

Error handling

Error responses use application/problem+json (https://tools.ietf.org/html/rfc7807) media type.

The Merchant API currently define the following extension members:

name	description
errors	Describe the issues with the request invalid parameters
oauth2-token	Hint at where the consumer should authenticate before trying again
request-id	Used for request traceability

Invalid request parameters:

{
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains invalid parameters",
  "errors": {
    "currency": [
      "does not follow ISO 4217"
    ]
  },
  "request-id": "ecb2fc78-d992-4fc4-bef5-66cd68a639e8"
}

Unauthorized request:

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid token",
  "oauth2-token": "https://merchant.test.clearhaus.com/oauth/token",
  "request-id": "98a877f6-d703-44ad-891d-4b4317d7b870"
}

Service unavailable:

{
  "title": "Service Unavailable",
  "status": 503,
  "request-id": "e3ae5e99-67ec-4ac9-a8ff-e75db5833cb8"
}

Pagination

A Collection resource will be paginated.

Pagination links (first, prev, next, last - see IANA Link Relations) are available when appropriate.

Collections use one of two pagination styles: page-based or cursor-based. Clients should detect which style is in use from the response and follow the relevant pagination links rather than constructing them by hand.

Page-based pagination

A page-based collection provides per_page as a template variable. It defaults to 20 and has a maximum value of 50. The response carries page, per_page, and count (total number of items) fields, so the total number of pages is known.

A page-based resource will provide a templated link of the form:

{
  ...
  "_links": {
    "ch:applications": {
      "href": "https://merchant.test.clearhaus.com/applications{?query,per_page,page}",
      "templated": true
    }
  }
  ...
}

The _links section of a page-based collection response contains first, prev, next, and last (each conditional on position within the collection):

{
  "_links": {
    "self": {
      "href": "https://merchant.test.clearhaus.com/applications"
    },
    "first": {
      "href": "https://merchant.test.clearhaus.com/applications?per_page=20&page=1"
    },
    "prev": {
      "href": "https://merchant.test.clearhaus.com/applications?per_page=20&page=2"
    },
    "next": {
      "href": "https://merchant.test.clearhaus.com/applications?per_page=20&page=4"
    },
    "last": {
      "href": "https://merchant.test.clearhaus.com/applications?per_page=20&page=7"
    },
    "curies": [
      {
        "href": "https://developer.clearhaus.com/rels/{rel}",
        "templated": true,
        "name": "ch"
      }
    ]
  },
  ...
}

Cursor-based pagination

A cursor-based collection does not expose page or count fields. The per_page template variable is still accepted, with the same default (20) and maximum (50) as page-based pagination, and is echoed back as a response property.

Navigation is performed by following the next link, whose href carries an opaque cursor token in the next query parameter. Clients should treat the token as opaque — do not parse or construct it — and simply follow the link as-is. A first link is also provided.

Because the cursor token does not encode position within a known total, the total number of pages and items is not known up-front. The end of the collection is reached when the next link is no longer present.

The _links section of a cursor-based collection response contains first and next (each conditional on the collection containing items / having more items to return). There are no prev or last links:

{
  "_links": {
    "self": {
      "href": "https://merchant.test.clearhaus.com/transactions"
    },
    "first": {
      "href": "https://merchant.test.clearhaus.com/transactions?per_page=20"
    },
    "next": {
      "href": "https://merchant.test.clearhaus.com/transactions?per_page=20&next=<opaque-token>"
    },
    "curies": [
      {
        "href": "https://developer.clearhaus.com/rels/{rel}",
        "templated": true,
        "name": "ch"
      }
    ]
  },
  ...
}

To detect which style a given collection uses, inspect the response: presence of a page field indicates page-based pagination; otherwise, the presence of a next link indicates cursor-based pagination.

File handling

Some resources allow files to be associated with them. Examples of this are Person resources (Company director and owners, where a document with picture and address are required), the Application itself, and Disputes (where one might add copies of invoices and other relevant documentation).

Important: When uploading files for dispute cases, ensure that each file does not exceed 10MB. Files larger than this limit may not be processed correctly by the card schemes, which could impact the dispute resolution process.

To create a file resource, POST file metadata to ch:files. The resulting resource contains link relations (ch:data) for uploading and downloading the actual binary content.

curl -X POST https://merchant.test.clearhaus.com/people/3128a7e4-9594-42fb-a9bd-4f444b58110f/files \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
           "label": "picture_legitimation",
           "name": "passport.jpg",
           "content_type": "image/jpeg",
           "size": 1234
         }'

{
  "label": "picture_legitimation",
  "name": "passport.jpg",
  "content_type": "image/jpeg",
  "size": 1234,
  "_links": {
    "self": {
      "href": "https://merchant.test.clearhaus.com/files/93cc1a9a-70f7-48d3-afad-d5de920414bc"
    },
    "ch:person": {
      "href": "https://merchant.test.clearhaus.com/people/3128a7e4-9594-42fb-a9bd-4f444b58110f"
    },
    "ch:data": [
      {
        "href": "https://clrhs-staging-cutter.s3.amazonaws.com/5/faf8e4b963ceb372be2cf1b43d37cb3b4eaa7bba503bfb6c41c102710fd695ea.pdf?AWSAccessKeyId=AKIAJES3GRGWBQL7JHXA&Expires=1469819943&Signature=xq029mepfm1ii90b00tfZQQlg94%3D",
        "name": "upload"
      },
      {
        "href": "https://merchant.test.clearhaus.com/files/93cc1a9a-70f7-48d3-afad-d5de920414bc/content",
        "name": "download"
      }
    ],
    "curies": [
      {
        "href": "https://developer.clearhaus.com/rels/{rel}",
        "templated": true,
        "name": "ch"
      }
    ]
  }
}

Once the file resource is created, PUT the binary content to ch:data upload href.

curl -X PUT https://clrhs-staging-cutter.s3.amazonaws.com/5/faf8e4b963ceb372be2cf1b43d37cb3b4eaa7bba503bfb6c41c102710fd695ea.pdf?AWSAccessKeyId=AKIAJES3GRGWBQL7JHXA&Expires=1469819943&Signature=xq029mepfm1ii90b00tfZQQlg94%3D \
     -H "Content-Type: image/jpeg" \
     --upload-file <filepath>

Stamps

Stamps are a means of advancing a resource through a given set of steps.

For example, an Application, once it has all the necessary data, is ready to be submitted. To submit an application, PUT the submitted stamp:

curl -X PUT https://merchant.test.clearhaus.com/applications/ef7c6a50-65d7-47dd-baa6-b7f836d540b1/stamps/submitted \
     -H "Authorization: Bearer <access_token>"

Some stamps can only be added (PUT), others can be removed (DELETE). See Application as example.

Some stamps support an optional note request parameter. See Contract as example.

The documentation for each resource will have details on the supported stamps, if any.

Field comments

Field comments are used to attach comments to a specific property of a resource.

A field comment is attached to the resource with a special tag crafted by prefixing the property name with ch-field:.

Resources that support field comments have a Commentable column in the list of properties which indicates if a property supports field comments.

A comment will be rejected unless exactly one of the supported field comment tags are used when commenting on a resource that supports field comments.

Selection

Some resources support select semantics.

For example, an Application, requires the selection of a Gateway.

curl -X PUT "https://merchant.test.clearhaus.com/applications/3128a7e4-9594-42fb-a9bd-4f444b58110f/gateways/88a92fb6-cf56-4ece-bc5d-1b544ad5a1e1"
     -H "Authorization: Bearer <access_token>"

Profiles

... a profile can be described as additional semantics that can be used to process a
resource representation, such as constraints, conventions, extensions, or any other aspects
that do not alter the basic media type semantics.
...

in The ‘profile’ Link Relation Type (RFC 6906).

The API documentation is mostly organized around link relations and how to interact with them.

However, when visiting a given link relation page, there will be profile information, describing the semantics of the represented resource.

Rate limit

We use rate limits as an anti-abuse mechanism to protect the API.

From RateLimit Header Fields for HTTP we utilize the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers to inform the consumer about the quota that applies to the endpoint, how many request are remaining, and when the quota usage will reset.

Gracefully handling limits

The best approach for handling rate limits it to build in retry logic for when the status code 429 is encountered.

Retry logic for rate limiting should factor in the rate limit headers returned from the API.