CorePaymentActions XML file

The CorePaymentActions.xml file defines the payment actions required to move the payment from the current state to the required targeted state.

Possible payment actions are: Approve, Deposit, ReverseApproval, ConsumeAmount, and Error. The CorePaymentActions.xml file defines each of these target states:

TargetDNE
TargetApproved
TargetDeposited

This file is located in the following directory:

workspace_dir/WC/xml/config/payments/edp/groups/default/paymentConfiguration_name
workspace_dir/wc/xml/config/payments/edp/groups/default/paymentConfiguration_name

The paymentConfiguration_name is defined in PaymentMethodConfigurations.XML file

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

If you are a writing a payments plug-in and need to connect with a payment back-end system, it is recommended that you become familiar with this file.

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 (Does not exist), 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 payment rules configuration for payment actions. For an explanation of the elements and attributes used in the example, see the section that follows the example.

Figure 1. Example

<?xml version="1.0" encoding="UTF-8"?>
<PaymentActions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation="com/ibm/commerce/edp/parsers/PaymentActions.xsd">
	<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"
				minamount="currency_min" />
		</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

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 HCL 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 movement 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

existing: The same as the amount currently known by the system.
delta: Different from the current amount.
requested: The same as the payment amount requested.

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.

minamount

Specifies the minimum amount for the action. If the request amount is less than the minimum amount, the action will take the minimum amount instead of the request amount. You can specify the amount for this element. But you also can specify one special value for this element currency_min, this means the amount will be the minimum amount for the currency: 1 for Japanese Yen and 0.01 for US Dollar.

Example explanation

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

<CurrentDNE> An empty element. An empty element indicates no applicable payment actions need to take place. The move from a current state of DNE to a target state of DNE does not require any real payment action to occur with any back-end payment system at this stage.
<CurrentApproved> An error action is defined. A payment should not move from a current state of APPROVED to a target state of DNE. An error message is generated to note the request for the invalid change.
<CurrentDeposited> An error action is defined. A payment should not move from a current state of DEPOSITED to a target state of DNE. An error message is generated to note the request for the invalid change.

In the example, the TargetApproved section contains:

<CurrentDNE> If a payment object is not already created, create a new payment object and approve the requested amount of the payment reservation.
<CurrentApproved> If the current state of the payment is APPROVED:
- If the amount of the payment is less than the payment requested, update the payment amounts and create a new payment object and approve the difference in the payment amounts.
- If the amounts are equal, perform no payment action but update the payment amount to know how much of the payment amount is being consumed.
- If the amount of the payment is greater than the payment requested, perform no payment action but update the payment amount to know how much of the payment is being consumed.
<CurrentDeposited> If the current state of the payment is DEPOSITED:
- If the amount of the payment is less than the payment requested, update the payment amounts, create a new payment object, and approve the difference in the payment amounts.
- If the amounts are equal, perform no payment action but update the payment amount to know how much of the payment amount is being consumed.
- If the amount of the payment is greater than the payment requested, perform no payment action but update the payment amount for the business phase to know how much of the payment is being consumed.

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

<CurrentDNE> If the payment object is not already created, approve the payment amount requested, create an additional payment, and deposit the requested amount for the existing payment.
<CurrentApproved> If the current state of the payment is APPROVED:
- If the amount of the payment is less than the payment requested, deposit the amount for the existing payment. Then, approve the difference as an additional payment amount, and deposit the difference for the existing payment.
- If the amounts are equal, deposit the existing amount for the existing payment.
- If the amount of the payment is greater than the payment requested, consume the payment approval amount.
```
<AmountGreaterThanRequested>
     <Action name="ConsumeAmount"/>
</AmountGreaterThanRequested> 
```
  In a cumulative deposit, when the amount approved is greater than the requested deposit amount, the action performed is "ConsumeAmount." This action performs no direct payment action with the payment back-end system. It updates the payment amount internally for the business phase to know how much of the payment is being consumed.
  Deposits can be configured as either cumulative or non-cumulative in the CorePaymentActions.xml file. By default, the deposit type is cumulative. Unless you are writing or adding a new payment plug-in or modifying the default payment rules you should not need to change the deposit type.
  
  cumulative deposit
  
  A deposit that is made only when all the money is available to deposit. For example, if a payment is approved for $100 (U.S. dollars) for a sweater and a shirt, and funds are available for capture at $60 (sweater) in one release and $40 (shirt) in a later release, the individual deposits for $60 and $40 do not occur individually. Rather, the system "waits" until all $100 is available for deposit. A cumulative deposit captures funds as late as possible. Merchants pay lower processing fees for this type of deposit because it minimizes the amount of processing activity that occurs with a back-end financial system. Cumulative deposits are commonly associated with the sale of inexpensive order items, where merchants have high tolerance of risk should payments not occur. By default, the type of deposit configured in the CorePaymentActions.xml file is cumulative.
  
  noncumulative deposit
  
  A deposit that captures funds as soon as possible. Deposits take place as they occur even if only a portion of the total amount is available for capture. When more than one release is involved, the amounts are deposited as they occur and are not accumulated to be deposited at once. Merchants typically pay additional fees for processing noncumulative deposits because there is a greater amount of deposit processing activity occurring with the back-end financial system. Noncumulative deposits are often associated with the sale of expensive order items, where merchants might have a low tolerance of risk should payments not occur.
