NAV
bash javascript php html

Introduction

Welcome to the Vapulus third-party API reference.
This document instructs third-party applications in how to access our API in order to make and schedule transactions on behalf of users.
Use our API to get the most out of Vapulus.

There are two ways to Integrate with Vapulus API
Hosted Session
  please use Hosted Session Integration Module
Direct API -for PCI DSS certified Merchant
   for one step payment
    call Make Transaction

Available Operations

  1. Make Transaction
    Add user and Make transactions using User Data and Card Data.

  2. Transactions List
    Get all transactions.

  3. Transaction Info
    Get all information of a successfull transaction.

  4. Session Retrieve
    Get information stored in session.

  5. Session Pay
    Make transaction using hosted session.

  6. Transaction Status
    Get Transaction status.

Sample Code

We have included sample code in NODE.js and PHP!. For testing, you can use CURL.

You can view code examples in the dark area on the right side of this window. Use the tabs on the top right to switch programming languages.

Authentication

Vapulus requires authentication before allowing API access. You can register a new merchant account though our merchant portal to begin using our API.

Generating Secure Hash

In order to generate your hash secret:

  1. Order all sent parameters from A-Z except AppId and Password
  2. Concatenate parameters as URL query parameters, e.g. param1=param1Value&param2=param2Value
  3. Hash the concated string using SHA-256 HMAC with your hash secret. You can get your hash secret from your merchant account.

Example

// https://repl.it/@islamvapulus/Integration
function generateHash(hashSecret,postData) {
    //sort input param
    var orderedData = {};
    Object.keys(postData).sort().forEach(function(key) {
            orderedData[key] = postData[key];
    });

    //format uri encoding of param Object
    var message = '';
    for (var i in orderedData) {
            message += '&' + i + '=' + orderedData[i];
    }
    message = message.substr(1);

    //generate the secure hash
    var cr = require('crypto');
    var Buffer = require('buffer').Buffer;
    var privateKey = new Buffer(hashSecret, 'hex', 'ascii');

    var hash = cr
                .createHmac('sha256', privateKey)
                .update(message)
                .digest('hex');

    return hash;
}

//send params without apiId and password
var postData ={
    cardNum : '5123456789012346',
    cardExp : 2105,
    cardCVC : 123,
    holderName :'John Doe',
    mobileNumber :'20100000000000'
};
//your hash secret from app you create on app.vapulus.com/business
var hashSecret='C0DF9A7B3819968807A9D4E48D0E65C6';

// this value of secureHash should be with the request
var mySecureHash = generateHash(hashSecret,postData);
//output 
//6975f8f502e5972722a6d8760cc558e7867f36a312a5d336c4ba983dcfb81691
//https://repl.it/@islamvapulus/Integration-php
function generateHash($hashSecret,$postData) {
    ksort($postData);

    $message="";
    $appendAmp=0;
    foreach($postData as $key => $value) {
            if (strlen($value) > 0) {
                if ($appendAmp == 0) {
                    $message .= $key . '=' . $value;
                    $appendAmp = 1;
                } else {
                    $message .= '&' . $key . "=" . $value;
                }
            }
        }

    $secret = pack('H*', $hashSecret);

    return hash_hmac('sha256', $message, $secret);
}

$postData = array(
    "cardNum" =>  "5123456789012346",
    "cardExp" =>  2105,
    "cardCVC" =>  123,
    "holderName" => "John Doe",
    "mobileNumber" => "20100000000000"
);

$hashSecret= 'C0DF9A7B3819968807A9D4E48D0E65C6';

$secureHash = generateHash($hashSecret,$postData);
//output
//6975f8f502e5972722a6d8760cc558e7867f36a312a5d336c4ba983dcfb81691

If your requested parameters are as follows:

Param Name Example Value
cardNum 5123456789012346
cardExp 2105
cardCVC 123
holderName John Doe
mobileNumber 20100000000000

After order and concat string will read:
cardCVC=123&cardExp=2105&cardNum=5123456789012346&holderName=John Doe&mobileNumber=20100000000000

