Virtual Terminal iFrame Integration Guide V2

Updated by Tech Support

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.

Virtual Terminal URL - https://activepay.telecomdata.co.uk/iLogin.aspx
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:

  1. Concatenate mandatory parameters and client password
  1. Perform SHA512 hash
  1. Encode using URL-safe variation of Base64
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
The hash password is obtained from Support. If you do not have one already please let us know and we will generate one for you.
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:

  1. The character for index 62 is ‘-‘ (in place of ‘+’)
  2. The character for index 63 is ‘_’ (in place of ‘/’)
  3. 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

For security, access to this iFrame method is restricted only to known IP addresses that have been pre-registered within the processing platform. Please contact support to register IP addresses.

How did we do?