Payment system plug-in mapping XML file

Payment system plug-in mapping XML file

Use the PaymentSystemPluginMapping.xml file to map payment systems to payment plug-ins.

This file is used by the Payment Plugin Controller to know what plug-ins to use for a particular payment system name in an Payment Rules configuration.

In the following example, two plug-ins are used, SimpleOffline and WC PaymentsPlugin:

The SimpleOffline plug-in is used to process transactions for the payment system name SimpleOffline. The plug-in named SimpleOffline is used with the SimpleOffline payment system. The SimpleOffline payment system is an offline payment approach that does not involve direct communication with a payment back-end system.
The WCPaymentPlugin is used to handle transactions with another payment system named VisaNet. The WCPayment plug-in uses a cassette called VisaNet to process transactions for the VisaNet payment system.

Note: When using the WC Payments Cassette plug-in, be aware that there is no relationship between the PaymentSystemName and the cassette used in WebSphere Commerce Payments. The cassette is determined by the ProfileName in the Property element. For example, a PaymentSystemName of "VisaNet" can be mapped to the WC Payments Cassette plug-in using the ProfileName "WCPPPlugin_OfflineCard." In this case transactions for the PaymentSystemName of VisaNet are handled by the WebSphere Commerce Payments component using the OfflineCard payment cassette.

Example of PaymentSystemPluginMapping.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<Mapper xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PaymentSystemPluginMapper.xsd">

  <RetainKeywords>
       <Keyword name="billing_address_id"/>
  </RetainKeywords>     
  <PaymentSystemName 
          name="SimpleOffline" >
          <Mapping paymentConfigurationId="default" PluginName="SimpleOffline" >
              <Keyword name="cc_cvc" mask="-" plain="0" removeAfterApproval="true"/>
              <Keyword name="cc_nameoncard" mask="*" plain="0" removeAfterApproval="true"/>
              <Keyword name="account" mask="*" plain="-5" searchable="true"/>
          </Mapping> 
  </PaymentSystemName>
  <PaymentSystemName 
          name="VisaNet" >
          <Mapping paymentConfigurationId="VisaNet" PluginName="WCPaymentsPlugin" >
              <Property name="ProfileName" value="WCPPlugin_VisaNet"/>
              <Keyword name="cc_cvc" mask="-" plain="0" removeAfterApproval="true"/>
              <Keyword name="cc_nameoncard" mask="*" plain="0" removeAfterApproval="true"/>
              <Keyword name="account" mask="*" plain="-5" searchable="true"/>
          </Mapping>
  </PaymentSystemName>

  
</Mapper>
Use the following parameters to change the behavior of this file:

RetainKeywords

(Optional) Specify any keywords that should be retained in the WebSphere Commerce database rather than not stored. This is a global setting that applies to all payment instructions for all plug-ins named in this file. In the example shown, the billing address ID is kept in the database for any plug-in used in this file.
Another way to specify the retention of keywords is through the <ProtocolProperties> and <ProtocolProperty> elements in the plug-in deployment descriptor. (For an example, see SimpleOffline plug-in deployment descriptor.) When you retain keywords through the plug-in deployment descriptor, the retention is at the plug-in level only (not a global retention for all plug-ins).

This element can be used to determine what important data should be retained so as to improve the performance of the WebSphere Commerce application and your online store.

PaymentSystemName name

The name of the payment back-end system. Refer to Payment system names for more information.

Mapping

paymentConfigurationId The ID of the payment configuration for the payment method that will have transactions processed through this plug-in. Refer to Payment configuration IDs for more information.
PluginName The name of the payment plug-in. The name can be that of a plug-in provided by WebSphere Commerce or the name of a third-party plug-in.

Property

(Optional)
name The name of the plug-in property that should be used in transactions for this particular payment method. A plug-in can require additional parameters, or a payment configuration can have unique needs.
value The value of the named plug-in property.

Keyword