If the hash secret is: C0DF9A7B3819968807A9D4E48D0E65C6

The secure hash value is:
6975f8f502e5972722a6d8760cc558e7867f36a312a5d336c4ba983dcfb81691

Using NPM package to generate secure hash

var vapulusHash = require('vapulus-hashing-pkg');

var myRequestParams = {
    cardNum : '5123456789012346',
    cardExp : 2105,
    cardCVC : 123,
    holderName :'John Doe',
    mobileNumber :'20100000000000'
};
var hashSecret='C0DF9A7B3819968807A9D4E48D0E65C6';

var secureHash = vapulusHash.generateHash(hashSecret,myRequestParams);
//output
//6975f8f502e5972722a6d8760cc558e7867f36a312a5d336c4ba983dcfb81691

If you wish to use our NPM package to generate your secure hash string, follow these steps:

  1. Install NPM package npm install vapulus-hashing-pkg –save
  2. The package is now installed in your project. You can now use it as shown on the right hand side of the screen.

Hosted session

The SessionJS JavaScript library is a part of the vapulus Payment Gateway that allows simple payment integrations for merchant mobile applications and websites.
with functions that include; Configures a Hosted Session interaction, Stores the input from the hosted field into the session, Sets focus on the specified hosted field and more. vapulus Payment Gateway Service delivers an enhanced digital payment experience on any device. This enables customers to accept and process transactions across e-commerce, m-commerce and cardholder present channels and includes; Hosted Checkout, Hosted Session, Direct Payment and Batch. Vapulus is a financial technical company that provides electronic payments globally for Individuals, Business, Travel and Leisure, Airlines, Telecommunications, Retail, Gaming, Entertainment and more.

Integration Steps:

  1. Card form
    Create an html form for the user to add card and include our hosted session script.

  2. Session Retrieve
    Get information stored in the session.

  3. Session Pay
    Process the transaction using the hosted session.

  4. Transaction Status
    Get Transaction status.

Card form

<!DOCTYPE html>
<html>

<head>
    <title>Test Hosted Session</title>
    <link rel="icon" href="https://www.vapulus.com/favicon.ico" type="image/x-icon"/>

    <link href="https://getbootstrap.com/docs/3.3/dist/css/bootstrap.min.css" rel="stylesheet">

    <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
    <script src="https://api.vapulus.com:1338/app/session/script?appId=XXXXXXXX"></script>
    <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE -->
    <style id="antiClickjack">
        body {
            display: none !important;
        }
    </style>
</head>

