Clearhaus Transaction API

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:

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.9.0; charset=utf-8

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[number]=4111111111111111&card[expire_month]=06&card[expire_year]=2018&card[csc]=123

then the Signature header should be

Signature: 4390aec7-f76a-4c2f-8597-c87c2d06cb4f RS256-hex af30dfbca8ae965accde234e49f93ced184feb612faf440d12a3993bcce747b729069241dd1b6e68420607301d737c6828289b9889c38727a6cc853dbfcae103

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[number]=4111111111111111" \
     -d "card[expire_month]=06"         \
     -d "card[expire_year]=2018"        \
     -d "card[csc]=123"

Example response (snippet):

{
    "id": "84412a34-fa29-4369-a098-0165a80e8fda",
    "status": {
        "code": 20000
    },
    "csc": {
        "present": true,
        "matches": true
    },
    "processed_at": "2014-07-09T09:53:41+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": "2014-07-09T11:47:28+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": "2014-07-09T11:57:58+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[number]=5500000000000004" \
     -d "card[expire_month]=06"         \
     -d "card[expire_year]=2018"        \
     -d "card[csc]=123"

Example response (snippet):

{
    "id": "58dabba0-e9ea-4133-8c38-bfa1028c1ed2",
    "status": {
        "code": 20000
    },
    "processed_at": "2014-07-09T12:14:31+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. Before you can make a payout you need to tokenize a card.

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/cards/58dabba0-e9ea-4133-8c38-bfa1028c1ed2/credits \
     -u <your-api-key>: \
     -d "amount=50000"  \
     -d "currency=EUR"

Example response (snippet):

{
    "id": "1b377999-bafb-42b0-a24f-106b312b0b40",
    "status": {
        "code": 20000
    },
    "processed_at": "2014-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 payment gateways offer a subscription concept where a card can be subscribed for recurring payments. This is supported in our API using card tokens. Card tokens can be created explicitly or implicitly when the first authorization is created.

Actual recurring transactions must be made by creating an authorization.

Repeatedly reserve money

A recurring payment is made by making an authorization based on a card resource and setting recurring parameter to true:

curl -X POST \
  https://gateway.test.clearhaus.com/cards/58dabba0-e9ea-4133-8c38-bfa1028c1ed2/authorizations \
  -u <your-api-key>:  \
  -d "amount=2050"    \
  -d "currency=EUR"   \
  -d "recurring=true"

Example response (snippet):

{
   "id": "e3e9d215-6efc-4c0e-b3d7-2226057c6de8",
   "status": {
       "code": 20000
   },
   "processed_at": "2014-07-09T13:33:44+00:00",
   "recurring": true
}

Above can be repeated whenever you need to reserve money and must be followed by a capture transaction.

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.

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[number]=4111111111111111" \
     -d "card[expire_month]=06"         \
     -d "card[expire_year]=2018"        \
     -d "card[csc]=123"                 \
     --data-urlencode "threed_secure[pares]=<some-pares-value>"

Example response (snippet):

{
    "id": "84412a34-fa29-4369-a098-0165a80e8fda",
    "status": {
        "code": 20000
    },
    "processed_at": "2014-07-09T09:53:41+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.",
    "descriptor": "merchant.com",
    "country": "GBR",
    "mcc": "1111"
}

See account resource documentation for further details.

API Reference

Resources

Our API offers six different resources:

• Authorizations
• Captures
• Refunds
• Voids
• Credits
• Cards
• Account

Authorizations

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

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

Parameters

amount

[1-9][0-9]{0,9}
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; CLP and UGX changes on 2017-10-13.)

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

text_on_statement

[\x20-\x7E]{0,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]{0,30} ASCII printable characters
Optional
A reference to an external object, such as an order number.

threed_secure[pares]

[:base64:]
Optional
See more information on 3Dsecure.io

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}
Card Security Code.

Notice: The card dictionary is not required when making an authorization based on a card resource. However, card[csc] should be populated when CSC is available.

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]{0,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]{0,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 is 30 days old.

Credits

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

Parameters

POST https://gateway.clearhaus.com/cards/:id/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; CLP and UGX changes on 2017-10-13.)

text_on_statement

[\x20-\x7E]{0,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]{0,30} ASCII printable characters
Optional
A reference to an external object, such as an order number.

Cards

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”). A card resource must be used to make subsequent recurring authorization transactions.

Parameters

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

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}
Card Security Code.

Notice: The exact same card details can be sent multiple times but will give you a unique card resource (card token).
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.

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 3-letter country code for merchant company.

mcc

[0-9]{4}
Merchant category code.

acquirer

Used for 3-D Secure.

Transaction status codes

The JSON response will include one of following transaction status codes when you make a new transaction.

Status message

A status message is included in every response when you make a new transaction. The status message can be used for debugging and may include a more specific error message.

Examples:

{
    "status": {
        "code": 40000,
        "message": "parameter 'amount' is required"
    }
}

{
    "status": {
        "code": 40200,
        "message": "amount > 100 EUR"
    }
}

{
    "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:

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

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/: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

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.