Applications examples

The examples assume that an access_token has been obtained and the client is ready to call the Merchant API. See Authentication example for more information.

Create application

See Application JSON for more information on how to supply a json file and its structure.

api_client.config(API_ROOT => { 'headers' => { 'Authorization' => "Bearer #{access_token}" } })

# Load application.json with full application data (except files)
json = File.read('application.json')

# POST the json file to ch:applications
app = api_client.get.links['ch:applications'].post(JSON.load(json))

app.body
=>
{
  "signer"                 => {
    "name"  => "Mia M. Lassen",
    "email" => "MiaMLassen@example.com"
  },
  "business_model" => {
    "trading_name"                         => "Acme Co.",
    "description"                          => "Prime non-generic products",
    "recurring"                            => true,
    "physical_delivery"                    => true,
    "delivery_delay"                       => "5to10days",
    "estimate_currency"                    => "DKK",
    "estimated_monthly_turnover"           => 300000,
    "estimated_average_transaction_amount" => 1000
  },
  "additional_information" => "Hello",
  "metadata"               => {
    "state"      => "unsubmitted",
    "created_at" => "2016-08-22T13:55:20.699Z"
  },
  "_links"                 => {
    "self"              => {
      "href" => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d"
    },
    "ch:contact"        => {
      "href" => "https://merchant.test.clearhaus.com/contacts/d050f64f-7cf7-4015-bdcf-20c85f7d198d"
    },
    "ch:company"        => {
      "href" => "https://merchant.test.clearhaus.com/companies/6e641d2d-3073-4969-a9a4-af4b492c3881"
    },
    "ch:bank-account"   => {
      "href" => "https://merchant.test.clearhaus.com/bank_accounts/42bceae3-7c88-4c01-92fc-7d2058014f8d"
    },
    "ch:websites"       => {
      "href"      => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d/websites{?page,per_page}",
      "templated" => true
    },
    "ch:files"          => {
      "href"      => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d/files{?page,per_page}",
      "templated" => true
    },
    "ch:collaborators"  => {
      "href"      => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d/collaborators{?page,per_page}",
      "templated" => true
    },
    "curies"            => [
      {
        "href"      => "https://developer.clearhaus.com/rels/{rel}",
        "templated" => true,
        "name"      => "ch"
      }
    ]
  }
}

Add mandatory files

The previous example created a full application with the Director as the sole owner. It is required that each Person resource have at least 2 files, with labels picture_legitimation and address_legitimation.

company = app.get.links['ch:company']

director_files = company.get.links['ch:director'].get.links['ch:files']

# POST file metadata (picture_legitimation)
picture_legitimation = director_files.post({ label: 'picture_legitimation',
                                             content_type: 'image/png' })

picture_legitimation.body
=>
{
  "label"        => "picture_legitimation",
  "name"         => "picture_legitimation",
  "content_type" => "image/png",
  "_links"       => {
    "self"      => {
      "href" => "https://merchant.test.clearhaus.com/files/f607d457-fc61-4ead-beb8-e6a63e13668c"
    },
    "ch:person" => {
      "href" => "https://merchant.test.clearhaus.com/people/40b34d39-d5f8-4658-b5b3-26e82cf5c1ca"
    },
    "ch:data"   => [
      {
        "href" => "https://clrhs-staging-cutter.s3.amazonaws.com/4/8860397b09a112985c4054e8388a8cf90dbd4817781794e9a3eae4f469679a6a.png?AWSAccessKeyId=AKIAJES3GRGWBQL7JHXA&Expires=1471878435&Signature=xKso9BOnPpOVPPgSZmaxNhQAJ30%3D",
        "name" => "upload"
      },
      {
        "href" => "https://merchant.test.clearhaus.com/files/f607d457-fc61-4ead-beb8-e6a63e13668c/content",
        "name" => "download"
      }
    ],
    "curies"    => [
      {
        "href"      => "https://developer.clearhaus.com/rels/{rel}",
        "templated" => true,
        "name"      => "ch"
      }
    ]
  }
}

