PaymentSystemPluginMapping XML file

Reference > Payments subsystem > Payment configuration files

PaymentSystemPluginMapping XML file

Overview

To map payment systems to payment plug-ins use...

WC_EAR/xml/config/payments/ppc/plugins/PaymentSystemPluginMapping.xml
workspace_dir/wc/xml/config/payments/plugins/PaymentSystemPluginMapping.xml

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> 
If you remove the parameters from the extended data in a payment instruction, then you can not re-use 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 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 by using the elements...

<ProtocolProperties>
<ProtocolProperty>
...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 so as to improve the performance of the WebSphere Commerce application and the 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 provided in WebSphere Commerce for supported payment (and refund) methods. The associations shown below are examples; you could, 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.

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 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 (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 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.

NeverPersist

(Optional) Indicates whether the keyword is stored in the PPCEXTDATA table, which stores extended data for payment instructions.

true Do not persist the keyword.
false Default. The keyword is stored in 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.
The keyword is stored in the SEARCHVALUE column of the PPCEXTDATA table. Searchable keywords increase the amount of space is used and slow 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 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.

Example explanation

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

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 WCPayments plug-in uses a cassette called VisaNet to process transactions for the VisaNet payment system.
When using theWCPayments 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 theWCPayments plug-in using the ProfileName "WCPPPlugin_OfflineCard." In this case transactions for the PaymentSystemName of VisaNet are handled by WebSphere Commerce Payments using the OfflineCard payment cassette.

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.

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.
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"
account = "12345"

...modify the JSP files to collect both of these values.

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 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 to the OrderProcess command.

Related reference

AVSRules XML file
CorePaymentActions XML file
EDPGlobalConfigs XML file
PaymentMappings XML file
PaymentMethodConfigurations XML file
RefundMethodConfigurations XML file
RefundMappings XML file

+
Search Tips | Advanced Search

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

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

true	Enable the data to be searched. The keyword is stored in the SEARCHVALUE column of the PPCEXTDATA table. Searchable keywords increase the amount of space is used and slow processing speed.
false	The default value. Data cannot be searched.

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.

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.