SSLCOMMERZ 
Connectivity Guide (v 2.1) 
 
 
 
 
 
 
 
 
 
Last updated 

November 2, 2010
 

TABLE OF CONTENTS 
1.  INTRODUCTION ......................................................................................................................................... 3 

2.  CONNECTION METHODS ........................................................................................................................... 3 

LIVE ................................................................................................................................................................ 4 

AN EXAMPLE ................................................................................................................................................. 5 

TESTBOX ........................................................................................................................................................ 6 

3.  INSTANT PAYMENT NOTIFICATION (IPN) .................................................................................................. 7 

IPN MECHANISM ........................................................................................................................................... 7 

AN EXAMPLE ................................................................................................................................................. 8 

4.  SUPPORT ................................................................................................................................................. 10 

Page 2 of 10 
 
1. Introduction 
 

Welcome  to  SSLCOMMERZ  Connectivity  Guide.  This  guide  will  give  you  the  idea  of  the  process  of 
performing and receiving payment on the internet using Visa, MasterCard and Nexus debit card. This guide 
will  also  give  you  the  idea  of  the  process  of  connecting  your  online  store  and  explanation  of  different 
parameters by which you will be able to process and monitor online payments, a full transaction, Instant 
Payment Notification (IPN) etc. By reading this guide you will be able to know what you will have to do for 
SSLCOMMERZ  to  perform  a  successful  transaction,  or  what  to  do  in  case  of  a  failed  or  cancelled 
transaction. 

 
2. Connection Methods 
Secure and flexible integration options 

www.sslcommerz.com.bd enables all types of merchants to accept secure and reliable credit card quickly 
and easily. We offer flexible application programming interfaces (APIs) with no licensing fees.  

There  will  be  integration  between  your  online  store  and  SSLCOMMERZ  gateway  for  accepting  certain 
parameters,  which  need  to  be  exchanged  between  the  store  and  SSLCOMMERZ  when  an  e‐commerce 
transaction takes place. Each transaction will be linked to a unique order number for a product or service 
sold by the merchant store. 

This means that you will have to maintain the order related details as to what are the ordered items, their 
quantities,  shipping  details,  etc.  SSLCOMMERZ  Gateway  is  concerned  with  the  end  order  number 
generated and amount to be transferred. 

There are two types of connection for SSLCOMMERZ: 

i. Live 

ii. TestBox 

We highly recommend you test your transaction mechanism with TestBox connection before going for Live 
connection. 

Page 3 of 10 
Live 
You  can  connect  your  online  store  to  SSLCOMMERZ  for  live  transactions.  This  means  the  transactions  of 
funds will be real. Your customers will have to provide their original credit/debit card numbers, CVV2/CVC, 
etc. for the fund transfer to happen. After you successfully register with SSLCOMMERZ and select it as your 
payment  gateway,  you  will  be  given  a  Store  ID  by  which  SSLCOMMERZ  will  identify  you.  There  will  be 
certain parameters that have to be submitted when a transaction takes place.  

Your online store has to generate an HTTP POST request to the designated SSLCOMMERZ gateway page. 
The  gateway  will  provide  the  customer  with  a  payment  form  where  the  actual  payment  instruction  will 
generate. The gateway after receiving the customer’s payment instruction will pass a payment request to 
the customer selected processor. The following parameters will authenticate the validity of your store in 
SSLCOMMERZ gateway. 

Name  Parameter  Description  Type  Length  Requirement 

Transaction ID  tran_id  The gateway will save the  Alphanumeric  25  Mandatory 
Transaction ID for any sort of 
future queries and cross 
checking with online store 
system for verification of 
payment completion. 
Amount  total_amount  This will have the amount of  Double  10,2  Mandatory 
money the customer has to 
spend for his purchase 
including VAT/Taxes, 
shipping/delivery charges and 
other costs. 
Payment  success_url  This parameter is sent as the  Alphanumeric  255  Mandatory 
Success URL  payment success URL and after 
the customer’s payment is 
successfully received by the 
gateway, it will forward the 
customer to the URL as 
customer’s payment received 
destination. The online store 
must form the URL intelligently 
and should be able to detect 
the customer’s order in the 
destination page. The 
recommended way is to set a 
flag or ID with the URL to 
detect the correct customer 
and the actual order of the 
purchased products. 
Payment  cancel_url  This parameter will be used  Alphanumeric  255  Mandatory 
Cancel URL  when the customer chooses 
not to purchase the products 
after he/she has checked out 
and redirected to the payment 
system. After cancellation of 
the payment, the gateway will 
redirect the customer to the 
online store’s cancel page. 

