Alias Gateway

Integration Guide v.3.1.3

© ePDQ 2015, All rights reserved.

Alias Gateway

Table of Contents

1 .......................................................................................... 3
Introduction

2 ..........................................................................................
Implementation scenario 4

3 ..........................................................................................
Step 1: Alias Gateway 5

3.1 Input Fields ..................................................................................... 5

3.1.1 Direct Debits..................................................................................... 6

3.1.2 PostFinance .....................................................................................
Card 6
3.1.3 SHA signature
.....................................................................................
for input 7
3.2 Pass-through .....................................................................................
fields 7

3.3 Output Fields ..................................................................................... 7

3.3.1 SHA signature

.....................................................................................
for output 9
3.4 Re-submission..................................................................................... 9

3.4.1 Error messages

..................................................................................... 9

4 .......................................................................................... 11
Step 2: DirectLink

5 Appendix:..........................................................................................
Alias update using the Alias Gateway 12

page 2 © ePDQ 2015, All rights reserved.

Alias Gateway 1: Introduction

1 Introduction
The Alias Gateway is an interface that allows merchants to post transactions to the ePDQ platform
by using a payment page they build themselves.

A 2-step process is involved:

Firstly, the merchant sends the card data to our system, where it is securely stored (including the
C VC , but for a limited time only)
Secondly, the merchant submits the actual order, without needing to submit the card data.

Advantages
- The merchant has full control over the look & feel of the payment page, including the check-out
sequence;
- ePDQ is completely invisible in the payment process;
- Seamless integration for various checkout scenarios including one-page-checkout;
- Merchants can offer upselling and cross-selling on the final checkout page;
- All credit card brands (VISA, MasterC ard, American Express, Diners etc.) are supported, as well as
Maestro and Bancontact MisterC ash, Direct Debits and PostFinance C ard.

Some of the features covered in this document may not be available in your chosen ePDQ
subscription. If you are unsure, please access our website to see what is included with your
subscription type: http://www.barclaycard.co.uk/business/accepting-payments/epdq-ecomm/

If you wish to take advantage of any of these extra features please contact ePDQ Support on
[email protected].

page 3 © ePDQ 2015, All rights reserved.

Alias Gateway 2: Implementation scenario

2 Implementation scenario

("Subm it Card inform ation via Alias Gatew ay" is not applicable for PostFinance Card)

REMARK
No operation is performed on the card in the first step. Our system simply performs a basic
format validation, but cannot guarantee that the card is still valid, or has sufficient funds to
proceed.
Optionally for credit cards and always for payment methods like Maestro and Bancontact
MisterC ash, with 3-D Secure an additional flow is applied (cf. DirectLink 3-D guide).

page 4 © ePDQ 2015, All rights reserved.

Alias Gateway 3: Step 1: Alias Gateway

3 Step 1: Alias Gateway

To use the Alias Gateway, the merchant must construct a webpage containing a form that does
NOT send data to his own website, but directly to the ePDQ Alias gateway page instead. In
this way, the card details never pass through the merchant’s web servers.

The URLs for the Alias Gateway are:

https://mdepayments.epdq.co.uk/ncol/test/alias_gateway.asp for Test
https://payments.epdq.co.uk/ncol/prod/alias_gateway.asp for Production

REMARK
It is extremely risky for a merchant to send credit card information to his own website, both from a
security as well as a legal perspective!
It must be ensured that the data are always only sent to the ePDQ platform.

3.1 Input Fields

The form should contain the following parameters:

Name Mandatory Mandatory Mandatory Max Description

for For For Length
Credit Direct PostFinance
Cards Debits Card

PSPID Y Y Y 30 Merchant's identification

BRAND N Y Y 25 C ard brand

CN Y Y n/a 50 C ard holder's name

C ARDNO Y Y n/a 35 C ard/account number

C VC Y n/a n/a 6 C ard Verification C ode

ED Y* n/a n/a 4 Expiry date (MMYY)

EC OM_C ARDINFO_ Y* n/a n/a 2 Expiry month

EXPDATE_MONTH

EC OM_C ARDINFO_ Y* n/a n/a 4 Expiry year

EXPDATE_YEAR

AC C EPTURL Y Y Y 255 URL for redirection in the

event of success

EXC EPTIONURL Y Y Y 255 URL for redirection in the

event of error

PARAMPLUS N N N 1000 Additional parameters to

be sent by the merchant

SHASIGN Y Y Y 128 SHA hash calculation

(security feature)

ORDERID Y Y Y 40 Order identification

ALIAS N N N 50 C ustomer alias

LANGUAGE N N Y 5 Language of the

page 5 © ePDQ 2015, All rights reserved.

