Getting Started

To use this transaction API you must be a technical partner (and such partners must be PCI DSS L1).

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

Accounts and keys

There are two types of accounts:

A merchant account belongs to a merchant.
A partner account belongs to you, i.e. a partner being tech-wise integrated into the transaction API.

Merchant accounts can process transactions whereas partner accounts cannot.

An API key (UUIDv4) points to an account (either a merchant account or a partner account). An account can have multiple API keys pointing to it; this allows for easy rolling of API keys. A merchant account usually uses one API key.

API keys can have an expire date. API keys can be enabled or disabled. For merchant accounts, these details can be observed in the Clearhaus Dashboard.

A partner account API key can be a signing API key, meaning that it has a verification key for verifying request signatures. This verification key is the public part of an RSA key pair; the RSA key pair is generated by the partner. The public part, the verification key, is communicated to Clearhaus during the technical integration.

Only partner accounts have signing API keys.

Signing requests

POST requests must be signed. Other requests can optionally be signed.

The signature is an RSA signature of the HTTP body; it is represented in hex. The partner account is identified by the partner’s signing API key. Both the partner’s signing API key and the RSA signature must be provided in a Signature header together with RS256-hex:

Signature: <partner-signing-api-key> RS256-hex <signature>

Notice: If the signature header is included, it must 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 0a1b2c3d-4e5f-4c2f-9999-000000000000, the signing private key (in PEM format) is

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: 0a1b2c3d-4e5f-4c2f-9999-000000000000 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"              \
     -H "Signature: <signing-api-key> RS256-hex <signature>"

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.

Notice: csc matches is true if issuer or card scheme confirmed CSC to match; it is false if issuer or card scheme did not perform validation or if validation failed.

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>: \
  -H "Signature: <signing-api-key> RS256-hex <signature>"

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"   \
  -H "Signature: <signing-api-key> RS256-hex <signature>"

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"    \
  -H "Signature: <signing-api-key> RS256-hex <signature>"

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 wish to 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"     \
     -H "Signature: <signing-api-key> RS256-hex <signature>"

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

Depending on card scheme and merchant category, the name on the card might be necessary for approval of credits. It may be provided through the optional parameter card[name].

Series of transactions

Clearhaus supports two types of subscription billing:

Recurring: Transactions processed at agreed, predetermined, regular intervals not exceeding 1 year; e.g. a monthly subscription for a magazine.
Unscheduled (UCOF, Unscheduled Credential on File): Transactions not occurring on predetermined, regular intervals; e.g. a car sharing subscription billed weekly but only for weeks when the service is used.

For both types, there may be an agreed end of the series and the amount may be varying. See the partner guideline for more details.

Repeatedly reserve money

A first-in-series payment is created by making an authorization and marking it as either a recurring or unscheduled series. For instance, a first-in-series recurring payment could be made this way:

curl -X POST \
  https://gateway.test.clearhaus.com/authorizations \
  -u <your-api-key>:  \
  -d "amount=2050"    \
  -d "currency=EUR"   \
  -d "series[type]=recurring"     \
  -d "card[pan]=4111111111111111" \
  -d "card[expire_month]=06"      \
  -d "card[expire_year]=2026"     \
  -d "card[csc]=123"              \
  --data-urlencode "card[3dsecure][v2][rreq]=<some-rreq-value>" \
  -H "Signature: <signing-api-key> RS256-hex <signature>"

Example response (snippet):

{
    "id": "1b722683-92ad-4c6b-85da-e119d550670d",
    "status": { "code": 20000 },
    "series": {
        "type": "recurring",
        "tid": "481048839682954"
    }
}

This should be followed by a capture.

Subsequent-in-series authorizations initiated by the merchant are made similarly, however, CSC is not included, and the previous-in-series is referenced, e.g.:

curl -X POST \
  https://gateway.test.clearhaus.com/authorizations \
  -u <your-api-key>:  \
  -d "amount=2050"    \
  -d "currency=EUR"   \
  -d "series[previous][id]=1b722683-92ad-4c6b-85da-e119d550670d" \
  -d "card[pan]=4111111111111111" \
  -d "card[expire_month]=06"      \
  -d "card[expire_year]=2026"     \
  -H "Signature: <signing-api-key> RS256-hex <signature>"

A first-in-series authorization can also be made using the applepay, googlepay or mobilepayonline payment methods.