Page 4 of 10 
Payment  fail_url  This URL will be used in the  Alphanumeric  255  Mandatory 
Failure URL  case of any failure occurring 
during the payment process. 
The failure notice with a button 
linked to the online site’s 
failure page will be shown to 
the customer. 
Store ID  store_id  The Store ID will be provided  Alphanumeric  20  Mandatory 
by SSLCOMMERZ gateway after 
your online store is registered 
and connected. Every store has 
an account where all payment 
and settlement information 
can be found. These accounts 
are used for different 
processors/banks where the 
actual payment is processed. 
 

The  aforementioned  parameters  must  be  sent  as  per  specified  here  to  the  payment  gateway  for  the 
transaction process to start. In addition, you will have to provide your real IP and domain name which we 
will register at your end. 

An Example 
After  the  customer  chooses  to  checkout  from  the  shopping  cart  and  enters  the  shipping/delivery 
information,  the  online  store  requires  generating  an  HTTP  POST  request  using  the  parameters  specified 
above. A sample HTML Form is given below as an example having it set to POST as the ‘Method’ and use 
the gateway URL as the ‘Action’: 

<form action="https://www.sslcommerz.com.bd/process/index.php" method="post" name="form1"> 

<input type="hidden" name="store_id" value="hguhgujgg"> <!—You have put your store ID here ‐‐> 

              <input type="hidden" name="total_amount" value="12312">        

              <input type="hidden" name="tran_id" value="123456">          

          <input type="hidden" name="success_url" 
value="http://www.example.com/pay_test/notify.php?itemid=<?php echo $itemid;?>">  

              <input type="hidden" name="fail_url" value = "http://www.example.com/pay_test/fail.php?itemid=<?php echo 
$itemid;?>"> 

              <input type="hidden" name="cancel_url" value = "http://www.example.com/pay_test/cancel.php?itemid=<?php echo 
$itemid;?>">                      

              <input type="submit" value="Pay with SSLCOMMERZ" name="pay"> 

      </form> 

Page 5 of 10 
After  the  submission  of  the  above,  it  will  hit  the  payment  gateway  with  the  given  parameters.  After 
validation,  the  customer  will  be  shown  a  payment  form  to  enter  his/her  payment  information.  The 
customer  may  enter  his/her  Debit/Credit  Card  Number,  CVV/CVC  number  for  making  the  payment.  The 
number  of  fields  displayed  to  the  customer  for  entry  of  payment  information  may  differ  for  different 
payment processors. 

The  customer  will  be  returned  to  store’s  success  page  if  the  payment  is  successfully  completed  at  the 
selected  payment  processor’s  end.  If  the  customer  decides  not  to  pay,  he/she  will  be  returned  to  the 
store’s cancel page. For a failed transaction the customer will be returned to store’s failure page. 

TestBox 
In this type of connection, the whole process of fund transfer is tested only.  The fund transaction will not 
be  real.  This  connection  tests  the  different  aspects  of  the  fund  transfer  process.  The  parameters  for 
TestBox  are  the  same  as  for  Live  connection.  We  develop  the  TestBox  at  our  end.  After  you  have 
successfully done testing with the TestBox, we will provide you the link for live testing. 

A sample form for integrating with the TestBox may look like this: 

<form action="https://www.sslcommerz.com.bd/testbox/process/index.php" method="post" name="form1"> 

<input type="hidden" name="store_id" value="hguhgujgg"> <!—You have put your store ID here ‐‐> 

              <input type="hidden" name="total_amount" value="12312">        

              <input type="hidden" name="tran_id" value="123456">          

          <input type="hidden" name="success_url" 
value="http://www.example.com/pay_test/notify.php?itemid=<?php echo $itemid;?>">  

              <input type="hidden" name="fail_url" value = "http://www.example.com/pay_test/fail.php?itemid=<?php echo 
$itemid;?>"> 

              <input type="hidden" name="cancel_url" value = "http://www.example.com/pay_test/cancel.php?itemid=<?php echo 
$itemid;?>">                      

              <input type="submit" value="Pay with SSLCOMMERZ" name="pay"> 

      </form> 

Page 6 of 10 
3. Instant payment notification (IPN) 
While  the  Internet  can  be  a  wonderful  new  sales  channel,  it  also  provides  criminals  with  wonderful  new 
opportunities  to  defraud  customers  and  merchants.  You  should  take  significant  measures  to  ensure  that 
customers presenting card information are indeed the rightful owners of those cards. 

SSLCOMMERZ with Instant Payment Notification provides you with a variety of valuable tools to help you 
validate the identity of your customer and thereby control fraud losses.  

After the confirmation of a successful payment, you will have to cross‐check the payment with the gateway 
to make sure it actually happened through the SSLCOMMERZ fraud prevention SOAP based API. This will 
ensure elimination of fraud at the online store. 