(Optional) All keywords defined under the <Mapping> element are saved to the WebSphere Commerce database.
name
The name of the keywords associated with payment protocol data and their attributes. The attributes can be used to configure whether the data can be used in an order search, what portion of the data is visible in the search results, whether any part of the data should be masked when displaying the protocol data in the user interface, and whether the data should be removed from the database after the total amount of the payment instruction is approved.
mask The character used to mask the portion of the data which should not be visible. The character can be a minus sign, asterisk, or some other character. This attribute is used in combination with "plain" when sensitive data is displayed in the WebSphere Commerce Accelerator.

plain The length of the plain text (visible portion). This attribute is used in combination with "mask" when sensitive data is displayed in the WebSphere Commerce Accelerator. The value for plain is an integer with or without a minus sign. The minus sign is used to define the location of the plain part of the text in the string relative to the end of the string. For example, plain="2" means the first two characters in the string. Plain="-5" means the last 5 characters in the string. Plain="0" means there are no plain characters.

This attribute applies to the mask and searchable attributes. If plain is omitted, it is treated as plain="0" for masking (no characters masked) and plain="total_text_length" for searching (all characters used in search). The value for plain is used only when mask is specified or when searchable is specified.

Example: Suppose a configuration shows <keyword name="billto_address" searchable="true">. No mask value is specified so the entire string of the bill-to address will be displayed in the user interface. Because searchable="true" is set without a plain value, the whole bill-to address string is used for order searching.

removeAfterApproval Indicates whether the keyword will be removed from the extended data of the payment instruction after the total amount of the payment instruction is approved. Type "true" to remove the keyword or "false" to keep the keyword. If no value is specified, it is assumed to be "false."

Some financial protocols require that sensitive data (such as the card verification value and the name on the card) not be stored. If the attribute value is "true," the sensitive data will be removed from the extended data after the total amount of the payment is approved.

searchable Indicates whether the keyword can be searched in the WebSphere Commerce Accelerator on the Find Orders page. Type "true" to enable the data to be searched or "false" to not enable the data to be searched. If the attribute is not specified it is assumed not to be searchable.

Note: When you add information to be searchable, the keyword is stored in an extra column. The more searchable keywords you have, the greater the total amount of space is used and the slower the processing of the data will be.

The previous example shows, for the SimpleOffline payment system, configurations that determine what protocol data is searchable in the WebSphere Commerce Accelerator when an orders search is performed. If a particular piece of protocol data should be searchable on the Find Order page in the WebSphere Commerce Accelerator, the keyword for that data should be listed with the necessary search attributes.

In the example shown:

The payment "account" is the only payment protocol data that can be used in the order search. On the Find Orders page in the WebSphere Commerce Accelerator, a field would exist for the user to enter the last 5 digits of the payment account number (for example, the credit card number for a credit card). The user interface would not show fields for the card verification code (CVC) code or the cardholder name on the card.
The user interface can be changed to use other payment protocol data for the order search. Only the "account" field is initially made available for order search. Any payment protocol data can be made available for searching. If you want to search on something other than the last 5 digits of the payment account number, you can customize the order search page. For example, to search on 'bankname' instead of 'account', modify the order search or order list JSP page to change the protocol data name to 'bankname'.

To use two types of protocol data to search an order, such as cc_brand and account (for example, cc_brand="CardBrandX" and account = "12345"), modify the JSP files to collect both of these values. For more information, refer to Using other payment protocol data to find orders.

The digits preceding the last 5 digits of the payment account number are masked in the search results with asterisks (*). For example, if the account number is 123456789012345, it is displayed as **********12345 in the WebSphere Commerce Accelerator and only 12345 is saved internally for the order search.
The keyword cc_cvc is masked with dash characters in the user interface with no digits plainly visible.
The values for cc_cvc and cc_name on card are removed after the total amount of the payment instruction is approved. The account number is not removed (absence of the attribute means removeAfterApproval="false").

The following table summarizes the meanings of various combinations of configurations for keywords (not all possible combinations are shown). Blank cells in the table indicate that the corresponding attribute is not specified in the configuration file.

mask plain searchable Description of configuration

