This section lists the details of reviews for this document:

This section details the changes this document has undergone:

Vistamoney is a PCI-DSS compliant platform with the ability to support strong data encryption for secure transactions. The target of Vistamoney is to keep the merchants’ online e-commerce business up and running by applying simple integration methods and by offering advanced payment technology with high end risk management solutions.

This document is intended for programmers responsible for the merchant payment gateway interface. It describes the interface that merchant systems use to process the e-commerce transactions by means of standard form posting method. This interface supports various integration methods as Transport method.

Vistamoney payment gateway exchanges data between merchant and gateway in the form of Request and Response.

The following diagram explains the components involved in the process:

A Merchant integrated with the Gateway initiates the transaction by sending request to gateway by HTTPS POST method. The Gateway sends back the response over the same socket to the merchant. Response time depends on the acquiring bank / acquiring gateway processing with the interbank networks.

Request/Response process is identified by a set of XML message fields which provides the transaction interface between the merchant and the Vistamoney payment gateway. Each integration URL will be provided along with the integration document to the merchant.

We recommend to timeout the request connection after 30 seconds.

Protocol: https

Method: Post in REST

LIVE URL: https://vistamoney.info/paymentgateway/payments/performXmlTransaction

TEST URL: https://test.vistamoney.info/paymentgateway/payments/performXmlTransaction

Content-Type: URL Encoded

We use application/xml;charset=utf-8content type.

Encryption Level: SSL Version 3.0

As an example – The following XML message can be sent by the merchant as one of the permitted service requests by means of HTTPS RESTFULL Post method:

<?xml version='1.0' encoding='ISO-8859-1' ?>
<request>
<terminalid>Term1</terminalid>
<password>password</password>
<action>1</action>
<card>4444444444444444</card>
<cvv2>115</cvv2>
<expYear>2012</expYear>
<expMonth>12</expMonth>
<member>Test User</member>
<currencyCode>USD</currencyCode>
<address>Ebene</address>
<city>MOKA</city>
<statecode>MOKA</statecode>
<zip>152458</zip>
<CountryCode>Mauritius</CountryCode>
<email>[email protected]</email>
<amount>1.25</amount>
<trackid>soft1256</trackid>
<udf1></udf1>
<udf2></udf2>
<udf3></udf3>
<udf4></udf4>
</request>

Request and response message data exchange depends on the following factors:

1. Each request sent by the merchant will get a response from the gateway on the same socket or the connection will be closed by the timeout of either the Gateway or the merchant;

2. The request and response have fields that provide authorization and authentication on both sides;

3. Request and response messages have some matching fields to maintain consistency between two interacted parties;

4. Every requested service has exact set of request and response fields.

There are several transactions Vistamoney payment gateway provides to the merchants within the scope of current version.

Purchase transaction is an operation of debiting the cardholder’s account.

XML Request for Purchase:

<request>
<terminalid>Term1</terminalid>
<password>password</password>
<action>4</action>
<card>4444444444444444</card>
<cvv2>310</cvv2>
<expYear>2017</expYear>
<expMonth>12</expMonth>
<member>Test user</member>
<currencyCode>USD</currencyCode>
<address> Test address</address>
<city> Test </city>
<statecode>MNK</statecode>
<zip>45638</zip>
<CountryCode>US</CountryCode>
<amount>2.00</amount>
<trackid> Test </trackid>
<email>[email protected]</email</email>
</request>

XML Response:

<?xml version="1.0" encoding="UTF-8"?>
<response><result>Successful</result><responsecode>000</responsecode><authcode></authcode><RRN>
</RRN><ECI></ECI><tranid>2584589010416223482</tranid><trackid>Test</trackid><terminalid>
Term1</terminalid><udf1></udf1><udf2></udf2><udf3></udf3><udf4></udf4><udf5>Transaction Successful -
Transaction Status : Approved Description : 0: Approved | </udf5></response>

The transaction request should include the following fields:

Refund transaction is an operation to credit back the funds onto customer’s card account. Merchant can refund any amount which has been debited by the previously successful purchase or capture transactions.

XML Request for Refund:

<request>
<terminalid>Term1</terminalid>
<password>password</password>
<action>2</action>
<currencyCode>USD</currencyCode>
<CountryCode>US</CountryCode>
<amount>2.00</amount>
<transid>0035245601821955669</transid>
<trackid>test</trackid>
</request>

XML Response:

