For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Loading...

Card Blocking

See the full range of request types and field values for this solution

Card Blocking allows you to choose which card types can be accepted for payment or stored for future-dated payments.

In this API reference, we present an overview of each request type, examples of request and response values, as well as how to handle them. For more information on Card Blocking, see our main article.

Payment request

Card Blocking can be enabled at an account level or payment-request level. Here, we set it up at the payment-request level.

<?xml version="1.0" encoding="UTF-8"?>
<request type="auth" timestamp="20180613141207">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <channel>ECOM</channel>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <amount currency="EUR">1001</amount>
  <card>
    <number>4263970000005262</number>
    <expdate>0425</expdate>
    <chname>James Mason</chname>
    <type>VISA</type>
    <cvn>
      <number>123</number>
      <presind>1</presind>
    </cvn>
  </card>

<blockcard>
	<commercialcredit>true</commercialcredit>
	<commercialdebit>false</commercialdebit>
	<consumercredit>false</consumercredit>
	<consumerdebit>false</consumerdebit>
</blockcard>

  <autosettle flag="1"/>
  <sha1hash>87707637a34ba651b6185718c863abc64b673f20</sha1hash>
</request>

Request syntax

You can use the following fields to control how Card Blocking options are presented to the customer in the HPP based on the card type used.

Type indicates whether the field is Mandatory (M), Optional (O), or Conditional (C) - depending on another optional field. Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
consumerdebit	integer	enum	O	NA	TRUE - Enables card blocking functionality when the card type is identified as Consumer Debit. FALSE - Disables card blocking functionality when the card type is identified as Consumer Debit.
consumercredit	integer	enum	O	NA	TRUE - Enables card blocking functionality when the card type is identified as Consumer Credit. FALSE - Disables card blocking functionality when the card type is identified as Consumer Credit.
commercialcredit	integer	enum	O	NA	TRUE - Enables card blocking functionality when the card type is identified as Commercial Credit. FALSE - Disables card blocking functionality when the card type is identified as Commercial Creditdebit.
commercialdebit	integer	enum	O	NA	TRUE - Enables card blocking functionality when the card type is identified as Commercial Debit. FALSE - Disables card blocking functionality when the card type is identified as Commercial Debit.

Sample response

The following response will be received if a supported Transaction Processing request is attempted with a card-block parameter passed in the payment request or account setting.

<response timestamp="20220815171818">
  <result>560</result>
  <message>Card type is not permitted by merchant config</message>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
</response>

Set all card types to block

Setting all card types to block is an invalid configuration and will result in the following error code:

<response timestamp="20220815171818">
  <result>561</result>
  <message>All card types are blocked, invalid request</message>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
</response>

Generate hash

Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

In addition to SHA-1, you can also generate your hash using SHA-256. The resulting hash should be placed in the tag instead of the tag. For more information, contact our support team.

Build the request hash

1. Create a SHA-1 hash made up of request values

The blueprint of the hash for this request is shown below:

"timestamp.merchantid.orderid.amount.currency.cardnumber"

Based on the XML example above, our initial string will be:

"20200414103508.MerchantId.N6qsk4kYRZihmPrTXWYS6g.1001.EUR.4263970000005262"

2. Concatenate the hashed string with your Shared Secret

After step 1, you'll have a string like:

“28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882”

You'll need to concatenate this with your Shared Secret, for example:

"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"

3. SHA-1 hash the concatenated string

Our final string that we add to the request should be a hash using the SHA-1 algorithm of your concatenated string. For example:

947903969e7aaf996164c680a6669805fe405269

Check hash

Follow the steps in this section to build the response security hash, concatenate the specified fields, and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Check the response hash

1. Create a SHA-1 hash string made up of response values

The blueprint of the hash for the response is shown below:

timestamp.merchantid.orderid.amount.currency

So, based on the above example, the initial string to check the hash of the response will be:

20200414103508.MerchantId.N6qsk4kYRZihmPrTXWYS6g.1001.EUR

2. Concatenate the hashed string with your Shared Secret

After step 1, you'll have a string like:

28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882

You'll need to concatenate this with your Shared Secret, for example:

28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a

3. SHA-1 hash the concatenated string and compare

Our final string that we add to the request should be a hash using the SHA-1 algorithm of your concatenated string. For example:

947903969e7aaf996164c680a6669805fe405269

We create the hash in the same way on our side and sends it back. To confirm that a response hasn't been tampered with, compare what you've generated with what was returned in the sha1hash element.