<body>
    <section class="text-center">
        <div class="container">
            <h1 class="jumbotron-heading">Hosted Session</h1>
            <p class="lead text-muted">Vapulus Hosted Session Integration Sample.</p>
        </div>
    </section>
    <!-- CREATE THE HTML FOR THE PAYMENT PAGE -->
    <div class="container">
        <div class="row">
            <div class="contents col-12">
                <fieldset>
                    <div class="form-group">
                        <label class="col-md-8 control-label" for="cardNumber">Card number:</label>
                        <div class="col-md-8">
                            <input type="text" id="cardNumber" class="form-control input-md" value="" readonly />
                        </div>
                    </div>
                    <div class="form-group">
                        <label class="col-md-8 control-label" for="cardMonth">Expiry month:</label>
                        <div class="col-md-8">
                            <input type="text" id="cardMonth" class="form-control input-md" value="" />
                        </div>
                    </div>
                    <div class="form-group">
                        <label class="col-md-8 control-label" for="cardYear">Expiry year:</label>
                        <div class="col-md-8">
                            <input type="text" id="cardYear" class="form-control input-md" value="" />
                        </div>
                    </div>
                    <div class="form-group">
                        <label class="col-md-8 control-label" for="cardCVC">Security code:</label>
                        <div class="col-md-8">
                            <input type="text" id="cardCVC" class="form-control input-md" value="" readonly />
                        </div>
                    </div>
                </fieldset>
                <button class="btn btn-primary pull-right" id="payButton" onclick="pay();">Pay</button>
            </div>
        </div>


        <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING -->
        <script type="text/javascript">
            if(window.PaymentSession){
                PaymentSession.configure({
                    fields: {
                        // ATTACH HOSTED FIELDS IDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD
                        card: {
                            cardNumber: "cardNumber",
                            securityCode: "cardCVC",
                            expiryMonth: "cardMonth",
                            expiryYear: "cardYear"
                        }
                    },
                    callbacks: {
                        initialized: function (err, response) {
                            console.log("init....");
                            console.log(err, response);
                            console.log("/init.....");
                            // HANDLE INITIALIZATION RESPONSE
                        },
                        formSessionUpdate: function (err,response) {
                            console.log("update callback.....");
                            console.log(err,response);
                            console.log("/update callback....");

                            // HANDLE RESPONSE FOR UPDATE SESSION
                            if (response.statusCode) {
                                if (200 == response.statusCode) {
                                    console.log("Session updated with data: " + response.data.sessionId);
                                } else if (201 == response.statusCode) {
                                    console.log("Session update failed with field errors.");

                                    if (response.message) {
                                        var field = response.message.indexOf('valid')
                                        field = response.message.slice(field + 5, response.message.length);
                                        console.log(field + " is invalid or missing.");
                                    }
                                } else {
                                    console.log("Session update failed: " + response);
                                }
                            }
                        }
                    }
                });
            }else{
                alert('Fail to get app/session/script !\n\nPlease check if your appId added in session script tag in head section?')
            }

            function pay() {
                // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
                PaymentSession.updateSessionFromForm();
            }
        </script>

</body>

</html>

 

1- Create an html page to include our hosted session script with your appId as a query parameter in the url
<script src="https://api.vapulus.com:1338/app/session/script?appId=xxxxx"/></script>

 

2- Add the antiClickjack style in your page
<style id="antiClickjack">body {disply: none !important;}</style>

3- Add an Input form for
 - card Number
 - card month
 - card year
 - card security code
with a unique id for each of those fields

<input type="text" id="cardNumber" value="" readonly />
<input type="text" id="cardMonth" value="" />
<input type="text" id="cardYear" value="" />
<input type="text" id="cardCVC" value="" readonly />

and please make sure the card number and card security code input are read only.
you will need these input ids’ to configure PaymentSession function

4- Configure PaymentSession.configure function with card input IDs’ and handle callback function after you initialized and formSessionUpdate events

 

5- Add a call to PaymentSession.updateSessionFromForm(); under the pay button.

Session retrieve

curl -X POST "https://api.vapulus.com:1338/app/session/retrieve" \
  -d appId=XXX \
  -d password=XXX \
  -d hashSecret=XXX \
  -d sessionId=XXX 
//https://repl.it/@islamvapulus/node-http-request-with-hashing
var vapulusHash = require('vapulus-hashing-pkg');
var request = require('request');


var postData = {
    sessionId : 'XXXXXXXXXXXXXXXX'
};

var secureHash='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
postData.hashSecret=vapulusHash.generateHash(secureHash,postData);

postData.appId='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
postData.password='XXXXXXXX';

var _option = {
  url: 'https://api.vapulus.com:1338/app/session/retrieve',
  method: 'POST',
  // rejectUnauthorized: false,
  form:postData
};

request.post(_option,
  function (err, response, body) {
    if (err)
      console.log(err);
      else
          console.log(response.body);
  }
);
//https://repl.it/@islamvapulus/php-http-request-with-hashing
function generateHash($hashSecret,$postData) {
    ksort($postData);
        $message="";
        $appendAmp=0;
    foreach($postData as $key => $value) {
            if (strlen($value) > 0) {
                if ($appendAmp == 0) {
                    $message .= $key . '=' . $value;
                    $appendAmp = 1;
                } else {
                    $message .= '&' . $key . "=" . $value;
                }
            }
        }

    $secret = pack('H*', $hashSecret);
    return hash_hmac('sha256', $message, $secret);
}