A subsequent-in-series authorization must be made using the card payment method with the exact card details of the referenced previous-in-series authorization.

Any first-in-series authorization must be made with strong customer authentication (SCA) regardless of the authorization amount (when the cardholder is in scope for SCA).

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 version 1 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[3dsecure][v1][pares]=<some-pares-value>" \
     -H "Signature: <signing-api-key> RS256-hex <signature>"

Example response (snippet):

{
    "id": "84412a34-fa29-4369-a098-0165a80e8fda",
    "status": {
        "code": 20000
    },
    "processed_at": "2018-07-09T12:58:56+00:00",
    "3dsecure": {
        "version": "1.0.2",
        "status": "Y"
    }
}

To perform a 3-D Secure version 2 transaction you make an ordinary authorization including an ares or an rreq value. The former is used in the following example:

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[3dsecure][v2][ares]=<some-ares-value>" \
     -H "Signature: <signing-api-key> RS256-hex <signature>"

Example response (snippet):

{
    "id": "d0949241-1ee8-47da-a77c-d251fd9e1e88",
    "status": {
        "code": 20000
    },
    "processed_at": "2020-07-03T11:06:58+00:00",
    "3dsecure": {
        "version": "2.1.0",
        "status": "Y"
    }
}

Notice: The response element threed_secure is deprecated, please use 3dsecure.

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
Captures
Refunds
Voids
Credits
Account

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, moto, vipps. Exactly one payment method must be used.

Parameters

amount (0|[1-9][0-9]{,8})

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

credential_on_file (store|use)

Indicate if the payment credential (e.g. PAN and expiry) will be stored for future use where the payment credential is not provided by the cardholder but collected from (encrypted) storage.
store: The payment credential will be stored; it may only be stored if the authorization is approved.
use: The payment credential has already been stored and is now being used.
Default:

use, if initiator is merchant (store is invalid),
store, if the authorization is first-in-series.

Optional

initiator (cardholder|merchant)

The initiator of the authorization. An authorization is initiated by the cardholder if the cardholder decided the transaction should be created. This is regardless of whether a stored payment credential is being used.
For compliance reasons there should be a previous approved transaction (for the combination of card and merchant) where credential_on_file=store before initiator may be merchant.
Default:

merchant, if the authorization is subsequent-in-series (cardholder is invalid),
cardholder, otherwise.

Optional

ip [0-9.a-fA-F:]{3,45}

Cardholder’s IP address. It must be a valid v4 or v6 address.

Optional

reference [\x20-\x7E]{1,30} ASCII printable characters

A reference to an external object, such as an order number.

Optional

series[type] (recurring|unscheduled)

The type of series.
This parameter is used exactly when initiating a series. To create a subsequent-in-series authorization use series[previous][...].
recurring: A series of transactions where the cardholder has explicitly agreed that the merchant may repeatedly charge the cardholder at regular, predetermined intervals that may not exceed 1 year.
unscheduled: A series of transactions where the cardholder has explicitly agreed that the merchant may repeatedly charge the cardholder at non-predetermined times, e.g. based on cardholder usage.

Conditional. Cannot be present if series[previous] is present.

series[previous][id] [:UUIDv4:]

The Clearhaus authorization ID as a reference to the latest approved authorization in the series.
This parameter is used for a subsequent-in-series. To create a first-in-series authorization use series[type].
Can be used only with payment method card.
If the latest approved authorization in the series was not processed via Clearhaus, after obtaining explicit approval from Clearhaus, you can provide raw scheme values; see Scheme reference to series.

Conditional. Cannot be present if series[type] is present.

text_on_statement [\x20-\x7E]{2,22} ASCII printable characters

Text that will be placed on cardholder’s bank statement.

May not be all digits, all same character, or all sequential characters (e.g. “abc”)

Optional

~~recurring~~ (true|false)

Deprecated! Please use series.

Optional. Cannot be used with series or initiator.

Notice: When recurring is used, Clearhaus automatically identifies if there was a previous-in-series and if that is the case uses the level of authentication (CSC, 3-D Secure, etc.) to conclude if the payment is a first-in-in-series or a subsequent-in-series recurring.

Notice: Since series[type] cannot be supplied together with series[previous], the type of a series cannot change.

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}: Card Security Code.
Optional when partner is trusted
card[3dsecure] dictionary: See Authentication: [3dsecure].
Optional
~~card[pares]~~ [:base64:]: Deprecated! Please use card[3dsecure][v1][pares].
See more information at 3dsecure.io
Optional

