SSLCOMMERZ Connectivity Guide v2.1
SSLCOMMERZ Connectivity Guide v2.1
SSLCOMMERZ Connectivity Guide v2.1
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.
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 [email protected].
END OF DOCUMENT
Page 10 of 10