Maldives Payment Gateway Developer's Guide

Version 1.0

Table of Contents
1 Introduction..............................................................................................................................................3 1.1 Purpose of the Developer's Guide.....................................................................................................3 1.2 MPG Basics and Requirements..........................................................................................................3 1.2.1 What is MPG?............................................................................................................................3 1.2.2 What is Credit Card Processing?................................................................................................4 1.2.3 What is the 3D Secure protocol?...............................................................................................4 1.2.3 Processing your First Test Transaction.......................................................................................7 1.2.4 Sample Checkout Page.............................................................................................................8 1.2.5 Mandatory Fields.......................................................................................................................9 1.2.6 Processing Method..................................................................................................................10 1.2 Data Integrity and Security using a Hash Signature........................................................................11 1.2.1 Response Page........................................................................................................................13 1.2.2 Conclusion..............................................................................................................................14

Introduction Purpose of the Developer's Guide MPG Basics and Requirements What is MPG? What is Credit Card Processing? What is the 3D Secure protocol? Processing your First Test Transaction Sample Checkout Page Mandatory Fields Checkout Method Data Integrity and Security using a Hash Signature Response Page Conclusion Getting Started The Merchant Menu What's next? Merchant Account Processing Methods MPG Integration Methods Virtual POS Appendix A Transaction Fields Form Fields Appendix B Response Codes System Response Codes Data Sent with Response Codes System Response Reason Codes Appendix C AVS Result Codes

Maldives Payment Gateway Developer's Guide

All Rights Reserved Bank of Maldives PLC - 2008

1 Introduction
The Internet represents a tremendous opportunity for business whatever the size of a company. But selling goods and services on the Internet presents it's own set of challenges. How can someone set up and maintain a secure, reliable, cost-effective system for processing credit cards and managing those transactions? You want to sell your products in an easy to use and secure method but do not want to bother with the complexities that are involved in the card processing business. MPG (Maldives Payment Gateway) is a platform built with a target to remove the complexity and effort that is required from you in order to do business on the Internet. All you need to process and manage transactions over the World Wide Web is MPG, a merchant account, and a computer with an Internet connection and a Web browser. You can even incorporate third party shopping cart technology into your site, making the customer experience painless and enjoyable.

1.1 Purpose of the Developer's Guide

The information in this guide aim to help developers integrate their web applications with MPG. The guide does not provide coding techniques, in depth examples for integration nor does it describe to developers how to build their web site. On the other hand, it exposes you and your developers to the functionality offered by MPG and allows you to choose the right options according to your business environment.

1.2 MPG Basics and Requirements

1.2.1 What is MPG?

MPG is a real-time transaction processing system that functions as a payment gateway switch using a secure transaction server on the Internet. Merchants with a valid, enabled merchant account can use the system to submit, authorize and capture card transactions without the need for a separate transaction terminal. In addition to the normal e-commerce functionality, MPG supports 3D Secure transactions, file based batch transactions, web-service based transactions and several other mechanism, utilities and applications to help you process and manage e-commerce transactions. To offer a complete e-commerce authorization system, MPG is made up of three main modules: the Checkout Application, the Merchant Plug-In and Merchant Administration. The Checkout Application is the main module for e-commerce transaction processing. The Merchant Plug-In, or MPI for short, is the module that is fully integrated with the Checkout Application and is responsible for handling the 3D Secure protocol. The Merchant Administration is the main front end application that provides a user friendly interface that can be used to manage your transactions. Although processing credit cards can be a complex and error prone exercise, the MPG has been designed to be as user friendly as possible to both you and the card holder, but at the same time provide a highly secure and stable platform that you can depend on, to run your businesses. The following section explains the basic e-commerce processing flow. The section after that discusses the 3D Secure protocol which is considered the most secure credit card authentication protocol for Internet transactions. If you are familiar with the methodology used for processing e-commerce transactions you can jump right to the Processing your First Transaction section which explains the easiest and fastest method for connecting your website with the Payment Gateway.

