Getting Started

Sign up for an API key and read all about getting started using our API.

Examples

Have a look at some examples and see how simple and powerful our API is.

API Reference

Read our complete API reference and learn all about our different resources.

Getting Started

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

API endpoint

https://gateway.clearhaus.com      # live accounts
https://gateway.test.clearhaus.com # test accounts

Authentication

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

Resource discovery

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" },
        "account":        { "href": "/account" }
    }
}

Response format

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

Signing requests

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.

RSA signature

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&currency=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

Examples

Charge a cardholder

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.

Reserve money

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.

Withdraw money

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"
        }
    }
}

Refund to cardholder

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" }
    }
}

Payout to cardholder

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"
}

Recurring payments

Recurring payments enable you to repeatedly charge cardholders without having them to provide card information for subsequent payments.

Subscription concept

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.

Repeatedly reserve money

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
}

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

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.

Secure transactions

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
}

Fetch account information

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.

API Reference

Resources

Our API offers six different resources:

Authorizations

To reserve money on a cardholder’s bank account you make a new authorization resource.

POST https://gateway.clearhaus.com/authorizations

Authorizations can be created using different payment methods: card, applepay, mobilepayonline. Exactly one payment method must be used.

Parameters

amount
[0-9]{1,10}
Amount in minor units of given currency (e.g. cents if in Euro).
currency
[A-Z]{3}
3-letter currency code. (Some exponents differ from ISO 4217.)
ip
[0-9.a-fA-F:]{3,39}
Optional
Cardholder’s IP address (v4 or v6).
recurring
(true|false)
Optional
Must be true for recurring payments.
text_on_statement
[\x20-\x7E]{2,22} ASCII printable characters
May not be all digits, all same character, or all sequential characters (e.g. “abc”).
Optional
Text that will be placed on cardholder’s bank statement.
reference
[\x20-\x7E]{1,30} ASCII printable characters
Optional
A reference to an external object, such as an order number.
Method: card
card[pan]
[0-9]{12,19}
Primary account number of card to charge.
card[expire_month]
[0-9]{2}
Expiry month of card to charge.
card[expire_year]
20[0-9]{2}
Expiry year of card to charge.
card[csc]
[0-9]{3}
Optional when transaction is signed and partner is trusted.
Card Security Code.
card[pares]
[:base64:]
Optional
See more information at 3Dsecure.io

Notice: A valid PARes included in card[pares] can indicate 3 different levels: non-authenticated, attempted 3-D Secure, fully 3-D Secure.
Notice: An authorization made with card[] is strongly authenticated if it is fully 3-D Secure.
Notice: An authorization that includes card[pares] and/or card[csc] cannot be a subsequent recurring authorization.

Method: applepay

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

applepay[payment_token]
[:json:]
Full PKPaymentToken serialized as JSON, supplied as a string.
Example: {"paymentData":{"version":"EC_v1","data":"",...},"paymentMethod":{...},...}
applepay[symmetric_key]
[:hex:]
Symmetric AES key (unique per transaction) that can decrypt 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.

Method: mobilepayonline
mobilepayonline[pan]
[0-9]{12,19}
Primary account number of card to charge.
mobilepayonline
[expire_month]
[0-9]{2}
Expiry month of card to charge.
mobilepayonline
[expire_year]
[0-9]{4}
Expiry year of card to charge.
mobilepayonline
[phone_number]
[\x20-\x7E]{1,15}
Optional
Phone number from where the PAN originates.
mobilepayonline[pares]
[:base64:]
Optional
See more information at 3Dsecure.io

Notice: Signing is required to use the mobilepayonline payment method.
Notice: An authorization made with mobilepayonline is strongly authenticated (SCA in PSD2).

Captures

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

Parameters

amount
[1-9][0-9]{1,9}
Optional
Amount in minor units of given currency (e.g. cents if in Euro). The full or remaining amount will be withdrawn if no amount is given.
text_on_statement
[\x20-\x7E]{2,22} ASCII printable characters
May not be all digits, all same character, or all sequential characters (e.g. “abc”).
Optional
Text that will be placed on cardholder’s bank statement. Overrides text_on_statement from authorization.

Notice: A capture cannot be made if the authorization is 180 days old.

Refunds

