Payment Methods and PSP Gateway

Requested page is not in the provider filter.

An important part of the payment architecture is the payment pipeline system.  The pipelines provide an extensible model when creating payment modules. A pipeline can be defined as a number of steps that can be executed in any order.

 

A step contains a small piece of logic to execute in the payment pipeline. Examples include: Deleting of a basket, changing order status. Steps can be added to any position in the pipeline, they should not depend on any other steps. This way the pipelines can easily be updated by adding/deleting and even moving steps.

 

This is a responsibility of a payment module to create and manage pipelines. An internal payment module will in most cases contain a single pipeline that will execute a number of defined steps, while an external payment module will contain multiple pipelines that will be executed at different times, over multiple pages.

 

Class Diagram of ZeroPaymentModule and ExternalPaymentModule

 

The ZeroPaymentModule, which is an internal module, executes a single pipeline which is created and immediately executed in the OnPay method. The ExternalPayment module creates and handles multiple pipelines.

For an overview of pipelines that are executed in an external payment module see the image below:

 

 

Payment Flow for an External Payment Module 

 

The user will start the payment from the 'Order Overview' page. At the moment the user starts the payment the pre-process pipeline will be executed. It will check if the payment module overrides the default pre-process pipeline. If so, the custom pipeline will be used if not it will take the default pipeline. This concept is the same for all pipelines. The pre-process pipeline will gather all information needed to start the payment and will redirect the user to the PSP website. The user can continue his/her payment at the site of the PSP.

 

The 'Order Overview' Page Flow Diagram

On the diagram above you can see that the sequence starts on the 'Order Overview' page.  After the user has clicked the 'Pay' button, the IPaymentModule.Pay method calls an appropriate pipeline, depending on the implementation.

For example, on the image below a ZeroOrderPaymentModule sequence diagram is shown. This is an internal module and it is invoked when the order total amount is zero.

 

ZeroOrderPaymentModule Sequence Diagram

 

On the diagram above the payment pipeline instance is created and immediately executed. In this case the pipeline contains only the following steps:

In case if any custom step should be added to this pipeline, the CreatePipeline method can be overridden in a custom class.

 

See the chapter 'Pipeline Steps' for the detailed description of all steps which are available in the Sana Commerce solution.

 

In case an external Payment Service Provider (PSP) is configured (e.g. DocData or Authorize.Net), the appropriate ExternalPaymentModule implementation will be invoked. Below is the sequence diagram for the ExternalPaymentModule:

 

ExternalPaymentModule Sequence Diagram

 

If a custom external PSP should be implemented for the Sana Commerce solution, the ExternalPaymentModule class can be inherited by a custom class and appropriate methods can be overridden to build the needed pipelines. The existing pipelines in ExternalPaymentModule contain the following steps:

Thus each pipeline can have three collections of steps: pre-steps, steps and post-steps. Each collection is executed immediately one by one in this exact order during the Execute method call.

Order Submit Page 

If the user finishes a payment successfully he/she is redirected to the 'ordersubmit.aspx' page. This page will give a feedback about the payment. At this page the Post-process pipeline will be executed. While this pipeline will contain no steps by default, in some cases it is useful to add steps here. But keep in mind that it is not recommended to add any important logic here because it is uncertain if the user will reach to this page. It is not unthinkable for the user to close his/her browser at the PSP page before reaching this page. Be sure never to update any order status here unless really required by the PSP. This location is more susceptible to fraud and/or misuse because it can easily be requested by anyone. For more information check the payment flows.

 

The 'Order Submit' Page Flow Diagram

 

For most PSP implementations, the 'PaymentConfirm.aspx' page will not be called by the user's browser but by the PSP engine itself. This page is used to provide status updates to an order. The page will directly call the Confirm pipeline. All logic for handling order statuses, but also things like deleting baskets and sending order mails will be handled in this pipeline. Since the steps to execute depend on the status supplied by the PSP, the pipeline will contain child pipelines to execute for each payment status. For example the pipeline executed for the status 'cancelled' will be different that the pipeline for 'paid'. Important to note is that this call can be executed multiple times, for different statuses and at any time in the payment process (it can extend over multiple days). For more information check the payment flows.

 

The 'Payment Confirm' Page Flow Diagram

 

The last pipeline is the Cancel pipeline. This pipeline will be executed on the 'OrderFailed.aspx' page. Like the post-process pipeline this pipeline will contain no steps by default and the same discretions apply. The PSP should be configured to redirect to the 'Orderfailure.aspx' page whenever a user cancels a payment or the payment will fail for some reason.

 

The 'Order Failed' Page Flow Diagram

 

To summarize:

 

	Pre-process pipeline	Gathers all information needed to start the payment and redirects the user to the PSP payment page.
	Post-process pipeline	Is called whenever the user will see the payment successful page/message after a successful payment.
	Confirm pipeline	Is called indirectly by the PSP engine to update the status of an order. Will contain most business rules related to a payment.
	Cancel pipeline	Is called whenever a payment fails or is cancelled.

 

The Confirm pipeline also calls one of the following custom child pipelines based on the payment status:

 

	StatusOkPipeline	Executed if the status of the order is 'paid'.
	StatusCancelPipeline	Executed if the status of the order is 'cancelled'.
	StatusPendingPipeline	Executed if the status of the order is 'in progress'.