Disputes 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.
List disputes
After retrieving accounts, one can list and query the disputes for a given account:
root_links = api_client.get.links
# Get first item on _embedded ch:accounts
account = root_links['ch:accounts'].get.objects['ch:accounts'].first
# Get disputes scoped to the account
disputes = account.get.links['ch:disputes']
The same can be accomplished using Dispute Query Language:
disputes = api_client.get.links['ch:disputes'] \
.where(query: 'status:open reason:4837 mid:2000001')
disputes.get.body
=>
{
"count" => 1,
"page" => 1,
"per_page" => 20,
"_links" => {
"self" => {
"href" => "https://merchant.test.clearhaus.com/disputes"
},
"curies" => [
{
"href" => "https://developer.clearhaus.com/relations/{rel}",
"templated" => true,
"name" => "ch"
}
]
},
"_embedded" => {
"ch:disputes" => [
{
"id" => "c6d9153b-32cb-472a-9dc9-553e9c79ea22",
"reference" => "76305919047987300424222",
"amount" => 58704,
"currency" => "DKK",
"partial" => false,
"opened_at" => "2016-02-28",
"due_at" => "2016-03-13",
"expires_at" => "2016-04-10",
"status" => "open",
"reason_code" => "4837",
"reason" => "fraud",
"type" => "1st_chargeback",
"_links" => {
"self" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22"
},
"ch:transaction" => {
"href" => "https://merchant.test.clearhaus.com/transactions/a51a3abe-8eee-4a92-b941-e89f18c5bf66"
},
"ch:files" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/files"
},
"ch:comments" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/comments"
},
"ch:stamps" => [
{
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/stamps/refuted",
"name" => "refuted"
},
{
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/stamps/accepted",
"name" => "accepted"
}
]
}
}
]
}
}
Add comment
# Retrieve the dispute from the previous listing
dispute = disputes.get.objects['ch:disputes'].first
comments = dispute.get.links['ch:comments']
comments.post(body: 'Please see attached files.')
=>
{
"body" => "Please see attached files.",
"created_at" => "2016-09-09T13:16:16.939Z",
"_links" => {
"self" => {
"href" => "https://merchant.test.clearhaus.com/comments/5b8ba59a-8409-4615-bc8c-fedca5842123"
},
"ch:dispute" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22"
},
"curies" => [
{
"href" => "https://developer.clearhaus.com/relations/{rel}",
"templated" => true,
"name" => "ch"
}
]
},
"_embedded" => {
"ch:user" => {
"name" => "Mia M. Lassen",
"email" => "MiaMLassen@example.com",
"_links" => {
"self" => {
"href" => "https://merchant.test.clearhaus.com/users/bb7139df-f88d-4b5e-906e-4e7efabf0b0b"
}
}
}
}
}
Refute a dispute
Once a merchant receives a dispute, it can be accepted or refuted through the use of Stamps.
In this case, Dispute supports 2 different stamps. See the dispute additional semantics for details about the supported stamps.
To refute, start by adding the relevant documentation.
files = dispute.get.links['ch:files']
# POST file metadata
invoice_copy = files.post({
name: 'CustomerInvoice.pdf',
label: 'customer invoice',
content_type: 'application/pdf'
})
invoice_copy.get.body
=>
{
"label" => "customer invoice",
"name" => "CustomerInvoice.pdf",
"content_type" => "application/pdf",
"_links" => {
"self" => {
"href" => "https://merchant.test.clearhaus.com/files/83054c75-5c01-4bf7-a9ee-3769ec3a00a3"
},
"ch:dispute" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22"
},
"ch:data" => [
{
"href" => "https://clrhs-stag-nonpci-filr.s3.amazonaws.com/4/8860397b09a112985c4054e8388a8cf90dbd4817781794e9a3eae4f469679a6a.png?AWSAccessKeyId=AKIAJES3GRGWBQL7JHXA&Expires=1471878435&Signature=xKso9BOnPpOVPPgSZmaxNhQAJ30%3D",
"name" => "upload"
},
{
"href" => "https://merchant.test.clearhaus.com/files/83054c75-5c01-4bf7-a9ee-3769ec3a00a3/content",
"name" => "download"
}
],
"curies" => [
{
"href" => "https://developer.clearhaus.com/rels/{rel}",
"templated" => true,
"name" => "ch"
}
]
}
}
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.
Once the relevant documentation is in place, the dispute can be refuted.
dispute.get.body
=>
{
"id" => "c6d9153b-32cb-472a-9dc9-553e9c79ea22",
"reference" => "76305919047987300424222",
"amount" => 58704,
"currency" => "DKK",
"partial" => false,
"opened_at" => "2016-02-28",
"due_at" => "2016-03-13",
"expires_at" => "2016-04-10",
"status" => "open",
"reason_code" => "4837",
"reason" => "fraud",
"type" => "1st_chargeback",
"_links" => {
"self" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22"
},
...
"ch:stamps" => [
{
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/stamps/refuted",
"name" => "refuted"
},
{
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/stamps/accepted",
"name" => "accepted"
}
],
...
}
}
# PUT the `refuted` stamp to mark the dispute as refuted
dispute.get.links['ch:stamps'].find {|s| s.name == 'refuted' }.put
dispute.get.body
=>
{
"id" => "c6d9153b-32cb-472a-9dc9-553e9c79ea22",
"reference" => "76305919047987300424222",
"amount" => 58704,
"currency" => "DKK",
...
"status" => "under_review",
"reason_code" => "4837",
"reason" => "fraud",
"type" => "1st_chargeback",
"_links" => {
"self" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22"
},
...
"ch:files" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/files"
},
...
}
}
List new disputes
It is a common scenario for a merchant to want to import dispute data into their own systems.
New dispute data is processed daily (except for sunday) between 1am-3am UTC.
If wanting to import newly arrived disputes, one can make use of the opened_at query modifier, available in the Dispute Query Language:
disputes = api_client.get.links['ch:disputes'] \
.where(query: 'status:open opened_at:today')
disputes.get.body
=>
{
"count" => 1,
"page" => 1,
"per_page" => 20,
"_links" => {
"self" => {
"href" => "https://merchant.test.clearhaus.com/disputes"
},
"curies" => [
{
"href" => "https://developer.clearhaus.com/relations/{rel}",
"templated" => true,
"name" => "ch"
}
]
},
"_embedded" => {
"ch:disputes" => [
{
"id" => "c6d9153b-32cb-472a-9dc9-553e9c79ea22",
"reference" => "76305919047987300424222",
"amount" => 58704,
"currency" => "DKK",
"partial" => false,
"opened_at" => "2016-02-28",
"due_at" => "2016-03-13",
"expires_at" => "2016-04-10",
"status" => "open",
"reason_code" => "4837",
"reason" => "fraud",
"type" => "1st_chargeback",
"_links" => {
"self" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22"
},
"ch:transaction" => {
"href" => "https://merchant.test.clearhaus.com/transactions/a51a3abe-8eee-4a92-b941-e89f18c5bf66"
},
"ch:files" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/files"
},
"ch:comments" => {
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/comments"
},
"ch:stamps" => [
{
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/stamps/refuted",
"name" => "refuted"
},
{
"href" => "https://merchant.test.clearhaus.com/disputes/c6d9153b-32cb-472a-9dc9-553e9c79ea22/stamps/accepted",
"name" => "accepted"
}
]
}
}
]
}
}