Welcome

Welcome to Clearhaus Merchant API.

The Merchant API is currently in Public Beta.

General guidelines

  1. Use the link relations provided to interact with the API; don’t rely on URLs (which are not supplied, on purpose)
  2. To query a resource or a collection of resources use GET
  3. To create a resource use POST on a collection link
  4. To update a resource use PATCH on a resource link
  5. To remove a resource use DELETE on a resource link
  6. If you have doubts about what you can do with a given link use OPTIONS
  7. 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 a Client App with Clearhaus to obtain client credentials, client_id and client_secret.

While the API is in public beta, registration is made by request, via support@clearhaus.com.

Please send Client App name (e.g. Transactions collector bot), short description (e.g. Collect and process transaction information) and contact email (e.g. trxbot@example.com).

A GPG Public Key is also required, so that client_id and client_secret can be securely sent.

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

Currently two grants are supported: Resource Owner Password Credentials Grant and Client Credentials Grant.

  1. Resource Owner Password Credentials Grant (Partners and Merchants)

    For partners and merchants, that already have a Clearhaus account.

    The username and password parameters should be that of a user that is a member of the merchant account(s) in Dashboard.

    Please note that the email for this user should match the one provided as contact email on Client registration.

    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=password"      \
         -d "username=user@domain.com" \
         -d "password=password"
    
  2. Client Credentials Grant (Partners)

    For partners, that wish to automate application creation and bootstrapping.

    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": {
    "curies": [
      {
        "href": "http://developer.clearhaus.com/rels/{rel}",
        "templated": true,
        "name": "ch"
      }
    ],
    "ch:root": {
      "href": "https://merchant.test.clearhaus.com"
    }
  }
}

Media types

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.

A paginated collection provides page and per_page template variables. per_page default value is 20, maximum value is 50.

A paginated resource will provide a templated link of the form:

{
  ...
  "_links": {
    "ch:files": {
      "href": "https://merchant.test.clearhaus.com/applications/ef7c6a50-65d7-47dd-baa6-b7f836d540b1/files{?page,per_page}",
      "templated": "true"
    }
  }
  ...
}

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).

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 <token>"
     -H "Content-Type: application/json" \
     -d '{
           "label": "picture_legitimation",
           "name": "passport.jpg",
           "content_type": "image/jpg",
           "size": 1234
         }'
{
  "label": "picture_legitimation",
  "name": "passport.jpg",
  "content_type": "image/jpg",
  "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": "http://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/jpg" \
     --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 <token>"

Some stamps can only be added (PUT), others can be removed (DELETE). The documentation for each resource will have details on the supported stamps, if any. See Application as example.

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.