Hey! These docs are for version 1.0, which is no longer officially supported. Click here for the latest version, 3.0!

Content Filters

A content filter is an XML structure which provides instructions to the PCI Booking system on how to parse a message. The content filter is set as part of Setting up a Target Profile and is used on messages in the Tokenization in Response and Token Replacement in Request processes.

General

PCI Booking supports content filters for the following scenarios:

The XML structure is the same in all cases and only the content settings change. Below are examples of content filters for tokenization and token replacement.

The selector property of each element in the XML represents the path that the PCI Booking system needs to go through in order to locate the value for this parameter.

Some of the card elements may contain formatting instructions:

  • The expYear and expMonth can include a format property to set the format of the date:
    • For the expiration year, you can set the format to be either YY or YYYY.
    • For the expiration month, you can set the format to be either M or MM.
  • The expYear and expMonth can also include a substring property in order to allow concatenation or separation of these values into one combined value.
    • The first number is the start location and the second number is the length of characters to store
    • For example, if the card expiration date is listed in a field called expDate and the format of this date is "DD-MM-YYYY" (01-02-2019), then the applicable selectors for these two fields would be:
<expYear selector="expDate" format="YYYY" substring="6,4"></expYear>
<expMonth selector="expDate" format="MM" substring="3,2"></expMonth>
  • The nameOnCardcan be set with a limit of the number of characters stored within the token. This is set in the format of substring="0,32" - the first number is the start location and the second number is the length of characters to store.
    • Currently PCI Booking supports storing up to 32 characters in the card owner name field.
  • The type can be set with a list of mapping from card types stored in PCI Booking to the types that the third party uses.
<?xml version="1.0" encoding="utf-8" ?>
<transform xmlns="http://www.pcibooking.net/pciShieldProfiles" type="body">
   <content selector="/reservation/payments/payment[@type='cc']/bankCard">
       <number selector="num" />
       <expYear selector="expiration" substring="0,4"></expYear>
       <expMonth selector="expiration" substring="5"></expMonth>
       <nameOnCard selector="cardHolderName"></nameOnCard>
       <securityCode selector="@cvv"/>
       <issueNumber selector="issue_number"></issueNumber>
       <type selector="Type" />
   </content>
</transform>
<?xml version="1.0" encoding="utf-8" ?>
<transform xmlns="http://www.pcibooking.net/pciShieldProfiles" type="body">
   <replace selector="/*/*/*/*/*/*">
       <number selector="*[local-name()='Number']"/>
       <expYear selector="*[local-name()='ExpirationDate']/*[local-name()='Year']" format="YY"></expYear>
       <expMonth selector="*[local-name()='ExpirationDate']/*[local-name()='Month']" format="MM"></expMonth>
       <nameOnCard selector="*[local-name()='NameOnCard']"></nameOnCard>
       <securityCode selector="*[local-name()='CVV']"/>
       <issueNumber selector="*[local-name()='IssueNumber']"/>
       <type selector="*[local-name()='Type']">
           <Visa>Visa</Visa>
           <AMEX>AMEX</AMEX>
           <MasterCard>MasterCard</MasterCard>
           <Dankort>Dankort</Dankort>
           <DinersClub>DinersClub</DinersClub>
       </type>
   </replace>
</transform>

Content in the URL

This scenario is usually only for the token replacement method (i.e. when pushing the card details to a third party). In this scenario, you would have to use the following formats:

  • The type property of the transform element would be querystring.
  • The replace element will not have a selector property (the location of the fields is known)
  • The selector property of each of the card elements would simply be the name of the querystring key that the value should be set with.

Below is an example of a profile for replacing the card details into this URL query string:

