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

Tokenize a card

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

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",
    "_embedded": { "card": { "id": "58dabba0-e9ea-4133-8c38-bfa1028c1ed2" } }
}

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,
    "_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

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

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.
threed_secure[pares]
Deprecated! Please use card[pares].
[:base64:]
See more information at 3Dsecure.io.
card[number]
Deprecated! Please use card[pan].
[0-9]{12,19}
Primary account number of card to charge.
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: 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.

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, raw PKPaymentToken object, UTF-8 encoded serialization of a JSON dictionary.
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]{0,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]{0,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]{0,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.

Parameters (deprecated)

POST https://gateway.clearhaus.com/cards/:id/credits # deprecated
amount
[1-9][0-9]{0,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.

Cards

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”).

Parameters

POST https://gateway.clearhaus.com/cards
card[pan]
[0-9]{12,19}
Primary account number of card to charge.
card[number]
[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.

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.

Response parameters

card[last4]
[0-9]{4}
Last 4 digits of card number.
card[scheme]
visa, mastercard or unknown
card[type]
debit or credit
Omittable
card[country]
[A-Z]{2}
Omittable
ISO 3166-1 2-letter country code for issuing bank.

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.
text_on_statement
Deprecated! Please refer to descriptor.

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

Test card numbers

Any card number within the following BIN ranges can be used to perform test transactions on gateway.test.clearhaus.com:

Range Card scheme
222100 - 272099 MasterCard
400000 - 499999 Visa
500000 - 699999 MasterCard

Please use PANs that are not Luhn-compliant, one of the following special PANs: 2221000000000009, 4111111111111111, 5500000000000004, or an Apple Pay test card.

You can specify a status code as transaction amount to trigger a specific error.

Endpoint summary

# 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

Changes

Sorted by descending timestamp.

Add credits resource

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.

Accept 3-D Secure PARes for MobilePay Online

Starting 2018-08-31T13:30:00+00:00 the parameter mobilepayonline[pares] is accepted.

VES support

Starting 2018-08-31T13:30:00+00:00 we support the currency VES.

Add payment methods

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.

STD no longer accepted from July 2018

Starting 2018-07-01T00:00:00+00:00 the currency STD is no longer accepted.

MRU and STN support

Starting 2018-05-15T13:00:00+00:00 we support the currencies MRU and STN.

CLP and UGX exponent changes

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.