Alias Gateway 3: Step 1: Alias Gateway

Name Mandatory Mandatory Mandatory Max Description

for For For Length
Credit Direct PostFinance
Cards Debits Card

cardholder (e.g. de_C H,

en_US, etc.)

ALIASPERSISTEDA N N N 1 Inidicate whether you

FTERUSE (N / Y) want to store an alias
temporarily or
indefinitely.
The possible values are:
"N": the alias will be
deleted after 2 hours
"Y": the alias will be
stored indefnitely, for
future use
This parameter should
only be used in
combination with Alias
Manager.

* The merchant can choose whether to send the expiry date in a single field (ED) or in two fields;
both formats are supported. If both are submitted, the “ED” field will prevail.

More information about these fields can be found in your ePDQ account. Just log in and go to:
Support > Integration & user manuals > Technical guides > Parameter Cookbook.

Note
If any of the mandatory input fields, e.g. ED (expiry date), contain no or invalid data, no alias will
be returned.

Note on character encoding

The Alias Gateway will use the character encoding specified in the merchant’s technical information
in the “Global Security Parameters” tab. You can enforce the usage of UTF-8 by calling the
Alias_gateway_utf8.asp page.
The character encoding is preserved in all subsequent redirections and responses.

3.1.1 Direct Debits

If you use the Alias Gateway and Direct Debits (DE, NL and/or AT):

The account number (regular or IBAN) has to be sent with the CARDNO field.
When relevant, the BIC (bank code) must be sent with the same parameter: BIC
The BRAND input field must contain either 'Direct Debits NL', 'Direct Debits DE' or 'Direct Debits
AT'.
The expiry date and C VC fields should be left empty.

3.1.2 PostFinance Card

When using PostFinance C ard, note that the process is slightly different, as the cardholder will be
prompted to authenticate himself when the alias is created.

The LANGUAGE field is mandatory

The minimum AMOUNT value is 0.5 C HF

page 6 © ePDQ 2015, All rights reserved.

Alias Gateway 3: Step 1: Alias Gateway

3.1.3 SHA signature for input

To check the integrity of the data, we require all requests to be accompanied by an SHA signature, in
the same way as for e-commerce transactions. Please refer to the e-Commerce documentation
for more information about SHA signatures and how to generate them.

Our system will use the SHA algorithm as defined in the Global security parameters of the
merchant's Technical information page.

IMPORTANT
As the merchant does not have the card number (C ARDNO), cardholder name (C N), C VC and
expiry date (ED) at his disposal – which is the underlying reason for the Alias Gateway – these
parameters should of course NOT be included in the SHA.
The merchant can choose whether or not to submit the parameter BRAND in the form. If the
BRAND is submitted, it has to be included in the SHA calculation.

Example
Parameters (in alphabetical order)
AC C EPTURL: https://www.myshop.com/ok.html
EXC EPTIONURL: https://www.myshop.com/nok.html
PSPID: test1

Secret passphrase (as defined in Technical information)

Mysecretsig1875!?

String to hash
AC C EPTURL=https://www.myshop.com/ok.htmlMysecretsig1875!?EXC EPTIONURL=https://
www.myshop.com/nok.htmlMysecretsig1875!?PSPID=test1Mysecretsig1875!?

Resulting SHA signature (SHA-1)

0F3455990D4859E20FD2B9F7B326304549DE6069

3.2 Pass-through fields

In addition to the input data, the merchant may also submit supplementary fields; these will not be
stored in our system, but will be appended to the redirection URLs so that the merchant can re-use
them in his order process. These fields are known as “Pass-Through Fields”.

Note:

These fields should NOT be included in the SHA signature.

These fields are not supported in combination with PostFinance C ard; we recommend to use
PARAMPLUS instead (cf. Input fields)

3.3 Output Fields

Our system will append several parameters to the Return URL (accept or exception) in order to
provide the merchant with feedback on the operation. These parameters are:

Name Relevant Relevant Relevant Max Description

for for for Length
credit Direct PostFinance
cards Debits Card
DE
ORDERID Y Y Y 40 The unique identifier of the
order. This must be sent in the
event of a retry, so we can

page 7 © ePDQ 2015, All rights reserved.

Alias Gateway 3: Step 1: Alias Gateway

Name Relevant Relevant Relevant Max Description

for for for Length
credit Direct PostFinance
cards Debits Card
DE
match them with the aliases
(card/C VC )
The ORDERID is generated
automatically and is numeric.

STATUS Y Y Y 1 Result of the alias creation.

0=OK, 1=NOK, 2=Alias
updated

ALIAS Y Y Y 50 Generated alias. According to

