voguepay / voguepay
VoguePay API Library
README
PHP 5.5+ and Composer are required.
Installation Process
composer require voguepay/voguepay
After installation, include the VoguePay class in your code. Example below
require_once './vendor/autoload.php'; // location of the autoload file use VoguePay\VoguePay;
The class would make available the following functions
VoguePay::card($payLoad); VoguePay::chargeToken($payLoad); VoguePay::getResponse($transactionDetails);Using the PHP Library
Initiating Payment
Using the VoguePay::card function
VoguePay::card($payLoad);
require_once './vendor/autoload.php'; // location to the autoload file of the composer use VoguePay\VoguePay; $payLoad = []; $payLoad = [ "version" => "2", // version of the API to be called "merchant" => [ "merchantUsername" => "***", // Username of Merchant On VoguePay "merchantID" => "***-***", // Merchant ID of account on VoguePay "merchantEmail" => "***@gmail.com", // Registered email of account on VoguePay "apiToken" => "TUDMQ735hNKNaQCBkZYVHvjHqNBk", // Command API Key of account on VoguePay "publicKey" => file_get_contents('key.crt') // Public Key of account on Voguepay. This is to be copied and save to a file. The location of the file is to be replaced. ], "card" => [ "name" => "***", //Card holder name "pan" => "******************", //Card pan number "month" => "05", //Card expiry month e.g 06 "year" => "21", //Card expiry year e.g 21 "cvv" => "***" //Card CVV number ], "customer" => [ "email" => "***@gmail.com", // Email of customer "phone" => "***********", // phone number of customer "address" => "*************", // address of customer "state" => "********", // state or province of customer "zipCode" => "100005", // zip code of customer "country" => "Nigeria" // country of country - Valid country or valid 3 letter ISO ], "transaction" => [ "amount" => 100, //amount to be charged "description" => "Payment Description Goes Here", //Description of payment "reference" => "1x2345vbn", // Unique transaction reference, this is returned with the transaction details "currency" => "USD", //Supported currency USD, GBP, EUR, NGN ], "notification" => [ "callbackUrl" => "https://yourdomain.com/", // Url where a transaction details will be sent on transaction completion "redirectUrl" => "https://yourdomain.com/inspection" // Url where the customer is redirected on transaction completion ], "descriptor" => [ "companyName" => "****", // {Optional} - Company name "countryIso" => "NGA" //3 letter country ISO ], "demo" => false, // boolean (true / false) , set to true to initiate a demo transaction and false for live transaction ]; print_r(VoguePay::card($data));
Sample successful response below
stdClass Object ( [description] => Redirection Required - 3D Authentication required. // Response code description [redirectUrl] => https://voguepay.com/?p=vpgate&ref=czoxMzoiNWNiZjQ2OTBlNDFkMCI7 // 3D redirection URL [reference] => 1x2345vbn // Transaction reference [response] => WL3D // Transaction response code [status] => OK // API query status [transactionID] => 5cbf4690e41d0 // Generated VoguePay transaction ID )
On a successful API call, this returns an array of data, which includes the 3D authentication url. [redirectUrl]
Redirect to the 3D authentication URL to complete transaction.
If there is an error, or a details prvoided is invalid, the status is represented as [status] => ERROR
Sample of an error response below
stdClass Object ( [description] => Incorrect CVV [field] => CVV [reference] => 1x2345vbn [response] => WL003 [status] => ERROR )
The status [status] => OK is not a representation of a successful transaction. To get transaction status check the usage for voguepay::getResponse()
After payment is completed. A POST request ($_POST['transaction_id]) is sent to the callback URL and redirect URL included in the payload. This is used to get the transaction response and validate if the transaction is successful
Getting transaction response
oguepay::getResponse($transactionDetails)
Sample code below
require_once './vendor/autoload.php'; use VoguePay\VoguePay; $data = [ "transactionID" => "5cbf4690e41d0", "merchant" => [ "merchantUsername" => "***", // merchant username on VoguePay "merchantID" => "***-***", // merchantID of account on VoguePay "merchantEmail" => "***@gmail.com", // registered email address of account on VoguePay "apiToken" => "TUDMQ735hNKNaQCBkZYVHvjHqNBk", // Command API token of account on VoguePay ], ]; print_r(VoguePay::getResponse($data));
Sample Transaction response below
stdClass Object ( [apiProcessTime] => 0.002103 // API response time [buyerDetails] => stdClass Object ( [email] => ***@gmail.com // Customer Email address [phone] => *********** // Customer Phone Number [maskedPan] => 537010******6414 // Masked Pan used for payment [cardType] => Mastercard // Card type ) [description] => API query sucessful // API response description [response] => OK // API response code [status] => OK // API status [transaction] => stdClass Object ( [total] => 10.00 // Transaction Amount [status] => Approved // Transaction status [currencySymbol] => ₦ // Transaction currency symbol [currency] => NGN // Transaction currency Code [merchantID] => ***-*** // Merchant ID of merchant on VoguePay [transactionID] => 5cbf4690e41d0 // Transaction ID of transaction on VoguePay [transactionDate] => 2019-05-01 // Date of transaction [transactionTime] => 08:30:53 // Time of transaction [reference] => 1x2345vbn // Reference, returned as passed in the payload. This can be used to authenticate transaction on merchant side [description] => This is a test payment //Payment description [totalPaidByCustomer] => 10.00 // Total paid by the customer [creditedToMerchant] => 9.85 // Amount credited to merchant account on VoguePay [chargesPaid] => 0.15 // Total charges paid on transaction [extraConfiguredCharges] => 0.00 // Extra configured charges if applicable [fundsMaturity] => 2019-05-02 // Date of transaction maturity [responseCode] => 00 // Transaction response code [responseDescription] => Transaction Approved // Transaction response decription ) )
Interpreting the transaction response
As explained earlier. the API [status] and [response] when OK does not mean the transaction is approved.
An approved transaction is interpreted by checking the transaction details of the array. [transaction][status] and [transaction][responseCode]
A transaction is only to be approved when the transaction status [transaction][status] is equals to Approved and the transaction response code [transaction][responseCode] is equals to 00
Sample code of a declined transaction
stdClass Object ( [apiProcessTime] => 0.002103 // API response time [buyerDetails] => stdClass Object ( [email] => ***@gmail.com // Customer Email address [phone] => *********** // Customer Phone Number [maskedPan] => 537010******6414 // Masked Pan used for payment [cardType] => Mastercard // Card type )
[description] => API query sucessful // API response description
[response] => OK // API response code
[status] => OK // API status
[transaction] => stdClass Object
(
[total] => 10.00 // Transaction Amount
[status] => Declined // Transaction status
[currencySymbol] => ₦ // Transaction currency symbol
[currency] => NGN // Transaction currency Code
[merchantID] => ***-*** // Merchant ID of merchant on VoguePay
[transactionID] => 5cca90d020532 // Transaction ID of transaction on VoguePay
[transactionDate] => 2019-05-01 // Date of transaction
[transactionTime] => 08:30:53 // Time of transaction
[reference] => 1x2345vbn // Reference, returned as passed in the payload. This can be used to authenticate transaction on merchant side
[description] => This is a test payment //Payment description
[totalPaidByCustomer] => 0 // Total paid by the customer
[creditedToMerchant] => 0 // Amount credited to merchant account on VoguePay
[chargesPaid] => 0 // Total charges paid on transaction
[extraConfiguredCharges] => 0 // Extra configured charges if applicable
[fundsMaturity] => 2019-05-02 // Date of transaction maturity
[responseCode] => EC0571 // Transaction response code
[responseDescription] => Transaction not Permitted to Cardholder // Transaction response decription
)
)
Tokenized details of the card [transaction][token] can be saved and used for future debits using VoguePay::chargeToken()
Charging a card with token
Using VoguePay::chargeToken()
Sample code below
require_once './vendor/autoload.php'; use VoguePay\VoguePay; $data = []; $data = [ "version" => "2", // version of the API to be called "merchant" => [ "merchantUsername" => "***", // Username of Merchant On VoguePay "merchantID" => "***-***", // Merchant ID of account on VoguePay "merchantEmail" => "***@gmail.com", // Registered email of account on VoguePay "apiToken" => "TUDMQ735hNKNaQCBkZYVHvjHqNBk", // Command API Key of account on VoguePay "publicKey" => file_get_contents('key.crt') // Public Key of account on Voguepay. This is to be copied and save to a file. The location of the file is to be replaced. ], "card" => [ "token" => "**********", // Transaction token "cvv" => "948" //Card CVV number ], "customer" => [ "email" => "***@gmail.com", // Email of customer ], "transaction" => [ "amount" => 100, //amount to be charged "description" => "This is a test payment", //Description of payment "reference" => "1x2345vbn", // Unique transaction reference, this is returned with the transaction details "currency" => "USD", //Supported currency USD, GBP, EUR, NGN ], "descriptor" => [ "companyName" => "***", // {Optional} - Company name "countryIso" => "NGA" // 3 letter country iso ], ]; print_r(VoguePay::chargeToken($data));
For sample response of VoguePay::chargeToken() make reference to VoguePay::getResponse() sample response and explanation.