```
 <AmountGreaterThanRequested>
        <Action name="ReverseApproval"   amount="existing"      target="existing"/>
        <Action name="Approve"           amount="requested" target="additional"/>
        <Action name="Deposit"           amount="requested" target="existing"/>
        <Action name="Approve"           amount="delta"     target="additional"/>
  </AmountGreaterThanRequested>
```
  If deposits are cumulative and for some reason not all of the approved deposits were deposited, a cleanup activity can be performed to deposit amounts that should have been deposited but were not. For more information about using the EDPDepositableAmountProcessCmd controller command to do this. Refer to the API documentation for more information about specific commands.
<CurrentDeposited> If the current state of the payment is DEPOSITED:
- If the amount of the payment is less than the payment requested, deposit the existing amount for the existing payment. Then, approve the difference as an additional payment amount, and deposit the difference for the existing payment.
- If the amounts are equal, deposit the existing amount for the existing payment.
- If the amount of the payment is greater than the payment requested, perform no payment action but update the payment amount for the business phase to know how much of the payment is being processed.

Figure 2. Cumulative deposit. In this configuration, there is no financial transaction that will take place with a payment back-end system (the action is ConsumeAmount and not a Deposit action). Instead, the system updates the payment amount internally for the business phase to know how much of the payment is being consumed.


<TargetDeposited>
     <CurrentApproved>
          <AmountGreaterThanRequested>
               <Action name="ConsumeAmount"/>
          </AmountGreaterThanRequested>
     <CurrentApproved>
</TargetDeposited>

Figure 3. Noncumulative deposit with an Approve action and Deposit action in separate calls.. In this configuration, the existing approval amount is reversed. Two separate approvals will occur and a deposit. No approval amounts will expire in the payment back-end system.


<TargetDeposited>
     <CurrentApproved>
          <AmountGreaterThanRequested>
               <Action name="ReverseApproval"   amount="existing"      target="existing"/>
               <Action name="Approve"           amount="requested" target="additional"/>
               <Action name="Deposit"           amount="requested" target="existing"/>
               <Action name="Approve"           amount="delta"     target="additional"/>
          </AmountGreaterThanRequested>
     <CurrentApproved>
</TargetDeposited>

Figure 4. Noncumulative deposit with an Approval and Deposit action in one call. In this configuration, the existing approval amount is reversed. An Approve and Deposit action occurs at the same time. An additional approval action will occur. No approval amounts expire in the payment back-end system.


<TargetDeposited>
     <CurrentApproved>
          <AmountGreaterThanRequested>
               <Action name="ReverseApproval"   amount="existing"  target="existing"/>
               <Action name="ApproveAndDeposit" amount="requested" target="additional"/>
               <Action name="Approve"           amount="delta"     target="additional"/>
          </AmountGreaterThanRequested>
     <CurrentApproved>
</TargetDeposited>

Examples Noncumulative deposit with an Approve action and Deposit action in separate calls. and Noncumulative deposit with an Approval and Deposit action in one call show more than one action or financial transaction taking place. If you are using the SimpleOfflinePlugin payment plug-in and have configured the SimpleOfflinePlugin.xml file to keep transactions in a pending state for manual intervention, you cannot use these examples because each action will require a manual approval. You can minimize the number of actions requiring manual intervention by using example 2 instead.