Notice: An authorization that includes card[3dsecure][v1][pares], card[3dsecure][v2][rreq], and/or card[csc] cannot be a subsequent-in-series 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.

Additionally, an Apple Pay authorization can be created using raw values from a payment token:

applepay[raw][pan] [0-9]{12,19}: Primary account number of card to charge.
applepay[raw][expire_month] [0-9]{2}: Expiry month of card to charge.
applepay[raw][expire_year] 20[0-9]{2}: Expiry year of card to charge.
applepay[raw][cryptogram] [:base64:]{28}: Online payment cryptogram. Found as onlinePaymentCryptogram in the payment token.
applepay[raw][eci] [0-9]{2}: Electronic Commerce Indicator. Found as eciIndicator in the payment token.
Optional

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 3-D Secured to some degree or not at all; this is indicated by the eciIndicator of the applepay[payment_token].
Notice: An authorization made with applepay cannot be a subsequent-in-series authorization.
Notice: Clients using applepay[raw] are responsible for verifying the payment token’s signature, decrypting the token’s payment data, validating the format of the fields in the payment data, etc. The procedure is available in Apple Pay’s Payment Token Format Reference.

Method: `googlepay`

To accept a payment using Google Pay, the complete payment token, recipient ID and derived shared secret, are required. Please refer to the official documentation. Only protocol version ECv2 is supported.

googlepay[token] [:json:]: Raw payment method token as received in response from Google. UTF-8 encoded serialization of a JSON dictionary.
googlepay[shared_key] [:base64:]: The shared secret derived from the ephemeral public key and your private key.
googlepay[recipient_id] [\x21-\x7E]+ ASCII printable characters excluding space: The Google Pay recipient of the payload, e.g. merchant:0123456789.

Notice: Signing is required to use the googlepay payment method.
Notice: An authorization made with googlepay is strongly authenticated (SCA in PSD2) if authMethod is CRYPTOGRAM_3DS and the Google Pay guidelines for SCA (link) have been followed. If authMethod is PAN_ONLY, a 3-D Secure flow is required for SCA.
Notice: An authorization made with googlepay cannot be a subsequent-in-series authorization.
Notice: The recipient_id for the googlepay test environment is merchant:12345678901234567890.

Method: `mobilepayonline`

mobilepayonline[pan] [0-9]{12,19}: Primary account number of card to charge.
If payment_token parameter is included, the pan must be a Token PAN.
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[payment_token] [:json:]: Full tokenCallback response serialized as JSON, supplied as a string. Required for token-based authentication.
Example: {"paymentId":"string","tokenData":{"cryptogramInfo":{...},...},...}
Optional
mobilepayonline[phone_number] [\x20-\x7E]{1,15}: Phone number from where the PAN originates.
Optional
mobilepayonline[3dsecure] dictionary: See Authentication: [3dsecure].
Optional
~~mobilepayonline[pares]~~ [:base64:]: Deprecated! Please use mobilepayonline[3dsecure][v1][pares].
See more information at 3dsecure.io
Optional

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

Method: `moto`

moto[pan] [0-9]{12,19}: Primary account number of card to charge.
moto[expire_month] [0-9]{2}: Expiry month of card to charge.
moto[expire_year] [0-9]{4}: Expiry year of card to charge.

Notice: Signing is required to use the moto payment method.
Notice: Neither series[] (nor recurring) nor credential_on_file is supported. Also, initiator cannot be merchant.

Method: `vipps`

vipps[pan] [0-9]{12,19}: Primary account number of card to charge.
vipps[expire_month] [0-9]{2}: Expiry month of card to charge.
vipps[expire_year] [0-9]{4}: Expiry year of card to charge.
vipps[payment_token] [:json:]: Full response serialized as JSON, supplied as a string.
Example: {"pspTransactionId":"string","networkToken":{"cryptogram": "string",...},...}
Optional
vipps[3dsecure] dictionary: See Authentication: [3dsecure].
Optional

Notice: Signing is required to use the vipps payment method.

Authentication: `[3dsecure]`

Only one 3-D Secure version can be used for a given authorization.

[3dsecure][v1] dictionary: 3-D Secure version 1.
Optional. Cannot be present if v2 is present.
[3dsecure][v2] dictionary: 3-D Secure version 2, also known as EMV 3-D Secure.
Optional. Cannot be present if v1 is present.