http://httpbin.org/post?card_number=&card_emp_year=&card_exp_month=&card_owner=&card_cvv=&card_type=
<?xml version="1.0" encoding="utf-8" ?>
<transform xmlns="http://www.pcibooking.net/pciShieldProfiles" 
           type="querystring">
   <replace>
       <number selector="card_number"></number>
       <expYear selector="card_emp_year" format="YY"></expYear>
       <expMonth selector="card_exp_month" format="MM"></expMonth>
       <nameOnCard selector="card_owner"></nameOnCard>
       <securityCode selector="card_cvv"></securityCode>
       <type selector="card_type">
           <Visa>VA</Visa>
           <AMEX>AE</AMEX>
           <MasterCard>MC</MasterCard>
           <Dankort>DK</Dankort>
           <DinersClub>DC</DinersClub>
       </type>
   </replace>
</transform>

Content in the body as XML

This scenario can be used both for tokenization of the response and token replacement into the request. In this scenario, you would have to use the following formats:

  • The type property of the transform element would be body.
  • The replace (for token replacement) or the content (for tokenization) element will have a selector property to indicate the xpath settings for the parent element of the card details. (for simplicity, we recommend using the * wildcard in order to indicate a level down.
    • For example, if the card details are all stored within the element BankCard and this element is the second level in the XML, the selector would be /*/*[local-name()='BankCard']
  • The selector property of each of the card elements would be the xpath settings for this element from the parent selector.

📘

XML name space

in order to overcome namespace conventions, we recommend using the [local-name()='elementName' command. This will ignore the namespace and will look only for the element's name itself.

Below is an example of an XML message body and the corresponding content filter for this message:

<message>
    <otherElements>
        <childElement1></childElement1>
        <childElement2></childElement2>
    </otherElements>
    <BankCard>
        <card_number></card_number>
        <card_emp_year></card_emp_year>
        <card_exp_month></card_exp_month>
        <card_owner></card_owner>
        <card_cvv></card_cvv>
        <card_type></card_type>
    </BankCard>
</message>
<?xml version="1.0" encoding="utf-8" ?>
<transform xmlns="http://www.pcibooking.net/pciShieldProfiles" type="body">
   <replace selector="/*/*[local-name()='BankCard']">
       <number selector="*[local-name()='card_number']"></number>
       <expYear selector="*[local-name()='card_emp_year']" 
                format="YYYY"></expYear>
       <expMonth selector="*[local-name()='card_exp_month']" 
                 format="MM"></expMonth>
       <nameOnCard selector="*[local-name()='card_owner']"></nameOnCard>
       <securityCode selector="*[local-name()='card_cvv']"></securityCode>
       <type selector="*[local-name()='card_type']">
           <Visa>VA</Visa>
           <AMEX>AE</AMEX>
           <MasterCard>MC</MasterCard>
           <Dankort>DK</Dankort>
           <DinersClub>DC</DinersClub>
       </type>
   </replace>
</transform>
<?xml version="1.0" encoding="utf-8" ?>
<transform xmlns="http://www.pcibooking.net/pciShieldProfiles" type="body">
   <content selector="/*/*[local-name()='BankCard']">
       <number selector="*[local-name()='card_number']"></number>
       <expYear selector="*[local-name()='card_emp_year']" 
                format="YYYY"></expYear>
       <expMonth selector="*[local-name()='card_exp_month']" 
                 format="MM"></expMonth>
       <nameOnCard selector="*[local-name()='card_owner']"></nameOnCard>
       <securityCode selector="*[local-name()='card_cvv']"></securityCode>
       <type selector="*[local-name()='card_type']">
           <Visa>VA</Visa>
           <AMEX>AE</AMEX>
           <MasterCard>MC</MasterCard>
           <Dankort>DK</Dankort>
           <DinersClub>DC</DinersClub>
       </type>
   </content>
</transform>

Content in the body as JSON

This scenario can be used both for tokenization of the response and token replacement into the request. In this scenario, you would have to use the following formats:

  • The type property of the transform element would be body.
  • The replace (for token replacement) or the content (for tokenization) element will have a selector property to indicate the jpath settings for the parent element of the card details. (for simplicity, we recommend using the . wildcard in order to indicate a level down.
    • For example, if the card details are all stored within the element BankCard and this element is the second level in the JSON, the selector would be $..BankCard
  • The selector property of each of the card elements would be the jpath settings for this element from the parent selector.

Below is an example of an JSON message body and the corresponding content filter for this message:

{
  "message": {
    "otherElements": {
      "ChildElement1":"some value",
      "childElement2":"some value"
    },
    "BankCard": {
      "card_number": "",
      "card_emp_year": "",
      "card_exp_month": "",
      "card_owner": "",
      "card_cvv": "",
      "card_type": ""
    }
  }
}
<?xml version="1.0" encoding="utf-8" ?>
<transform xmlns="http://www.pcibooking.net/pciShieldProfiles" type="body">
   <replace selector="$..BankCard">
       <number selector="card_number"></number>
       <expYear selector="card_emp_year" format="YYYY"></expYear>
       <expMonth selector="card_exp_month" format="MM"></expMonth>
       <nameOnCard selector="card_owner"></nameOnCard>
       <securityCode selector="card_cvv"></securityCode>
       <type selector="card_type">
           <Visa>VA</Visa>
           <AMEX>AE</AMEX>
           <MasterCard>MC</MasterCard>
           <Dankort>DK</Dankort>
           <DinersClub>DC</DinersClub>
       </type>
   </replace>
</transform>
<?xml version="1.0" encoding="utf-8" ?>
<transform xmlns="http://www.pcibooking.net/pciShieldProfiles" type="body">
   <content selector="$..BankCard">
       <number selector="card_number"></number>
       <expYear selector="card_emp_year" format="YYYY"></expYear>
       <expMonth selector="card_exp_month" format="MM"></expMonth>
       <nameOnCard selector="card_owner"></nameOnCard>
       <securityCode selector="card_cvv"></securityCode>
       <type selector="card_type">
           <Visa>VA</Visa>
           <AMEX>AE</AMEX>
           <MasterCard>MC</MasterCard>
           <Dankort>DK</Dankort>
           <DinersClub>DC</DinersClub>
       </type>
   </content>
</transform>

Content in the body as form data

This scenario can be used both for tokenization of the response and token replacement into the request. In this scenario, you would have to use the following formats:

  • The type property of the transform element would be body.
  • The replace (for token replacement) or the content (for tokenization) element will not have a selector property (the location of the fields is known)
  • The selector property of each of the card elements would simply be the name of the form data key that the value should be set with.

Below is an example of a profile for processing the card details in this form data key/value pairs:
guestName=Sam&card_type=&card_number=&expDate=xx-xx&card_cvv=&card_owner=&amount=1200

<?xml version="1.0" encoding="utf-8" ?>
<transform xmlns="http://www.pcibooking.net/pciShieldProfiles" type="body">
   <replace>
       <number selector="card_number"></number>
       <expYear selector="expDate" format="YY" substring="3,2"></expYear>
       <expMonth selector="expDate" format="MM" substring="0,2"></expMonth>
       <nameOnCard selector="card_owner"></nameOnCard>
       <securityCode selector="card_cvv"></securityCode>
       <type selector="card_type">
           <Visa>VA</Visa>
           <AMEX>AE</AMEX>
           <MasterCard>MC</MasterCard>
           <Dankort>DK</Dankort>
           <DinersClub>DC</DinersClub>
       </type>
   </replace>
</transform>
<?xml version="1.0" encoding="utf-8" ?>
<transform xmlns="http://www.pcibooking.net/pciShieldProfiles" type="body">
   <content>
       <number selector="card_number"></number>
       <expYear selector="expDate" format="YY" substring="3,2"></expYear>
       <expMonth selector="expDate" format="MM" substring="0,2"></expMonth>
       <nameOnCard selector="card_owner"></nameOnCard>
       <securityCode selector="card_cvv"></securityCode>
       <type selector="card_type">
           <Visa>VA</Visa>
           <AMEX>AE</AMEX>
           <MasterCard>MC</MasterCard>
           <Dankort>DK</Dankort>
           <DinersClub>DC</DinersClub>
       </type>
   </content>
</transform>