function HTTPPost($url, array $params) {
        $query = http_build_query($params);
        $ch    = curl_init();
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $query);
        $response = curl_exec($ch);
        curl_close($ch);
        return $response;
    }

$postData = array(
    'sessionId' =>  'XXXXXXXXXXXXXXXX'
);

$secureHash= 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$postData['hashSecret'] = generateHash($secureHash,$postData);

$postData['appId']='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$postData['password']='XXXXXXXX';

$url ='https://api.vapulus.com:1338/app/session/retrieve';

$output=HTTPPost($url,$postData);

print_r($output);

The above request will returns JSON structured like this:

{
    "statusCode": 200,
    "message": "Success Message",
    "data": {
        "cardNum": "XXXXXX******XXXX",
        "cardExp": "XXXX"
    }
}

POST https://api.vapulus.com:1338/app/session/retrieve

This allows the third-party applications to retrieve masked card number and expiry date from stored session data.

In the following you will find the parameters you will need:

Params Description restriction
sessionId ID of session return from card form callback required

Session pay

curl -X POST "https://api.vapulus.com:1338/app/session/pay" \
  -d appId=XXX \
  -d password=XXX \
  -d hashSecret=XXX \
  -d sessionId=XXX \
  -d mobileNumber=XXX \
  -d email=XXX \
  -d firstName=XXX \
  -d lastName=XXX \
  -d onAccept=XXX \
  -d onFail=XXX \
  -d amount=XXX \
  -d merchantReferenceId=XXX \
  -d notificationCallbackUrl=XXX \
//https://repl.it/@islamvapulus/node-http-request-with-hashing
var vapulusHash = require('vapulus-hashing-pkg');
var request = require('request');


var postData = {
    sessionId : 'XXXXXXXXXXXXXXXX',
    mobileNumber :'XXXXXXXXXXX',
    email :'XXXX@XXXX.XXX',,
    firstName : 'xxxxxxxx',
    lastName : 'xxxxxxxx',
    amount: 'XXXXX.XX',
    onAccept: 'https://example.com/success',
    onFail: 'http://example.com/fail',
    notificationCallbackUrl: 'xxxxxxxxxxxxxxxxx',
    merchantReferenceId: 'xxxxxxxx'
};

var secureHash='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
postData.hashSecret=vapulusHash.generateHash(secureHash,postData);

postData.appId='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
postData.password='XXXXXXXX';

var _option = {
  url: 'https://api.vapulus.com:1338/app/session/pay',
  method: 'POST',
  // rejectUnauthorized: false,
  form:postData
};

request.post(_option,
  function (err, response, body) {
    if (err)
      console.log(err);
      else
          console.log(response.body);
  }
);
//https://repl.it/@islamvapulus/php-http-request-with-hashing
function generateHash($hashSecret,$postData) {
    ksort($postData);
        $message="";
        $appendAmp=0;
    foreach($postData as $key => $value) {
            if (strlen($value) > 0) {
                if ($appendAmp == 0) {
                    $message .= $key . '=' . $value;
                    $appendAmp = 1;
                } else {
                    $message .= '&' . $key . "=" . $value;
                }
            }
        }

    $secret = pack('H*', $hashSecret);
    return hash_hmac('sha256', $message, $secret);
}

function HTTPPost($url, array $params) {
        $query = http_build_query($params);
        $ch    = curl_init();
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $query);
        $response = curl_exec($ch);
        curl_close($ch);
        return $response;
    }

$postData = array(
    'sessionId' =>  'XXXXXXXXXXXXXXXX',
    'mobileNumber' => 'XXXXXXXXXXX',
    'email' => 'XXXX@XXXX.XXX',
    'amount' => 'XXXXX.XX',
    'firstName' => 'xxxxxxxx',
    'lastName' => 'xxxxxxxx',
    'onAccept' => 'https://example.com/success',
    'onFail' => 'http://example.com/fail',
    'notificationCallbackUrl' => 'xxxxxxxxxxxxxxxxxx',
    'merchantReferenceId' => 'xxxxxxxxxxxxxxxxx'
);