<?xml version="1.0" encoding="UTF-
8"?><response><result>Successful</result><responsecode>000</responsecode><authcode></authcode><RRN>
</RRN><ECI></ECI><tranid>2922627518652618877</tranid><trackid>test</trackid><terminalid>
Term1</terminalid><udf1></udf1><udf2></udf2><udf3></udf3><udf4></udf4><udf5>Transaction Successful -
Transaction Status : Approved Description : 0: Approved | </udf5></response>

The transaction request should include the following fields:

Pre-Authorization transaction is an authorization of payment on card. In case of successful authorization, the transaction amount will be frozen on customers account without debiting.

XML Request for Pre-Authorization:

<request>
<terminalid>Term1</terminalid>
<password>password</password>
<action>4</action>
<card>4444444444444444</card>
<cvv2>310</cvv2>
<expYear>2017</expYear>
<expMonth>12</expMonth>
<member>test user</member>
<currencyCode>USD</currencyCode>
<address> test address</address>
<city> test </city>
<statecode>MNK</statecode>
<zip>45638</zip>
<CountryCode>US</CountryCode>
<amount>2.00</amount>
<trackid> test </trackid>
<email>[email protected]</email>
</request>

XML Response:

<?xml version="1.0" encoding="UTF-
8"?><response><result>Successful</result><responsecode>000</responsecode><authcode></authcode><RRN>
</RRN><ECI></ECI><tranid>5868885818957796198</tranid><trackid>test</trackid><terminalid>
Term1</terminalid><udf1></udf1><udf2></udf2><udf3></udf3><udf4></udf4><udf5>Transaction Successful - Transaction Status : Approved Description : 0: Approved | </udf5></response>

The transaction request should include the following fields:

Capture transaction is the actual amount debited from the customer’s account after the previous successful Pre-Authorization transaction.

XML Request for Capture:

<request>
<terminalid>Term1</terminalid>
<password>password</password>
<action>5</action>
<currencyCode>USD</currencyCode>
<amount>2.00</amount>
<trackid> test </trackid>
<transid>3213874245790117249</transid>
</request>

XML Response:

<?xml version="1.0" encoding="UTF-
8"?><response><result>Successful</result><responsecode>000</responsecode><authcode></authcode><RRN>
</RRN><ECI></ECI><tranid>4030835365049819081</tranid><trackid>test</trackid><terminalid>
Term1</terminalid><udf1></udf1><udf2></udf2><udf3></udf3><udf4></udf4><udf5>Transaction Successful -
Transaction Status : Approved Description : 0: Approved | </udf5></response>

The transaction request should include the following fields:

Void Pre-Authorization transaction is used to unfreeze the amount held by the successful Pre-Authorization transaction. Once the amount is captured, it cannot be voided.

XML Request for Void:

<request>
<terminalid>Term1</terminalid>
<password>password</password>
<action>9</action>
<currencyCode>USD</currencyCode>
<amount>2.00</amount>
<trackid> test  </trackid>
<transid>4454874175595575617</transid>
</request>

XML Response:

<?xml  version="1.0" encoding="UTF-
8"?><response><result>Successful</result><responsecode>000</responsecode><authcode></authcode><RRN>
</RRN><ECI></ECI><tranid>7296489321379159269</tranid><trackid>test</trackid><terminalid>
Term1</terminalid><udf1></udf1><udf2></udf2><udf3></udf3><udf4></udf4><udf5>Transaction  Successful -
Transaction Status :  Approved Description : 0: Approved | </udf5></response>

The transaction request includes the following fields:

The Vistamoney Payment Gateway service offers the “3D Secure Host” service for authorization of credit card transactions originated from payment orders received by the Merchants on their websites.

3-D Secure is an authenticated payment system to improve online transaction security and encourage the growth of e-commerce payments. Collectively Visa, MasterCard and AMEX secure systems are brand identities of the 3-D Secure Cardholder Authentication Scheme.

3-D secure is a protocol introduced to provide issuer banks with the ability to actually authenticate the cardholders during e-commerce transaction, to reduce the fraudulent usage of Credit/Debit cards in e-commerce transactions and to benefit merchants, consumers and acquirers.

A 3D Secure transaction introduces some extra steps to a normal credit card transaction, necessary to achieve cardholder authentication. The complete sequence of activities is as follows:

1. The Cardholder browses the Merchant website, chooses one or more items from the catalogue and provides personal data for subsequent goods shipping. For example, when the merchant initiates Purchase transaction, the Vistamoney payment gateway checks if the merchant is configured to process the 3D secure validation.
2. The Cardholder provides, on a secure web page, its credit card data.
3. The payment service queries VISA or MasterCard Directory Server to know if the Cardholder is
   • If the Cardholder is enrolled in the 3D Secure Directory Server, the gateway responses with the3D-Secure Processing URL and payment id generated by gateway in the request.Xml response:TEST:

     <?xml version="1.0"  encoding="UTF-8"?><response><targetUrl>http://test.vistamoney.info/paymentgateway-
     external/processthreed.xhtml?payId=</targetUrl><payId>122</payId></response>

     LIVE:

     <?xml version="1.0"  encoding="UTF-8"?><response><targetUrl>http://vistamoney.info/paymentgateway-
     external/processthreed.xhtml?payId=</targetUrl><payId>122</payId></response>

   • If card is not configured for the 3D secure verification process, gateway processes the transaction as NON-3D transaction and returns the result to the merchant over same communication channel. Following are the response fields returned in the response as described above for purchase and pre-authorization.Response Message Fields
     

     Field Name	Data Type	Field Maximum Length	Description
     Result	A	12	Result of the transaction processing on gateway. This field have two values “Successful” or “Unsuccessful”
     Response code	AN	3	Response code of the transaction. Refer to Appendix D for valid response codes
     Authcode	AN	6	Authorization code generated by bank
     ECI	N	2	Electronic Commerce Authentication Indicator
     Tranid	AN	50	Unique transaction id generated by gateway. In case of Capture and refund transaction requests this id should be Send as original transaction reference.
     Trackid	AN	50	Unique merchant tracking id sent in the request
     Terminalid	AN	10	Terminal id provided in the request
     RRN	N	12	Retrieval Reference Number from international exchange
     Currency	A	3	Alphabetic currency code of the transaction.
     Amount	N	12	Amount of the transaction with or without decimal points, i.e. 2.25 or 2
     Email	AN	50	Customer’s email address.
     udf5	AN	30	It is reserved to receive bank response code as an additional detail from some acquirers.
     udf1	AN	30	User defined field1. User can provide additional information which will be stored on the gateway.
     udf2	AN	30	User defined field2. User can provide additional information which will be stored on the gateway.

4. The Cardholder is directed to a page on which Merchant, transactions and bank data are displayed, along with the “Verified by Visa” or “MasterCard Secure Code” logo which encourages the Cardholder to trust the ongoing transaction process. An input field is also displayed on the page, which the cardholder must fill with the secret password associated with its credit card.

When selecting Pay Now, the user will be redirected for verification purposes.

The user is prompted to insert a password to validate its transaction. From here, the payment gateway will notify your website if the transaction is successful or problems have arisen.

5. The Cardholder provides the secret password.
6. The server redirects the Cardholder browser to the Merchant payment service, carrying the authentication result field as a hidden field.
7. The Merchant payment service checks the Cardholder authentication result:
   • If positive, the transaction is processed and authorization results are displayed to the Cardholder browser.
   • If negative, the process is stopped and an error message is displayed to the Cardholder browser.

Merchant can extract response details from the following:

TEST:

http://test.vistamoney.info/paymentReceipt.html?results=successful&transid=12345&ecis=07&trackids=testTra
ck&responsecodes=000&auths=12345&rrns=456789&udfs5=succcess&currencys=QAR&
amounts=1.0&[email protected]&udfs1=test1&udfs2=test2&udfs3=test3&udfs4=test4

LIVE:

http://vistamoney.info/paymentReceipt.html?results=successful&transid=12345&ecis=07&trackids=liveTrack&
responsecodes=000&auths=12345&rrns=456789&udfs5=succcess&currencys=QAR&
amounts=1.0&[email protected]&udfs1=test1&udfs2=test2&udfs3=test3&udfs4=test4

You may use the following option to retrieve the data from the above URL. This is an e.g. of a receipt URL html files:

<html>
<head>
<meta charset="UTF-8">
<title>Receipt</title>
</head>
<body>
<form>
<h1>Transaction Receipt</h1>
<table>
<tr>
<td>Result</td>
<td id="result"/>
</tr>
<tr>
<td>Tran Id</td>
<td id="tranid"/>
</tr>
<tr>
<td>ECI</td>
<td id="eci"/>
</tr>
<tr>
<td>Track Id</td>
<td id="trackid"/>
</tr>
<tr>
<td>Response Code</td>
<td id="responsecode"/>
</tr>
<tr>
<td>Auth Code</td>
<td id="auth"/>
</tr>
<tr>
<td>RRN</td>
<td id="rrn"/>
</tr>
<tr>
<td>Additional Data</td>
<td id="udf5"/>
</tr>
<tr>
<td>Amount</td>
<td id="amount"/>
</tr>
<tr>
<td>Email</td>
<td id="email"/>
</tr>
<tr>
<td>User Defined Field 1</td>
<td id="udf1"/>
</tr>
<tr>
<td>User Defined Field 2</td>
<td id="udf2"/>
</tr>
<tr>
<td>User Defined Field 3</td>
<td id="udf3"/>
</tr>
<tr>
<td>User Defined Field 4</td>
<td id="udf4"/>
</tr>
</table>
<script>
    </script>
</form>
</body>
</html>

In this scenario, javascript is used to retrieve the data.

For e.g:

var results = params[0].split(‘=’);

then, assign the result to the receipt URL

document.getElementById(“result”).innerHTML = results[1];

Note: You will have to implement a script to follow up on any situation that might have arisen

Note: 3D-secure integration only applies to Purchase and Pre-Authorization transactions where user has to provide card details. Transaction processing for transactions other than Purchase and Pre-Authorization happens as stated earlier in the document.

Tokenization

For recurring transaction, the e.g for test url and screenshot of the pghosted page is shown below.

Test Url : http://test.vistamoney.info/paymentgateway-external/pghostedvista.xhtml?trackId=wes123&terminalId=feedeology2&amount=10.50&currency=QAR

The customer will tick the recurring flag and will proceed with the transaction. If the transaction is successful, he will obtain a token in the response as shown below

The merchant will use this token to send a recurring transaction in the future. The format of the transaction would be as shown below.

<request>
<terminalid>feedeology2</terminalid>
<password>Password1!</password>
<action>1</action>
<currencyCode>USD</currencyCode>
<amount>10.50</amount>
<token>BYutwJIWvolcJXOuqIwyfURmtXUqDsuo</token>
<trackid>pcv</trackid>
</request>

The token will be decrypted to get his card details along with the track id will be used for the recurring transaction. Note that there is no cvv inside the token. The generated token will contain only card number and expiry date.
The response of the transaction will be sent to the merchant as shown below for a successful recurring transaction.

<?xml version="1.0" encoding="UTF-
8"?><response><result>Successful</result><responsecode>000</responsecode><authcode></authcode><RRN>
</RRN><ECI></ECI><tranid>2584589010416223482</tranid><trackid>pcv</trackid><terminalid>
Term1</terminalid><udf1></udf1><udf2></udf2><udf3></udf3><udf4></udf4><udf5>Transaction  Successful -
Transaction Status : Approved Description : 0:  Approved | </udf5></response>

Other flows
Automated recurring flows consists of mainly two types of requests (without intervention of merchant):

1. Down payments
2. Intimation

Down payments occurs when payment amount (Tag <amount>10.00</amount>) is greater than 0.
Initmation occurs when payment is equal to zero.

Two types of requests can be sent for recurring :

1. Purchase
2. Pre-Authorisation

In order to identify a recurring transaction, following parameters should be added in your XML requests

Purchase:

<request>
  <terminalid>TEST</terminalid>
  <password>password</password>
  <action>1</action>
  <card>5444444444444444</card>
  <cvv2>333</cvv2>
  <expYear>2017</expYear>
  <expMonth>12</expMonth>
  <member>test  user</member>
  <currencyCode>USD</currencyCode>
  <address>test  address</address>  
  <city>Gotham</city>
  <statecode>MNK</statecode>
  <zip>45638</zip>
  <CountryCode>US</CountryCode>
  <amount>2.00</amount>
  <trackid>test</trackid>
  <email>[email protected]</email>
  <paymenttype>R</paymenttype>
  <paymentmethod>CC</paymentmethod>
  <subscriptiontype>i</subscriptiontype>
  <paymentcycle>D</paymentcycle  >
  <paymentdays></paymentdays>
  <noOfRecurringpayments>5
  </noOfRecurringpayments>  
  <paymentstartdate>20/03/2017
  </paymentstartdate>
  <recurringpaymentamount>2.00
  </recurringpaymentamount  >
  </request>

Pre auth:

<request>
  <terminalid>BKONE</terminalid>
  <password>password</password>
  <action>4</action>
  <card>5444444444444444</card>
  <cvv2>333</cvv2>  
  <expYear>2017</expYear>
  <expMonth>12</expMonth>
  <member>test  user</member>
  <currencyCode>USD</currencyCode>
  <address> test  address</address>
  <city>Gotham</city>
  <statecode>MNK</statecode>
  <zip>45638</zip>  
  <CountryCode>US</CountryCode>  
  <amount>10.00</amount>
  <trackid> test  </trackid>
  <email> test  @d.com</email>
  <paymenttype>R</paymenttype>
  <paymentmethod>CC</paymentmethod>
  <subscriptiontype>i</subscriptiontype>
  <paymentcycle>D</paymentcycle  >
  <paymentdays></paymentdays>
  <noOfRecurringpayments>5</noOfRecurringpayments>
  <paymentstartdate>20/03/2017</paymentstartdate>
  <recurringpaymentamount>2.00</recurringpaymentamount>
</request>

If recurring request is successful, the following email will be sent to the Merchant and the Institution.

If recurring payment is successful, the following email will be sent to the Merchant and the Institution.

To make a successful payment, on a website for which you need to add a purchase button for a particular item, you will have to send a small series of confidential information to the payment gateway which will deduct money from your client’s bank account and deposit the amount on the bank account on the owner’s website. For the Information to be sent, a button on the merchant website will trigger a page on the payment gateway which will pass the small series of data to the payment gateway. This will deduct and credit money on relevant bank accounts.

The data passed to the payment gateway will not update your stock records or trigger shipping of your item. This section will have to be handled by the website integrator. The other records keeping might be needed, and all this will have to be implemented by you in a sequence you deem fit, in the code triggered by the purchase button. The payment gateway only handles financial transactions and will return a value that indicates if the banking transaction was successful or if any problems arose. From there, you will be able to make “IF-ELSE” or “SWITCH” statements to handle any situation that might arise.

For example, if you have many products, and each product has a price and various details associated with it, each purchase button is an object on your website that has an “on click” event.

Let us make a trivial example where we pass four minimal data values that need to be sent to the gateway. This is only for educational purposes, and not meant for use in production.

To inspect an object, e.g. button on a website, right click and choose “inspect” from the pop-up menu.

You can find below the code being executed each time the ‘Pay Now’ button is selected:

TEST:

http://test.vistamoney.info/paymentgateway-

external/pghostedvista.xhtml?trackId=Jawad123&terminalId=feedeology2&amount=10.50&currency=QAR

LIVE:

http://vistamoney.info/paymentgateway-
external/pghostedvista.xhtml?trackId=Jawad123&terminalId=feedeology2&amount=10.50&currency=QAR

This code segment will pass four variables to the gateway:

1. terminalId= feedeology2
2. amount=10.50
3. currency= QAR
4. trackId= Jawad123
   1. “feedeology2” is the identification provided to each merchant, or department the merchant requires. A merchant may have several terminal IDs, in case there are several sales departments for different categories of products and services.
   2. The amount is the amount of money to be deducted.
   3. The currency is the currency on which all calculations will be base and it must be valid for the terminal.
   4. The TrackId is an identifier for the transaction provided by the merchant.

From there, the client will be forwarded to the secure page of the payment gateway.

The merchant is not allowed to obtain credit card details from customers directly on their own website. The level of security would be inadequate and it is preferable to always offset credit card detail captures on the gateway systems where the security has been properly audited. While integrating your website, these four values might change if there are several terminals. The prices are different and the currency might change depending on the country of the customer.

The client will see this page on our payment gateway and the client may now enter his credit card details.

When selecting Pay Now, the user will be redirected to Modirum for verification purposes. See section 10.1.

From here, the payment gateway will notify your website if the transaction is successful or problems have arisen. It will be notified by the receipt URL you provided.

In the receipt url, you will have to map the values obtained from our response.

For example,

TEST:
http://test.vistamoney.info/paymentReceipt.html?results=successful&transid=12345&ecis=07&trackids=testTrack
&responsecodes=000&auths=12345&rrns=456789&udfs5=succcess&currencys=QAR&
amounts=1.0&[email protected]

LIVE:
http://vistamoney.info/paymentReceipt.html?results=successful&transid=12345&ecis=07&trackids=testTrack&
responsecodes=000&auths=12345&rrns=456789&udfs5=succcess&currencys=QAR&
amounts=1.0&[email protected]

Merchants will have to provide their receipt URL to be configured on the terminal, else it will go to Vistamoney as default receipt URL.

You may use a receipt URL html file to retrieve the data. See section 10.2.