Next-generation platform

Capturing payment

As a store associate, you can capture the payments for an order before confirming the order. You can select the payment methods and confirm the order by paying with single or multiple payment methods. This section describes the APIs, services, user exits, and other components that are used to implement payment capture.

Payment confirmation is the last stage of order capture. By default, Sterling Store Engagement supports payment methods such as cash, gift cards, and credit cards. Dummy user exit implementations are used to support authorization and settlement of payment against credit card and gift card payment methods. Additional payment types are supported in the Capture payment page through customization.

The following APIs are called from the Capture payment page:
  • The getCompleteOrderDetails API is called to retrieve the amount that the customer must pay to place the order and the payment methods that was used if any payment has already been done.
  • The getPaymentTypeList API is called to retrieve the payment methods that are allowed by your enterprise. From this list, you can select a payment method to add to the order.
    Note: Only the payment types that are supported through customization are displayed in this page.
  • The getRuleDetails API is called with RuleSetFieldName="ISF_STORE_ALLOW_ADDR_CAP_FOR_CC" to check if address capture is required while capturing the credit card information for payment.
  • The capturePayment API is called to add the payment methods to the order, depending upon the type of payment method information that is passed.
  • The processOrderPayments API is called to invoke the requestCollection() and executeCollection() APIs within a single API. This is called after every successful capturePayment API call.
  • The confirmDraftOrder API confirms completion of a draft order, and moves it to the Created status. This is called only after the first successful processOrderPayments API call.
  • The changeOrderStatus API is called in the end to change the status of the Carry order lines from Created to Carried.

Assumptions/Limitations

  • Once partial payment is done for an order, you cannot go back to the View cart page currently.
  • Draft order is confirmed as soon as you make a payment on the order. Carry order lines are moved to the Carried status once order amount is paid fully.

Adding payment methods to an order

The getPaymentTypeList API retrieves the payment methods that are allowed by your enterprise.

You can select a payment method by clicking the + icon adjacent to a payment method. The customer can use one or more payment methods to make the payment. After selecting a payment method, you can add the amount to be paid by using the selected payment method.

The capturePayment API saves the payment method to the order and deals with any external payment types. The processOrderPayment API is invoked immediately after the capturePayment API to handle the authorization and collection of the amount paid by using the selected payment method.

Once a partial payment is made for a draft order, the confirmDraftOrder API is invoked to confirm the order. However, order capture process is not complete until the full order amount is paid. An information banner message is displayed to inform about the balance amount to be collected for the order.

The customer can choose to pay by using multiple payment methods and distribute the charges across credit cards, cash, or gift cards. After making partial or full payment on the order, pending amount on the order is calculated. In case there is any pending amount to be collected on the order, an information banner is displayed to assist the store associate to collect the same.

When the total amount due on the order is paid, the changeOrderStatus API is invoked to change the status of carry order lines from CREATED to CARRIED status. This API is invoked only if order contains any carry lines. The changeOrderStatus API looks up the Status Inventory types configuration and adjust inventory supply accordingly for carry lines.

Additionally, commit listeners (OMPSIMChangeOrderStatusRestCommitListener) are registered with the changeOrderStatus API to publish inventory updates to Store Inventory Management service. The OMPSIMChangeOrderStatusRestCommitListener class is responsible for publishing inventory updates to Store Inventory Management by invoking the remove inventory API synchronously to Store Inventory Management.

The changeOrderStatus API reads the ShipNode from the carry order lines, if any, and checks if the node is Store Inventory Management (SIM) enabled. If yes, the OMPSIMChangeOrderStatusRestCommitListener is registered to publish the inventory updates to Store Inventory Management. Inventory adjustments to Store Inventory Management is done in real time. Any errors while adjusting the inventory on Store Inventory Management will result in failures in the order capture process.

The charge sequence that is configured in 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 customer wants to change 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.

After making a partial payment on the order, the customer might choose to cancel the order. In this case, as a store associate, you can cancel the order by choosing an appropriate cancellation reason. The changeOrder API is invoked to cancel the order and the processOrderPayments API is invoked to process the refund of the partial payment. You can view the refund summary after the successful cancellation of the order. The refund summary provides a list of payment methods that were used to pay for the order and also lists the payment method that is used for refund based on the refund configuration. If the refund is via cash, you have to hand over the amount specified in the refund summary as cash to the customer.

Cash

