Commerce

8.0.x

Payments

B2B and B2C store owners want to be able to offer customers a variety of payment options. For example, some customers prefer to use a credit card through a traditional payment provider, while other customers might prefer to use a digital wallet through a mobile payment provider. B2B customers might prefer to use purchase orders and offline payments. With Elastic Path Commerce, you can implement the payment options you need by using the Payments framework and payment plug-ins.

You can offer the following types of payment options:

  • Online payment providers, such as Authorize.net, WorldPay, or Stripe
  • Online or offline payments and methods, such as purchase orders
  • Digital wallet and online payment providers, such as Apple Pay, Google Pay, or AliPay

The following diagram shows the Payments framework for supporting custom payment plug-ins:

Payments Framework

The Payments framework consists of the following items:

  • Order Payment API: Evaluates the order state and delegates the payment specific capabilities to the Payment API. For example, when an order is submitted, the Payment API calls the Reserve to reserve the order amount on the attached payment instrument.

  • Payment API: Calculations and core payment logic are done by the Payment API. After the calculations are complete, the Payment API delegates further capabilities to the payment plug-in for the selected payment instrument.

  • Payment plug-in: Performs actions (also known as capabilities) such as Reserve, Charge, and Credit. Back-end developers create and implement payment plug-ins specific to a payment provider and method by using the interfaces provided by the Payments framework.

After you create a payment plug-in, you can configure it and associate it with one or more stores. For example, if you are using AliPay, you can associate AliPay with all of your stores in China. Front-end developers, using the REST APIs, make the payment options available to shoppers.

Payment Plug-in Implementation

The Payments framework provides interfaces for the following capabilities that are required to process a payment:

  • Reserve
  • Modify Reservation
  • Cancel Reservation
  • Charge
  • Reverse Charge
  • Credit / Refund

The mechanism for implementing the capabilities is through the capaibility-based plug-in model. To implement a payment plug-in and the following PaymentProviderPlugin capabilities, create a class that extends AbstractPaymentProviderPlugin:

  • ReserveCapability

    Provides the ability to perform a reservation operation for a payment instrument. A reservation is also referred to as an authorization, pre-authorization, or a hold.

  • ModifyCapability

    Provides the ability to modify the amount of a reservation.

  • CancelCapability

    Provides the ability to cancel a reservation.

  • ChargeCapability

    Provides the ability to reserve funds on the payment instrument to cover the cost of an order. A reservation is also known as an authorization, pre-authorization, or a hold.

  • ModifyCapability

    Modifies the amount of a reservation.

  • ReverseChargeCapability

    Returns a reverse charge response from the payment provider.

  • CreditCapability

    Provides an interface for the credit capability.

  • PICClientInteractionRequestCapability

    Returns an object that encapsulates payment instructions request fields. Use the values of the request fields as parameters when you request a payment instrument from a payment provider. For more information, see the Payment Instrument Creation (PIC) Workflow section.

Workflows

The following sections detail the end-to-end process for processing payments.

Payment Instrument Creation (PIC)

A payment method is the type of payment that you can use, such as a type of credit card. To use a payment method, a payment instrument is also required. A payment instrument is a token that represents the customer’s account number, such as their credit card number. A payment instrument is used during the Payment Instrument Creation (PIC).

In the Payments framework, payment instruments are sent to the payment provider. The payment provider processes the payment.

The following diagram illustrates the workflow for creating a payment instrument:

Workflow for Payment Instrument Creation

PIC workflow

  1. User requests the payment options and starts the payment instrument creation process.

  2. Store returns the supported payment methods to the user.

  3. User selects the payment method.

  4. Cortex requests the PIC Instructions from the payment provider plug-in in the following sequence:

    1. Cortex requests the payment instrument creation instruction fields.

    2. Payment plug-in returns the creation fields for the payment instrument.

    3. Cortex fills the PIC creation fields and requests the PIC instructions.

    4. Payment provider plug-in returns the PIC instructions.

  5. Store redirects to the payment provider using this information and creates a token from the user provided information.

  6. Cortex creates a payment instrument in the following sequence:

    1. Cortex requests the PIC form from the payment plug-in.

    2. Payment plug-in returns the PIC form.

    3. Cortex populates the form with the information from Step 5 and submits to the payment provider plug-in.

    4. The payment instrument is created and persisted to the database.

  7. Cortex receives the payment information and the user receives a usable payment instrument.

note

The cart must have at least one payment instrument and a cart total greater than zero. With this information present, if there is an error, PaymentInstrumentCreationFailedException is thrown.

Reserve

A Reserve capability is an authorization for funds. Elastic Path Commerce uses the shopper’s selected payment instrument and calls the associated payment plug-in to request the reservation of funds.

During the reservation call, the CartContext request can pass the following data to the plug-in:

  • SKU code
  • Product code
  • Product display name
  • Product attributes
  • SKU attributes
  • Quantity
  • Unit price
  • Tax amount
  • Subtotal

Reserve workflow

The following diagram illustrates the Reserve capability workflow:

Reserve Workflow

  1. Shopper selects the payment instrument.

  2. Commerce Engine creates CartOrderPaymentInstrument from the PaymentInstrument.

  3. Shopper submits order for processing. Elastic Path Commerce converts CartOrderPaymentInstrument to OrderPaymentInstrument.

  4. Elastic Path Commerce calls the associated payment plug-in to reserve the funds.

  5. Payment plug-in sends the status of the order. The status is based on the type of confirmation:

    • If the provider confirms the reservation, Elastic Path Commerce persists the confirmation as an OrderPayments object and the order is in the In Progress state.
    • If the provider does not confirm the reservation, Elastic Path Commerce records the transaction as failed in the database and the order is in the Failed state.

Modify Reservation

The modifyReservation capability is called as items are added or removed from an order by a Customer Service Representative (CSR). The CSR carries out these order amendments in Commerce Manager, before the shipment is complete.

If a CSR modifies an order by adding a physical item on pre-order or the item is on back order, the item is reserved for the full amount when the shopper makes the purchase. When the item is available, the shipment becomes shippable and the order is charged the full amount. For more information about modifying an order in Commerce Manager, see Customers in Elastic Path Commerce.

The following diagram illustrates the Modify Reservation workflow:

Modify Reservation workflow

Modify Reservation workflow

  1. Shopper calls CSR to modify the order.

  2. CSR modifies the unshipped shipment. Commerce Manager calls OrderPaymentAPI.

  3. OrderPaymentAPI calculates the new required amount and calls PaymentAPI to request the modification.

Scenario 1: modifyReservation capability is implemented

  • If the payment plug-in has the Elastic Path payments Modify capability implemented, Commerce Engine calls the modifyReservation capability. modifyReservation increases or decreases the amount of the reservation as required. (4a.)

  • If modifyReservation is successful, the Payment API allows the order modification in Commerce Manager. If the modifyReservation fails, Payment API does not allow the order modification and the order is left unchanged. (4b.)

Scenario 2: modifyReservation capability is not implemented

When a payment provider does not support reservation modification, the Payment API simulates the modifications of reservations. The Payment API cancels the existing reservation and creates a new reservation with the new amount. The payment plug-in performs one of the following actions:

  • Scenario 2a: Increase If the modification request is to increase the reservation.

    • The Payment API attempts to make the new reservation with the new amount (4a).

    • If successful, the Payment API goes ahead and cancels the original reservation and allows the order modification (4b).

    • If not successful, Payment API does not cancel the original reservation and does not allow the order modification (4c).

  • Scenario 2b: Decrease If the modification request is to decrease the reservation:

    • The Payment API attempts to make the new reservation (4a).

    • If successful, the Payment API cancels the original reservation and the order is modified (4b).

    • If not successful, the Payment API does not cancel the original reservation, but the order is still modified (4c).

    Note: If the reservation is of the higher amount, the charge is for the reduced order amount.

Cancel Reservation

The cancelReservation resource provides the capability to cancel a reservation on a payment instrument.

The following diagram illustrates the Cancel Reservation workflow:

Cancel Reservation workflow

Cancel Reservation workflow

  1. Shopper calls a CSR to cancel the order.

  2. CSR cancels the unshipped shipment. Commerce Manager calls OrderPaymentAPI to cancel the shipment.

  3. OrderPaymentAPI requests the cancellation of reservation.

  4. PaymentAPI calls the cancelReservation capability.

  5. Payment plug-in performs one of the following actions:

    • If the cancel reservation is successful, Commerce Engine records the successful cancel reservation transaction and cancels the shipment.

    • If the cancel reservation is not successful, Commerce Engine records the cancel reservation transaction failure and cancels the shipment.

    note

    If the cancellation is either the only shipment or the last shipment to be canceled, the order is completely canceled. If the order is divided into more than one shipment, and the cancellation is for the last shippable item in the order, the order is completely canceled.

Charge

Before a shipment is released to the shopper, the shipment amount is charged to the payment instrument.

The following diagram illustrates the Charge workflow:

Reserve Workflow

Charge workflow

  1. CSR releases the shipment. Commerce Manager calls OrderPaymentAPI to charge the shipment.

  2. OrderPaymentAPI requests to charge the reservation with the shipment total.

  3. PaymentAPI calls the payment plug-in to charge the amount.

  4. Payment plug-in sends one of the following confirmations:

    • If the provider confirms the charge, the shipment is marked as completed, and Elastic Path Commerce persists the confirmation as an orderPayments object
    • If the provider does not confirm the charge, Elastic Path Commerce records the transaction as failed.

    Note: If the requested shipment is not the last shippable shipment in the order, Payment API requests a new reservation for the leftover amount.

Credit

A CSR can use the credit capability to return an amount of an order to a shopper. By using Commerce Manager, a CSR can refund the whole or a partial amount of the order. For more information about refunds, see Creating a Refund.

The following diagram illustrates the Credit workflow:

Refund Workflow

Credit workflow

  1. Shopper calls a CSR to request a refund.

  2. CSR credits the order. Commerce Manager calls OrderPaymentAPI to credit the order.

  3. PaymentAPI calls the payment plug-in to credit the amount and PaymentInstrumentis credited the refund amount.

  4. Credit transaction is recorded as orderPayment with the credit amount.

