# Quick Start

Learn how to receive fast and secure payments with VoguePay.

VoguePay offers a range of services that make it possible for you to send and receive money across the world in minutes. In this documentation, we'll go over some of the integration options we offer to give you a quick overview of what is obtainable with VoguePay.

To start collecting payments online with VoguePay, It is required to first and foremost create an account with VoguePay.

To set up your VoguePay account, Go to <https://voguepay.com/register> and provide your details to create a free account.

After setting up your VoguePay account, Integration can begin. You can integrate VoguePay into your projects using any of our integration options. Once you're done, you will be able to receive payments from customers all over the world.


# Integration Options

VoguePay integration options has been simplified and made seamless. It is as simple as copying our sample codes and changing the required parameters to suit your needs. Integration to your platform can be done by using:

1. Simple HTML Forms.
2. Inline Payment
3. Standard Integration
4. Mobile / Server to server API.
5. Command API (Automate function on your account).
6. Joomla Plugin Installation.
7. Manual WordPress Plugin Installation.


# Know the Parameters

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

| Parameters          | Expected Value                                                       | Explanation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **v\_merchant\_id** | Merchant ID. Can be found on the Merchant VoguePay dashboard         | <p>Your merchant ID is your unique account identifier.</p><p><br>Your merchant ID can be found in Account Settings on your dashboard. Your merchant ID is a set of numbers separated with a hyphen (-) e.g. 1234-0000, 2817-0154360</p>                                                                                                                                                                                                                                                                                                                           |
| **cur**             | 3 letters Currency code.                                             | <p>Supported currency codes</p><p>NGN - Nigerian Naira<br>USD - US Dollar<br>EUR - Euro<br>GBP - British Pound<br>ZAR - South African Rand<br>JPY - Japanese yen<br>INR - India Rupiee<br>AUD - Australia Dollar<br></p><p>This field is optional. If not provided, the transaction will be initiated and processed in the default currency of your VoguePay account.</p><p>In situations when a currency code is provided, and the provided country code differs from the VoguePay account currency. VoguePay conversion rates will be used for settlements.</p> |
| **merchant\_ref**   | Can be any value provided by the merchant.                           | <p>This identifier is recommended but yet remains optional.</p><p>Any value provided here, will be returned with the confirmation results. VoguePay does not use this value, it is used by the merchant to store any data to be retrieved later with the transaction details.</p>                                                                                                                                                                                                                                                                                 |
| **memo**            | Transaction Description - Can be any value provided by the merchant. | This is the transaction summary or description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **developer\_code** | A unique code generated by VoguePay for Developers                   | A code is unique to every developer. Using this code earns the developer a commission on every successful transaction made through any selected integration methods. To get a developer code, Login to your VoguePay account and select 'Developer Codes' on your dashboard                                                                                                                                                                                                                                                                                       |
| **total**           | Total Amount to charge the customer.                                 | Total Amount to be charged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **notify\_url**     | A URL provided by the merchant.                                      | If provided, a notification is sent automatically to this notification URL immediately after the status of a transaction is confirmed.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **success\_url**    | A URL provided by the merchant.                                      | <p>If provided, buyers are automatically redirected to the success URL on completion of a successful transaction.</p><p></p><p>When no success URL is provided, buyers are automatically redirected to the URL from which the transaction originated.</p><p>NB: This requires redirection to be triggered.</p>                                                                                                                                                                                                                                                    |
| **fail\_url**       | A URL provided by the merchant                                       | <p>If provided, buyers are automatically redirected to the fail URL when a transaction is declined or not successful.</p><p></p><p>When no fail URL is provided and no fail URL is set in the account settings, buyers are automatically redirected to the URL from which the transaction originated.</p><p>NB: This requires redirection to be triggered.</p>                                                                                                                                                                                                    |


# Simple HTML Form

VoguePay can be integrated into your application via HTML form following these easy steps, making it the easiest way to start accepting payments

**1. Pass required Information in HTML Form**

To initialize a transaction, you'll need to pass information such as merchant ID, memo, amount, item name, item description, item value, merchant reference (transaction reference) etc. Merchant ID, memo and amount are required. Here is the full list of parameters you can pass:

