Getting Started

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

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>

RSA signature

The RSA signature is an RSASSA-PKCS1-v1_5 v 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"              \
     -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.

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.

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

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 eight different resources:

• Authorizations
• Captures
• Capture refunds
• Voids
• Debits
• Debit refunds
• 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, googlepay, mobilepayonline, moto, token and 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 previously 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, defaults to account’s descriptor

recurring

(true|false)

Deprecated! Please use series.

Optional

Cannot be used with series or initiator.

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

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

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

Primary account number of card to charge.

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

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.

Method: token

Two token frameworks are supported:

• token[m4m]: Mastercard Digital Enablement Service (MDES) for Merchants (M4M)
• token[vts]: Visa Token Service (VTS)

Requirement of some parameters depends on the initiator of the transaction; a parameter might be required for cardholder-initiated transactions (CITs) and otherwise optional. See the details for each parameter.

Method: token[m4m]

The required values are found in either the MDES transact response or the Secure Card on File (SCOF) checkout response.

token[m4m][tan]

[0-9]{12,19}

Token Account Number (TAN) of the token to charge.

Found in encryptedPayload.encryptedData.accountNumber (MDES) or encryptedPayload.token.paymentToken (SCOF).

token[m4m][expire_month]

[0-9]{2}

Expiry month of token to charge.

Found in encryptedPayload.encryptedData.applicationExpiryDate (MDES) or encryptedPayload.token.tokenExpirationMonth (SCOF).

token[m4m][expire_year]

20[0-9]{2}

Expiry year of token to charge.

Found in encryptedPayload.encryptedData.applicationExpiryDate (MDES) or encryptedPayload.token.tokenExpirationYear (SCOF).

token[m4m][eci]

0[267]

Electronic Commerce Indicator.

Found in eci (SCOF). (Not available in MDES.)

Required for CITs; otherwise optional (defaults to 07).

token[m4m][tav]

[:base64:]{28}

Token Authentication Value (TAV). Also known as token cryptogram and Digital Secure Remote Payments (DSRP) cryptogram.

Only DSRP cryptograms are supported. The value must start with [A-P] to be a DSRP cryptogram.

Found in encryptedPayload.encryptedData.de48se43Data (MDES) or encryptedPayload.dynamicData.dynamicDataValue (SCOF).

Required for CITs; otherwise optional.

token[m4m][rcai]

[:base64:]{1..150}

Remote Commerce Acceptor Identifier.

Merchant identifier such as business website URL or reverse domain name (e.g. com.example.www). The identifier must be encoded as Base64.

Found in customOutputData.remoteCommerceAcceptorIdentifier (SCOF). (Not available in MDES.)

Optional.

token[m4m][3dsecure][v2]

dictionary

See Authentication: [3dsecure][v2].

Optional

Method: token[vts]

The required values are found in the VTS provision token response.

token[vts][tan]

[0-9]{12,19}

Token Account Number (TAN) of the token to charge.

Found in tokenInfo.encTokenInfo.

token[vts][expire_month]

[0-9]{2}

Expiry month of token to charge.

Found in tokenInfo.expirationDate.month.

token[vts][expire_year]

20[0-9]{2}

Expiry year of token to charge.

Found in tokenInfo.expirationDate.year.

token[vts][eci]

0[57]

Electronic Commerce Indicator.

Found in cryptogramInfo.eci.

Required for CITs; otherwise optional (defaults to 07).

token[vts][tav]

[:base64:]{28}

Token Authentication Value (TAV). Also known as token cryptogram and Token Authentication Verification Value (TAVV).

Found in cryptogramInfo.cryptogram.

Required for CITs; otherwise optional.

token[vts][3dsecure][v2]

dictionary

See Authentication: [3dsecure][v2].

Optional

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

Authentication: [3dsecure]

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

[3dsecure][v1]

dictionary

Deprecated! Will stop working anytime after 2022-10-18. Please use [3dsecure][v2].

3-D Secure version 1.

Optional. Cannot be present if v2 is present.

Authentication: [3dsecure][v1]

[3dsecure][v1][pares]

[:base64:]

Deprecated! Will stop working anytime after 2022-10-18. Please use [3dsecure][v2].

See more information at 3Dsecure.io.

Optional.

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

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.

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

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

These are refunds of one or more captures made on an authorization and shall not be confused with debit refunds. Notice the association with authorizations rather than directly with 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 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

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.

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

Parameters

No parameters are needed to make a new void transaction.

Debits

To transfer money from a cardholder’s bank account in real-time, in one step, you make a new debit resource.

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

Debits support the same parameters and payment methods as Authorizations, with the exception that 3-D Secure version 1 is not supported.

Under certain circumstances, sender information is required for a debit. See Sender information.

Sender information

Information about the sender is required for debits under certain circumstances to be compliant with card scheme rules. See the partner guideline for more details.

Intra-EEA, mentioned below, includes the United Kingdom and Gibraltar.

sender[name]

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

The sender’s legal name.

Example: “Doe Jane A.” (last name, first name, optional middle initial).

It must not contain special characters (?, @, #, $, &, *, etc.), be all numeric, be fictious, be a nickname or be incomplete (only first or last name).

Required for intra-EEA and international debits. Also required if any of the address-related parameters are supplied.

sender[address]

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

The sender’s address (street name, house number, etc.).

Required for intra-EEA and international debits.

sender[city]

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

The sender’s city.

Required for intra-EEA and international debits.

sender[state]

[A-Z]{2}

The sender’s state.

Required if the country is CA (Canada) or US (USA).

sender[country]

[A-Z]{2}

The sender’s country (ISO 3166-1 2-letter country code).

Required for intra-EEA and international debits.

sender[account_number]

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

The sender’s account number, i.e. an identification of the account being funded by the debit. It can be an IBAN, a proprietary wallet number, a prepaid PAN, etc.

Required

sender[reference]

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

Sender reference number. You must be able to uniquely identify the sender using this number.

Required if the merchant account’s Business Application Identifier (BAI) is Funds Disbursement (FD).

Debit refunds

To refund money to a cardholder’s bank account that has been transferred by a debit you make a new refund resource. Only a single refund can be made for a debit and it can only be for the full amount.

POST https://gateway.clearhaus.com/debits/:id/refunds

Parameters

No parameters are needed to make a new refund transaction.

Credits

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

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

Parameters

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, defaults to account’s descriptor

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

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 messages

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

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

Debits and debit refunds resources added

Starting 2023-02-01, debits and debit refunds resources are available.

Croatian Kuna (HRK) changes to Euro (EUR)

Due to the accession of Croatia to the euro area on 2023-01-01, HRK will become an invalid currency. Please notice the deadlines communicated in the partner bulletin of Q4 2022.

Deprecation and phase-out of 3-D Secure version 1

Both Visa and Mastercard are phasing out 3-D Secure version 1 (3DSv1) in favour of 3-D Secure version 2 (3DSv2). As a consequence, we are deprecating 3DSv1 which will effectively stop working with schemes mid-October; 2022-10-18 for Mastercard and 2022-10-14 for Visa. The [3dsecure][v1] authentication method and the [pares] parameters will be removed any time after 2022-10-18.

Payment method for token frameworks

The payment method token has been added on 2022-10-07. Please see Method: token for an introduction.

Change SLL currency to SLE

The currency SLL has been changed to SLE on 2022-10-07.

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.