$secureHash= 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$postData['hashSecret'] = generateHash($secureHash,$postData);

$postData['appId']='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$postData['password']='XXXXXXXX';

$url ='https://api.vapulus.com:1338/app/session/pay';

$output=HTTPPost($url,$postData);

print_r($output);

The above request will returns JSON structured like this:

{
    "statusCode": 200,
    "message": "Success Message",
    "data": {
        "status": "pending",
        "action": "process 3Ds",
        "transactionId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "htmlBodyContent" : "XXXXXXXXXXXXX"
    }
}

POST https://api.vapulus.com:1338/app/session/pay

Allows the third-party applications to pay using hosted session data.


In the following you will find the parameters you will need:

Params Description restriction
sessionId ID of session return from card form callback required
mobileNumber mobile number of card owner with country code required
email email of card owner required
amount amount requested in the transaction required
firstName first name of card owner required
lastName last name of card owner required
onAccept Full callback url to redirect when user accept transaction optional
onFail Full callback url to redirect when user fail to accept transaction optional
notificationCallbackUrl The web hook url of the transaction optional
merchantReferenceId merchant reference in the transaction optional


Direct API

BaseUrl: https://api.vapulus.com:1338/
HTTP Method: POST

Available operations:

  1. Make Transaction
    Add user and Make transactions using User Data and Card Data.

Make transaction

curl -X POST "https://api.vapulus.com:1338/app/makeTransaction" \
  -d appId=XXX \
  -d password=XXX \
  -d hashSecret=XXX \
  -d cardNum=XXX \
  -d cardExp=XXX \
  -d cardCVC=XXX \
  -d holderName=XXX \
  -d mobileNumber=XXX \
  -d email=XXX \
  -d onAccept=XXX \
  -d onFail=XXX \
  -d amount=XXX  \
  -d merchantReferenceId=XXX \
  -d notificationCallbackUrl=XXX \ 

//https://repl.it/@islamvapulus/node-http-request-with-hashing
var vapulusHash = require('vapulus-hashing-pkg');
var request = require('request');


var postData = {
    cardNum : 'XXXXXXXXXXXXXXXX',
    cardExp : '2105',
    cardCVC : '123',
    holderName :'John Doe',
    mobileNumber :'XXXXXXXXXXX',
    email :'XXXX@XXXX.XXX',
    amount: 'XXXXX.XX',
    onAccept: 'https://example.com/success',
    onFail: 'http://example.com/fail',
    notificationCallbackUrl: 'xxxxxxxxxxxxxxxxx',
    merchantReferenceId: 'xxxxxxxx'
};

var secureHash='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
postData.hashSecret=vapulusHash.generateHash(secureHash,postData);

postData.appId='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
postData.password='XXXXXXXX';

var _option = {
  url: 'https://api.vapulus.com:1338/app/makeTransaction',
  method: 'POST',
  // rejectUnauthorized: false,
  form:postData
};

request.post(_option,
  function (err, response, body) {
    if (err)
      console.log(err);
      else
          console.log(response.body);
  }
);
//https://repl.it/@islamvapulus/php-http-request-with-hashing
function generateHash($hashSecret,$postData) {
    ksort($postData);
        $message="";
        $appendAmp=0;
    foreach($postData as $key => $value) {
            if (strlen($value) > 0) {
                if ($appendAmp == 0) {
                    $message .= $key . '=' . $value;
                    $appendAmp = 1;
                } else {
                    $message .= '&' . $key . "=" . $value;
                }
            }
        }

    $secret = pack('H*', $hashSecret);
    return hash_hmac('sha256', $message, $secret);
}

function HTTPPost($url, array $params) {
        $query = http_build_query($params);
        $ch    = curl_init();
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $query);
        $response = curl_exec($ch);
        curl_close($ch);
        return $response;
    }