| Params          | Required | Description                                                                                                                                                                                                                                                                                                     |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v\_merchant\_id | Yes      | Merchant ID                                                                                                                                                                                                                                                                                                     |
| merchant\_ref   | No       | Merchant Reference or Transaction Reference. Can be any value provided by merchant. Merchant value will be returned with the confirmation results from the confirmation API. VoguePay doesn't need this value, it is used by the merchant to store any data to be retrieved later with the transaction details. |
| memo            | Yes      | Transaction Memo                                                                                                                                                                                                                                                                                                |
| cur             | Yes      | Currency code. e.g NGN                                                                                                                                                                                                                                                                                          |
| developer\_code | No       | A code unique given to every developer. Using this code earns the developer a commission on every successful transaction made through any selected integration methods.                                                                                                                                         |
| total           | Yes      | Total Cost                                                                                                                                                                                                                                                                                                      |
| email           | Yes      | Merchant's Email                                                                                                                                                                                                                                                                                                |
| notify\_url     | Yes      | Link to Send Transaction status/details to                                                                                                                                                                                                                                                                      |
| success\_url    | Yes      | Link to redirect users to if payment is successful                                                                                                                                                                                                                                                              |
| fail\_url       | Yes      | Link to redirect users to if payment is fails.                                                                                                                                                                                                                                                                  |

**2. Add VoguePay Link in HTML Form Action attribute**

To get VoguePay Payment window, It is required to add VoguePay Payment Link as the value of your HTML Form Action attribute.&#x20;

See code snippets below.

```markup
<form method='POST' action='https://pay.voguepay.com'>
</form>
```

```markup
<form method='POST' action='https://pay.voguepay.com'>
  <input type="hidden" name='v_merchant_id' value='sandbox_760e43f202878f651659820234cad9' />
  <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='cur' value='NGN' />
  <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='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='ajayishegs@gmail.com'/>
  <input type="hidden" name='phone' value= 'Customer phone' />
  <input type="hidden" name='notify_url' value= 'https://example.com/notification.php'/>
  <input type="hidden" name='fail_url' value= 'https://example.com/notification.php'/>
  <input type="hidden" name='success_url' value= 'https://example.com/notification.php'/>
  <input type='submit' alt='Submit' />
</form>

<!-- Demo Link: https://codepen.io/sakarious/pen/yLbWyNB -->
```

For notification, if a URL is provided in 'notify\_url', a transaction notification will be sent. If transaction is successful, customers are automatically redirected to 'success\_url'.


# Inline Payment

Quickly embed VoguePay in your website using our Inline JavaScript integration.

Receive payment with our inline script. To initialize the transaction, you'll need to  include the VoguePay inline script anywhere on your page and pass the required information such as email, amount, transaction reference, etc. Here is the full list of parameters you can pass.

| Parameter       | Required | Description                                                                         |
| --------------- | -------- | ----------------------------------------------------------------------------------- |
| v\_merchant\_id | Yes      | Merchant ID                                                                         |
| total           | Yes      | Total Amount to be paid                                                             |
| notify\_url     | Yes      | Link to Send Transaction status/details to                                          |
| cur             | Yes      | Currency code. e.g NGN                                                              |
| merchant\_ref   | No       | Merchant Reference or Transaction Reference. Can be any value provided by merchant. |
| memo            | Yes      | Transaction Memo                                                                    |
| developer\_code | No       | A code unique given to every developer.                                             |
| items           | No       | An object containing all items to be paid for                                       |
| customer        | Yes      | An Object containing customer's details.                                            |
| closed          | No       | Function that runs when payment  window is closed without completing payment.       |
| success         | No       | Function that runs when payment is successful.                                      |
| failed          | No       | Function that runs when payment is fails                                            |

HTML:

```markup
<h3>Inline Payment Demo</h3>
<button type="button" onclick="pay('shirt',500)"> Pay for shirt </button>
<button type="button" onclick="pay('shoe',10000)"> Pay for shoe </button>
<script src="https://pay.voguepay.com/js/voguepay.js"></script>
```

JAVASCRIPT:

```javascript
let closedFunction = function() {
        alert('window closed by Sakarious');
    }

let successFunction=function(transaction_id) {
        alert('Transaction was successfully carried out, Ref: '+transaction_id)
    }

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

function pay(item,price){
      //Initiate voguepay inline payment
      Voguepay.init({
        v_merchant_id: 'sandbox_760e43f202878f651659820234cad9',
        total: price,
        notify_url:'http://domain.com/notification.php',
        cur: 'NGN',
        merchant_ref: 'ref123',
        memo:'Payment for '+item,
        developer_code: '5a61be72ab323',
        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: 'example@example.com',
          phone: 'Customer phone'
        },
        closed:closedFunction,
        success:successFunction,
        failed:failedFunction
      });
    }
    
    //Demo Link: https://codepen.io/sakarious/pen/OJmYVxM
```