note

If the shopper attempts to create a credit with the amount larger than the charged amount, the credit is declined.

Additional Data Available to Plug-in

The following orderContext is available to all of the Capabilities:

  • MoneyDTO orderTotal

  • String orderNumber

  • String customerEmail

  • AddressDTO billingAddress

  • Order SKU code

     String displayName;
 int quantity;
 BigDecimal price;
 BigDecimal taxAmount;
 BigDecimal total;
 String skuCode;

Using Payment Instruments

After you create a payment instrument, it can be used for multiple pre-authorization requests to avoid passing sensitive cardholder data.

A registered shopper can select a default payment instrument and save it to their profile. When a default payment instrument exists, Cortex uses the default-on-profile payment instrument as the selected payment method. If a shopper adds another payment instrument as the default, the new payment instrument replaces the previous default payment method.

You can also create a single-use token to use once for a reservation. Regardless of the number of shipments or modifications to the order, the Payments framework ensures that the single-use token only processes a single reservation and capture for the order. For more information about single-use, see Additional Plug-in Behaviors.

Glossary

Payment plug-in: The component that implements payment provider Capabilities, such as Charge or Credit capabilities, potentially interacting with a third-party payment processor.

Payment configuration data: The specific configuration data for a payment plug-in.

Payment method: The method that you use to make the payment, such as credit card.

Payment instrument: A representation of a payment method, such as a token for a specific credit card (the method).

Token: A string representing the value of certain cardholder data, such as encrypted credit card information. Passing the token is more secure than passing the information it represents.

Saveable payment instrument: A reusable payment instrument that can be saved on a shopper’s profile.

Profile payment instrument: A saveable payment instrument that is saved to a shopper’s profile.

Default payment instrument: A payment instrument that is selected as the default payment instrument for all orders.

Payment Database Tables

The following tables are the database tables processed through PaymentAPI.

TPaymentInstrument

Represents the payment instrument in each table row.

Unique Identifier Primary Key int pk

GUID varchar

Name varchar

PAYMENT_CONFIGURATION_UID int

TPaymentInstrumentData

Represents additional data associated with the payment instrument as key value pairs.

Unique Identifier Primary Key int pk

GUID varchar

Key varchar

Value varchar

TPaymentProviderConfig

Represents an association to the payment provider configuration by GUID and name.

Unique Identifier Primary Key int

GUID varchar

PAYMENT_PROVIDER_UID int

Name varchar

TPaymentProviderConfigData

Represents additional data associated with the payment provider configuration.

Unique Identifier Primary Key int pk

PAYMENT_PROVIDER_CONFIG_UID int

CONFIG_KEY varchar

CONFIG_DATA varchar

TCustomerPaymentInstrument

Represents the payment instrument saved in profile for a customer.

Unique Identifier Primary Key BIGINT

PAYMENT_INSTRUMENT_GUID VARCHAR(64)

CUSTOMER_UID int

GUID VARCHAR(255)

TCustomerDefaultPaymentInstrument

Represents the default profile payment instrument for a customer.

Unique Identifier Primary Key BIGINT

CUSTOMER_UID BIGINT

CUSTOMER_PAYMENT_INSTRUMENT_UID int

TCartOrderPaymentInstrument

Represents the relationship between the selected payment instrument and the cart order.

Unique Identifier Primary Key BIGINT

PAYMENT_INSTRUMENT_GUID VARCHAR(64)

CART_ORDER_UID BIGINT

Limit DECIMAL(19,2)

GUID VARCHAR(255)

TOrderPaymentInstrument

Represents a payment instrument used for an order.

Unique Identifier Primary Key BIGINT

PAYMENT_INSTRUMENT_GUID VARCHAR(64)

ORDER_NUMBER VARCHAR(64)

LIMIT_AMOUNT DECIMAL(19,2)

GUID VARCHAR(255)

CURRENCY_CODE VARCHAR(64)

TOrderPayments

Represents a payment transaction on a payment instrument.

Unique Identifier Primary Key BIGINT

CREATED_DATE TIMESTAMP

Type VARCHAR(64)

Status VARCHAR(64)

ORDER_NUMBER VARCHAR(64)

Amount DECIMAL(19,2)

CURRENCY_CODE VARCHAR(64)

PAYMENT_INSTRUMENT_GUID VARCHAR(64)

GUID VARCHAR(255)

PARENT_ORDER_PAYMENT_GUID VARCHAR(255)

IS_ORIGINAL_PI BIT(1)

TPaymentLocalizedProperties

Represents a localized name for a payment provider configuration.

Unique Identifier Primary Key BIGINT

OBJECT_UID BIGINT

LOCALIZED_PROPERTY_KEY VARCHAR(255)

Value VARCHAR(255)

Type VARCHAR(31)

TStorePaymentProviderConfig

Represents the relationship between the store and the payment provider configuration.

Unique Identifier Primary Key BIGINT

PAYMENT_PROVIDER_CONFIG_GUID VARCHAR(64)

STORECODE VARCHAR(64)

GUID VARCHAR(255)

Last updated on 6/1/2024
← Shipping CalculationPayment Plugins →