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:people" => {
"href" => "https://merchant.test.clearhaus.com/applications/19be420f-491b-407c-8505-a506326f935d/people{?page,per_page}",
"templated" => true
},
"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
},
"ch:record": {
"href": "https://merchant.test.clearhaus.com/records/19be420f-491b-407c-8505-a506326f935d"
},
"curies" => [
{
"href" => "https://developer.clearhaus.com/rels/{rel}",
"templated" => true,
"name" => "ch"
}
]
}
}
Add mandatory files
The previous example created a full application with a
Person as director and 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']
person_files = company.get.links['ch:people'].get.first.links['ch:files']
# POST file metadata (picture_legitimation)
picture_legitimation = person_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 = person_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 query parameter. See Application Query Language (APQL) for details about the query parameter.
# Filter applications by state `under_review`
api_client.get.links['ch:applications'].where(query: 'metadata.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"
},
...
}
}
]
}
}