In the code snippets above, notice how:

1. The Voguepay inline javascript is included using a `script` tag. This is how you import Voguepay into your code.
2. The `Pay for shirt` and `Pay for shoe` buttons has been tied to an `onClick` function called `pay`. This is the action that causes the Voguepay popup to load.

**MORE SAMPLES**

This sample loads VoguePay using javascript Onclick function

HTML:

```markup
<button onclick="Voguepay.init(
{v_merchant_id: 'sandbox_760e43f202878f651659820234cad9',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',
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: 'example@example.com',phone: 'Customer phone' },
closed:closedFunction,
success:successFunction,
failed:failedFunction})">Pay using onclick</button >
<script src="https://pay.voguepay.com/js/voguepay.js"></script>
```

JAVASCRIPT:

```javascript
let closedFunction = function() {
        alert('window closed');
    }

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

let failedFunction = function(transaction_id) {
         alert('Transaction was not successful, Ref: '+transaction_id)
    }
    
  //Demo Link: https://codepen.io/sakarious/pen/NWjVENv
```

This sample loads VoguePay using function call.

HTML:

```markup
<button onclick="payWithVoguePay()">Pay function call</button>
<script src="https://pay.voguepay.com/js/voguepay.js"></script>
```

JAVASCRIPT:

The function "payWithVoguePay" can be any name.

```javascript
let closedFunction = function() {
        alert('window closed');
    }

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

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

function payWithVoguePay() {
      Voguepay.init({
        v_merchant_id: 'sandbox_760e43f202878f651659820234cad9',
        total: 1500,
        notify_url: 'http://domain.com/notification.php',
        cur: 'NGN',
        merchant_ref: 'ref123',
        memo: 'Payment for shirt',
        developer_code: '5a61be72ab323',
        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: 'example@example.com',
          phone: 'Customer phone'
        },
        closed:closedFunction,
        success:successFunction,
        failed:failedFunction
      });
    }
```


# Standard Integration

This shows you how to accept payments using the standard integration flow

Accept payment quickly and securely using the standard method by calling our API. When you call the API with the required parameters, we will return a response with a payment link. Do a redirect to the link and a secure checkout modal will be loaded for your customer to enter their payment details and complete the payment.

When the transaction is completed and your customer closes the payment modal, if the transaction was successful, we would call your `success_url`&#x20;

&#x20;Follow the steps below to integrate VoguePay Standard

**Standard API**

```
https://pay.voguepay.com
```

### &#x20;**STEP 1 - Collect payment details, Customer details and Pass required query parameters**

Collect the customer's email address, total amount to be paid and currency if they are not paying in NGN.&#x20;

When you've collected the necessary details, add it to your request object and call our standard payment API.

**VoguePay Standard Query Parameters**

Here are the standard request parameters and descriptions:

| Parameter       | Required | Description                                                                                                                                                                                                                                                                                                     |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| p               | Yes      | Required for payment link generation. Value must be 'linkToken'. i.e ?p=linkToken                                                                                                                                                                                                                               |
| v\_merchant\_id | Yes      | Merchant's ID                                                                                                                                                                                                                                                                                                   |
| merchant\_ref   | No       | Merchant Reference or Transaction Reference. Can be any value provided by merchant. Merchant value will be returned with the confirmation results from the confirmation API. VoguePay doesn't need this value, it is used by the merchant to store any data to be retrieved later with the transaction details. |
| memo            | Yes      | Transaction Memo                                                                                                                                                                                                                                                                                                |
| cur             | Yes      | Currency code. e.g NGN                                                                                                                                                                                                                                                                                          |
| developer\_code | No       | A code unique given to every developer. Using this code earns the developer a commission on every successful transaction made through any selected integration methods.                                                                                                                                         |
| total           | Yes      | Total Cost                                                                                                                                                                                                                                                                                                      |
| email           | Yes      | Merchant's Email Address                                                                                                                                                                                                                                                                                        |
| notify\_url     | Yes      | Link to Send Transaction ID to. Same as Webhook URL.                                                                                                                                                                                                                                                            |
| success\_url    | Yes      | Link to redirect users to if payment is successful                                                                                                                                                                                                                                                              |
| fail\_url       | Yes      | Link to redirect users to if payment is fails.                                                                                                                                                                                                                                                                  |

### Step 2 - Initiate payment

After collecting payment details and filling required parameters, initiate the payment by calling our API with the collected payment details, see example below.