Maldives Payment Gateway Developer's Guide

All Rights Reserved Bank of Maldives PLC - 2008

1.2.2 What is Credit Card Processing?

Credit card processing sounds and can be a relatively difficult process that can take a lot of effort and money to implement. Thankfully MPG provides the means to process e-commerce transactions much easier. The following is an outline of the steps involved in processing a credit card transaction: 1. MPG takes over from the point where the customer is ready to checkout (and pay with the credit card). MPG provides the means of doing both the Authentication cycle (3D Secure protocol) and the Authorization cycle. After entering the credit card number an electronic request is submitted to the processing network for authorization and capture from the card holder's credit card account of the amount of the purchase. In a brick and mortar merchant, one would submit this request by swiping a credit card through an electronic transaction terminal provided by the acquiring bank. This request is provided electronically to MPG, which then routes the request to the Provider's Payment System Host. In case Authentication is required by your provider before step 3 takes place (Authorization Cycle), MPG will authenticate the card holder using 3D Secure protocol (Authentication Cycle). The authorization cycle, via MPG and the provider's acquiring host, is passed through the credit card interchange system to the credit card issuer. The credit card issuer determines if the card holder's account is valid and if the funds are available. If they are, the processing network returns an electronic response (retracing it's steps) to your terminal or computer. This response is called an authorization code, and is your guaranteed authorization to capture the funds. Typically, this code is a six-digit number. The transaction and it's associated authorization are stored in a batch, where other currently unsettled transactions for that day reside. This entire authorization process typically takes 3 to 4 seconds, but this can greatly vary depending on network and payment system traffic. At the end of your business day (scheduled by your provider to a default time), the MPG server automatically creates batch files of your transactions that were flagged as captured. This is called settlement or settling your batch. With a traditional physical credit card swipe terminal, this settlement process is initiated automatically every day. Your Provider will transmit the transaction batches to the Credit Card Interchange System, which in turn, passes the batch onto the Credit Card Issuer. A settlement report can be printed showing the grand totals by card type (Visa, MasterCard, American Express, etc.) for the settled batch. Note: any corrections to your batch, such as voiding a transaction, must be made prior to settlement. Within 48 to 72 hours (usually), the funds associated with the batch you settled will be deposited electronically into your bank account. At the end of the month, your provider will mail a statement to you, detailing the credit card activity for the month and the associated fees you have been charged for.

2.

3.

4.

5.

6. 7.

1.2.3 What is the 3D Secure protocol?

Since the first e-commerce credit card processing it was apparent that the possibility of fraudulent transactions is much higher than the traditional POS model of processing. The Payment Systems have recognized this and they have jointly developed the 3D Secure protocol which is a highly secure protocol that was designed from scratch with the purpose in mind. The protocol is called 3D Secure because during its cycle it involves the Acquirer (Merchant), the Interoperability Domain (Payment System) and the Issuer (Card Holder). The main scope of the protocol is to generate a digital signature which will be impossible to generate unless all three parties are authenticated properly. This digital signature is called the Card Authentication and Verification Value or CAVV and is generated by the Issuer only after the Card Holder enters a password or secret phrase, during the 3D Secure cycle. This signature is included in the authorization message that will be sent by the Acquirer and at the end of the process it will be verified by

Maldives Payment Gateway Developer's Guide

All Rights Reserved Bank of Maldives PLC - 2008

the same Issuer. In order to process credit cards using this protocol from beginning to end, all three parties must be enrolled in this program. If the Merchant is 3D Secure enabled, the processing cycle changes at the point where the Payment Gateway sends the request to the Acquirer. Before this step is taken the Payment Gateway will have to check if the transaction can be performed with 3D Secure. To do that the Payment Gateway (or the Merchant) will contact the MPI (Merchant Plug In) and inquire if this card holder's Issuer and the card itself support the protocol. The details of the protocol are explained in a later section but in simple words this is what happens: 1. The Payment Gateway will send the card number to the MPI to check if the card and the Issuer are both enrolled in this program. The MPI will send a request (VeReq, Verification Enrollment Request), to the Payment System's Directory Server (VISA, MasterCard, etc.). The Directory Server will respond to the MPI with a Y or N response indicating if the card and the Issuer are enrolled. If the answer is Y then the MPI will inform the Payment Gateway that the card holder has to be redirected to his/hers Issuer's web site (PaReq, Payer Authentication Request). The card holder will be redirected to the Issuer to enter a password. After this is done the Issuer will send a response back to the MPI (PaRes, Payer Authentication Response). If the password was correct the MPI will receive a Y in the PaRes and the verification value (CAVV). The Payment Gateway will take this value and insert it into the authorization message that will be sent to the Acquirer. From there on, the cycle is the same, except that the Issuer before checking that there are enough funds in the card, it will check that the CAVV value is valid.

2. 3. 4. 5. 6.

The following diagrams show a simplified version of the Authorization cycle together with the Authentication cycle (3D Secure).

Maldives Payment Gateway Developer's Guide

All Rights Reserved Bank of Maldives PLC - 2008

The Credit Card Holder enters the card information, the Payment Gateway requests from the MPI to check if the card is enrolled from the Directory Server. The Directory Server will locate the Issuer and request this information and send it back to the MPI. The MPI will inform the Payment Gateway of the status of the request. This all happens behind the scenes and is not seen by the card holder.

Maldives Payment Gateway Developer's Guide

All Rights Reserved Bank of Maldives PLC - 2008

The Acquirer will send the transaction for authorization to the Credit Card's Issuer including the CAVV in the authorization request. The Issuer will receive the request, then validate the CAVV, then check for funds availability and finally respond back to the Acquirer. The Acquirer will forward the response back to the Payment Gateway and from there the Merchant will receive the response and inform the Card Holder.

1.2.3 Processing your First Test Transaction

Processing transactions using the MPG is relatively easy. It is important that the developer to undertake the integration with MPG has basic knowledge of Internet technology (HTML, SSL, scripting, etc.). Let's go through the simple transaction flow and how you can start sending test transactions as soon as possible. First of all, we need your Web Site and a potential customer. The customer will select which items he/she wants to purchase, prepare the shopping basket and proceed to checkout. The following diagram shows the customer selecting to proceed to the checkout and what happens from there.

Maldives Payment Gateway Developer's Guide

All Rights Reserved Bank of Maldives PLC - 2008

1. 2. 3. 4.

First your website will create the request and send it to MPG. Secondly MPG will ask the card holder to enter the card information. Typically this is the card holder's name, card number, expiry date and the security code. Then the authorization will be sent to the card holder's bank. And finally a response will be sent to your Web Site informing you if the authorization was successfully or not.

Simple enough you say but there is probably a lot of effort required to do the cycle. One of the strong points of MPG is that as long as you have an account with an Acquirer and you are set up correctly in MPG your part is trivial. The only thing that is needed is a way to build the Checkout page in order send transactions to MPG for processing. To prove that this process is easy let's see what is actually required from your side in order to do this.

1.2.4 Sample Checkout Page

The way MPG works is that it waits for you to request a particular page with the required data. As soon as it receives a request for that page, MPG will validate the data that you sent and will start processing the transaction. Please find below a simple page that can be stored in your web server and when loaded will show only a checkout button. As soon as you press that button, the request will be sent to MPG and the processing will initiate (if you would like to experiment by using this example note that some of the fields' values will have to change according to the data that you Acquirer will provide otherwise the request will be rejected. You will also need to calculate the signature correctly). Here is the HTML code of the page:
<html>

<body> <form method=post action=https://testgateway.bankofmaldives.com.mv/SENTRY/PayementGateway/Application/RedirectLink .aspx> <input type=hidden name=Version value=1.0.0 /> <input type=hidden name=MerID value=7796090001009 /> <input type=hidden name=AcqID value=407387 /> <input type=hidden name=MerRespURL value=https://your_server.com/response.aspx /> <input type=hidden name=PurchaseCurrency value=462 /> <input type=hidden name=PurchaseCurrencyExponent value=2 /> <input type=hidden name=OrderID value=MPGORDID01154321 /> <input type=hidden name=SignatureMethod value=SHA1 /> <input type=hidden name=PurchaseAmt value=000000001200 /> <input type=hidden name=Signature value=w25B1ISM517iMsNpUUmfKweze9M= /> </form> </body> <input type=submit name=submit value=Submit />

</html>

The page is as simple as it can be and it should look like the one below:

Maldives Payment Gateway Developer's Guide

All Rights Reserved Bank of Maldives PLC - 2008

By pressing this button the request will be sent to MPG for authorization. In a few fractions of a second the checkout page (similar to the one below) should load. Then the card number will be entered and finally the transaction will complete. > insert image of MPG checkout page. But the question is basically, how does this work, and what are those hidden fields? In the next section we will go over the mandatory fields that are required in order for the transaction to take place and we will send our first test transaction.

1.2.5 Mandatory Fields

As in most applications most fields are optional and others are mandatory. In the case of MPG there are only few mandatory fields that MPG will expect to receive in the page in order to continue the transaction. Most of these are fixed (per Merchant) and some depend on the transaction. In the sample Web page above the following fields were used: 1. 2. 3. 4. Version This is the version of the MPG and currently it has to be set to 1.0.0. MerID This is your Merchant ID as set in MPG (will be provided by your MPG Provider). AcqID This is your Acquierer ID (will be provided by your MPG Provider). MerRespURL This is the URL of a Web Page on your server where the response will be sent.

Maldives Payment Gateway Developer's Guide

All Rights Reserved Bank of Maldives PLC - 2008

5. 6. 7.

PurchaseCurrency This is the standard ISO code of the currency used for the transaction. PurchaseCurrencyExponent This is the number of decimal places used in the amount (usually 2). OrderID This is your own Order ID that will be used to match your Orders with MPG transactions. It is recommended that this Order ID is always unique. SignatureMethod This is the signature method used to calculate the signature (explained below). PurchaseAmt This is the total amount of the purchase.

8. 9.

10. Signature This is a digital signature that will verify that the contents of this Web Page will not be altered in transit. (MPG will verify this signature). As you can see most of the fields will always be the same or rarely change. The only fields that will almost always change are the OrderID, PurchaseAmt and Signature. NOTE The Order ID MUST be a unique number because it will be easier for you to track the Orders that you have on the Web Site with the actual transactions in MPG. A unique order id will also guarantee that even if the card holder presses the back or submit button several times the transaction will only be processed once. NOTE The PurchaseAmt is straight forward, it is basically the normal amount eg: 134.78, but without the decimal place and left padded with zeros in order to make the number twelve characters long. Therefore the amount 134.78 should be 000000013478. NOTE The signature is a little more complicated and will be discussed later on.

1.2.6 Processing Method

The HTML page shown above has a single submit button that when pressed will POST the page to the URL defined in the action tag of the form element. This basically instructs the page to redirect the page to that URL and all the data in the input fields will be sent with the request. When MPG picks up this request on the other side, it will read all the data in the input fields and process the request accordingly. In addition to the mention method other more advanced methods can be used to generate the display and submit the data to MPG, but it all depends on what you want to achieve and how well versed your developers are in Web based application development.

Maldives Payment Gateway Developer's Guide

10

All Rights Reserved Bank of Maldives PLC - 2008

1.2 Data Integrity and Security using a Hash Signature

A hash signature is required when using either of the methods. The MD5/SHA1 hash is a security feature that enables your script to identify that the results of a transaction are actually from the appropriate authorization source and also for the Payment Gateway Server to make sure the integrity of data received on a transaction request. Using either MD5 or SHA1 algorithm, a unique signature or fingerprint of the transaction can be created. The mathematical algorithm used to construct this signature is designed in such a way that any change to the information used in the calculation of the signature will cause a completely different signature to be created. Also, the information used in the calculation of the signature cannot be discovered through any analysis of the signature itself. This is done by using information from your account. Every transaction that is processed through the system has a corresponding hash signature of the transaction created during the transaction process. This signature must be included in the request of every transaction. The signature for a request is a hash of the following six fields: 1. 2. 3. 4. 5. 6. Password (this is the password included in the mailer that we provided during your account setup). MerchantId AcquirerId OrderId (the Order Id that your system generates) Purchase Amount Purchase Currency

The fields must be set in the following order: (Password + MerchantID + AcquirerID + OrderID + Purchase Amount + Purchase Currency) For an example: If your password was orange, your Merchant Id was 7796090001009, your Acquirer Id was 407387, the Order Id was MPGORDID01154321, the amount was 12.00 and Purchase Currency was 462. The has would be calculated on the following string: orange7796090001009407387MPGORDID01154321000000001200462 The resulting hash signature value equals to (using SHA1 algorithm and encoded as a base 64 string, in this case): P4XgdpDnYrM6vtDlOr1DHUE/vkU= If the authorization request is successful MPG will create a second SHA1 hashed signature and include it in the response message. Therefore when you receive the response data you can verify that the values were not modified in transit. The hash signature for the response is a hash of the following fields: 1. 2. 3. 4. Password (this is the password included in the mailer that we provided). Merchant Id Acquirer Id Order Id (the Order Id that you included in the request)

The fields must be set in the following order: (Password + MerchantID + AcquirerId + OrderID) For an example: If your password was orange, your Merchant Id was 7796090001009, your Acquirer Id was

Maldives Payment Gateway Developer's Guide

11

All Rights Reserved Bank of Maldives PLC - 2008

407387 and the Order Id was MPGORDID01154321. The hash would be calculated on the following string: orange7796090001009407387MPGORDID01154321 The resulting hash signature value equals to: (only SHA1 is supported for the response, and encoded as a base 64 string): WcxmDQb02Aj4BRA8/yplsQ/bSAI= When MPG receives the request of the transaction order, it will check if the Hash value it will generate matches the value you have included. When your script receives the results of the transaction you can create the hash on your side and compare it to the one sent by MPG to be sure that both are the same. You will already know your password and Merchant Id, and will receive the Order Id as presented to us. Make a note that the Signature in the response will only be present if the transaction is not in error, that is, for approved and declined transactions. A developer would take the results of the transaction AFTER it was returned to your server, and run the hash algorithm on the fields mentioned above. The only way the results of the developer's processing can match the signature included with the transaction results is if the password used in the hash on the developer's end MATCHES the one used in the transaction. The MPG password is a shared secret (between you and the server), and is one of the key pieces of information in the hash. One can be assured that if the signature generated on your end matches the one sent with the transaction, then the transaction has in fact been processed by our system, and has not been posted back to the merchant's server from any other location. The MPG password is generated automatically by our system and is sent to you. This is also used to authenticated your server to our server during transaction posting. It is only know by the merchant and the System. All sensitive data and passwords are saved using AES encryption. Also not that the merchant has the ability to choose which algorithm to use on every request. If no value is supplied, system will default to SHA1. We recommend SHA1 which is a better algorithm. The SHA1 is called secure because it is computationally infeasible to find a message which corresponds to a given message digest, or to find two different messages which produce the same message digest. Any change to a message in transit will, with very high probability, result in a different message digest, and the signature will fail to verify. More information about the SHA1 hash algorithm, including sample implementation code, can be found in RFC3174 in The Internet Engineering Task Force web site. More information about the MD5 hash algorithm, including sample implementation code, can be found in RFC1321 in The Internet Engineering Task Force web site. Using .NET you can use the available libraries to perform this:
Public Shared Function ComputeHash(ByVal Key As String) As String Dim objSHA1 As New SHA1CryptoServiceProvider() objSHA1.ComputeHash(System.Text.Encoding.UTF8.GetBytes(Key.ToCharArray)) Dim buffer() As Byte = objSHA1.Hash Dim HashValue As String = System.Convert.ToBase64String(buffer) Return HashValue End Function

Or using Python:
import hashlib import base64 def computeHash(string): hash = hashlib.sha1(string)

Maldives Payment Gateway Developer's Guide

12

All Rights Reserved Bank of Maldives PLC - 2008

signature = base64.b64encode(hash.digest()) return signature

Apart from the hashing algorithm described above, there is an extra layer of security with the use of bitmaps. See section Incoming/Outgoing Signature or Response field's customization.

1.2.1 Response Page

By this point you have all the information required to send a request to MPG. The only problem remaining is the response page. MPG will expect you to pass a Response URL in the POST page that will point somewhere on your server so that when the authorization request completes it can send you back a response in order for you to know if the card had the funds required or not. The response is made of several parts. The first is the Response Code which is the most important part of the equation. This will equal to 1, 2 or 3. Basically 1 means that the transaction was authorized, 2 means it was declined and 3 means that an error occurred. By reading this value you can know whether to accept the payment or not. There are also several other values that can be returned when a transaction is completed, which include the Reason Code, which is an error code that explains why a particular transaction was declined and the Response Description which explain in words the result of the transaction. There are also other response fields like the Authentication response, the AVS response codes etc, depending on the type of transaction requested. For a complete list of these values you can look at Appendix A (Response Codes). All these response codes will be returned as part of hidden fields inputs found in an HTML page posted back to your Response URL. In order to get the response page you will need the following: A simple Web Page that will show the response page to the card holder. A way to read the data from the page and use it to update the order of the customer. A simple Web Page that will accept the response from MPG.

Usually the first and last points are the same Web Page. This Web Page will read the response codes from MPG and will update the order of your customer and at the same time will show a message indicating to the customer if the transaction was successful or not. The method used to update the order and display the information to the client is up to you and there are several methods of achieving this, which can range from very simple to very complex depending on how your business logic will be enforced and the complexity of your Web Site. The following VB.Net snippet will simply read the value from the request page and display them on a placeholder (label) on the form that the customer will see. This method is usually too simple to be used in a real environment but can nevertheless form the basis of a more complex and solid one.
Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load If Page.IsPostBack = False Then Dim FormKey As String Dim FormValue As String lblAllFormItems.Text = lblAllFormKeys.Text = For Each FormKey In Request.Form FormValue = Request.Form.Item(FormKey) If FormValue <> String.Empty Then lblAllFormKeys.Text &= <br /><b> & FormKey & :</b> lblAllFormItems.Text &= <br /> & FormValue End If Next End If End Sub

Maldives Payment Gateway Developer's Guide

13

All Rights Reserved Bank of Maldives PLC - 2008

1.2.2 Conclusion
By now you should understand the basic concepts of how to submit your transactions to MPG and if you already have a Merchant Account, you should be able to send transaction requests successfully.

Maldives Payment Gateway Developer's Guide

14

All Rights Reserved Bank of Maldives PLC - 2008

2 Getting Started
Every merchant has access to several modules of MPG that can be viewed and edited. This is called the Merchant Administration module. The system is quite easy to use. Each merchant user that uses the system has a unique login id and password that are used to gain access to the system. We will provide you with your login id and password once your account has been created on the system. Your account will not be live (ready to process real transactions) until your merchant account is active. Upon logging in for the first time, you will need to change your password to an alphanumeric value. In addition, a merchant is and password will be provided that is to be used when submitting transactions in real-time mode through the Internet. Keep the password in a secure place and refrain from distributing it to anyone who does not need access to your merchant account interface. To log into the system, you must first have access to the World Wide Web on the Internet. Once you are online, open you Internet browser. You can log in to the by typing in your browser address bar the following URL: https://egateway.bankofmaldives.com.mv/SENTRY/PaymentGateway/Merchant/Administration

2.1 The Merchant Menu

The first time you log in to the system, you will be required to change your password from the one that we have given you. Once you modify your password, you will have full access to the system, which starts with the Merchant Menu. The Merchant Menu is the central area from which you can access all of the system's configuration, reporting, and processing features. Please refer to the Merchant Administration's User Guide provided along with this guide. This document contains all the information you need to understand the various options available. The remainder of this document will be primarily concerned with technical implementation and integration of a merchant's Website into the MPG system.

2.2 What's next?

At this point, you should have: 1. 2. 3. 4. A merchant account. Familiarity with how credit card processing works. An understanding of MPG architecture. Access to the Internet.

We will help you now to determine how MPG can best be integrated into your environment. Basically, if you don't have a web site from which users can purchase products, then you will want to use the Virtual POS or the Batch File option. If you have a web site from the which users can purchase products, then you have to use the MPG processing method. 2.2.1 Merchant Account NOTE The terms and conditions of your Merchant Account should be kept strictly confidential between you and us and we should be consulted for specific information related to your account. A Merchant Account is required to accept credit cards through the application. A Merchant Account is a special account with you which must be a member of the payment association for which you want to process transactions.

Maldives Payment Gateway Developer's Guide

15

All Rights Reserved Bank of Maldives PLC - 2008

We will: Assign you a Merchant Account Number (Merchant Id) Set up your MPG (Checkout Application) account based on the Assign you an Administrator Login Id and password for you to be able to login to Merchant Administration Web Site. Act as your main point of contact for basic issues regarding your Merchant and MPG accounts. Enable you to add certain types of credit cards to your Merchant account.

Once your Merchant Account is setup up and live on the credit card system, you can begin to accept credit cards from customers.

Maldives Payment Gateway Developer's Guide

16

All Rights Reserved Bank of Maldives PLC - 2008

3 Processing Methods
The system offers a number of methods for integration and the method of integration depends on your developer(s) skills and environment you want to build. One of these methods should be just right for your customer's shopping experience. You should choose the processing method that will fit your business model the best.

3.1 MPG Integration Methods

As was mentioned above MPG has a lot more functionality than accepting cards and sending them for authorization using the processing method show above. There are several methods of processing your transactions and for each method there are many optional fields that can be used to customize each method to your individual needs. The main transaction engine is made up of several request handlers, implemented as HTTP handlers within MPG Checkout Application. These handlers include several HTTP Post methods, like the one used above, Web Services, plain text files that can process many transactions in a batch method etc. For your information here is all the different integration methods that MPG supports: Virtual POS (Merchant Administration module) HTTP Handlers (Handlers are explained in more detailed in Section Handler Details). Redirect Link (Authorization with 3D Secure (MPG MPI) or Authorization only. Depending whether merchant is enrolled for 3D Secure). Page to post is RedirectLink.aspx. Direct Link with 3D Secure (MPG MPI). Page to post to is DirectAuthLink.aspx. Direct Link without 3D Secure (Authorization Only, no 3D Secure). Page to post is DirectAuthzLink.aspx. Direct Link with 3D Secure (using an external MPI). Page to post is DirectAuthztpLink.aspx. Web Services Store Front Services List transactions Refund transactions Reverse transactions Capture transactions Batch Files Authorization Capture Authorization + Capture Refund Reversal Installment Recurring

These methods can be used on their own or in combination. For example you can use the Redirect Link for all your transactions, 3D Secure or not. Alternatively you can use the Redirect Link to complete the 3D Secure Authentication cycle and then depending on the response you can decide whether to send the authorization using the Direct Method. Another combination could be to use the Direct Link with 3D Secure for authentication only and then use the Direct without 3D Secure to do the authorization. Finally a very common approach for some Merchants is to send authorizations through one host but use another host for their 3D Secure Authentications. This can also work by using an external MPI for example to do the Authentication and then use the Direct Link with external MPI to do the Authorization with MPG. All these methods and the way to call them will

Maldives Payment Gateway Developer's Guide

17

All Rights Reserved Bank of Maldives PLC - 2008

be discussed in the following sections.

3.2 Virtual POS

The Virtual POS is used for manual key entry of transactions using the Merchant Administration interface. The effect of the Virtual POS is similar to the normal Point of Sale of a Credit Card terminal. You might need to use the Virtual POS for cases such as if: You received an order by phone, face or mail and need to process the transaction. You previously received a voice authorization by phone and now need to submit the transaction to be captured.

This type of transaction is called, Mail Order/Telephone Order transactions (MOTO). The Virtual POS allows you to either authorize only and capture later, or to do a full authorization and funds capture with a single transaction. You don't need to have a Web site to use Virtual POS. You can log in to the Merchant Administration web site and choose MOTO option on the Merchant Menu.

3.2 HTTP Handlers

3.2.1 Difference between MPG HTTP Handler Methods

Two types of MPG HTTP Handler methods are available that both require familiarity with Web Programming: 1. 2. Direct Link Redirect Link

In Direct Link, a customer's Web browser makes a secure connection to your server and transmits all of the information necessary to process a transaction (including the credit card information) when ready to checkout. Your server connects securely to MPG web server, transmits all of the transaction information in a Web Request via HTTPS by POST inside an HTML form to the gateway for processing. The gateway server returns the results of the transaction processing to your server. Then you can determine from the results of the transaction how to proceed and continue by returning a response to the customer. In Redirect Link, the customer's interaction is with the MPG server. Your Web page initiates a transaction by posting an HTML form with the required transaction information (without the card information) to the Payment Gateway server. The customer provides additional information to the Payment Gateway server if it is desired for them to do so. The Payment Gateway server processes he transaction, and then transmits the results of the transaction to your server via HTTPS form POST.

3.3 When to use which method

Both methods provide ways for developers to integrate transaction processing into whatever programs or databases they may desire. However, one method might be better for certain situations than another. Most likely, the main factor that determines which method to use will be the ability to make secure encrypted connections and also what is required by your provider. The Direct Link method will generally be more desirable than the Redirect Link method because of the greater control it gives developers over the whole transaction process flow. However, a developer won't be able to implement the Direct Link method unless they can provide a secure server side connection and initiate a secure client side connection when they send the transaction information to the gateway server. Implement client side secure connections is made easier by using some of the readily available tools and libraries for implementing protocols like SSL. However,

Maldives Payment Gateway Developer's Guide

18

All Rights Reserved Bank of Maldives PLC - 2008

implementing client side security requires a lot of effort. If it's not possible to create a secure connection on both the server and client sides of the link, the Redirect Link method provides an alternative where sensitive data such as credit card numbers is only transmitted across the secure link between the system's gateway server and the customer's browser. In brief: 1. 2. If you can write a script that can process information sent via an HTTPS form POST, then you might want to consider using Redirect Link method. If you can write a script that can process information sent via an HTTPS form POST, AND you can provide a secure server side connection and initiate a secure client side connection, then you might want to consider using Direct Link method.

Make a note that your provider may not allow you to use the direct link method. Also, in the case of 3D Secure, the Redirect Link method is most likely going to be used. Before deciding on the method to use, check with your Payment Provider.

Maldives Payment Gateway Developer's Guide

19

All Rights Reserved Bank of Maldives PLC - 2008