Authentication: `[3dsecure][v1]`

[3dsecure][v1][pares] [:base64:]: See more information at 3Dsecure.io.
Optional

Notice: A valid PARes can indicate three different levels: non-authenticated, attempted 3-D Secure, fully 3-D Secure.

Authentication: `[3dsecure][v2]`

[3dsecure][v2][ares] [:json:]: The 3-D Secure version 2 ARes containing authenticationValue, dsTransID, etc.
Optional. Cannot be present if rreq is present.
[3dsecure][v2][rreq] [:json:]: The 3-D Secure version 2 RReq containing authenticationValue, dsTransID, etc.
Optional. Cannot be present if ares is present.

Scheme reference to series

If the previous-in-series authorization was made via this API, you should use series[previous][id] to reference it. If it was not made via this API, you must obtain explicit approval from Clearhaus to use the raw scheme values grouped in series[previous][mastercard] and series[previous][visa]. This is relevant when moving a subscription from another acquirer to Clearhaus or among Clearhaus accounts.

The Mastercard specific reference to the series contains the following parts.

series[previous][mastercard][type] (recurring|unscheduled)

The type of the existing series.
Default: recurring.

Conditional. Cannot be present if series[previous][id] or any series[previous][visa][...] is present.

series[previous][mastercard][tid] [A-Za-z0-9]{3}[A-Za-z0-9]{6}[0-9]{4} {2}

Trace ID being the concatenation of values Data element 63 subfield 1 (Financial Network Code) (position 1-3), Data element 63 subfield 2 (Banknet Reference Number) (position 4-9), Data element 15 (Date, Settlement, in MMDD format) (position 10-13), and two spaces; to be used in Data Element 48, Subfield 63.

Conditional. Required if any series[previous][mastercard][...] is present. Cannot be present if series[previous][id] or any series[previous][visa][...] is present.

series[previous][mastercard][exemption] (fixed_amount_series|variable_amount_series)

The Mastercard exemption is used to indicate if the series is fixed-amount or a variable-amount.

fixed_amount_series: The series is a fixed-amount series. (MPMI value 03.)
variable_amount_series: The series is a variable-amount series. (MPMI value 01.) A Mastercard exemption (not formally an acquirer exemption for SCA) indicating that the transaction is out of scope for SCA.

If the previous-in-series is a subsequent-in-series it should be equal to the Mastercard exemption applied for the previous-in-series. The value originates from Mastercard Data element 48, Subelement 22, Subfield 1. The value 01 indicates variable amount whereas 03 indicates fixed amount.
Clearhaus uses the same Mastercard exemption for an entire series when a previous-in-series authorization in the series is referenced via series[previous][id].

Conditional. Required if any series[previous][mastercard][...] is present. Cannot be present if series[previous][id] or any series[previous][visa][...] is present.

The Visa specific reference to the series contains the following parts.

series[previous][visa][type] (recurring|unscheduled): The type of the existing series.
Default: recurring.
Conditional. Cannot be present if series[previous][id] or any series[previous][mastercard][...] is present.
series[previous][visa][tid] [0-9]{15}: Transaction ID from Field 62.2 of the first-in-series or previous-in-series authorization; to be used in Field 125, Usage 2, Dataset ID 03.
Conditional. Required if series[previous][visa][type] is present. Cannot be present if series[previous][id] or any series[previous][mastercard][...] is present.

Notice: A series migrated to Clearhaus using these scheme references cannot be continued with the now deprecated recurring flag. Instead, the subsequent-in-series following an authorization created using scheme references must use series[previous][id] to point to the previous in series.

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]{,8}: 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.
Optional
text_on_statement [\x20-\x7E]{2,22} ASCII printable characters: Text that will be placed on cardholder’s bank statement. Overrides text_on_statement from authorization.
May not be all digits, all same character, or all sequential characters (e.g. “abc”)

Optional
travel dictionary: See Travel data.
Optional

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

Travel data

At most one type of travel data can be supplied for a capture; if travel is supplied, it must include exactly one of travel[car], travel[flight], or travel[lodging].

For service type [car] (rental), the following parameter is relevant.

travel[car][pick_up_date] 20[0-9]{2}-[0-9]{2}-[0-9]{2} (YYYY-MM-DD): The agreed pick-up date; can be in the future or in the past.

For service type [flight], the following parameter is relevant.

