Change payment methods

A customer might want to use a different payment method or distribute charges across multiple payment methods to pay for an order. In such scenarios, the user must be able to add or modify the payment methods conveniently.


The following section describes APIs, user exits, services, and other components.

The user can change the payment methods on an order by using the "Change Payment Method" related task in the Order Summary screen. The logic that is used while capturing payments for an order is reused while changing payment methods.

When the user chooses to change the payment methods on a confirmed order, the getCompleteOrderDetails API is called to retrieve the payment methods that exist on the order. The user can adjust the amount to charge on payment methods that support the adjustment and also add new payment methods, if required. The maximum amount that can be charged for a payment method is determined by the MaxChargeLimit attribute. However, the value of the MaxChargeLimit cannot be reduced to a value less than the TotalCharged attribute that is returned by the API.

The getCompleteOrderDetails API returns the following ModificationType attributes, which determine what the user can do based on whether the modification is allowed or not.

  • PRICE: Determines whether the user can modify adjustments.
  • PAYMENT_METHOD: Determines whether the user can add or delete payment methods on an order.
  • CHANGE_PROMOTION: Determines whether the user can apply new promotions to the order.
  • REMOVE_PROMOTION: Determines whether the user can remove the associated promotions.

The getPaymentTypeList API retrieves the payment methods that are allowed by the current organization. From this list, the user can select a payment method to add to the order.

The capturePayment API considers the fundsAvailable, RemainingAmountToAuth, UnlimitedCharges, and other variables to calculate the maximum charge limit of a payment method.

The capturePayment API is called to consider any correction and adjust the MaxChargeLimit for the order when there are multiple payment methods. The capturePayment API is called to save a payment method to the order.

In order to set up encryption for credit card name and expiration date, you must implement the logic for payment encryption and enable the "Encrypt Credit Card Name and Expiration Date" rule in the Business Center. The application displays asterisks in place of the characters in the credit card name and expiration date fields.

The CVV field is exposed only for credit cards when real-time authorization is required. When the user confirms payments for the first time on an order, the processOrderPayments API handles all authorizations and calculates the actual amount to be collected at any point while processing the order. The API in turn calls user exits that validate the payment methods and returns errors, if the payments fail validation. The PaymentTransactionError element in the output of the API contains the errors. All payment methods that are successfully authorized are immediately considered for the payments. If a payment method fails authorization, the user is prompted to either fix the payment method, or use a different payment method. If the payment verification system is down, the payment method is still considered. However, the authorization occurs later through the payment processing agents. When the Payment Confirmation screen is loaded again, the payment methods that returned errors in the previous transaction are retrieved based on the status that is set for each of the payment methods. The processOrderPayments API is not called again to validate the payment methods that exist on the order. However, when the user fixes the erroneous payment methods and applies the changes, the processOrderPayments API is called to validate the payments.

To save all the changes to the order, the changeOrder API is called to add or update payment methods and add a default note automatically. For more information, see Automatic notes logging. The manageCustomer API is called, if a payment method must be saved to the customer.

After the user modifies payment methods and charges, if the customer still owes money to fulfill the order, an appropriate error message is displayed.


The following section describes the rules that you must configure.

Configure the following rules appropriately.
  • Use A Single Field To Enter The Name On The Credit Card In The User Interface: The rule allows the use single or multiple fields for credit card name on the user interface at the time of capturing payment information. You can configure this rule at the enterprise level. When the user captures the details of a credit card, the screen behaves based on the configuration of this rule for the seller organization.
  • Authorize Credit Cards In Real Time for Draft Orders: The rule allows the user to authorize payments for an order in real time
  • Payment Types and Payment Card Types.
You must enable the following status modification rules to allow the user to change payment details.
  • Change Payment Method
  • Change Price
  • Change Promotion
  • Remove Promotion

For more information about the APIs and user exits, refer to the Javadoc.

You can configure default notes to be logged automatically upon successful change of a payment method. For more information, see Automatic notes logging.

End-user impact

The user can accommodate payment methods and distribution of charges across various payment methods to suit customer's needs.