$postData = array(
    'cardNum' =>  'XXXXXXXXXXXXXXXX',
    'cardExp' =>  2105,
    'cardCVC' =>  123,
    'holderName' => 'John Doe',
    'mobileNumber' => 'XXXXXXXXXXX',
    'email' => 'XXXX@XXXX.XXX',
    'onAccept' => 'https://example.com/success',
    'onFail' => 'http://example.com/fail',
    'amount' => 'XXXXX.XX',
    'notificationCallbackUrl' => 'xxxxxxxxxxxxxxxxxx',
    'merchantReferenceId' => 'xxxxxxxxxxxxxxxxx'
);

$secureHash= 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$postData['hashSecret'] = generateHash($secureHash,$postData);

$postData['appId']='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$postData['password']='XXXXXXXX';

$url ='https://api.vapulus.com:1338/app/makeTransaction';

$output=HTTPPost($url,$postData);

print_r($output);

The above request will returns JSON structured like this:


// case no 3dSecure :- the response for transaction :

{
    "stautsCode": 200,
    "message": "Success Message",
    "data": {
        "cardId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "userId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "transactionId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "status": "accepted"
    }
}

// case 3dSecure :- the response for transaction :
// render html in  htmlBodyContent then user can accept transaction

{
    "stautsCode": 200,
    "message": "Transaction Accepted Successfully",
    "data": {
        "status": "pending",
        "action": "process 3Ds",
        "cardId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "userId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "transactionId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "htmlBodyContent":"contains html"
    }
}

POST https://api.vapulus.com:1338/app/makeTransaction

Allows the third-party app to add user and make transaction.

In the following you will find the parameters you will need:

Params Description restriction
cardNum 16-digit card number required
cardExp expiry date of the card, YYMM required
cardCVC CVC number on back of card required
holderName cardholder name required
mobileNumber mobile number of card owner with country code required
email email of card owner required
amount amount requested in the transaction required
onAccept Full callback url to redirect when user accept transaction (needed only if user uses 3ds-enabled card) required
onFail Full callback url to redirect when user fail to accept transaction (needed only if user uses 3ds-enabled card) required
notificationCallbackUrl The web hook url of the transaction optional
merchantReferenceId merchant reference in the transaction optional


Transaction

BaseUrl: https://api.vapulus.com:1338/
HTTP Method: POST

Available operations:

  1. Transactions List
    Get all transactions.

  2. Transaction Info
    Get all information of a successfull transaction.

  3. Transaction Status
    Get Transaction status.

Transactions list

curl -X POST "https://api.vapulus.com:1338/app/transactions/list" \
  -d appId=XXX \
  -d password=XXX \
  -d hashSecret=XXX \
  -d userId=XXX \
  -d status=XXX \
  -d sorting=XXX \
  -d fromDate=XXX \
  -d toDate=XXX \
  -d pageNum=XXX 
//https://repl.it/@islamvapulus/node-http-request-with-hashing
var vapulusHash = require('vapulus-hashing-pkg');
var request = require('request');

var postData = {
    userId: 'XXXXXXXX',
    status: 'XXXXXXXX',
    sorting: 'XXXXXXXX',
    fromDate: 'XXXXXXXX',
    toDate: 'XXXXXXXX',
    pageNum: 'XXXXXXXX'
};

var secureHash='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
postData.hashSecret=vapulusHash.generateHash(secureHash,postData);

postData.appId='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
postData.password='XXXXXXXX';

var _option = {
  url: 'https://api.vapulus.com:1338/app/transactions/list',
  method: 'POST',
  // rejectUnauthorized: false,
  form:postData
};

request.post(_option,
  function (err, response, body) {
    if (err)
      console.log(err);
      else
          console.log(response.body);
  }
);
//https://repl.it/@islamvapulus/php-http-request-with-hashing
function generateHash($hashSecret,$postData) {
    ksort($postData);
        $message="";
        $appendAmp=0;
    foreach($postData as $key => $value) {
            if (strlen($value) > 0) {
                if ($appendAmp == 0) {
                    $message .= $key . '=' . $value;
                    $appendAmp = 1;
                } else {
                    $message .= '&' . $key . "=" . $value;
                }
            }
        }

    $secret = pack('H*', $hashSecret);
    return hash_hmac('sha256', $message, $secret);
}

