VoguePay Documentation

Getting Started

Integration is seamless and easy. Integration to your platform can be done by using

1. Simple HTML Forms
2. Mobile / Server to server API
3. Inline Payment _{new_releasesNEW}
4. Command API (Automate function on your account.)
5. Query transaction responses

Know The Parameters

First, take a few minutes to familiarize yourself with the supported parameters required to complete your integration through our API.

Choosing An Integration Option

[sitename] integration options has been simplified and made seamless. It is just as simple as copying our sample codes and changing the required parameters to suit your needs.

new_releasesNEW Integrations can now be completed inline. This mean you do not have to redirect your buyers to our platform before your transactions are completed.

No worries! If you have previously integrated our API, our platform is backward compatible. Your redirections will work without any hassels.

Simple HTML Form

Integration is as simple as copying the HTML form below into your website.

Remember :

• For sandbox / development, user DEMO as the merchant ID
• Simply go live by changing the Merchant ID to the live merchant ID, which can be found on your dashboard when logged in.

To enable the inline payment option, include the [sitename] inline script anywhere on your page but above Inline Payment Script (2)

Inline Payment script (1)

HTML Form 1

This form explains the usage of item_x, description_x and price_x explained in 'Accepted Parameters' section

<form id='payform' onsubmit='return false;' method='POST' action='https://voguepay.com/pay/'>
    <input type='hidden' name='v_merchant_id' value='qa331322179752' />
    <input type='hidden' name='merchant_ref' value='234-567-890' />
    <input type='hidden' name='memo' value='Bulk order from McAckney Web Shop' />

    <input type='hidden' name='item_1' value='Face Cap' />
    <input type='hidden' name='description_1' value='Blue Zizi facecap' />
    <input type='hidden' name='price_1' value='2000' />

    <input type='hidden' name='item_2' value='Laban T-shirt' />
    <input type='hidden' name='description_2' value='Green XXL' />
    <input type='hidden' name='price_2' value='3000' />

    <input type='hidden' name='item_3' value='Black Noni Shoe' />
    <input type='hidden' name='description_3' value='Size 42' />
    <input type='hidden' name='price_3' value='8000' />

    <input type='hidden' name='developer_code' value='pq7778ehh9YbZ' />
    <input type='hidden' name='store_id' value='25' />

    <input type='hidden' name='total' value='13000' />

    <input type='hidden' name='name' value='Customer name'/>
    <input type='hidden' name='address' value='Customer Address'/>
    <input type='hidden' name='city' value='Customer City'/>
    <input type='hidden' name='state' value='Customer State'/>
    <input type='hidden' name='zipcode' value='Customer Zip/Post Code'/>
    <input type='hidden' name='email' value='Customer email'/>
    <input type='hidden' name='phone' value= 'Customer phone '/>
    <input type='image' src='http://voguepay.com/images/buttons/buynow_blue.png' alt='Submit' />
</form> 
                            

One more thing .... Include the script below on your page. This script helps to submit your form and completes the inline payment cycle.

Inline Payment Script (2)

Sumbit form for processing. Include the [sitename] inline script 2 below [voguepay] inline script 1.

When the form is submitted. The javacript below runs and submits your form while you are still on the same page. No redirections required.

NB: If you do not wish to use the inline payment options, simply do not include the javascript files in your codes.

<script>
    Voguepay.init({form:'payform'});
</script>
                                

Notifications With Simple HTML Forms

Sample HTML form 2

As explained above. Remember to include the [sitename] Inline Payment Script (1)

