Building the payment infrastructure for software 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: ```php $key = "3da541559918a808c2402bba5012f6c60b27661c"; $secret = "OTEyZWM4MDNiMmNINDk="; $date = date('Y-m-d'); $signature = sha1($key . $secret . $date); ``` ```csharp 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(); } } } ``` ```javascript 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 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. See full list of allowed characters below 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	Business Name
a-z, A-Z	Lowercase and uppercase letters	Yes	Yes	Yes	Yes	Yes
0-9	Integers	Yes	Yes	Yes	Yes	Yes
!	Exclamation	No	No	Yes	No	No
$	Dollar Sign	No	No	Yes	Yes	No
,	Comma	Yes	No	No	Yes	Yes
#	Number sign (hash)	No	No	Yes	No	No
:	Colon	Yes	Yes	No	No	No
_	Underscore	Yes	No	Yes	No	No
'	Single quote	Yes	Yes	Yes	Yes	Yes
(	Left parenthesis	Yes	No	No	Yes	No
)	Right parenthesis	Yes	No	No	Yes	No
/	Slash	Yes	No	Yes	Yes	No
\|	Vertical bar	No	No	Yes	No	No
-	Minus	Yes	Yes	Yes	Yes	Yes
+	Plus	No	No	Yes	No	No
.	Period	Yes	Yes	Yes	Yes	Yes
?	Question	No	No	Yes	No	No
	Space	Yes	Yes	No	Yes	Yes
&	Ampersand	No	No	No	Yes	Yes
*	Asterisk	No	No	No	Yes	No