Legacy platform

Capture payment

The store associate must be able to capture payments that are made by a customer for an order by using a mobile or desktop device.

When the store associate clicks Continue to Payment, the following logic is executed:
  • The getCompleteOrderDetails API is called to retrieve the order information for the Capture Payment screen. The Capture Payment screen is displayed and the store associate can select the payment type and enter the necessary information. If the customer is already associated with a billing address, then the address is automatically populated. Similarly, if the customer is associated with a default payment method, then the payment method is automatically defaulted for the order and is displayed on the screen.
  • 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.
  • If the payment method is credit card, the store associate must choose a credit card type, such as MasterCard or Visa. When the store associate selects a credit card as the payment type, the getPaymentCardTypeList API is called to populate the credit card type list.

    The store associate can enter the appropriate values into the fields. Once all required fields are populated, the store associate is ready to complete the payment. The store associate clicks Pay, the capturePayment API saves all payment method details to the order, deals with any external payment types, suspends a payment method that is no longer used by the customer, and returns the sequence of payment methods, in the order they are charged. If real-time authorization is on, the processOrderPayment API is called internally to process, authorize, and charge payments. After the payments are successful and there is no remaining balance on the order, the confirmDraftOrder API is called to confirm the order. After each API call is successful, the user will see a confirmation message with payment details. If any API call fails, an appropriate error message is displayed with the payment failure details.

    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 a Store Value Card (SVC) or gift card. This process prevents the store associate from defining the amount to be charged on each gift card. However, the store associate can choose to pay by using multiple payment methods and distribute the charges across credit cards, store value cards, and so on.

    The capturePayment API considers the fundsAvailable, RemainingAmountToAuth, and other attributes 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 when the store associate clicks Pay. The capturePayment API is called to consider the correction and update the MaxChargeLimits and the RemainingAmountToAuth attributes accordingly.

    If ChargeUpToAvailable = Y, the YFSGetFundsAvailableUE is called to get the funds. But if ChargeUpToAvailable = N, then the customer account payment methods defined for the customer (through other channels) are considered for capturing payments.

    The ChargeTransactionDetails element in the output identifies if there are any errors with the payment. If there is an error, the appropriate message is displayed.

Credit card, store value card, and other payments

The following logic is executed to capture payment by using credit card:

  • Based on the Payment Card Type configuration in the Sterling Business Center, the getCardTypeList API or getCommonCodeList API is called to retrieve the valid card types.
  • The expiration month and year are concatenated together to form the credit card expiration date.

    To setup 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 Sterling Business Center. The application displays asterisks in place of the characters in the credit card name and expiration date fields. For more information about payment encryption, see Encrypting payment method details.

  • The application verifies whether real-time authorization is enabled.
    • If the real-time authorization is enabled, the store associate is allowed to capture the CVV number of the credit card. This number is a secure credit card verification value. As it is confidential, the number is not recorded within any logs and is never saved against the payment method on the order. The CVV number is stored in the local screen memory. When the store associate confirms the payments for the order, the processOrderPayments API is called to process, authorize, and collect the payment that is entered by the store associate. The SecureAuthenticationCode attribute is passed as input to the API to capture the CVV code for each added credit card.
  • Similarly, the store associate can add new payment methods that are allowed by the organization to capture payments for the order. For example, Store Value Card (SVC). SVC (Store Value Cards or Gift Cards) payment types must be created with the Charge Instead of Authorize option enabled, so when the gift card is authorized, the funds available is immediately reduced to accurately display the new remaining balance to the store associate.

For all payment types, the following validations occur:

  • The ChargeTransactionDetails element that is returned in the output of the processOrderPayment API contains the details of any errors that occur in the payment process. If errors occur, an appropriate message is displayed with the details of the payment failure. The store associate can click OK to return to the Capture Payment screen and correct the errors.
  • If real-time authorization is disabled, any form of payment is collected and the order is confirmed. The payment agents execute and authorize the payment method before processing the order. The agents in turn call the procesOrderPayments API to authorize the payment, but payment collection occurs when the executeCollection API is called.
  • 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. These user exits provide the option of plugging in custom logic for authorizing and charging payments.
    • YFSCollectionCreditCardUE
    • YFSCollectionCustomerAccountUE
    • YFSCollectionOthersUE
    • YFSCollectionStoredValueCardUE
Note: The Charge Sequence configured for payment types is not considered while processing payments.

For information on payment related configuration, see the Implementation section.