Advanced orders CorePaymentActions XML file

The core behavior of payment actions executed for event-driven payments is defined in the CorePaymentActions.xml file. This file is located in the following directory:

You should not have to update or create this file when configuring payment processing for your store if you are using the payments function provided with WebSphere Commerce. However, if you are a payments plug-in writer and need to connect WebSphere Commerce with a payment back-end system not supported by existing WebSphere Commerce payments cassettes or plug-ins, it is recommended that you become familiar with this file.

This XML file defines what happens and when. Actions take two forms: action with a payment back-end system, and an internal update of payment information. The CorePaymentActions.xml file does not force an action to occur always; however, back-end actions always execute internal updates. Internal updates do not communicate with the back-end system.

Note: Only one CorePaymentActions.xml file should exist for every payment system named in the PaymentMethodConfiguration.xml file.

The CorePaymentActions.xml file defines how the required target state of the payment is achieved in terms of actual payment actions defined by the payment back-end system. Possible payment actions are: Approve, Deposit, ReverseApproval, Credit, ConsumeAmount, and Error. However, the valid target states that can be defined in payment actions are: DNE (does not exist), APPROVED, and DEPOSITED.

Payment actions are configured in the PaymentRules.xml file for every payment action rule used by a payment configuration ID. Because a particular payment action can have only one of three possible target states (DNE, APPROVED, or DEPOSITED), the CorePaymentActions.xml file contains elements that define each of these target states:

The markup within each of these elements defines the action that should be taken to move the payment object from its current state to the target state when the current state of the payment is one of the following states: DNE, APPROVED, or DEPOSITED.

The following example of a CorePaymentActions.xml file shows core behaviors being configured for the valid target states that can exist in an event-driven payments configuration for payment actions. For an explanation of the elements and attributes used in the example, see the section that follows the example.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<PaymentActions
     xmlns:edp="http://www.ibm.com/WebSphereCommerce/EDP>
     
     <TargetDNE>
            <CurrentDNE>
            </CurrentDNE>
                         
            <CurrentApproved>
                  <Action name="Error" msg="Target DNE; current Approved"/> 
            </CurrentApproved>      
                    
            <CurrentDeposited>
                   <Action name="Error" msg="Target DNE; current Deposited"/> 
            </CurrentDeposited>
            
       </TargetDNE> 
       
       <TargetApproved>
            <CurrentDNE>
                     <Action name="Approve" amount="requested" target="new"/>
            </CurrentDNE>
                         
            <CurrentApproved>
                  <AmountLessThanRequested>
                       <Action name="ConsumeAmount"/>
                       <Action name="Approve" amount="delta" target="new"/> 
                  </AmountLessThanRequested>
                  
                  <AmountEqualsRequested>
                       <Action name="ConsumeAmount"/>
                  <AmountEqualsRequested>
                  
                  <AmountGreaterThanRequested>
                       <Action name="ConsumeAmount"/>
                  <AmountGreaterThanRequested>

            </CurrentApproved>  
            
            <CurrentDeposited>
                  <AmountLessThanRequested>
                       <Action name="ConsumeAmount"/>
                       <Action name="Approve" amount="delta" target="new"/> 
                  </AmountLessThanRequested>
                  
                  <AmountEqualsRequested>
                       <Action name="ConsumeAmount"/>
                  <AmountEqualsRequested>
                  
                  <AmountGreaterThanRequested>
                       <Action name="ConsumeAmount"/>
                  <AmountGreaterThanRequested>

            </CurrentDeposited> 
                        
       </TargetApproved>
       
       <TargetDeposited>
       
          <CurrentDNE>
                 <Action name="Approve" amount="requested" target="additional"/>
                 <Action name="Deposit" amount="requested" target="existing"/>
          </CurrentDNE>
          
          <CurrentApproved>
                 <AmountLessThanRequested>
                       <Action name="Deposit" amount="existing" target="existing"/>
                       <Action name="Approve" amount="delta" target="additional"/>
                       <Action name="Deposit" amount="delta" target="existing"/>
                 </AmountLessThanRequested>
                 
                 <AmountEqualsRequested>
                       <Action name="Deposit" amount="existing" target="existing"/>
                 </AmountEqualsRequested>
                 
                 <AmountGreaterThanRequested>
                       <Action name="ConsumeAmount"/>
                 </AmountGreaterThanRequested>
          </CurrentApproved> 
          
          <CurrentDeposited>
                 <AmountLessThanRequested>
                       <Action name="Deposit" amount="existing" target="existing"/>
                       <Action name="Approve" amount="delta" target="additional"/>
                       <Action name="Deposit" amount="delta" target="existing"/>
                 </AmountLessThanRequested>
                 
                 <AmountEqualsRequested>
                       <Action name="Deposit" amount="existing" target="existing"/>
                 </AmountEqualsRequested>
                 
                 <AmountGreaterThanRequested>
                       <Action name="ConsumeAmount"/>
                 </AmountGreaterThanRequested>
          </CurrentDeposited>
                 
    </TargetDeposited>
          
</PaymentActions>      

Parameters

The following parameters affect the behavior of event-driven payments:

name
The name of the payment action. Possible values are:
  • Approve - Approves the payment.
  • ReverseApproval - Reverses the payment approval.
  • Deposit - Deposits the payment.
  • Credit - Refunds the payment.
  • ConsumeAmount - Updates information internally in WebSphere Commerce but does not perform any direct payment action with a payment back-end system. For example, ConsumeAmount can be used to update information about a credit card expiry date. An update is always performed if a payment action is defined.
  • Error - Generates an error.
msg
This parameter is used when the Action name="Error" and holds the actual text of the error message. An error message is displayed in exception situations where the transition from the current payment state to the target payment state is considered invalid. The text should display in the language supported by your store. The text of the error message can be displayed in a tickler message, to the customer in the Web browser, or to support personnel such as a Customer Service Representative.
amount
When the amount of the payment is being processed, it is either:
  • The same as the amount currently known by the system (existing)
  • Different from the current amount (delta)
  • The same as the payment amount requested (requested)
Possible values for the amount attribute are: delta, requested, existing.
target
Specifies the target payment object for the action. For example, when the current state of a payment is Approved and the payment amount being processed is less than requested, and the target state of the payment is Deposited, the amount being processed represents a delta and the target object should create an additional payment (additional payment object) for the amount of the delta. Possible values are for the target attribute are:
  • new - A new payment object should be created and data should be written to the database.
  • additional - An additional operation is expected to follow. Data is kept in memory but is not written to the database.
  • existing - The payment is the same amount currently expected by the system.
The TargetDeposited element should never contain a target="additional" attribute without being followed immediately with a target="existing" attribute.

Example explanation

In the example shown, the TargetDNE section contains the following:

In the example, the TargetApproved section contains the following:

In the example, the TargetDeposited section contains the following elements.

Feedback