Store associates can add the amount that the customer wants to pay by using the cash payment method in the Amount field and confirm the payment. The capturePayment API is called with the input as shown in the following example:
{
   "Order":{
      "OrderHeaderKey":"order_id",
      "EnterpriseCode":"enterprise_code",
      "PaymentMethods":{
         "PaymentMethod":[
            {
               "PaymentType":"CASH",
               "PaymentTypeGroup":"OTHER",
               "RequestedAmount":"100.00",
               "PaymentReference1":"Cash for Charge",
               "Operation":"Collect"
            }
         ]
      }
   }
}
  • If the amount received is equal to the order total, the order is confirmed and the Order summary page opens.
  • If the amount received is less than the order total, the amount due is updated to display the balance amount. A warning message is displayed to show the amount due. You can now select a new payment method to pay the amount due.
  • You cannot enter an amount greater than the order total.
  • If amount received is to be charged and authorized, that is, if it is being used to pay for both carry and ship or pick up order lines, the payment is split into two objects and the following entry is added to the Payment method array:
    {               
"PaymentType":"CASH",               
"PaymentTypeGroup":"OTHER",               
"RequestedAmount":"100.00",               
"PaymentReference1":"Cash for Charge",               
"Operation":"Collect"            
}

Gift cards

As a store associate, you must verify the gift card balance by entering the gift card number. This uses the invokeUE API with YFSGetFundsAvailableUE user exit. Based on the response received, the following actions are made:
  • If the balance amount available in the gift card is greater then 0, the Amount field and Confirm button are enabled.
  • If the balance amount available in the gift card is equal to 0, an appropriate error message is shown.
  • If the balance amount available in the gift card is less than the amount due, an amount equal to the amount available in the gift card is auto-updated in the Amount field and you can confirm the payment.
  • An error message is shown if you enter an amount greater then the amount available in the gift card or amount due, whichever is lesser.
  • If the amount received is to be charged and authorized, that is, if it is being used to pay for both carry and ship or pick up order lines, the payment is split into two objects and the following entry is added to the Payment method array:
    {  
"Order":{  
"OrderHeaderKey":"order_id",      
"EnterpriseCode":"enterprise_code",      
"PaymentMethods":{         
"PaymentMethod":[            
{               
"PaymentType":"GIFT_CARD",               
"PaymentTypeGroup":"OTHER",              
 "RequestedAmount":"100.00",               
 "PaymentReference1": giftCardNumber + 'ForCharge',
 "PrimaryAccountNo": giftCardNumber,
 "Operation":"Collect"            
},
{               
"PaymentType":"GIFT_CARD",               
"PaymentTypeGroup":"OTHER",              
 "RequestedAmount":"100.00",               
 "PaymentReference1": giftCardNumber + 'ForAuth',
 "PrimaryAccountNo": giftCardNumber,
 "Operation":"Manage"            
}
 ]     
}   
}
}

Credit cards

As a store associate, you can select credit card as the payment method, add the amount to be paid, and click Confirm. A message is displayed prompting you to swipe the credit card. On clicking OK, the swiped card details are fetched and a request for confirming the payment method is created as shown in the following example:
{
        PaymentType: 'CREDIT_CARD',
 Operation: (this.orderDetails.RemainingFinancialTotals.RemainingToCharge > 0) ? 'Collect' : 'Manage'
        RequestedAmount: 100,
        CreditCardExpDate: '',
        CreditCardNo: '1234', (random 4 digits)
        CreditCardType: '',
        FirstName: '',
 MiddleName: '',
        LastName: '',
        SecureAuthenticationCode: '',
        PaymentReference1: '',
        PaymentReference2: '',
        PaymentReference3: '',
 PaymentReference4: '',
 PaymentReference5: '',
 PaymentReference6: '',
 PaymentReference7: '',
 PaymentReference8: '',
 PaymentReference9: '',
 DisplayPaymentReference1: ''
 };
  • If the amount received is to be charged and authorized, that is, if it is being used to pay for both carry and ship or pick up lines, RequestedAmount = charged amount and SecondaryAmount = (RequestedAmount - RemainingToCharge) are added.
  • The credit-card-data.service.ts service is added to the credit-card component. This service is used to pass the credit card details to the main credit card component. By default, dummy data is being passed from that service. However, this can be extended to return data from an API and the returned data is added to the PaymentMethod object.
If the WSC_STORE_ALLOW_ADDR_CAP_FOR_CC rule is set to true, address capture is mandatory for credit card payments.
  • If a billing address (PersonInfoBillTo) is available in the order, the billing address is used.
  • If the customer is identified and the billing address is set as the default (isDefaultBillTo=true), then this address is used as the billing address. That is, if the order contains PersonInfoBillTo, then this information is used.
  • If a shipping address (PersonInfoShipTo) is available for the order, this address is used as the billing address if billToSameAsShipTo is selected.

    If billToSameAsShipTo is not selected, an option to add a billing address is displayed and a new billing address is captured for the payment method.

