Welcome to Clearhaus Transaction API. You can use our API to process payment card transactions. The API is organized around REST and designed to have predictable and resource-oriented URLs. The table below basically sums up what you can do:
POST https://gateway.clearhaus.com/authorizationsPOST https://gateway.clearhaus.com/authorizations/:id/capturesPOST https://gateway.clearhaus.com/authorizations/:id/refundsPOST https://gateway.clearhaus.com/cards/:id/creditsPOST https://gateway.clearhaus.com/cardsYou need an API key before you can interact with our API. Send an E-mail to support@clearhaus.com to request an API key.
API keys come with many privileges so keep them secret.
https://gateway.clearhaus.com # live accounts
https://gateway.test.clearhaus.com # test accounts
Authentication is done via HTTP Basic Auth. Simply provide your API key as
username and a blank string as password. Remember a colon : after username
when using cURL to specify an empty password.
curl https://gateway.test.clearhaus.com \
-u <your-api-key>:
You will get this response when you provide an invalid API key:
HTTP/1.1 401 Not Authorized
The API follows HATEOAS principle of REST which means all resources are discoverable.
curl https://gateway.test.clearhaus.com \
-u <your-api-key>:
{
"_links": {
"authorizations": { "href": "/authorizations" },
"cards": { "href": "/cards" },
"account": { "href": "/account" }
}
}
All responses will be delivered in JSON format (see JSON-HAL).
Content-Type: application/vnd.clearhaus-gateway.hal+json; version=0.10.0; charset=utf-8
where the version follows Semantic Versioning.
We use HTTP response codes to indicate API response status:
Number Text
200 OK
201 Created
400 Bad Request
401 Unauthorized
404 Not Found
5xx Server Error
Requests can optionally be signed.
The signature is an RSA signature of the HTTP body; it is represented in hex.
The signee must be identified by the signing API-key. Both should be provided in
a Signature header together with RS256-hex:
Signature: <signing api-key> RS256-hex <signature>
Notice: If the signature header is included, it should hold a correct signature, otherwise the transaction will fail.
The RSA signature is an RSASSA-PKCS1-v1_5 signature of the body. It is represented in hex.
If the signing API-key is 4390aec7-f76a-4c2f-8597-c87c2d06cb4f, the signing
private key (in PEM format) is
-----BEGIN RSA PRIVATE KEY-----
MIIBOwIBAAJBALYK0zmwuYkH3YWcFNLLddx5cwDxEY7Gi1xITuQqRrU4yD3uSw+J
WYKknb4Tbndb6iEHY+e6gIGD+49TojnNeIUCAwEAAQJARyuYRRe4kcBHdPL+mSL+
Y0IAGkAlUyKAXYXPghidKD/v/oLrFaZWALGM2clv6UoYYpPnInSgbcud4sTcfeUm
QQIhAN2JZ2qv0WGcbIopBpwpQ5jDxMGVkmkVVUEWWABGF8+pAiEA0lySxTELZm8b
Gx9UEDRghN+Qv/OuIKFldu1Ba4f8W30CIQCaQFIBtunTTVdF28r+cLzgYW9eWwbW
pEP4TdZ4WlW6AQIhAMDCTUdeUpjxlH/87BXROORozAXocBW8bvJUI486U5ctAiAd
InviQqJd1KTGRDmWIGrE5YACVmW2JSszD9t5VKxkAA==
-----END RSA PRIVATE KEY-----
and the body is
amount=2050¤cy=EUR&ip=1.1.1.1&card[pan]=4111111111111111&card[expire_month]=06&card[expire_year]=2022&card[csc]=123
then the Signature header should be
Signature: 4390aec7-f76a-4c2f-8597-c87c2d06cb4f RS256-hex 7ae0e14d35b2a15a7ff812a1899d7f0a5d28063f0c276081876a51fc3773f499459f944f8b57c6e0e76b47c218b20ebaad7c6250dcd1804dd19c87fb7f1216ba
In Ruby, you can calculate the RS256 hex signature using
key = OpenSSL::PKey::RSA.new(key_in_pem_string)
key.sign(OpenSSL::Digest.new('sha256'), body).unpack('H*').first
To charge a cardholder you first have to reserve money on his bank account. Next you can transfer money from his bank account to your merchant bank account.
The following will reserve EUR 20.50 (2050 cents) on cardholder’s bank account:
curl -X POST https://gateway.test.clearhaus.com/authorizations \
-u <your-api-key>: \
-d "amount=2050" \
-d "currency=EUR" \
-d "ip=1.1.1.1" \
-d "card[pan]=4111111111111111" \
-d "card[expire_month]=06" \
-d "card[expire_year]=2022" \
-d "card[csc]=123"
Example response (snippet):
{
"id": "84412a34-fa29-4369-a098-0165a80e8fda",
"status": {
"code": 20000
},
"csc": {
"present": true,
"matches": true
},
"processed_at": "2018-07-09T12:58:56+00:00",
"_links": {
"captures": { "href": "/authorizations/84412a34-fa29-4369-a098-0165a80e8fda/captures" }
}
}
In order to actually transfer money from cardholder’s bank account to your merchant bank account you will have to make a capture transaction.
Notice: Some issuers will approve authorizations although the CSC did not
match; in this case the status code will be
20000 but csc matches will be
false. Please be aware that rules to disallow captures for such
authorizations may be in place for a merchant.
The following will make a capture transaction and withdraw what you have reserved on cardholder’s bank account.
curl -X POST \
https://gateway.test.clearhaus.com/authorizations/84412a34-fa29-4369-a098-0165a80e8fda/captures \
-u <your-api-key>:
You can withdraw a partial amount by providing an amount parameter:
curl -X POST \
https://gateway.test.clearhaus.com/authorizations/84412a34-fa29-4369-a098-0165a80e8fda/captures \
-u <your-api-key>: \
-d "amount=1000"
Example response (snippet):
{
"id": "d8e92a70-3030-4d4d-8ad2-684b230c1bed",
"status": {
"code": 20000
},
"processed_at": "2018-07-09T12:58:56+00:00",
"amount": 1000,
"_links": {
"authorization": {
"href": "/authorizations/84412a34-fa29-4369-a098-0165a80e8fda"
},
"refunds": {
"href": "/authorizations/84412a34-fa29-4369-a098-0165a80e8fda/refunds"
}
}
}
You can refund all money or a partial amount of what you have withdrawn from cardholder’s bank account:
curl -X POST \
https://gateway.test.clearhaus.com/authorizations/84412a34-fa29-4369-a098-0165a80e8fda/refunds \
-u <your-api-key>: \
-d "amount=500"
Example response (snippet):
{
"id": "f04c0872-47ce-4683-8d8c-e154221bba14",
"status": {
"code": 20000
},
"processed_at": "2018-07-09T12:58:56+00:00",
"amount": 500,
"_links": {
"authorization": { "href": "/authorizations/84412a34-fa29-4369-a098-0165a80e8fda" }
}
}
A card token is a value that references card details (see Tokenization). You can use a card token (card resource) to make authorization and credit transactions.
A card resource is automatically made when you make an authorization transaction and supply card details. You can also make a card resource directly:
curl -X POST https://gateway.test.clearhaus.com/cards \
-u <your-api-key>: \
-d "card[pan]=5500000000000004" \
-d "card[expire_month]=06" \
-d "card[expire_year]=2022" \
-d "card[csc]=123"
Example response (snippet):
{
"id": "58dabba0-e9ea-4133-8c38-bfa1028c1ed2",
"status": {
"code": 20000
},
"processed_at": "2018-07-09T12:58:56+00:00",
"last4": "0004",
"country": "US",
"scheme": "mastercard",
"type": "credit",
"csc": {
"present": true,
"matches": true
},
"_links": {
"authorizations": { "href": "/cards/58dabba0-e9ea-4133-8c38-bfa1028c1ed2/authorizations" },
"credits": { "href": "/cards/58dabba0-e9ea-4133-8c38-bfa1028c1ed2/credits" }
}
}
Sometimes cardholders should receive money, e.g. if you will pay out some winnings.
The following will transfer EUR 500.00 to cardholder’s bank account from your merchant bank account:
curl -X POST https://gateway.test.clearhaus.com/credits \
-u <your-api-key>: \
-d "amount=50000" \
-d "currency=EUR" \
-d "ip=1.1.1.1" \
-d "card[pan]=4111111111111111" \
-d "card[expire_month]=06" \
-d "card[expire_year]=2022"
Example response (snippet):
{
"id": "1b377999-bafb-42b0-a24f-106b312b0b40",
"status": {
"code": 20000
},
"processed_at": "2018-07-09T12:58:56+00:00",
"amount": 50000,
"currency": "EUR",
"_embedded": { "card": { "id": "58dabba0-e9ea-4133-8c38-bfa1028c1ed2" } }
}
Recurring payments enable you to repeatedly charge cardholders without having them to provide card information for subsequent payments.
Many PSPs have a subscription concept for supporting recurring payments. The first approved authorization is the initial recurring authorization (also known as “first in series”), all later authorizations are called subsequent authorizations. Clearhaus supports subscriptions in the form of recurring payments.
A recurring payment is made by making an authorization and setting recurring
parameter to true. The first recurring payment for a given card could be made
this way (notice that the amount may be zero):
curl -X POST \
https://gateway.test.clearhaus.com/authorizations \
-u <your-api-key>: \
-d "amount=2050" \
-d "currency=EUR" \
-d "recurring=true" \
-d "card[pan]=4111111111111111" \
-d "card[expire_month]=06" \
-d "card[expire_year]=2022" \
-d "card[csc]=123" \
--data-urlencode "card[pares]=<some-pares-value>"
Example response (snippet):
{
"id": "e3e9d215-6efc-4c0e-b3d7-2226057c6de8",
"status": {
"code": 20000
},
"processed_at": "2018-07-09T12:58:56+00:00",
"recurring": true,
"_embedded": { "card": { "id": "58dabba0-e9ea-4133-8c38-bfa1028c1ed2" } }
}
This should be followed by a capture except when the amount is 0.
Subsequent authorizations are made similarly, but neither CSC nor PARes (see 3-D Secure) would be included.
An initial recurring authorization can also be made using the applepay and
mobilepayonline payment methods; subsequent recurring payments, however, must
be made using the card payment method using the card details of the initial
recurring authorization.
3-D Secure is a protocol designed to improve security for online transactions. Before you continue please read more about this protocol at 3Dsecure.io.
3-D Secure is the only way to achieve liability shift for fraud chargebacks.
To perform a 3-D Secure transaction you make an ordinary authorization including
a pares value:
curl -X POST https://gateway.test.clearhaus.com/authorizations \
-u <your-api-key>: \
-d "amount=2050" \
-d "currency=EUR" \
-d "ip=1.1.1.1" \
-d "card[pan]=4111111111111111" \
-d "card[expire_month]=06" \
-d "card[expire_year]=2022" \
-d "card[csc]=123" \
--data-urlencode "card[pares]=<some-pares-value>"
Example response (snippet):
{
"id": "84412a34-fa29-4369-a098-0165a80e8fda",
"status": {
"code": 20000
},
"processed_at": "2018-07-09T12:58:56+00:00",
"threed_secure": true
}
Some basic account information can be fetched:
curl https://gateway.test.clearhaus.com/account \
-u <your-api-key>:
Example response (snippet):
{
"merchant_id": "000000003000001",
"name": "Merchant Ltd.",
"country": "GB",
"mcc": "1111",
"descriptor": "merchant.com",
"transaction_rules":"reject authorization if amount > 100 EUR and (not fully 3dsecure)",
"acquirer": {
"visa_bin": 438309,
"mastercard_bin": 526571
}
}
See account resource documentation for further details.
Our API offers six different resources:
To reserve money on a cardholder’s bank account you make a new authorization resource.
POST https://gateway.clearhaus.com/authorizations
POST https://gateway.clearhaus.com/cards/:id/authorizations # deprecated
Authorizations can be created using different payment methods:
card, applepay, mobilepayonline.
Exactly one payment method must be used, unless the authorization is made on
a card resource (/cards/:id/authorizations, deprecated), in which case the
payment method must be omitted.
true for recurring payments.card[pares]. card[pan]. card
Notice: An approved authorization that includes
card[pares] is 3-D
Secured and is strongly authenticated (SCA in PSD2).
Notice: An authorization that includes card[pares] and/or
card[csc] cannot be a subsequent recurring authorization.
applepayApple Pay requires the payment details (PAN, expiry, etc.) of the payment token
to be decrypted by a symmetric key.
Your systems must derive this symmetric key using the payment token’s ephemeral
public key, the merchant’s private key and the merchant ID. For this, we refer
to our reference implementation written
in Ruby; see Apple’s documentation for the PaymentToken
object for more information.
PKPaymentToken object, UTF-8 encoded serialization of a JSON dictionary.data from the PKPaymentToken.
Notice: Signing is required to use the applepay payment
method.
Notice: An authorization made with applepay is
strongly authenticated (SCA in PSD2).
Notice: An authorization made with applepay may be fully
3-D Secured, 3-D Secure attempted, or with no 3-D Secure; this is indicated by
the eciIndicator of the applepay[payment_token].
Notice: An authorization made with applepay cannot be a
subsequent recurring authorization.
mobilepayonline
Notice: Signing is required to use the mobilepayonline
payment method.
Notice: An authorization made with mobilepayonline is
strongly authenticated (SCA in PSD2).
To transfer money from a cardholder’s bank account to your merchant bank account you make a new capture resource. You can make multiple captures for an authorization transaction.
POST https://gateway.clearhaus.com/authorizations/:id/captures
text_on_statement from authorization.
Notice: A capture cannot be made if the authorization is 180 days old.
To refund money to a cardholder’s bank account you make a new refund resource. You can make multiple refunds for an authorization transaction.
POST https://gateway.clearhaus.com/authorizations/:id/refunds
text_on_statement from authorization.
Notice: A refund does not “free up” what is captured from the authorization; that is, after authorizing 10, capturing 5 and refunding 5, you can still only capture 5.
Notice: A refund cannot be made if the last capture is 180 days old.
To release reserved money on a cardholder’s bank account you make a new void resource. A reservation normally last for 7 days depending on issuing bank and is then automatically released.
POST https://gateway.clearhaus.com/authorizations/:id/voids
No parameters are needed to make a new void transaction.
Notice: A void cannot be made if the authorization age is 30 days or more.
To payout (e.g. winnings and not refunds) money to a cardholder’s bank account you make a new credit resource.
POST https://gateway.clearhaus.com/credits
POST https://gateway.clearhaus.com/cards/:id/credits # deprecated
This resource is now deprecated!
A card resource (token) corresponds to a payment card and can be used to make a credit or authorization transaction without providing sensitive card data (see “Tokenization”).
POST https://gateway.clearhaus.com/cards
Notice: The exact same card details can be sent multiple times but
will give you the same card resource (card token) every time.
Notice: A card resource is automatically made when you make an
authorization transaction and you supply card details.
Notice: A “zero amount” authorization is made when POSTing to this endpoint.
visa, mastercard or unknowndebit or credit
The account resource holds basic merchant account information. Only HTTP GET
is supported for this endpoint.
GET https://gateway.clearhaus.com/account
text_on_statement.
descriptor.The JSON response will include one of following transaction status codes when you make a new transaction.
| Status | code |
Meaning |
|---|---|---|
| Approved | 20000 | Approved |
| Declined | 40000 | General input error |
| 40110 | Invalid card number | |
| 40111 | Unsupported card scheme | |
| 40120 | Invalid CSC | |
| 40130 | Invalid expire date | |
| 40135 | Card expired | |
| 40140 | Invalid currency | |
| 40150 | Invalid text on statement | |
| 40190 | Invalid transaction | |
| 40200 | Clearhaus rule violation | |
| 40300 | 3-D Secure problem | |
| 40310 | 3-D Secure authentication failure | |
| 40400 | Backend problem | |
| 40410 | Declined by issuer or card scheme | |
| 40411 | Card restricted | |
| 40412 | Card lost or stolen | |
| 40413 | Insufficient funds | |
| 40414 | Suspected fraud | |
| 40415 | Amount limit exceeded | |
| 50000 | Clearhaus error |
A status message may be included in the response when you create a new transaction. The status message can be used for debugging and may include a more specific error message.
Status messages should be shown to the merchant.
Examples:
{
"status": {
"code": 40000,
"message": "parameter 'amount' is required"
}
}
{
"status": {
"code": 40200,
"message": "amount > 100 EUR and (not strongly authenticated)"
}
}
{
"status": {
"code": 40200,
"message": "not (fully 3dsecure or subsequent recurring)"
}
}
For testing towards the test endpoint gateway.test.clearhaus.com please use
PANs that are either not
Luhn-compliant, are
one of the special test PANs 2221000000000009, 4111111111111111,
5500000000000004, or are Apple Pay test cards.
For PANs starting with 420000 and ending with 0000, and PANs starting with
555555 and ending with 4444, you can specify a valid status code as
transaction amount to trigger the status.
# authorizations
https://gateway.clearhaus.com/authorizations
https://gateway.clearhaus.com/authorizations/:id
https://gateway.clearhaus.com/cards/:id/authorizations
# captures
https://gateway.clearhaus.com/captures/:id
https://gateway.clearhaus.com/authorizations/:id/captures
# voids
https://gateway.clearhaus.com/voids/:id
https://gateway.clearhaus.com/authorizations/:id/voids
# refunds
https://gateway.clearhaus.com/refunds/:id
https://gateway.clearhaus.com/authorizations/:id/refunds
# credits
https://gateway.clearhaus.com/credits
https://gateway.clearhaus.com/credits/:id
https://gateway.clearhaus.com/cards/:id/credits
# cards
https://gateway.clearhaus.com/cards
https://gateway.clearhaus.com/cards/:id
# account
https://gateway.clearhaus.com/account
Sorted by descending timestamp.
Starting 2018-08-31T13:30:00+00:00 the /credits resource has been added,
enabling creation of credits without card tokenization. This is an essential
addition, as card tokenization, including the resource /cards/:id/credits, is
deprecated and will be removed on November 15, 2018.
Starting 2018-08-31T13:30:00+00:00 the parameter mobilepayonline[pares] is
accepted.
Starting 2018-08-31T13:30:00+00:00 we support the currency VES.
Payment methods have been added to the authorizations resource on 2018-07-20. Also, a few parameters and an endpoint have been deprecated. Refer to the documentation source code changes for the exact documentation change.
Please notice that there is no major version number change, so we stay backwards compatible until the deprecations take effect. We expect the deprecations to happen on 2018-11-15; it will be announced separately.
Starting 2018-07-01T00:00:00+00:00 the currency STD is no longer accepted.
Starting 2018-05-15T13:00:00+00:00 we support the currencies MRU and STN.
CLP and UGX changes from exponent 2 to exponent 0.
Transactions in CLP or UGX will be declined between 2017-10-12T19:00:00+00:00 and 2017-10-15T19:00:00+00:00 (both inclusive); before this timespan, the exponent is 2; after the timespan, the exponent is 0.