function HTTPPost($url, array $params) {
        $query = http_build_query($params);
        $ch    = curl_init();
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $query);
        $response = curl_exec($ch);
        curl_close($ch);
        return $response;
    }

$postData = array(
    'userId' =>  'XXXXXXXX',
    'status' => 'XXXXXXXX',
    'fromDate' => 'XXXXXXXX',
    'toDate' => 'XXXXXXXX',
    'sorting' => 'XXXXXXXX',
    'pageNum' => 'XXXXXXXX'
);

$secureHash= 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$postData['hashSecret'] = generateHash($secureHash,$postData);

$postData['appId']='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$postData['password']='XXXXXXXX';

$url ='https://api.vapulus.com:1338/app/transactions/list';

$output=HTTPPost($url,$postData);

print_r($output);

The above request will returns JSON structured like this:

// the response
{
    "statusCode": 200,
    "message": "Success Message",
    "data": {
        "count": 19,
        "transaction": [
            {
                "transactionId": "cfd2478b-b945-42e4-a1be-16eca8e5fd88",
                "fromId": "884ed6e3-0e36-407b-83c0-aa9abb20b682",
                "toId": "2a510161-381c-4ae7-88ba-fea9e119abe5",
                "amount": 2020,
                "status": "1",
                "currencyIso": "EGP",
                "from": {},
                "to": {}
            }
]
}

POST https://api.vapulus.com:1338/app/transactions/list

In the following you will find the parameters you will need:

Params Description restriction
userId ID of user registered on our system required
status status of the transactions optional
fromDate starting date optional
toDate end date optional
sorting the way the data is ordered optional
pageNum which page of transactions list optional

Transaction info

curl -X POST "https://api.vapulus.com:1338/app/transactionInfo" \
  -d appId=XXX \
  -d password=XXX \
  -d hashSecret=XXX \
  -d transactionId=XXX 
//https://repl.it/@islamvapulus/node-http-request-with-hashing
var vapulusHash = require('vapulus-hashing-pkg');
var request = require('request');


var postData = {
  transactionId: 'XXXXXXXX'
};

var secureHash='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
postData.hashSecret=vapulusHash.generateHash(secureHash,postData);

postData.appId='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
postData.password='XXXXXXXX';

var _option = {
  url: 'https://api.vapulus.com:1338/app/transactionInfo',
  method: 'POST',
  // rejectUnauthorized: false,
  form:postData
};

request.post(_option,
  function (err, response, body) {
    if (err)
        console.log(err);
      else
          console.log(response.body);
  }
);
//https://repl.it/@islamvapulus/php-http-request-with-hashing
function generateHash($hashSecret,$postData) {
    ksort($postData);
        $message="";
        $appendAmp=0;
    foreach($postData as $key => $value) {
            if (strlen($value) > 0) {
                if ($appendAmp == 0) {
                    $message .= $key . '=' . $value;
                    $appendAmp = 1;
                } else {
                    $message .= '&' . $key . "=" . $value;
                }
            }
        }

    $secret = pack('H*', $hashSecret);
    return hash_hmac('sha256', $message, $secret);
}

function HTTPPost($url, array $params) {
        $query = http_build_query($params);
        $ch    = curl_init();
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $query);
        $response = curl_exec($ch);
        curl_close($ch);
        return $response;
    }

$postData = array(
    'transactionId' => 'XXXXXXXX'
);

$secureHash= 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$postData['hashSecret'] = generateHash($secureHash,$postData);

$postData['appId']='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$postData['password']='XXXXXXXX';

$url ='https://api.vapulus.com:1338/app/transactionInfo';

$output=HTTPPost($url,$postData);

print_r($output);

The above request will returns JSON structured like this:

{
  "msg" : "response msg",
  "statusCode": 200,
  "data": {
    "transactionId": XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX,
    "fromId": XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX,
    "toId": XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX,
    "amount": XXXXX,
    "currencyIso": XXX,
    "mobileNumber": XXXXXXXXXXX,
    "status": 1 [0 for accepted, 1 for pending, 2 for rejected, and 3 for canceled],
    "transactionType": "request",
    "transactionCode": "5623626",
    "createdAt": "2018-04-05T06:59:33.000Z",
    "updatedAt": "2018-04-05T06:59:33.000Z"
  }
}

