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:

Field TypeValidations
ProvinceMust be a valid two-letter Provincial or Territorial code
StateMust be a valid two-letter US State alpha code
CountryMust be a valid two-letter Country code as defined by the ISO 3166-1 alpha-2 standard
Financial Institution NumberMust be a 3-digit integer value
Branch Transit NumberMust be a 5-digit integer value
Bank Account Number

Must be an integer value

Maximum length is 160 digits

ID (i.e., Shareholder ID, Transaction ID, Account ID, etc)Must be an integer value
CurrencyMust be a valid three-letter Currency code as defined by the ISO-4217 standard
Address

Maximum length is 150 characters

See full list of allowed characters below

City

Maximum length is 150 characters

See full list of allowed characters below

Postal CodeMust be in the standard A9A 9A9 format
Zip CodeMust be a 5-digit integer value
IP AddressMust be in the x.x.x.x format where x is an octet and must be an integer value be 0 and 255
URL

Must be a valid URL as defined by the W3C standard

Maximum length is 1024 characters

First/Last Name

Maximum length is 100 characters

Lowercase and uppercase letters

Numbers

See full list of allowed characters below

Business Name

Maximum length is 255 characters

Lowercase and uppercase letters

Numbers

See full list of allowed characters below

Email Address

Must be in the standard local-part@domain format as defined by the RFC standard.

Maximum length is 145 characters

See full list of allowed characters below

Phone NumberMust be an integer value between 6 and 11 digits long
AmountMust be a positive, non-zero numeric value
DateMust be in YYYY-MM-DD format (i.e., 2000-01-31)
TimestampMust be in YYYY-MM-DD HH:MM:SS format (i.e., 2000-01-31 12:34:56)
LanguageMust be 'EN' or 'FR' (not case-sensitive)
Question

Maximum length is 40 characters

No commas (,) or ampersands (&)

Answer

Maximum length is 64 characters

No commas (,) or ampersands (&)

List of allowable characters:

CharacterDescriptionAddressCityEmailNames
a-z, A-ZLowercase and uppercase lettersYesYesYesYes
0-9IntegersYesYesYesYes
!ExclamationNoNoYesNo
$Dollar SignNoNoYesYes
,CommaYesNoNoYes
#Number sign (hash)NoNoYesNo
:ColonYesYesNoNo
_UnderscoreYesNoYesNo
'Single quoteYesYesYesYes
(Left parenthesisYesNoNoYes
)Right parenthesisYesNoNoYes
/SlashYesNoYesYes
|Vertical barNoNoYesNo
-MinusYesYesYesYes
+PlusNoNoYesNo
.PeriodYesYesYesYes
?QuestionNoNoYesNo
SpaceYesYesNoYes
&AmpersandNoNoNoYes
*AsteriskNoNoNoYes