the 32 digit GUID format.
Example: 34F5302C -85D7-
4F35-BDF5-103C C EC 2FB61

BIC N Y N 11 The Bank Identifier C ode, for

Direct Debits transactions.
A value is returned only if
initially submitted, i.e. not
derived from the IBAN

BRAND Y Y Y 25 Brand of the payment method

CN Y Y Y 50 C ard/Account holder name

C ARDNO Y Y Y 35 C ard/Account number (regular

or IBAN), with Xs to replace
sensitive information.
N.B. In the event of an error,
the card/account will also be
masked.

C VC Y n/a n/a 6 C ard Verification C ode, with

Xs to replace sensitive data

ED Y n/a Y 4 Expiry date, e.g. 0216 (for

February 2016)

NC ERROR Y Y Y 50 Error code

NC ERRORC N Y Y Y 50 Error code for C N

NC ERRORC ARDNO Y Y Y 50 Error code for C ARDNO

NC ERRORC VC Y n/a n/a 50 Error code for C VC

NC ERRORED Y n/a Y 50 Error code for ED

SHASIGN Y Y Y 128 SHA signature for output

(More) Y Y Y / Pass-through fields + the

fields contained in PARAMPLUS

More information about these fields can be found in your ePDQ account. Just log in and go to:
Support > Integration & user manuals > Technical guides > Parameter Cookbook.

page 8 © ePDQ 2015, All rights reserved.

Alias Gateway 3: Step 1: Alias Gateway

3.3.1 SHA signature for output

Our system will return an SHA-OUT signature, in the same way as for e-C ommerce transactions, for
the following parameters:
ALIAS
BIC
BRAND
C ARDNO
CN
C VC
ED
NC ERROR
NC ERRORC ARDNO
NC ERRORC N
NC ERRORC VC
NC ERRORED
ORDERID
STATUS

Please refer to the e-Commerce documentation for more details about SHA.

3.4 Re-submission
When resubmitting data (e.g. because the first attempt was unsuccessful), the cardholder does not
have to re-enter previously validated details. For example, if the card number is OK, then the
browser will submit the “X-ed” card number, and our system will match it with the one stored for the
previous request.

To achieve this, the merchant must submit the ORDERID with every request. The same ORDERID is
sent back every time. If a new ORDERID is used, the error code 5555554 will be returned.

3.4.1 Error messages

The following error messages may be returned by the Alias Gateway:

NC ERROR
5555554 Incorrect ORDERID (within 2 hours after each submission)
55555555 General error
50001184 SHA_IN mismatch
50001186 *Operation not allowed
(when the merchant sends an ORDERID for which an alias already exists)
50001187 *Operation not allowed
(when the merchant sends an alias that already exists)
50001300 Wrong brand specified (Direct Debits)
50001301 Wrong bank account format (Direct Debits)

NC ERRORC N
60001057 Name is missing
50001174 Name is too long

NC ERRORC ARDNO
30141001 Invalid card number
50001069 Brand and card number do not match

page 9 © ePDQ 2015, All rights reserved.

Alias Gateway 3: Step 1: Alias Gateway

50001176 C ard number is too long

50001177 C ard number contains non-numeric info
50001178 C ard number too short/empty

NC ERRORC VC
50001090 C VC missing or too short
50001179 C VC too long
50001180 C VC contains non-numeric information

NC ERRORED
50001181 Expiry date contains non-numeric information
50001182 Invalid expiry month
50001183 Expiry date must be in the future
31061001 Expiry date empty or wrong format

page 10 © ePDQ 2015, All rights reserved.

Alias Gateway 4: Step 2: DirectLink

4 Step 2: DirectLink
Using the Alias generated with the Alias Gateway, you may then submit a DirectLink transaction
using our standard DirectLink implementation. Please refer to the DirectLink documentation for
implementation instructions.
This mecanism is also compatible with DirectLink 3D, as documented in DirectLink with 3-D
Secure supplement.
For more information about Alias usage, see the Alias Manager documentation.

page 11 © ePDQ 2015, All rights reserved.

Alias Gateway 5: Appendix: Alias update using the Alias Gateway

5 Appendix: Alias update using the Alias Gateway

The Alias gateway can also be used to update existing aliases, using the same input fields as for the
alias creation.

Note
If the merchant wants to simply update the cardholder name, it is not sufficient to only supply the
new name and the existing alias. The X-ed card number must also be sent in the C ARDNO field.
The C VC is not necessary.

In the response, the STATUS output field will inform the merchant of the alias update (status 2).

Result of the alias creation:

- 0 OK
- 1 Not OK
- 2 Alias Updated

For more information about Alias usage, please see our Alias Manager option guide.

page 12 © ePDQ 2015, All rights reserved.