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:
WAS_installdir/installedApps/cell_name/ WC_instance_name.ear/xml/config/payments/edp/configuration_dir/payment/configuration_ID
WAS_userdir/installedApps/cell_name/WC_instance_name.ear/xml/config/payments/edp/ configuration_dir/payment/configuration_ID
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:
- TargetDNE
- TargetApproved
- TargetDeposited
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)
- 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.
Example explanation
In the example shown, the TargetDNE section contains the following:
- <CurrentDNE> An empty element. An empty element indicates no applicable payment actions need to take place. The transition 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 transition.
- <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 transition.
In the example, the TargetApproved section contains the following:
- <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 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.
Cumulative deposits: In this example, the XML file shows that a cumulative deposit is configured:
<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.
Noncumulative deposits: If you wanted to configure a noncumulative deposit, you should provide the following values in the AmountGreaterThanRequested element instead:
<AmountGreaterThanRequested> <Action name="ReverseApproval" amount="zero" target="existing"/> <Action name="Approve" amount="requested" target="additional"/> <Action name="Deposit" amount="requested" target="existing"/> <Action name="Approve" amount="delta" target="additional"/> </AmountGreaterThanRequested>
For additional examples, see Configuration examples of cumulative and noncumulative deposits.
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, see Background tasks to clean up unfinished or stalled orders. 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.