POST https://api.vapulus.com:1338/app/transactionInfo

Get all information of a successfull transaction.

In the following you will find the parameters you will need:

Params Description restriction
transactionId ID of successful transaction required

Transaction Status

curl -X POST "https://api.vapulus.com:1338/app/transaction/status" \
  -d transactionId=XXX \
  -d merchantId=XXX 
var request = require('request');

var postData = {
transactionId: 'XXXXXXXX',
merchantId: 'XXXXXXXX',
};


var _option = {
  url: 'https://api.vapulus.com:1338/app/transaction/status',
  method: 'POST',
  // rejectUnauthorized: false,
  form:postData
};

request.post(_option,
  function (err, response, body) {
    if (err)
      console.log(err);
      else
          console.log(response.body);
  }
);

function HTTPPost($url, array $params) {
        $query = http_build_query($params);
        $ch    = curl_init();
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HEADER, false);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $query);
        $response = curl_exec($ch);
        curl_close($ch);
        return $response;
    }

$postData = array(
    'transactionId' =>  'XXXXXXXX',
    'merchantId' =>  'XXXXXXXX'
);

$url ='https://api.vapulus.com:1338/app/transaction/status';

$output=HTTPPost($url,$postData);

print_r($output);

The above request will returns JSON structured like this:

{
   "stautsCode": 200,
   "message": "Success Message",
   "data": {
       "status": "XXXXX" [accepted, pending, rejected, canceled],
   }
}

POST https://api.vapulus.com:1338/app/transaction/status

Get Transaction status, it could be accepted, pending, rejected or canceled.

In the following you will find the parameters you will need:

Params Description restriction
transactionId ID of successful transaction required
merchantId ID of merchant @ vapulus system required

Notification Callback Url

POST Notification Callback Url

The APIs use webhooks for event notification.
Webhooks are HTTP callbacks that receive notification messages for events.
A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur.

Vapulus will send an informative HTTP POST request to your notification callback endpoint on your own application server with the current details of transaction.

You should confgure an endpoint that takes the following body .

In the following you will find the parameters you will need:

Params Description restriction
notificationType Type of notification (transaction,charge) required
appId appId that you send when create transaction required
transactionId transaction Id required
merchantReferenceId your reference id required
amount transaction amount required
currency transaction amount currency required
status transaction status (accepted,pending,rejected,cancelled) required
createdAt transaction createdAt required
hashSecret hashing the body with app secretKey to ensure that request from vapulus required

Generating hashSecret
In order to generate your hash secret:

  1. Order all sent parameters from A-Z except hashSecret
  2. Stringify parameters as URL query parameters, e.g. param1=param1Value&param2=param2Value
  3. Hash the stringified string using SHA-256 HMAC with your hash secret. You can get your hash secret from your merchant account.

Test Data

you can use one of these test cards to test your requests. Just make sure that your test MID is selected as the default MID on the system.

Card Type PAN Expiry Date CVC 3-D Secure Enrolled
MasterCard 5123450000000008 May-2025 100 Y
Visa 4508750015741019 May-2025 100 Y
MasterCard 5111111111111118 May-2025 100 N
Visa 4012000033330026 May-2025 100 N

Please note that you won’t get a rejected transaction if you provide a wrong expiration date or CVC in test mode
If you want to test a rejected transaction, you can use on of these cards:

Card Type PAN Expiry Date CVC 3-D Secure Enrolled
MasterCard 2223000000000007 May-2025 100 Y
MasterCard 2223000000000023 May-2025 100 N

Response Code & Errors

You will receive a statusCode parameter with each response.

Code Meaning
200 OK Request, check data object for more information
201 invaild AppId or Password, check msg object for more information
202 app is not active, check msg object for more information
203 invalid secureHash, check msg object for more information