Building the payments infrastructure for digital platforms 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 documentation provides high level information on the methods used to perform transactions using the Vopay B2B API. 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 they 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 an 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 for 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 which 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 Type	Validations
	Province	Must be a valid two-letter Provincial or Territorial code
	State	Must be a valid two-letter US State alpha code
	Country	Must be a valid two-letter Country code as defined by the ISO 3166-1 alpha-2 standard
	Financial Institution Number	Must be a 3-digit integer value
	Branch Transit Number	Must 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
	Currency	Must 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 Code	Must be in the standard A9A 9A9 format
	Zip Code	Must be a 5-digit integer value
	IP Address	Must 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 Number	Must be an integer value between 6 and 11 digits long
	Amount	Must be a positive, non-zero numeric value
	Date	Must be in YYYY-MM-DD format (i.e., 2000-01-31)
	Timestamp	Must be in YYYY-MM-DD HH:MM:SS format (i.e., 2000-01-31 12:34:56)
	Language	Must 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

Character	Description	Address	City	Email	Names
a-z, A-Z	Lowercase and uppercase letters	Yes	Yes	Yes	Yes
0-9	Integers	Yes	Yes	Yes	Yes
!	Exclamation	No	No	Yes	No
$	Dollar Sign	No	No	Yes	Yes
,	Comma	Yes	No	No	Yes
#	Number sign (hash)	No	No	Yes	No
:	Colon	Yes	Yes	No	No
_	Underscore	Yes	No	Yes	No
'	Single quote	Yes	Yes	Yes	Yes
(	Left parenthesis	Yes	No	No	Yes
)	Right parenthesis	Yes	No	No	Yes
/	Slash	Yes	No	Yes	Yes
\|	Vertical bar	No	No	Yes	No
-	Minus	Yes	Yes	Yes	Yes
+	Plus	No	No	Yes	No
.	Period	Yes	Yes	Yes	Yes
?	Question	No	No	Yes	No
	Space	Yes	Yes	No	Yes
&	Ampersand	No	No	No	Yes
*	Asterisk	No	No	No	Yes