<form method='POST' id='payform' action='//voguepay.com/pay/' onsubmit='return false;'>
    <input type='hidden' name='v_merchant_id' value='qa331322179752' />
    <input type='hidden' name='merchant_ref' value='234-567-890' />
    <input type='hidden' name='memo' value='Bulk order from McAckney Web Shop' />

    <input type='hidden' name='notify_url' value='//www.mydomain.com/notification.php' />
    <input type='hidden' name='success_url' value='//www.mydomain.com/thank_you.html' />
    <input type='hidden' name='fail_url' value='//www.mydomain.com/failed.html' />

    <input type='hidden' name='developer_code' value='pq7778ehh9YbZ' />
    <input type='hidden' name='store_id' value='25' />

    ##Use notify url if you want a transaction response to be sent to the notify##
    <input type='hidden' name='notify_url' value='//www.mydomain.com/notification.php' />

    ##Success and fail URL are not required if integration method is inline.##
    ##These are to be uses if you are using the form redirect method.##
    <input type='hidden' name='success_url' value='//www.mydomain.com/thank_you.html' />
    <input type='hidden' name='fail_url' value='//www.mydomain.com/failed.html' />

    <input type='hidden' name='total' value='13000' />


     <input type='hidden' name='name' value='Customer name'/>
    <input type='hidden' name='address' value='Customer Address'/>
    <input type='hidden' name='city' value='Customer City'/>
    <input type='hidden' name='state' value='Customer State'/>
    <input type='hidden' name='zipcode' value='Customer Zip/Post Code'/>
    <input type='hidden' name='email' value='Customer email'/>
    <input type='hidden' name='phone' value= 'Customer phone '/>

    ##notification triggers for inline payments only##
    <input type='hidden' name='closed' value='closedFunction'>
    <input type='hidden' name='success' value='successFunction'>
    <input type='hidden' name='failed' value='failedFunction'>

    <input type='image' src='//voguepay.com/images/buttons/buynow_blue.png' alt='Submit' />
</form>
                            

[sitename] Inline Payment Script (2)

New fields are available to process notification / action triggers for inline payments

1. closed : when defined, this allows you to perform further actions in the [sitename] Inline Script 3 when the iframe closes.
2. success : when defined, this allows you to perform further actions in the [sitename] Inline Script 3 when the transaction performed is successful
3. failed : when defined, this allows you to perform further actions in the [sitename] Inline Script 3 when the transaction performed is not successful

<script>
    closedFunction=function() {
        alert('window closed');
    }

     successFunction=function(transaction_id) {
        alert('Transaction was successful, Ref: '+transaction_id)
    }

     failedFunction=function(transaction_id) {
         alert('Transaction was not successful, Ref: '+transaction_id)
    }
</script>
                            

Submit form using [sitename] Inline script 3

<script>
    Voguepay.init({form:'payform'});
</script>
                            

JavaScript Samples

The script below submits the form fields specified, using the inline method to [sitename].

Sample JS (1)

Here is a sample code that calls [sitename] and also handles the response.

<script src="//voguepay.com/js/voguepay.js"></script>

<script>
    closedFunction=function() {
        alert('window closed');
    }

     successFunction=function(transaction_id) {
        alert('Transaction was successful, Ref: '+transaction_id)
    }

     failedFunction=function(transaction_id) {
         alert('Transaction was not successful, Ref: '+transaction_id)
    }
</script>

 <script>
    function pay(item,price){
       //Initiate voguepay inline payment
        Voguepay.init({
            v_merchant_id: 'demo',
            total: price,
            notify_url:'http://domain.com/notification.php',
            cur: 'NGN',
            merchant_ref: 'ref123',
            memo:'Payment for '+item,
            developer_code: '5a61be72ab323',
            store_id:1,
            items: [
                {
                    name: "Item name 1",
                    description: "Description 1",
                    price: 500
                },
                {
                    name: "Item name 2",
                    description: "Description 2",
                    price: 1000
                }
            ],
            customer: {
                name: 'Customer name',
                address: 'Customer address',
                city: 'Customer city',
                state: 'Customer state',
                zipcode: 'Customer zip/post code',
                email: 'Customer email',
                phone: 'Customer phone'
            },
           closed:closedFunction,
           success:successFunction,
           failed:failedFunction
       });
    }

 </script>

 <button type="button" onclick="pay('shirt',500)"> Pay for shirt </button>
 <button type="button" onclick="pay('shoe',10000)"> Pay for shoe </button>
                            

Javascript Inline Sample (2)

Loading [sitename] using javascript Onclick function

<script src="//voguepay.com/js/voguepay.js"></script>

<script>
    closedFunction=function() {
        alert('window closed');
    }

     successFunction=function(transaction_id) {
        alert('Transaction was successful, Ref: '+transaction_id)
    }

     failedFunction=function(transaction_id) {
         alert('Transaction was not successful, Ref: '+transaction_id)
    }
</script>