**Method: POST**\
**Endpoint:** [**https://pay.voguepay.com**](https://pay.voguepay.com)

```
 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
```

**Query Parameter for Request Above**

```
 ?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
```

When you send this request to our API, we will return a payment link in the response. Pass this link back to your customer for them to complete the transaction. The link will load up our checkout modal in accordance with the configurations you defined in your initial payment call.

**VoguePay Standard Sample Response**

Here's a sample response object containing the payment link returned:

```
https://checkout.voguepay.com/?data=%7B%22_amount%22%3A1000%2C%22_callback%22%3A%7B%22_webhook%22%3A%22https%3A%2F%2Fsakarious.requestcatcher.com%2Ftest%22%7D%2C%22_created%22%3A%222021-08-20+11%3A34%3A02%22%2C%22_currency%22%3A%22NGN%22%2C%22_customer%22%3A%7B%22tokenize%22%3Afalse%2C%22email%22%3A%22ajayishegs%40gmail.com%22%2C%22phone%22%3A%22%22%2C%22address%22%3A%22%5Bobject+Object%5D%22%2C%22name%22%3A%22%22%7D%2C%22_ip%22%3A%2254.74.141.25%22%2C%22_items%22%3A%5B%7B%22name%22%3A%22Payment%22%2C%22description%22%3A%22Payment%22%2C%22amount%22%3A%221000%22%7D%5D%2C%22_live%22%3Afalse%2C%22_merchantCurrency%22%3A%22NGN%22%2C%22_parameters%22%3A%7B%7D%2C%22_paymentStatus%22%3A%22Awaiting+Payment%22%2C%22_reference%22%3A%22ref123%22%2C%22_schedule%22%3A%7B%7D%2C%22_status%22%3A%22Open%22%2C%22_uid%22%3A%2211dd49b79ba24a8caf1aa52ab0b32877%22%7D&merchantId=sandbox_760e43f202878f651659820234cad9&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJqdGlfNjExZjkzMmE4YzE3YzEuMzM4NTY0MDIiLCJpYXQiOjE2Mjk0NTkyNDIsImlzcyI6IjVmM2NmNTQ0NDFkMmVjMDYyYzUxMzQ2NSIsIk9yZ1VuaXRJZCI6IjVmMzkzYmUxOTZmOGNmN2YyZDRjMzE5NiIsIlJlZmVyZW5jZUlkIjoiMTFkZDQ5Yjc5YmEyNGE4Y2FmMWFhNTJhYjBiMzI4NzciLCJQYXlsb2FkIjp7Ik9yZGVyRGV0YWlscyI6eyJPcmRlck51bWJlciI6Imp3dE9yZGVyXzYxMWY5MzJhOGMxODQ0Ljg5MzM4NDg5IiwiQW1vdW50IjoxMDAwLCJDdXJyZW5jeUNvZGUiOiJOR04ifX0sIk9iamVjdGlmeVBheWxvYWQiOiJ0cnVlIiwiZXhwIjoxNjI5NDYwMTQyfQ.gD8HKPu2IiFwpItr8Ve6juveCyOe02dVoVdZzv7S2tw&refererUrl=
```

Now when you pass the returned link to the user, they will be provided with our payment modal to complete the payment.

### Step 3 - Get Transaction ID

**- What happens when the user completes the transaction on the page?**

When the user enters their payment details, VoguePay would validate then charge the card. Once the charge is completed we would:

1. Call your specified `notify_url` and post the transaction ID to you.

```javascript
{
    "transaction_id": "e6ba64edcdda472dad814020bcaecd10"
}
```

&#x20;   2\. Send an email to you and your customer on the successful payment.

### Step 4 - Verifying Payment

When the transaction is completed, we send the transaction ID to your `notify_url` link or webhook (If one is set). You can use the transaction ID sent to verify the payment or perform other action by sending a GET request to our Confirmation API. See format and required query parameters below.

**Confirmation API**

```
https://pay.voguepay.com
```

| Query Parameter    | Required | Description                                                       |
| ------------------ | -------- | ----------------------------------------------------------------- |
| v\_transaction\_id | Yes      | Transaction ID of transaction to be queried                       |
| type               | Yes      | Format for the expected data. e.g xml, json. Defaults type is xml |
| v\_merchant\_id    | Yes      | Merchant ID                                                       |

**Method: GET**\
**Endpoint:** [**https://pay.voguepay.com**](https://pay.voguepay.com)

```
 https://pay.voguepay.com/?v_transaction_id=409a283ede12461aa674d3abb9f9b92e&v_merchant_id=demo&type=json
```

**Query Parameter for Request Above**

```
?v_transaction_id=409a283ede12461aa674d3abb9f9b92e&
v_merchant_id=demo&
type=json
```

When you send this request to our API, we will return a json or xml response of the transaction queried and you can perform an action afterwards e.g save to some details to database.

**Confirmation API Sample Response**

Here's a sample response object containing details about the transaction ID queried:

JSON type

```javascript
{
    "cur": "NGN",
    "total_paid_by_buyer": "1000",
    "total": "1000",
    "fund_maturity": "1970-01-01",
    "buyer_email": "ajayishegs@gmail.com",
    "status": "Approved",
    "merchant_id": "sandbox_760e43f202878f651659820234cad9",
    "merchant_ref": "ref123",
    "transaction_id": "409a283ede12461aa674d3abb9f9b92e",
    "process_duration": 0.836074
}
```

XML type

```javascript
<?xml version="1.0" encoding="UTF-8"?>
<voguepay>
    <cur>NGN</cur>
    <total_paid_by_buyer>1000</total_paid_by_buyer>
    <total>1000</total>
    <fund_maturity>1970-01-01</fund_maturity>
    <buyer_email>ajayishegs@gmail.com</buyer_email>
    <status>Approved</status>
    <merchant_id>sandbox_760e43f202878f651659820234cad9</merchant_id>
    <merchant_ref>ref123</merchant_ref>
    <transaction_id>409a283ede12461aa674d3abb9f9b92e</transaction_id>
    <process_duration>0.566156</process_duration>
</voguepay>
```

<br>


# Mobile/Server-to-Server API

Get a Payment Link.

## Get Payment Link

<mark style="color:green;">`POST`</mark> `https://pay.voguepay.com`

This endpoint returns a payment URL. Visiting or redirecting users to this URL brings up VoguePay Payment Page that can be used for completing the transaction based on the parameters supplied. See Response in 'Response' Tab below.

#### Query Parameters

| Name                                              | Type   | Description                                                                                                                                                                                                      |
| ------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| p<mark style="color:red;">\*</mark>               | string | Required for payment link generation. Value must be 'linkToken'                                                                                                                                                  |
| v\_merchant\_id<mark style="color:red;">\*</mark> | string | Merchant ID                                                                                                                                                                                                      |
| memo<mark style="color:red;">\*</mark>            | string | Transaction Memo/Description                                                                                                                                                                                     |
| total<mark style="color:red;">\*</mark>           | string | Total amount                                                                                                                                                                                                     |
| email<mark style="color:red;">\*</mark>           | string | Merchant's Email Address                                                                                                                                                                                         |
| merchant\_ref                                     | string | Merchant Reference - A Value Provided by Merchant to be returned with the confirmation results from the confirmation API. It could be used to store any data to be retrieved with the transaction details later. |
| notify\_url                                       | string | URL to send payment notification to                                                                                                                                                                              |
| success\_url                                      | string | URL to send buyers to if payment is successful                                                                                                                                                                   |
| fail\_url                                         | string | URL to send buyers to when payment fails                                                                                                                                                                         |
| developer\_code                                   | string | A code unique to every developer. Using this code earns  the developer a commission on every successful transaction made through any selected integration methods.                                               |
| cur<mark style="color:red;">\*</mark>             | string | 3 letters currency code in which transaction would be carried out. e.g NGN, USD                                                                                                                                  |
| referral\_url<mark style="color:red;">\*</mark>   | String | URL where payment was initiated                                                                                                                                                                                  |

{% tabs %}
{% tab title="200 Payment Link Generated" %}

```
https://checkout.voguepay.com/?data=%7B%22_amount%22%3A1000%2C%22_callback%22%3A%7B%22_webhook%22%3A%22https%3A%2F%2Fexample.com%2Fnotification.php%22%7D%2C%22_created%22%3A%222021-08-16+12%3A54%3A46%22%2C%22_currency%22%3A%22NGN%22%2C%22_customer%22%3A%7B%22tokenize%22%3Afalse%2C%22email%22%3A%22ajayishegs%40gmail.com%22%2C%22phone%22%3A%22%22%2C%22address%22%3A%22%5Bobject+Object%5D%22%2C%22name%22%3A%22%22%7D%2C%22_ip%22%3A%2254.74.141.25%22%2C%22_items%22%3A%5B%7B%22name%22%3A%22Payment%22%2C%22description%22%3A%22Payment%22%2C%22amount%22%3A%221000%22%7D%5D%2C%22_live%22%3Afalse%2C%22_merchantCurrency%22%3A%22NGN%22%2C%22_parameters%22%3A%7B%7D%2C%22_paymentStatus%22%3A%22Awaiting+Payment%22%2C%22_reference%22%3A%22ref123%22%2C%22_schedule%22%3A%7B%7D%2C%22_status%22%3A%22Open%22%2C%22_uid%22%3A%22fcf56897fece41c5899742fa39e6d61d%22%7D&merchantId=sandbox_760e43f202878f651659820234cad9&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJqdGlfNjExYTYwMTY5ZjRkYTkuODg5NDc4MzgiLCJpYXQiOjE2MjkxMTg0ODYsImlzcyI6IjVmM2NmNTQ0NDFkMmVjMDYyYzUxMzQ2NSIsIk9yZ1VuaXRJZCI6IjVmMzkzYmUxOTZmOGNmN2YyZDRjMzE5NiIsIlJlZmVyZW5jZUlkIjoiZmNmNTY4OTdmZWNlNDFjNTg5OTc0MmZhMzllNmQ2MWQiLCJQYXlsb2FkIjp7Ik9yZGVyRGV0YWlscyI6eyJPcmRlck51bWJlciI6Imp3dE9yZGVyXzYxMWE2MDE2OWY0ZTIwLjE2MDI3NzU0IiwiQW1vdW50IjoxMDAwLCJDdXJyZW5jeUNvZGUiOiJOR04ifX0sIk9iamVjdGlmeVBheWxvYWQiOiJ0cnVlIiwiZXhwIjoxNjI5MTE5Mzg2fQ.lP1EVI3HNmR0u3srDqfKUOSlfCMZu9WgGwk53OY3B4c&refererUrl=
```

{% endtab %}
{% endtabs %}

For failed requests, one of the following is returned:

| Response                                                                                                                | Implication              |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| ​<https://checkout.voguepay.com/?error=Customer+object+not+provided.&merchantId=demo&refererUrl=>​                      | Email not provided       |
| ​<https://checkout.voguepay.com/?error=No+merchant+uid+provided.&merchantId=&refererUrl=>​                              | Merchant ID not provided |
| ​<https://checkout.voguepay.com/?error=Name+of+order+item+not+provided+in+order+object.&merchantId=demo&refererUrl=>​   | Memo not provided        |
| ​<https://checkout.voguepay.com/?error=Amount+of+order+item+not+provided+in+order+object.&merchantId=demo&refererUrl=>​ | Total not provided       |

[Next](https://mooseize-tech.gitbook.io/docs/simple-html-form)


# Confirmation/Notification/Order Processing API

Confirm Transaction Status

VoguePay sends a transaction id to the notification URL provided in your account for every transaction on that account.\
If your notification URL i.e notify\_url query parameter value is '<https://mydomain.com/n.php>', then notification will be sent to :

```
mydomain.com/n.php
```

## Confirm Transaction Status

<mark style="color:blue;">`GET`</mark> `https://pay.voguepay.com`

This endpoint returns details of a transaction. See Response sample is 'Response' Tab.

#### Query Parameters

| Name               | Type   | Description                                                  |
| ------------------ | ------ | ------------------------------------------------------------ |
| v\_transaction\_id | string | Transaction ID of transaction to be queried.                 |
| type               | string | Format for the expected data. e.g xml, json. Defaults to xml |
| v\_merchant\_id    | string | Merchant ID                                                  |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "cur": "NGN",
    "total_paid_by_buyer": "1000",
    "total": "1000",
    "fund_maturity": "1970-01-01",
    "buyer_email": "ajayishegs@gmail.com",
    "status": "Approved",
    "merchant_id": "sandbox_760e43f202878f651659820234cad9",
    "merchant_ref": "ref123",
    "transaction_id": "409a283ede12461aa674d3abb9f9b92e",
    "process_duration": 0.836074
}

// -------------- XML RESPONSE TYPE -------------------

<?xml version="1.0" encoding="UTF-8"?>
<voguepay>
    <cur>NGN</cur>
    <total_paid_by_buyer>1000</total_paid_by_buyer>
    <total>1000</total>
    <fund_maturity>1970-01-01</fund_maturity>
    <buyer_email>ajayishegs@gmail.com</buyer_email>
    <status>Approved</status>
    <merchant_id>sandbox_760e43f202878f651659820234cad9</merchant_id>
    <merchant_ref>ref123</merchant_ref>
    <transaction_id>409a283ede12461aa674d3abb9f9b92e</transaction_id>
    <process_duration>0.566156</process_duration>
</voguepay>
```

{% endtab %}
{% endtabs %}

Response Parameters Description

| Response Key           | Value                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| merchant\_id           | Merchant's ID                                                                                                                       |
| transaction\_id        | Transaction ID of the transaction requested                                                                                         |
| total\_paid\_by\_buyer | Total amount paid by buyer including any other charges.                                                                             |
| total                  | Total price of products paid for.                                                                                                   |
| fund\_maturity         | The date that the merchant will be able to withdraw or spend the amount credited to his/her wallet as a result of this transaction. |
| buyer\_email           | Email address of buyer.                                                                                                             |
| status                 | Status of transaction which can either be Approved, Declined, Partially Refunded or Fully Refunded.                                 |
| merchant\_ref          | merchant\_ref value sent by the merchant.                                                                                           |
| process\_duration      | Time transaction took to complete.                                                                                                  |
| cur                    | Currency in which transaction was executed                                                                                          |

Response for Transaction ID not found:

Response "status" value will be "Declined"

```javascript
{
    "cur": "",
    "total_paid_by_buyer": "0",
    "total": "0",
    "fund_maturity": "1970-01-01",
    "buyer_email": "",
    "status": "Declined",
    "merchant_id": "sandbox_760e43f202878f651659820234cad9",
    "merchant_ref": "",
    "transaction_id": "409a283ede12461aa674d3abb9f9b9",
    "process_duration": 0.448289
}
```


# Command API

Perfom several actions on VoguePay from your application without visiting your VoguePay Account/Dashboard.

The command API allows you to directly perform 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.

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

The Command API can be consumed with the secure url:

```
https://integration.voguepay.com
```

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

|    Key   | Value                                                                                                                                                                                                                                                                                         |
| :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   task   | fetch or pay or withdraw(Required)                                                                                                                                                                                                                                                            |
| merchant | Your VoguePay Merchant ID (Required)                                                                                                                                                                                                                                                          |
|    ref   | Unique id for each request (Required)                                                                                                                                                                                                                                                         |
|   hash   | <p>Required Security code generated by concatenating the following and passing the result through a sha512 encryption<br><strong>your command api token</strong><br><strong>task specified above</strong><br><strong>your voguepay email</strong><br><strong>ref specified above</strong></p> |
|   list   | Used as a parent container for non-fixed key/value pairs where multiple requests are made in a single call                                                                                                                                                                                    |
|    id    | unique ID for each item in a list if multiple requests are made in a single call                                                                                                                                                                                                              |

**Response**

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:

|     Key     | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|      id     | The original ID submitted for each item in a list of multiple items                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|   username  | Username of the merchant on voguepay is returned                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|     salt    | String used for calculating the returned hash code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|     hash    | <p>Security code for verifying the authenticity of the result.<br>Generated by concatenating the following and passing the result through a sha512 encryption<br><strong>your command api token</strong><br><strong>your voguepay email</strong><br><strong>salt specified above</strong></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
|     list    | Used as a parent container for status, response, values and description where multiple requests are made in a single call                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|    status   | <p><strong>OK</strong> for successful operations or<br><strong>FAIL</strong> for unsuccessful operations</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
|   response  | <p><strong>OK</strong> = successful operation<br><strong>X001</strong> = Invalid Merchant ID<br><strong>X002</strong> = Invalid Reference<br><strong>X003</strong> = Invalid hash<br><strong>X004</strong> = Invalid task<br><strong>X005</strong> = Invalid Merchant ID<br><strong>X006</strong> = Invalid hash<br><strong>C001</strong> = Unauthorised access<br><strong>C002</strong> = Invalid Email<br><strong>C003</strong> = Invalid username<br><strong>C004</strong> = Invalid phone number<br><strong>C005</strong> = Invalid firstname<br><strong>C006</strong> = Invalid lastname<br><strong>C007</strong> = Invalid country<br><strong>C008</strong> = Unable to create member<br><strong>C009</strong> = Currency not supported by country provided<br><strong>C010</strong> = Password must contain at Least one numeric value (0-9), one Uppercase, one Lowercase and one special character<br><strong>C011</strong> = Invalid Currency<br><strong>W001</strong> = Invalid amount<br><strong>W002</strong> = Operation Failed.<br><strong>W003</strong> = Amount is below minimum allowed<br><strong>W004</strong> = Insufficient balance<br><strong>W005</strong> = Withdrawal failed<br><strong>W006</strong> = Withdrawal failed<br><strong>P001</strong> = Invalid amount<br><strong>P002</strong> = Operation Failed.<br><strong>P003</strong> = Seller and buyer are one and the same<br><strong>P004</strong> = Invalid beneficiary<br><strong>P005</strong> = Invalid memo<br><strong>P006</strong> = payment amount is below minimum allowed<br><strong>P007</strong> = payment amount exceeds maximum allowed<br><strong>P008</strong> = Insufficient balance for payment<br><strong>P009</strong> = Payment failed<br><strong>P010</strong> = Payment failed<br><strong>P011</strong> = Payment failed<br><strong>WL000</strong> = System error<br><strong>WL001</strong> = Invalid Parameters<br><strong>WL002</strong> = Validation Error<br><strong>WL003</strong> = Transaction Request Declined<br><strong>WL004</strong> = Currency is not allowed<br><strong>WL3D</strong> = 3D Authorization required<br></p> |
|    values   | Comma separated transaction IDs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| description | Description of the response                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

Download sample PHP files for command API implementation below:

{% file src="/files/-Mhm5dnC77rZ7AvZXZJI" %}
Fetch
{% endfile %}

{% file src="/files/-Mhm5dn3\_\_Tf2sAzMy36" %}
Query
{% endfile %}

{% file src="/files/-Mhm5dnDdT7P27SSZxz2" %}
Withdraw
{% endfile %}

{% file src="/files/-Mhm5dn8-q-PvRSrevFt" %}
Country and Currency List
{% endfile %}

{% file src="/files/-Mhm5dnBRW06H9ro1E4G" %}
Pay
{% endfile %}

{% file src="/files/-Mhm5dnAAe7KlBqxx1wp" %}
Account Query
{% endfile %}


# Joomla Integration

**PLUGIN INSTALLATION**

Download and unzip the VoguePay Joomla PlugIn below&#x20;

{% file src="/files/-MiRo9BmsARPJXMpPfR7" %}
VoguePay Joomla PlugIn
{% endfile %}

Log in to your joomla admin panel and install the zip folder.

&#x20;**- Optional  - Request for sandbox\_id to test or test using your main debit card**


# Manual WordPress Installation

To integrate VoguePay to your WordPress site, Please follow the steps below:

* Login to your WordPress Admin Area.
* Go to “Plugins > Add New” from the left hand menu.
* In the search box type “VoguePay WooCommerce”.&#x20;
* Locate by kunlexzy.
* From the search result you will see “VoguePay WooCommerce” click on “Install” to install the plugin.
* Click “Activate” to activate the plugin.

Then login to your cpanel or your host provider file manager, open the public\_html folder, and replace these files, file path is given below

**File – 1** ( class.extracharge.php )&#x20;

file path : /public\_html/wordpress/wp-content/plugins/woo-voguepay/includes

Locate the old class.extracharge.php and delete the file and replace it with the new file below.

**File – 2** ( class.voguepay.php )

file path : /public\_html/wordpress/wp-content/plugins/woo-voguepay/includes

Locate the old class.voguepay.php and delete the file and replace it with the new file below.

{% file src="/files/qyBE8WM8KMJtim1bzy9S" %}
File - 1
{% endfile %}

{% file src="/files/cq4ldQikpJwdGgdPDgTz" %}
File - 2
{% endfile %}

&#x20;**- Optional  - Request for sandbox\_id to test or test using your main debit card**


# Demo Account

When building with VoguePay, we understand you need to test your implementations in a test environment before going live. That is why we've provided you with a list of test cards to use for test purposes. The cards cover a variety of use cases and simulations for failed and successful transactions.

| CARD TYPE | CARD NUMBER | CARD NAME | CARD EXPIRY DATE | CVV | PIN |
| --------- | ----------- | --------- | ---------------- | --- | --- |

| VISA | 4111111111111111 | Any Name | 12/24 | 123 | ​ |
| ---- | ---------------- | -------- | ----- | --- | - |

| MASTERCARD | 5105105105105100 | Any Name | 12/24 | 456 | ​ |
| ---------- | ---------------- | -------- | ----- | --- | - |

| VERVECARD | 5061230620202020202 | Any Name | 12/24 | 606 | 1234 |
| --------- | ------------------- | -------- | ----- | --- | ---- |