travel[flight][departure_date] 20[0-9]{2}-[0-9]{2}-[0-9]{2} (YYYY-MM-DD): The departure date; can be in the future or in the past.

For service type [lodging] the following parameter is relevant.

travel[lodging][check_in_date] 20[0-9]{2}-[0-9]{2}-[0-9]{2} (YYYY-MM-DD): The agreed check-in date; can be in the future or in the past.

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]{,8}: 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.
Optional
text_on_statement [\x20-\x7E]{2,22} ASCII printable characters: Text that will be placed on cardholder’s bank statement. Overrides text_on_statement from authorization.
May not be all digits, all same character, or all sequential characters (e.g. “abc”).

Optional

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 usually lasts for at least seven days depending on the 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]{,8}: 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.)
text_on_statement [\x20-\x7E]{2,22} ASCII printable characters: Text that will be placed on cardholder’s bank statement.
May not be all digits, all same character, or all sequential characters (e.g. “abc”).

Optional
reference [\x20-\x7E]{1,30} ASCII printable characters: A reference to an external object, such as an order number.
Optional
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}: Card Security Code.
Optional
card[name] [A-Za-z0-9 ]{1,30}: Name on card.
Optional

Notice: Implicitly, initiator is merchant and credential_on_file is use.

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.
currency [A-Z]{3}: ISO 4217 3-letter currency code for merchant currency.
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

When you make a new transaction, the JSON response includes one of the status codes in the following table. The rightmost columns indicate which transaction types a particular status code can be received for.

Status	`code`	Meaning	Auth	Capture	Refund	Void	Credit
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	✓	✓	✓		✓
	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, 5000000000000004, 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; any other transaction amount will result in 40110.

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.

Accept travel data

Travel data can be supplied for a capture as of 2022-02-11.

Removing VES from supported currencies

The currency VES will not be supported after 2021-10-01T04:00:00Z.

Update authorization parameters

Replace recurring with series[type]=recurring and add series[previous] as a way of pointing to the previous-in-series authorization (either via a Clearhaus authorization ID or via raw scheme values).

Add also two optional parameters credential_on_file and initiator to allow for explicitly specifying if credential on file is being stored or used, and if the transaction is merchant or cardholder initiated.

Support for multiple signatures removed

Support for multiple signatures for request signing will be removed any time after 2020-10-31.

3-D Secure version 2 supported

Starting 2020-07-08 support for 3-D Secure version 2 has been added. See 3-D Secure and Authentication: [3dsecure].

Deprecate `threed_secure` response element

The response element threed_secure is now deprecated; it will be available at least until 2021-02-15.

Optional name on card parameter added

Starting 2020-03-03 the optional parameter card[name] may be used to provide the name on the card for credits. Depending on card scheme and merchant category, the name might be necessary for approval.

Request signing becomes mandatory

In the first quarter of 2020 signing of POST requests will become mandatory. We will work together with clients to ensure their requests are compliant before introducing enforcement of the requirement in the transaction gateway.

Clearhaus Transaction API

Getting Started

Examples

API Reference

Getting Started

API endpoint

Authentication

Resource discovery

Response format

Accounts and keys

Signing requests

RSA signature

Examples

Charge a cardholder

Reserve money

Withdraw money

Refund to cardholder

Payout to cardholder

Series of transactions

Repeatedly reserve money

3-D Secure

Secure transactions

Fetch account information

API Reference

Resources

Authorizations

Parameters

Method: card

Method: applepay

Method: googlepay

Method: mobilepayonline

Method: moto

Method: vipps

Authentication: [3dsecure]

Authentication: [3dsecure][v1]

Authentication: [3dsecure][v2]

Scheme reference to series

Captures

Parameters

Travel data

Refunds

Parameters

Voids

Parameters

Credits

Parameters

Account

Response parameters

Transaction status codes

Status message

Merchant blocked by cardholder status

Test card numbers

Endpoint summary

Changes

Accept travel data

Removing VES from supported currencies

Update authorization parameters

Support for multiple signatures removed

3-D Secure version 2 supported

Deprecate threed_secure response element

Optional name on card parameter added

Request signing becomes mandatory

Method: `card`

Method: `applepay`

Method: `googlepay`

Method: `mobilepayonline`

Method: `moto`

Method: `vipps`

Authentication: `[3dsecure]`

Authentication: `[3dsecure][v1]`

Authentication: `[3dsecure][v2]`

Deprecate `threed_secure` response element