<button onclick="Voguepay.init( 
{v_merchant_id: 'demo',total: 2000,notify_url:'http://domain.com/notification.php',
loadText:'Custom load text',cur: 'NGN',
merchant_ref: 'ref123',memo:'Payment for books',
developer_code: '5a61be72ab323',store_id:1, 
items: [{ name: 'Item name 1',description: 'Description 1',price: '500'},
{name: 'Item name 2',description: 'Description 2',price: '1000' }],
customer: {name: 'Customer name',address: 'Customer address',
city: 'Customer city',state: 'Customer state',zipcode: 'Customer zip/post code',
email: 'Customer email',phone: 'Customer phone' },
closed:closedFunction,
success:successFunction,
failed:failedFunction})">Pay using onclick</button>

                                

Javascript Inline Sample (3)

Loading [sitename] using function call

NOTE: The function name (pay3) can be changed.

<script src="//voguepay.com/js/voguepay.js"></script>

<script>
    closedFunction=function() {
        alert('window closed');
    }

     successFunction=function(transaction_id) {
        alert('Transaction was successful, Ref: '+transaction_id)
    }

     failedFunction=function(transaction_id) {
         alert('Transaction was not successful, Ref: '+transaction_id)
    }
</script>
                                
  <script>
     function pay3() {
         Voguepay.init({
             v_merchant_id: 'demo',
             total: 1500,
             notify_url: 'http://domain.com/notification.php',
             cur: 'NGN',
             merchant_ref: 'ref123',
             memo: 'Payment for shirt',
             developer_code: '5a61be72ab323',
             store_id: 1,
             loadText:'Custom load text',
             items: [
                 {
                     name: "Item name 1",
                     description: "Description 1",
                     price: 500
                 },
                 {
                     name: "Item name 2",
                     description: "Description 2",
                     price: 1000
                 }
             ],
             customer: {
                name: 'Customer name',
                address: 'Customer address',
                city: 'Customer city',
                state: 'Customer state',
                zipcode: 'Customer zip/post code',
                email: 'Customer email',
                phone: 'Customer phone'
            },
             closed:closedFunction,
             success:successFunction,
             failed:failedFunction
         });
     }
  </script>

  <button onclick="pay3()">Pay function call</button>

                                

Javascript Inline Sample (4)

Loading [sitename] on window load

<script src="//voguepay.com/js/voguepay.js"></script>

<script>
    closedFunction=function() {
        alert('window closed');
    }

     successFunction=function(transaction_id) {
        alert('Transaction was successful, Ref: '+transaction_id)
    }

     failedFunction=function(transaction_id) {
         alert('Transaction was not successful, Ref: '+transaction_id)
    }
</script>
                                
<script
    data-v_merchant_id="demo"
    data-total="1500"
    data-email="email"
    data-phone="phone"
    data-notify_url="http://domain.com/notification.php"
    data-cur="NGN"
    data-merchant_ref="ref123"
    data-memo="Payment for laptop"
    data-developer_code="5a61be72ab323"
    data-store_id="1"
    data-items='[{"name": "Item name 1",
        "description": "Description 1", 
        "price": "500"},
        {"name": "Item name 2",
        "description": "Description 2",
        "price": "1000"
    }]'
    data-customer='{name: "Customer name",
                address: "Customer address",
                city: "Customer city",
                state: "Customer state",
                zipcode: "Customer zip/post code",
                email: "Customer email",
                phone: "Customer phone"}'
    data-closed="closedFunction"
    data-success="successFunction"
    data-failed="failedFunction"
    data-loadText="Custom load text"
    src="//voguepay.com/js/voguepay.js">
</script>

                                

Mobile/Server-to-server API

To use [sitename] on mobile or via server-to-server connection, you can get a URL for payment by sending your merchant ID and other necessary parameters in the format:

Sample Request Url

 https://voguepay.com/?p=linkToken&v_merchant_id=demo&
 memo=Payment for laptop&total=1000&merchant_ref=ref123&
 notify_url=https://example.com/notification.php&
 success_url=https://example.com/success.php&
 fail_url=https://example.com/fail.php&developer_code=ddd&cur=NGN
                            

Sample Response Url

https://voguepay.com/pay/bnlink/1521822726-x0     
                            

You can either redirect your customers to the above sample response URL or you could load the URL without redirection using the sample inline javascript code below

<script src="//voguepay.com/js/voguepay.js"></script>

<script>
    closedFunction=function() {
        alert('window closed');
    }

     successFunction=function(transaction_id) {
        alert('Transaction was successful, Ref: '+transaction_id)
    }

     failedFunction=function(transaction_id) {
         alert('Transaction was not successful, Ref: '+transaction_id)
    }
</script>
                                
<script>
    Voguepay.link({
        url:'https://voguepay.com/pay/bnlink/1521822726-x0',
        loadText:'Custom load text',
        closed:closedFunction,
            success:successFunction,
            failed:failedFunction
    });
</script>

                            

Where

For a successful request, the api returns a url. Visting the url brings up VogiuePay payment page that can be used for payment based on the parameters supplied. The returned URL is valid for up to 24 hrs.

For failed requests, one of the following is returned:

Response Code	Implication
-1	Unable to process command
-3	Empty Merchant ID
-4	Memo is empty
-14	invalid merchant id
-100	No result

Command API

The command API allows you to directly perfom several actions on VoguePay from your application.

With command API, you can:

fetch: Query our database for a list of transaction ids which can subsequently be processed with the notification API.

withdraw: You can make withdrawals to one or several bank accounts.

pay: You can transfer money to other VoguePay members.

create: You can create voguepay accounts for your members.

The Command API works for server-to-server communication.

The Command API can be consumed with the secure url:

https://voguepay.com/api

The command API accepts json, xml, yaml or ini formated parameter via HTTP POST to https://voguepay.com/api. Your query should conform to the format specified below.

Fixed key / value pairs:

Return values

Command API returns the result as key/pair values in the format that it receives them (json, xml, yaml or ini).

The fields returned as explained below.

Download sample PHP files for command API implementation below:

Notification/Order processing API

VoguePay sends a transaction id to the notification URL provided in your account for every transaction on that account.

The transaction ID is sent as a HTTP POST variable (transaction_id) e.g:
If your notification URL is //mydomain.com/n.php
then notification will be sent to :

//mydomain.com/n.php

You can retrieve it as a POST variable e.g $_POST['transaction_id'] for PHP.

You can confirm the status and details of a transaction anytime using our REST(full) API below:

//voguepay.com/

The api accepts parameters as a GET request. Below is a sample api call.

//voguepay.com/?v_transaction_id=11111&type=xml
                            

For demo transactions, use:

//voguepay.com/?v_transaction_id=11111&type=xml&demo=true
                            

Sample XML Response

<voguepay>

<merchant_id>qa331322179752</merchant_id>

<transaction_id>11111</transaction_id>

<email>[email protected]</email>

<total>500</total>

<total_paid_by_buyer>507.61</total_paid_by_buyer>

<total_credited_to_merchant>495.00</total_credited_to_merchant>

<extra_charges_by_merchant>0.00</extra_charges_by_merchant>

<merchant_ref>2f093e72</merchant_ref>

<memo>1000 SMS units at &#8358;1.20 each on www.bulksms.com</memo>

<status>Approved</status>

<date>2012-01-09 18:56:23</date>

<referrer>http://www.afrisoft.net/viewinvoice.php?id=2012</referrer>

<fund_maturity>2012-01-11</fund_maturity>

<cur>USD</cur>

</voguepay>
                            

Sample JSON Response

{
    "merchant_id":"qa331322179752",
    "transaction_id":"11111",
    "email":"[email protected]",
    "total":500,
    "total_paid_by_buyer":"507.61",
    "total_credited_to_merchant":"495.00",
    "extra_charges_by_merchant":"0.00",
    "merchant_ref":"2f093e72",
    "memo":"1000 SMS units at ₦1.20 each on www.bulksms.com",
    "status":"Approved",
    "date":"2012-01-09 18:56:23",
    "referrer":"http://www.afrisoft.net/viewinvoice.php?id=2012",
    "fund_maturity":"2012-01-11",
    "cur":"USD"
}
                            

Explanation of Responses

Test/Demo Accounts

While integrating VoguePay, you may need to test your application.

Use demo as your merchant ID to use this feature.

Test Card Details

The transaction ID will be sent to the notify_url parameter submitted by your form e.g:

    <input type="hidden" name="notify_url" value="//www.mydomain.com/notification.php" />
        

You may then call the notification/order processing API from there.

For demo transactions, use add demo=true to the notification API as shown below:

     //voguepay.com/?v_transaction_id=11111&type=xml&demo=true