Payment processing

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, you are 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 set to Y and the order is confirmed.

If any of the payment methods are unsuccessful, the value of PaymentTransactionSuccessful attribute is set to N. An appropriate message is displayed to indicate that the payment is not processed successfully. The message that is returned in the PaymentTransactionError element is displayed to indicate why the payment method is revoked. Depending on the reason, the relevant information can be modified, for example, the date of expiry of the card, billing address, or payment references.

The unique identifiers cannot be modified. For example, if the credit card number is incorrectly entered, the payment method is either removed or suspended and a new payment method must be added.

The executeCollection API calls one of the following user exits for each payment method on the order that is based on the PaymentTypeGroup attribute of the payment method.
  • YFSCollectionCreditCardUE
  • YFSCollectionCustomerAccountUE
  • YFSCollectionOthersUE
  • YFSCollectionStoredValueCardUE
These user exits provide the option of adding custom logic for authorizing and charging payments. For more information about the user exits, see the IBM® Sterling Order Management System: Javadoc.

Payment error handling

When the payments is confirmed for the first time for 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 the 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, you are 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 Capture payment page 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 in the order. However, when you fix the erroneous payment methods and apply the changes, the processOrderPayments API is called to validate the payments.

Capturing and processing payments in different scenarios

Order with Carry order lines only

In Carry orders, the customers order items in a store and leave the store with the items. In such cases, there is an immediate settlement on the order lines. The amount payable for the Carry order lines is charged at the time of purchase. The customers can use the available payment methods to complete the payment for the Carry order lines.

  • The order total must be settled, collected, or charged to confirm the order.
    • RemainingFinancialTotals.RemainingToCharge attribute is used for the amount to be charged.
    • Operation=Collect is passed while capturing the payment irrespective of the payment method used.
    • Payment capture is marked as failed in case of any payment errors.
  • The Carry order line amount can be split across multiple payment methods and each payment method is charged.
  • Order line charges, discounts, and taxes are automatically adjusted to the line sub total. Carry order line total is a part of InPerson=Y bucket of RemainingFinancialTotals and the amount is populated in RemainingToCharge attribute.
  • Order header charges applied on the order is taken as part of the InPerson=N bucket of RemainingFinancialTotals and the amount is populated in the RemainingToAuthorize attribute. This amount is also charged on the selected payment method in case of order with carry lines only.
Order with mixed order lines
  • In case of mixed lines, the Carry line amount is charged, collected, or settled at the time of the purchase for the selected payment method by passing the operation as Collect.
  • For rest of the order lines, namely Pick and Ship, the corresponding amount as provided by RemainingFinancialTotals.RemainingToAuthroize attribute is used for authorization by passing the operation as Manage.
  • Depending on the payment type configuration, this amount can be charged or used for authorization purposes. The capturePayment API and processOrderPayments API are invoked to process the payment based on the payment type configuration.
  • Order line charges, discounts, and taxes are automatically adjusted to the order line sub total. For Pick and Ship order lines, the line total is a part of the InPerson=N bucket of RemainingFinancialTotals and the amount is populated in the RemainingToAuthrorize attribute.
  • The order header charges applied ti the order are a part of the InPerson=N bucket of RemainingFinancialTotals and the amount is populated in the RemainingToAuthorize attribute.
Order cancellation after partial payment
  • After making a partial payment on the order, the customer might choose to cancel the order.
  • On closing the Payment capture page, a message is displayed. The customer has the option to either continue to complete the payment or cancel the order.
  • If the cancellation option is selected, the CommonCodeList API is used with CodeType="YCD_CANCEL_REASON" to fetch the cancellation reasons.
  • After choosing an option, the changeOrder API is used to cancel the order and the processOrderPayments API is called to process the refunds and show the refund summary.
  • The store associate can hand over the refund in cash to the customer.
Complete order capture for an abandoned order with partial payment
An order is considered to be abandoned if a partial payment is made for an order and then exited the order capture flow by closing the browser or due to various reasons such as a system failure. Because partial payment is made, the order is already confirmed. However, some payment is still pending.

In such cases, you can either search for this order from the Find order portlet by using the order number or other search criteria. Alternatively, if the customer is identified for the order, you can look into the order history from the Customer profile page. Clicking the relevant order opens the Order summary page. Here, a notification banner is displayed to complete the payment. The Payment capture is opened and you can assist the customer to pay the remaining amount and complete the order capture process.