Pipelines

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

Order Overview Page

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:

PayOrderStep

SaveOrderStep

DeductStockStep

TrackPromotionCodeStep

DeleteBasketStep

SendOrderMailStep

RedirectToSuccessPageStep

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:

PreProcessPipeline

Pre-steps:

<none>

Steps:

SaveOrderStep

TrackPromotionCodeStep

Post-steps:

PSPRedirectStep

ConfirmPipeline

Pre-steps:

<none>

Steps:

<none>

Post-steps:

OrderPathSelectorStep

SaveOrderStep

PostProcessPipeline

Pre-steps:

<none>

Steps:

DeleteBasketStep

Post-steps:

<none>

CancelPipeline

Pre-steps:

<none>

Steps:

SaveOrderStep

UnTrackPromotionCodeStep

Post-steps:

<none>

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

Payment Confirm Page

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

Order Failed Page

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:

Product Versions

Links

Sana Commerce does not accept any liability for the content of this website, or for the consequences of any actions taken on the basis of the information provided. The information below should be interpreted as an example. No rights can be derived from this information.
Sana Commerce – the integrated e-Commerce solution for Microsoft Dynamics NAV & AX