API Overview

Building the payment infrastructure for digital platforms is complex and requires large investments of time and money. With VoPay’s developer-friendly API solution you can significantly reduce development costs, infrastructure and staffing allowing you to focus resources on what matters most to your business.

This document provides high-level information on the methods used to perform transactions using VoPay's API technology. Details on the purpose and parameters for each of these methods can be found below. All API methods accept standard HTTP POST-form-encoded parameters and return JSON-encoded data.

Authentication

Only requests from whitelisted IP addresses will be accepted.

All requests are authenticated using a combination of an API key and a shared secret.

For example:

API Key: 3da541559918a808c2402bba5012f6c60b27661c

Shared Secret: OTEyZWM4MDNiMmNlNDk=

If an API Key or the shared secret is lost or compromised it can be regenerated from the account management portal.

All requests to the VoPay API must include the API key and must contain a signature which is calculated using the shared secret. The signature is calculated by generating a SHA1 hash made up of the API key, the account’s shared secret and the current date in YYYY-MM-DD format.

The following is an example of generating a valid signature:

$key = "3da541559918a808c2402bba5012f6c60b27661c";
$secret = "OTEyZWM4MDNiMmNINDk=";
$date = date('Y-m-d');
$signature = sha1($key . $secret . $date);

using System;
using System.Text;
using System.Security.Cryptography;

public class Program 
{
	public static void Main(string[] args)
	{
		string key = "3da541559918a808c2402bba5012f6c60b27661c";
		string secret = "OTEyZWM4MDNiMmNINDk=";
		string date = DateTime.Now.ToString("yyyy-MM-dd");
		string hash;
		var signature = String.Concat(key, secret, date);

		hash = GetSha1(signature);
		Console.WriteLine(hash);
	}

	public static string GetSha1(string value)
	{
		using (SHA1Managed sha1 = new SHA1Managed())
		{
			var hash = sha1.ComputeHash(Encoding.UTF8.GetBytes(value));
			var sb = new StringBuilder(hash.Length * 2);

			foreach (byte b in hash)
			{
				sb.Append(b.ToString("x2"));
			}
			
			return sb.ToString();
		}
	}
}

var crypto = require('crypto')
var shasum = crypto.createHash('sha1')

var key = "3da541559918a808c2402bba5012f6c60b27661c"
var secret = "OTEyZWM4MDNiMmNINDk="
var date = new Date()

// convert to yyyy-mm-dd
date = date.toISOString().split('T')[0]

shasum.update(key + secret + date)
var signature = shasum.digest('hex')

This value should be passed along in the Signature parameter of the request.

Idempotent Requests

All of our transaction endpoints support idempotency in order to allow users to safely retry requests without accidentally performing the same operation twice. This is useful when an API is disrupted in transit and you do not receive a response. For example, if a request to the EFT Fund endpoint does not respond due to a network connection error, the user can retry the request with the same idempotency key to guarantee that no more than one funding transaction has been created.

An idempotency key is a unique key that the server can use to recognize and reject subsequent retries of the same request. To perform an idempotent request, provide an IdempotencyKey in the body of the POST request.

VoPay's idempotency works by saving the provided idempotency key on the transaction record. Subsequent attempts to submit a transaction with a matching idempotency key will return an error to the user and request that they re-attempt the transaction using a different idempotency key.

Input Validation

The following input validations are executed on every API:

List of allowable characters: