|
|
Users Guide | Patterns Reference | WebsydianExpress | Search |
|
|
Users Guide | Patterns Reference | WebsydianExpress | Search |
Introduction Implementing Other Uses Parts
The PaymentWebShop pattern is an extension of the WebShop pattern where facilities for communication with a Payment Gateway has been added. This enables the Ordering.Submit Payment function to actually submit a payment request with credit card data to a payment gateway and the WebShop application to receive the response.
A Payment Gateway is a third-party server that provides services to clear credit card information, i.e. to authenticate the credit card information and to reserve the amount requested, services to capture the amount, i.e. to request that the amount is transferred to the bank account of the shop, and other services.
A web-based shop application does not directly send events as HTTP requests to a payment gateway. Instead the web documents of the shop include an external URL referring to the payment gateway, e.g. through the ACTION parameter of an HTML FORM for a "Submit Payment Ok" button.
When the web user selects "Submit Payment", the event together with credit card data and amount is send to the payment gateway referred to by the external URL. The payment gateway then verifies the credit card, and, depending on the success of this, requests that the shop application either generates an Ok page or an Error page. This result page is relayed back to the web user as a HTTP response.
This is illustrated in the event trace diagram below:
Successful Submit Payment Event Trace Diagram
If the credit card verification fails, a LoadErrorPage event will be sent instead, and the WebShop application should then instead generate a Payment Error document.
The shop application does not receive the credit card data at all; these fields are only available to the payment gateway. A payment gateway typically operates under SSL security.
This sligthly complicated event and page exchange scheme make it possible to make online payment without the need for the web user to change to another site, or experience that the control is changed to another site. It is complete transparent to the web user that the point of control is changed forth and back between the webshop application and the payment gateway.
The PaymentWebShop uses the Websydian ExternalServerControl pattern for control of event exchanges with a payment gateway. A few terms need to be defined, corresponding to abstract functions of this pattern.
In the above illustration Submit Payment. Ok is a SendToExternalServer event, LoadOkPage is a ReceiveFromExternalServer event and Submit Payment is a PageGeneratorWithExternalEvent function.
The events exchanges with the payment gateway and the parameters associated with the events together constitutes a payment gateway protocol. The various third-party payment gateways all have different protocols for their events and required and optional parameters.
Some payment gateway protocols require that the web document for
payment submission containing the blank credit card fields must be relayed
through the payment gateway. If the payment gateway operates as a secure
site under SSL control this approach will ensure that the web user sees a
padlock-symbol in
the browser when the Submit Payment document is displayed
(assuming frames are not used):
Other payment gateway protocols only require that the clearing event (the Submit Payment.Ok event) is handled by the payment gateway.
Since various payment gateways protocols are different, the Websydian PaymentWebShop has been developed with some minimum assumptions of the protocols and with support for the widest array of payment gateway protocols.
The Websydian PaymentWebShop pattern is made using the following assumptions:
The exact name, length and other attributes of the fields are determined by the field implementation, and is configured during the implementation of the PaymentWebShop application.
These are the basic assumptions, and a PaymentWebShop application can easily be modified to include other payment gateway events and other payment gateway fields. This is described in detail in the PaymentWebShop Other Uses section
Normally all URL's within a Websydian application refers to the Websydian Event Dispatcher:
|
<FORM ACTION="/WSYSHOP/WDISPAT.EXE" NAME="AAmhF" METHOD="POST"> |
Events that should refer to a external payment gateway URL need to have this URL dynamically substituted instead of using a static URL. This is obtained by using a replacement marker for the FORM ACTION attribute:
|
<FORM ACTION="/(CLEARURL)" NAME="AAmhF" METHOD="POST"> |
This replacement marker for External URL will appear in the generated Document Template for the Ordering.Submit Payment Document, and at run-time it will be substituted by the value of the field PaymentClearingURL of the Shop entity.
The Submit Payment.OK event initiates the credit card clearing process at the payment gateway. When the payment gateway has performed the clearing process and the credit card has been successfully or non-successfully validated, it request a result page from the WebShop application by sending the LoadOkPage or the LoadErrorPage event.
It is obvious from this that the payment gateway somehow should know the result return addresses. Various approaches to this exists, depending on the payment gateway.
Some payment gateway store the LoadOkPage and LoadErrorPage return addresses in a database when the payment shop is configured, and use the ApplicationID for look-up.
Others require the LoadOkPage and LoadErrorPage return addresses send as parameters to the Submit Payment.OK event. Refer to the specific protocol documentation for your payment gateway to find out what applies.
In a Websydian application secured with hidden field integrity checking by digital signatures, signing of hidden fields are based on that the digital signature is transferred from web user to the web application in a special hidden field WSYBASE/Signature with implementation name "WSYD_SIGN".
For a specific payment gateway protocol, the gateway events may not include a parameter that can hold the digital signature. Therefore the generated digital signatures for External Events are stored in the Session table in the field LastExternalSignature when a SendToExternalServer event is sent, and the signature of the fields of the first incoming ReceiveFromExternalServer event is compared to this stored value.
In order to prompt that the digital signature is calculated and stored in the Session table by a PageGeneratorWithExternalEvent function, the "/(WSYD_SIGN)/(implname)" replacement marker for the SendToExternalServer event must be included in the HTML Document Template. Where it is placed is not important.
The /(implname) must hold the implementation name of the external event that is sent to the payment gateway. It is recommended that you place within an HTML comment.
Example for the Submit Payment.Ok event FORM:
|
<FORM ACTION="/(CLEARURL)" NAME="AAmhF" METHOD="POST"> |
In the Submit Payment.Ok event FORM the three hidden fields will be signed, and the digital signature will be stored in the Session table.
When a response comes from the Payment Gateway through either LoadOkPage or LoadErrorPage events, the same fields will be signed again, and the signature compared with the signature stored in Session.LastExternalSignature.
Online documentation - Websydian v6.0