one character (*, -, or other) An integer with or without minus sign true/false The value of the keyword is masked with the mask character with some plain part in the user interface. The integer of the plain element defines the length of the plain part. The minus sign defines the location of the plain part from the end of the string. If searchable is true, only the plain part can be searched. If searchable is false, the search on this keyword is not supported. Here, the plain part is the same as the searchable part. If the length of the plain part is 0, searchable="true" equals searchable="false".

An integer with or without minus sign true/false The value of the keyword is not masked in the user interface. The entire string of the value is displayed plainly. If searchable is true, the searchable part is defined by plain. The integer defines the length of the searchable part, and the minus sign defines the location of the searchable part. If searchable is false, the search on this keyword is not supported.

one character (*, -, or other) An integer with or without minus sign The value of this keyword is masked with the mask character with some plain part in the user interface. The integer of the plain element defines the length of the plain part and the minus character defines the location of the plain part in the entire string. When searchable is not specified, the keyword is not searchable.

true The value of the keyword is not masked in the user interface. The entire string is plainly displayed. Because searchable is true without plain specified, the entire string value can be searched.

false The value of the keyword is not masked in the user interface. The entire string is plainly displayed. Because searchable is false, the value cannot be searched.

one character (*, -, or other) true/false The value of the keyword is masked with the mask character without any plain part visible in the user interface. If searchable is true, the entire string can be searched. If searchable is false, the search on this keyword is not supported. Here, the plain part is not the same as the searchable part.

one character (*, -, or other) The value of the keyword is masked with the mask character without any plain part showing in the user interface. Because searchable is not specified, this keyword is not searchable.

Nothing for mask, plain, or searchable is specified. The value of the keyword is not masked in the user interface. The entire string is plainly displayed. Because searchable is not specified, the value cannot be searched.

Related concepts

Payment plug-ins
Payment Plug-in Controller
Payment plug-ins provided in WebSphere Commerce
Retention of payment information in the WebSphere Commerce database

Related tasks

Mapping a payment system to a payment plug-in
Configure a payment plug-in

Related reference

Payment system names

(C) Copyright IBM Corporation 1996, 2006. All Rights Reserved.

mask	plain	searchable	Description of configuration
one character (*, -, or other)	An integer with or without minus sign	true/false	The value of the keyword is masked with the mask character with some plain part in the user interface. The integer of the plain element defines the length of the plain part. The minus sign defines the location of the plain part from the end of the string. If searchable is true, only the plain part can be searched. If searchable is false, the search on this keyword is not supported. Here, the plain part is the same as the searchable part. If the length of the plain part is 0, searchable="true" equals searchable="false".
	An integer with or without minus sign	true/false	The value of the keyword is not masked in the user interface. The entire string of the value is displayed plainly. If searchable is true, the searchable part is defined by plain. The integer defines the length of the searchable part, and the minus sign defines the location of the searchable part. If searchable is false, the search on this keyword is not supported.
one character (*, -, or other)	An integer with or without minus sign		The value of this keyword is masked with the mask character with some plain part in the user interface. The integer of the plain element defines the length of the plain part and the minus character defines the location of the plain part in the entire string. When searchable is not specified, the keyword is not searchable.
		true	The value of the keyword is not masked in the user interface. The entire string is plainly displayed. Because searchable is true without plain specified, the entire string value can be searched.
		false	The value of the keyword is not masked in the user interface. The entire string is plainly displayed. Because searchable is false, the value cannot be searched.
one character (*, -, or other)		true/false	The value of the keyword is masked with the mask character without any plain part visible in the user interface. If searchable is true, the entire string can be searched. If searchable is false, the search on this keyword is not supported. Here, the plain part is not the same as the searchable part.
one character (*, -, or other)			The value of the keyword is masked with the mask character without any plain part showing in the user interface. Because searchable is not specified, this keyword is not searchable.
			Nothing for mask, plain, or searchable is specified. The value of the keyword is not masked in the user interface. The entire string is plainly displayed. Because searchable is not specified, the value cannot be searched.