To refund money to a cardholder’s bank account you make a new refund resource. You can make multiple refunds for an authorization transaction.

Parameters

POST https://gateway.clearhaus.com/authorizations/:id/refunds
amount
[1-9][0-9]{1,9}
Optional
Amount in minor units of given currency (e.g. cents if in Euro). The full or remaining amount will be refunded if no amount is given.
text_on_statement
[\x20-\x7E]{2,22} ASCII printable characters
May not be all digits, all same character, or all sequential characters (e.g. “abc”).
Optional
Text that will be placed on cardholder’s bank statement. Overrides 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.

Voids

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.

Parameters

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.

Credits

To payout (e.g. winnings and not refunds) money to a cardholder’s bank account you make a new credit resource.

Parameters

POST https://gateway.clearhaus.com/credits
amount
[1-9][0-9]{1,9}
Amount in minor units of given currency (e.g. cents if in Euro). As for Mastercard, the amount must not exceed the equivalent of 5,000 EUR; as for Visa, the amount must not exceed the equivalent of 50,000 USD.
currency
[A-Z]{3}
3-letter currency code. (Some exponents differ from ISO 4217.)
text_on_statement
[\x20-\x7E]{2,22} ASCII printable characters
May not be all digits, all same character, or all sequential characters (e.g. “abc”).
Optional
Text that will be placed on cardholder’s bank statement.
reference
[\x20-\x7E]{1,30} ASCII printable characters
Optional
A reference to an external object, such as an order number.
card[pan]
[0-9]{12,19}
Primary account number of card to charge.
card[expire_month]
[0-9]{2}
Expiry month of card to charge.
card[expire_year]
20[0-9]{2}
Expiry year of card to charge.
card[csc]
[0-9]{3}
Optional.
Card Security Code.

Account

The account resource holds basic merchant account information. Only HTTP GET is supported for this endpoint.

GET https://gateway.clearhaus.com/account

Response parameters

merchant_id
[0-9]{15}
Used for 3-D Secure and also for reference when talking to our support staff. For 3-D Secure it is important to represent this number with leading zeros.
descriptor
[\x20-\x7E]{0,22} ASCII printable characters
The default text_on_statement.
name
[\x20-\x7E]{0,20} ASCII printable characters
Merchant company name.
country
[A-Z]{2}
ISO 3166-1 2-letter country code for merchant company.
mcc
[0-9]{4}
Merchant category code.
acquirer
Used for 3-D Secure.
transaction_rules
[\x20-\x7E]*
The processing rules that the merchant’s transactions must adhere to.

Transaction status codes

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
40416 Additional authentication required
40420 Merchant blocked by cardholder
50000 Clearhaus error

Status message

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)"
    }
}

Merchant blocked by cardholder status

A merchant blocked by cardholder status code is both a decline of the current authorization, but also a notice to halt all future merchant-initiated-transactions on this card from this merchant. This includes, but is not limited to, recurring transactions.

Only after the blockade has been lifted, by actions taken by the cardholder, may transactions be resumed.

Test card numbers

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.

When testing towards the test endpoint, the CSC 987—and only 987—is considered a match for all PANs.

Endpoint summary

# authorizations
https://gateway.clearhaus.com/authorizations

# captures
https://gateway.clearhaus.com/authorizations/:id/captures

# voids
https://gateway.clearhaus.com/authorizations/:id/voids

# refunds
https://gateway.clearhaus.com/authorizations/:id/refunds

# credits
https://gateway.clearhaus.com/credits

# account
https://gateway.clearhaus.com/account

Changes

Follow coming changes on the source code repository.

Sorted by descending timestamp.

Remove deprecated /cards, threed_secure and card[number]

The deprecations announced in 2018 will be executed. Partners must expect /cards endpoints, the threed_secure and the card[number] parameters to be unavailable at any point in time after 2019-08-20. Refer to the documentation source code changes for the exact documentation change.

Add merchant blocked by cardholder status

Starting 2019-04-11 a new status code 40420 - Merchant blocked by cardholder is avaliable. Please be advised that appropriate action must be taken to adequately handle this status code, see Merchant blocked by cardholder status

Add a valid test CSC

Starting 2019-02-22 the CSC 987 has been added as a valid CSC for all PANs when testing against gateway.test.clearhaus.com.