Confirm payments

Solution

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

The different stages in processing payments from different payment methods are shown in the following diagram:

Payment confirmation is the last stage of order creation or modification. The Confirm Payments screen can be accessed during order creation, modification, and cancellation.

The user can add a payment method by clicking the "Add Payment Method" button. The user can add one or more payment methods such as customer accounts, credit cards, checks, prepaid cards, or store value cards.

After adding a payment method, the user can choose to edit the payment method. However, only certain values can be edited based on the payment method. For example, if the user has added a customer account as the payment method, the user can edit the amount to charge only. The payment type and the account number cannot be modified.

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 getCustomerPaymentMethodList API returns the payment methods that are saved for the customer.

The capturePayment API saves a payment method to the order, deals with any external payment types, suspends a payment method that is no longer used by the customer, returns the sequence of payment methods, in the order they are charged. The sequence in which the payment methods are processed is based on the funds available in each payment method. Some payment methods are assigned with hard set amounts. Such payment methods are typically the first to be processed. However, this sequence in not enforced by the application. For example, all available funds on a gift card can be used before using an extra gift card. This process prevents the user from defining the amount to be charged on each gift card. However, the user can choose to pay by using multiple payment methods and distribute the charges across credit cards, customer accounts, and so on.

The charge sequence that is configured in the Sterling™ Business Center takes priority. The sequence in capturePayment API is considered if there is a tie in the sequence numbers. For example, if you have multiple payment methods of the same type or if multiple payment methods have the same sequence number.

The capturePayment API considers the fundsAvailable, RemainingAmountToAuth, and other variables to calculate the maximum charge limit of a payment method. If the user changes the amount that is charged against an existing payment method, the RequestedAmount attribute is updated automatically. The capturePayment API is called to consider the correction and update the MaxChargeLimits and the RemainingAmountToAuth attributes accordingly.

In addition to actual payment methods, the user can also apply promotion codes or coupon codes to the order. Based on the coupons that are selected, the changeOrder API reprices the order and applies or rejects the adjustments. If the coupon is valid, the adjustment is applied to the order and the total adjustment is displayed in the coupon list. The user cannot apply an invalid coupon.

Sometimes, payment methods are suspended. Payment methods can be suspended for various reasons. For example, when the amount to charge for a payment method is updated to $0, the payment method is suspended. The customer can also implement a user exit to process a payment method and suspend it when necessary. When the user removes a payment method, the PaymentKey attribute and the Operation attribute with the value as Suspend are passed to the capturePayment API. When the user resumes a suspended payment method on an order, the PaymentKey attribute and the Operation attribute with the value as Manage are passed to the capturePayment API.

The customer can also implement a user exit that suspends a payment method if the date is in the past. For example, when the expiration date of a credit card lapses, the YFSCollectionCreditCardUE user exit can be called to suspend the payment method.

The processOrderPayments API handles all authorizations and calculates the actual amount to be collected at any point while processing the order. All payment methods that are successfully authorized are immediately considered for the payments. If a payment method fails the 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.

Based on the results of the processOrderPayments API, if all payment methods are processed successfully, the value of the PaymentTransactionSuccessful attribute is "Y", the order is confirmed, and the user is directed to the appropriate screen.

If any of the payment methods are unsuccessful, the value of PaymentTransactionSuccessful attribute is "N". An appropriate message is displayed to indicate that the payment was not successfully processed. The message that is returned in the PaymentTransactionError element is displayed to the user to indicate why the payment method was revoked. Depending on the reason, some information can be modified (Expiration Dates, Billing Addresses, Payment References). The unique identifiers cannot be modified so if the credit card number was incorrectly entered, the payment method is either removed or suspended and a new payment method must be added.

For more information about the user exits, see the Javadoc.

The changeOrder API is called to update the payment methods to the order and the confirmDraftOrder API is called to confirm the order.

When the user modifies the order by performing related tasks like adding order lines, modifying order quantity, or modifying the charges, the user is prompted to capture the payments appropriately. When the user modifies the order, there can be a decrease or increase in the order total. Therefore, the user is guided through the payment confirmation process to confirm the change in the payments and pay the applicable amount to fulfill the order.

Based on the change in the order total, the previous order total, the additional amount, or the amount that is reduced, and the adjusted total are displayed. When the order total increases, the remaining amount that the customer must pay to fulfill the order is returned in the RemainingAmountToAuth attribute of the capturePayment API. When the customer must pay the additional amount, the "Add Payment Method" button is displayed to allow the user to capture the additional amount. The user cannot confirm the order until sufficient funds are collected.

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.

Implementation

The following section describes the rules that you must configure.

The "Save against customer" check box in the Add Payment Method and Edit Payment Method window is permission-controlled. The check box is enabled only if the user belongs to a group that is assigned the necessary permissions. For information about administering user group permissions, see Sterling Business Center System Configuration.

For more information about APIs and user exits, see Javadoc.

End-user impact

The user can find out how much money must be paid to fulfill the order and inform the customer appropriately. The user can also add payment methods to the order, authorize, and confirm the order.