# POST file metadata (address_legitimation)
address_legitimation = director_files.post({ label: 'address_legitimation',
                                             content_type: 'image/png' })

After the file metadata is created the client should PUT the binary content to ch:data upload href. See File handling for more information on handling files.

Invite collaborator

collaborators = app.get.links['ch:collaborators']

# Invite a collaborator to access the application
invited = collaborators.post(email: 'CarolineSBech@example.com',
                             message: 'Please finish the application. Thanks.')

invited.body
=>
{
  "name"   => "Caroline S. Bech",
  "email"  => "CarolineSBech@example.com",
  "_links" => {
    "self"           => {
      "href" => "https://merchant.test.clearhaus.com/collaborators/e7499f1a-7148-4549-bc49-fd461a8704ea"
    },
    "ch:application" => {
      "href" => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d"
    },
    "curies"         => [
      {
        "href"      => "https://developer.clearhaus.com/rels/{rel}",
        "templated" => true,
        "name"      => "ch"
      }
    ]
  },
}

To give other users access to the application one must add them as collaborators. Please note that at least the contact person should be invited as a collaborator. See Contact for more information on how the contact person relates to a collaborator.

Submit an application

Once all the application data and required files are supplied, new links (ch:stamps) become available, as the application is now ready to be submitted.

In this case, Application supports 2 different stamps. See the application additional semantics for details about the supported stamps.

# Retrieve the application resource to get the new links
app.get.body
=>
{
  "additional_information" => "Hello",
  "signer"                 => {
    "name"  => "Mia M. Lassen",
    "email" => "MiaMLassen@example.com"
  },
  "metadata"               => {
    "state"      => "unsubmitted",
    "created_at" => "2016-08-22T13:55:20.699Z"
  },
  "_links"                 => {
    "self"              => {
      "href" => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d"
    },
    ...
    "ch:stamps"         => [
      {
        "href" => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d/stamps/submitted",
        "name" => "submitted"
      },
      {
        "href" => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d/stamps/archived",
        "name" => "archived"
      }
    ],
    ...
  }
}

# PUT the `submitted` stamp to mark the application as submitted
app.get.links['ch:stamps'].find {|s| s.name == 'submitted' }.put

app.get.body
=>
{
  "additional_information" => "Hello",
  "signer"                 => {
    "name"  => "Mia M. Lassen",
    "email" => "MiaMLassen@example.com"
  },
  "metadata"               => {
    "state"      => "submitted",
    "created_at" => "2016-08-22T13:55:20.699Z"
  },
  "_links"                 => {
    "self"              => {
      "href" => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d"
    },
    ...
  }
}

See Stamps for more about how Stamps work.

List applications

The applications resource is a paginated collection that can be filtered via the state query parameter. See ch:applications request parameters for details about the state query parameter.

# Filter applications by state `under_review`
api_client.get.links['ch:applications'].where(state: 'under_review').get.body
=>
{
  "count"     => 1,
  "page"      => 1,
  "per_page"  => 20,
  "_links"    => {
    "self"   => {
      "href" => "https://merchant.test.clearhaus.com/applications"
    },
    "curies" => [
      {
        "href"      => "https://developer.clearhaus.com/rels/{rel}",
        "templated" => true,
        "name"      => "ch"
      }
    ]
  },
  "_embedded" => {
    "ch:applications" => [
      {
        "additional_information" => "Hello",
        "signer"                 => {
          "name"  => "Mia M. Lassen",
          "email" => "MiaMLassen@example.com"
        },
        "metadata"               => {
          "state"      => "under_review",
          "created_at" => "2016-08-22T13:55:20.699Z"
        },
        "_links"                 => {
          "self"              => {
            "href" => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d"
          },
          ...
        }
      }
    ]
  }
}