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.

For a merchant account, the use of one active (enabled and unexpired) API key is indistinguishable from the use of another active API key. An authorization made with one API key can be captured using any active API key for that same merchant account. In contrast, an authorization made on one merchant account cannot be captured on another merchant account.

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 (and public) 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-----

-----BEGIN PUBLIC KEY-----
MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBALYK0zmwuYkH3YWcFNLLddx5cwDxEY7G
i1xITuQqRrU4yD3uSw+JWYKknb4Tbndb6iEHY+e6gIGD+49TojnNeIUCAwEAAQ==
-----END PUBLIC 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"
}

The field card[name] is mandatory for Mastercard Payment of winnings (gaming/gambling merchants). Depending on card scheme and merchant category, the name on the card might be necessary for approval of credits.

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

For an authorization this should be followed by a capture. Subsequent-in-series authorizations or debits initiated by the merchant are made similarly, however, CSC is not included, and a 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 or debit can also be made using the applepay , googlepay , mobilepayonline , token or vipps payment methods.

A subsequent-in-series authorization or debit on a token must be made using the token payment method. In case it is made using a PAN the card payment method must be used.

When the cardholder is in scope for strong cardholder authentication (SCA), a first-in-series authorization or debit must be made with SCA regardless of the authorization amount.

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, or was already stored and is now being used.

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

Notice: If an authorization does neither use nor store credential on file, omit the credential_on_file parameter.

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.

Mutually exclusive with series[previous] and sca_exemption.

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 methods card and token. 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.

Mutually exclusive with series[type] and sca_exemption.

sca_exemption

transaction_risk_analysis

Request the Transaction Risk Analysis (TRA) SCA exemption.

Mutually exclusive with series.

Notice: Rules to disallow authorizations with sca_exemption may be in place for a merchant.

Notice: The exemption will be requested upstream regardless of the necessity of SCA.

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

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.

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

ID assigned by Google. Prepend it with either merchant: or gateway: depending on ID type.

googlepay[3dsecure]

dictionary

See Authentication: [3dsecure].

Optional

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 have been followed. If authMethod is PAN_ONLY, a 3-D Secure flow is required for SCA and the resulting ARes/RReq must be supplied in the 3dsecure sub-dictionary.

Notice: To obtain liability shift for a googlepay token with authMethod CRYPTOGRAM_3DS the ECI must be 02 or empty for Mastercard and 05 for VISA. For other values, a 3-D Secure flow is required for liability shift.

Notice: An authorization made with googlepay cannot be a subsequent-in-series authorization.

Notice: The recipient_id for googlepay in the 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

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][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. For MITs it shall only be included on the first, tokenized transaction or if there is a change to the token.

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.

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.

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

marketplace[interregional_retailer]

(true|false)

Indicates whether or not a marketplace retailer outside EEA, Gibraltar, and the UK is involved in the transaction.

Required if the merchant is a marketplace.

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

marketplace[interregional_retailer]

(true|false)

Indicates whether or not a marketplace retailer outside EEA, Gibraltar, and the UK is involved in the transaction.

Required if the merchant is a marketplace.

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 amount must be greater than zero.

Information about sender and recipient is required for debits under certain circumstances to be compliant with card scheme rules. See Sender information and Recipient information.

Sender information

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.

Recipient information

See the partner guideline for more details.

recipient[name]

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

The recipient’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.

recipient[account_number]

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

The recipient’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 PAN, etc.

Required.

recipient[reference]

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

Recipient reference number. You must be able to uniquely identify the recipient 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.

Required for Mastercard Payment of winnings, otherwise 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 funding 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 20000 is the only code for which the transaction is approved. For the other codes the transaction is declined.

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

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

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

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

# debit refunds 
https://gateway.clearhaus.com/debits/: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.

Removal of threed_secure property from response

Starting 2024-11-01, an authorization response will no longer contain the threed_secure property. We recommend that the sca dictionary is used instead. The sca dictionary contains the two boolean-valued properties provided and necessary. Another useful property in the response is liable_for_fraud_disputes which is either "merchant" or "issuer". Properties specifically related to 3-D Secure are available in the 3dsecure dictionary, however, please note that strong customer authentication (SCA) is usually the most important property and can be achieved by other means than 3-D Secure.

Capture refund period extended

Starting 2024-10-03 the maximum allowed period of time between the latest approved capture and a capture refund has been extended from 180 to 365 days.

Allowing voids on status code 50000 authorizations

We have added support for voids on authorizations with status code 50000.

Added new currencies and countries

Starting 2024-09-25, the Zimbabwe Gold (ZWG) and Zambian Kwacha (ZMW) currencies are now supported.

Country codes BQ, CW, QZ, SS, and SX are also now supported.

Removal of token[m4m][eci] parameter

Starting 2024-06-03, the token[m4m][eci] parameter has been removed. As the API accepts unknown parameters in general, the parameter can still be sent. It is, however, recommended that the parameter is omitted to avoid confusion.

Addition of sca_exemption parameter

Starting 2024-02-09, the sca_exemption parameter is available for authorizations and debits.

Addition of 3dsecure sub-dictionary to googlepay payment method

Starting 2023-12-11, 3-D Secure authentication details can be added to a Google Pay authorization and debit.

Addition of marketplace interregional retailer indicator to captures and capture refunds

A marketplace concept has been added to captures and capture refunds. The marketplace[interregional_retailer] parameter is required if the merchant is a marketplace.

Addition of recipient to debits

The recipient concept has been added to debits. The recipient[account_number] and recipient[name] parameters are now required for merchant accounts with Business Application Identifier (BAI) Account-to-Account (AA) from 2023-07-31.

Removal of deprecated parameters

We are removing several parameters that have been deprecated for an extended period of time. We promise that the following parameters are functional until 2023-05-01T00:00:00Z but give no guarantees thereafter.

• Request parameter recurring. Please use series[] instead.
• Request parameters card[pares], mobilepayonline[pares] and [3dsecure][v1] since 3DSv1 is being fully sunset 2023-04-15.
• Response parameter threed_secure, since 3DSv1 is being sunset fully on 2023-04-15.

Icelandic Krona (ISK) exponent change

ISK changes exponent from 2 to exponent 0. Transactions in ISK will be declined between 2023-04-13T19:00:00Z (Thursday evening) and 2023-04-17T08:00:00Z (Monday morning) (both inclusive); before this timespan, the exponent is 2; after the timespan, the exponent is 0.

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.