IPN Mechanism 
After  a  payment  is  successfully  made,  the  customer  is  returned  back  to  the  success  page  of  the  online 
store. After loading the success page, the store must cross check whether the payment made was valid or 
invalid  to  prevent  fraud.  The  gateway  will  send  a  payment  ID  in  POST  method  in  the  success  page 
parameterized as ‘val_id’. You have to extract the ID in your page and send a request with a SOAP client 
back to SSLCOMMERZ.  

You write your IPN script in the scripting or programming language of your choice and host it on your web 
server. You can use sample code provided by SSLCOMMERZ as a starting point. 

As  a  good  programming  practice,  as  well  as  to  keep  things  simple,  your  IPN  script  should  receive  POST 
parameters from SSLCOMMERZ and dispatch it immediately to another routine or process that handles the 
business logic associated with the message. If your script is structured in this way, it will receive a message 
against a query and dispatch it for processing by your application logic. 

The IPN script must 

1. Wait for an HTTPS post from SSLCOMMERZ.  
2. Create a request that contains exactly the same IPN variables and values in the same order.  
3. Send SOAP client request to www.sslcommerz.com.bd’s Live or TestBox URL depending on 
whether you are going live or testing your IPN script in the TestBox.  
4. Wait for a response from SSLCOMMERZ, which is either VALID or INVALID TRANSACTION.  
5. If the response is VALID, perform the following checks:  
o Confirm your system that the payment status is completed. 

Page 7 of 10 
 SSLCOMMERZ sends IPN messages for pending and denied payments as well; do not ship 
until the payment has cleared. 

o Use the transaction ID to verify that the transaction has not already been processed, which 
prevents duplicate transactions from being processed. 

Typically, you store transaction IDs in a database so that you know you are only processing 
unique transactions. 

o Verify that the price, item description, and so on, match the transaction on your website. 

This check provides additional protection against fraud. 

6. If the verified response passes the checks, take action based on the verification; otherwise, do not 
ship or deliver the product.  
7. If the response is INVALID TRANSACTION, save the transaction ID for further investigation. There 
might be some fraudulent activity involved. 

An Example 
The following is a sample PHP code for TestBox integration that shows how to verify a transaction using the 
SSLCOMMERZ WEB SERVICE. The SOAP server at the gateway end will respond to the store whether the ID 
(val_id)  is  valid  or  not.  Thus  it  will  ensure  prevention  from  any  fraudulent  activities  at  the  merchant’s 
online store by cross checking the payment. 

After the transaction is completed SSLCOMMERZ will send the Success Page with five parameters. 

1. tran_id: the ID that your store sent to SSLCOMMERZ for transaction request. 

2. val_id: the ID that will be used to cross‐check the transaction. 

3. amount: The amount of money that has been transacted. 

4. card_type : The type of card the customer transacted along with bank name. For example, if you 
transect from Dutch Bangla bank gateway with Nexus card, The card type field's value will be 
NEXUS‐Dutch bangla. 

5. store_amount:  This is the amount the store will get from the gateway after deducting the charges. 

The val_id will validate the transaction. You have to enable WEB SERVICE at your server end. The validation 
process may look like this:  

Page 8 of 10 
$val_id = $_POST['val_id']; 

$tran_id = $_POST['tran_id']; 

$amount = $_POST['amount']; 

$ card_type = $_POST['card_type']; 

$store_amount = $_POST['store_amount']; 

try{ 

       $c = new soapclient('https://www.sslcommerz.com.bd/testbox/validator/validationserver.php?wsdl'); 

     } 

catch (Exception $e) { 

    echo 'Caught exception: ',  $e‐>getMessage(), "\n"; 

                } 

$res = $c‐>checkValidation($val_id);  //  here $res will get ‘VALID’ if the transaction is a valid one 

if (strcmp ($res, "VALID") == 0) {  

  

                /******  Write your success actions here  *******/ 

} 

else  {  

// PAYMENT INVALID 

/******  Take necessary steps required  *******/ 

} 

If  the  transaction  is  not  valid  or  a  fraud  has  been  detected  then  SSLCOMMERZ  will  reply  INVALID 
TRANSACTION. 

If    WEB  SERVICE  is  not  available  in  your  system  or  you  feel  any  complexity  implanting  it,  you  can 
temporarily use fopen. If you want to use fopen then contact our technical team. 

We highly recommend you to use WEB SERVICE for better security.  

Page 9 of 10 
 

For Live transaction the SOAP client will be  

$c = new soapclient('https://www.sslcommerz.com.bd/validator/validationserver.php?wsdl'); 

There will be no change for the rest parts. 

4. Support 
For technical support, contact sslcommerz.com.bd as follows: 

• Call  01730070548,  01730070547  (BST),  from  Saturday  to  Thursday,  24  hours  a  day  (excluding 
holidays). 

• Send email to support@sslcommerz.com.bd. 

END OF DOCUMENT 

Page 10 of 10