PaymentSystemPluginMapping XML file

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

This file is in the following directory:

WC_eardir/xml/config/payments/ppc/plugins
workspace_dir/wc/xml/config/payments/plugins

Example

<?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" neverPersist="true"/>
              <Keyword name="cc_nameoncard" mask="*" plain="0" removeAfterApproval="true" neverPersist="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" neverPersist="true"/>
              <Keyword name="cc_nameoncard" mask="*" plain="0" removeAfterApproval="true" neverPersist="true"/>
              <Keyword name="account" mask="*" plain="-5" searchable="true"/>
          </Mapping>
  </PaymentSystemName>

  
</Mapper>

Note: If you remove the parameters from the extended data in a payment instruction, then you cannot reuse those parameters in later transactions, for example, in return flow.

Parameters

RetainKeywords

Optional: Specify any keywords that should be retained in the WebSphere Commerce database. This is a global setting that applies to all payment instructions for all plug-ins that are named in this file. In the example that is shown, the billing address ID is kept in the database for any plug-in that is used in this file.

Another way to specify the retention of keywords is by using the <ProtocolProperties> and <ProtocolProperty> elements in the plug-in deployment descriptor. When you retain keywords in 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 to improve the performance of the WebSphere Commerce application and your online store.

PaymentSystemName

name

The name of the payment back-end system.

A payment system name is a string that is independent of the plug-in name. The payment system name maps to the payment plug-in used to process the transactions. The payment system name should match between the PaymentMethodConfigurations.xml (or RefundMethodConfigurations.xml) and PaymentSystemPluginMapping.xml files.

The following table lists the payment system names that are provided in WebSphere Commerce for supported payment (and refund) methods. The associations that are shown below are examples; you can, for instance, configure a particular credit card brand to use a different payment system name or payment plug-in.


Payment system name	Plug-in name	Method
LOCSystem	LOCPlugin	LOC
OfflineACHSystem	SimpleOfflinePlugin	Check
OfflineCreditCardSystem	SimpleOfflinePlugin	AMEX
OfflineCreditCardSystem	SimpleOfflinePlugin	Master Card
OfflineCreditCardSystem	SimpleOfflinePlugin	VISA
OfflineSystem	SimpleOfflinePlugin	BillMeLater
OfflineSystem	SimpleOfflinePlugin	COD
OfflineSystem	SimpleOfflinePlugin	PayLater

Mapping

paymentConfigurationId

The ID of the payment configuration for the payment method. The combination of the payment system name and the paymentconfigurationId determine which plug-in is used. For more information, seePayment configuration group.

PluginName

The name of the payment 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 that are defined under the <Mapping> element are saved to the WebSphere Commerce database.

name

The name of the keyword that is 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 that is used to mask the portion of the data that should not be visible. The character can be a minus sign, an 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 five characters in the string (For example, the credit card number 4111111111111111, is displayed as ***********11111). 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 that are 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 are displayed in the user interface. Because searchable="true" is set without a plain value, the whole bill-to address string is used for searching orders.

NeverPersist

Optional: Indicates whether the keyword is stored in the PPCEXTDATA table. The PPCEXTDATA table stores extended data for payment instructions.

true: Do not persist the keyword.
false: The default value. The keyword is stored in the PPCEXTDATA table when a payment instruction is added.

searchable

Indicates whether the keyword can be searched in the WebSphere Commerce Accelerator on the Find Orders page.

true: Enable the data to be searched.
Note: The keyword is stored in the SEARCHVALUE column of the PPCEXTDATA table. Increasing the number of searchable keywords increases the amount of space that is used and slows the processing speed.
false: The default value. Data cannot be searched.

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. Some financial protocols require that sensitive data (such as the card verification value and the name on the card) not be stored.

true: Remove the keyword. Sensitive data is removed from the extended data after the total amount of the payment is approved.
false: The default value. Keep the keyword.

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 that shows 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.

Example explanation

In the preceding example, two plug-ins are used, SimpleOffline and WCPayments:

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

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 Orders page in the WebSphere Commerce Accelerator, the keyword for that data should be listed with the necessary search attributes.
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 five 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 five 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, see Using other payment protocol data to find orders.
The digits that precede the last five 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 values for cc_cvc and cc_nameoncard do not persist to the PPCEXTDATA table. To use protocol data at payment authorization, pass the value of cc_cvc and cc_nameoncard to the OrderProcess command.