Virtual Terminal Integration
Updated
by
RM
Virtual Terminal iFrame Integration Guide
The iFrame integration is one of several methods available for creating a payment processing solution. This guide is intended to provide application programmers with the information necessary to implement the Virtual Terminal (VT) within an existing CRM solution. Please note the following:
Overview
The VT payment pages are designed to be presented to the user in an iFrame (500 by 500 pixels) embedded within the existing CRM solution.
By passing the query parameters within the URL string to the VT page, the user can be authenticated and input fields pre-populated with previously collected data. This leaves the agent free to concentrate on collecting cardholder details.
Parameter | Mandatory | Description |
ClientID | Yes | Unique Client Identifier |
AgentID | Yes | Agent Identifier |
Value | Yes | Full Transaction Value (pence) |
OrderID | Yes | Unique Order reference number |
Name | No | Card Holder Name |
Info1 | No | Additional data as necessary |
Info2 | No | Additional data as necessary |
Hash | Yes | Authentication Hash Algorithm |
Hash Generation
Generation of the hash parameter is a multi-stage process. The process must be performed as follows:
|
|
|
Concatenating parameters and password
The parameters must be concatenated in the correct order without any separator characters. This is the only place the iFrame password is used; the password should not be included in plain text as part of the URL. Any optional parameters included in the URL must not be used when generating the hash.
- OrderID
- ClientID
- AgentID
- Value
- Hash Password
SHA512 hash
Perform a SHA512 hash on the result from the first stage. UTF8 text encoding should be used where applicable
Base64 Encoding
The output from the SHA512 hash must be encoded using a URL-safe variant of Base64.
This variation differs from standard Base64 in the following 3 ways:
- The character for index 62 is ‘-‘ (in place of ‘+’)
- The character for index 63 is ‘_’ (in place of ‘/’)
- Padding (see subsection ‘Padding’ below)
Character Index Table
Value | Char | Value | Char | Value | Char | Value | Char | |||
0 | A | 16 | Q | 32 | g | 48 | w | |||
1 | B | 17 | R | 33 | h | 49 | x | |||
2 | C | 18 | S | 34 | i | 50 | y | |||
3 | D | 19 | T | 35 | j | 51 | z | |||
4 | E | 20 | U | 36 | k | 52 | 0 | |||
5 | F | 21 | V | 37 | l | 53 | 1 | |||
6 | G | 22 | W | 38 | m | 54 | 2 | |||
7 | H | 23 | X | 39 | n | 55 | 3 | |||
8 | I | 24 | Y | 40 | o | 56 | 4 | |||
9 | J | 25 | Z | 41 | p | 57 | 5 | |||
10 | K | 26 | a | 42 | q | 58 | 6 | |||
11 | L | 27 | b | 43 | r | 59 | 7 | |||
12 | M | 28 | c | 44 | s | 60 | 8 | |||
13 | N | 29 | d | 45 | t | 61 | 9 | |||
14 | O | 30 | e | 46 | u | 62 | - | |||
15 | P | 31 | f | 47 | v | 63 | _ |
Padding
The last character in the string indicates how many bytes were missing from the final group in the sequence. Please see the example table below:
Input | Standard | URL-Safe |
ExampleTe | RXhhbXBsZSBUZQ== | RXhhbXBsZSBUZQ2 |
ExampleTex | RXhhbXBsZSBUZXg= | RXhhbXBsZSBUZXg1 |
ExampleText | RXhhbXBsZSBUZXh0 | RXhhbXBsZSBUZXh00 |
