Barclaycard SmartPay
Virtual Terminal / MOTO Guide
Version 3.0 Released April 2012
DOC Version Control
Version No.
Date Issued
Reason for Change
1.0
July 2010
Initial Document
2.0
February 2012
Update
3.0
April 2012
Update
COPYRIGHT NOTICE
No part of this publication may be reproduced, stored in a retrieval system or
transmitted in any form or by any means electronic or mechanical, including
photocopying and recording, for any purpose, without the prior written permission of
Product Development, Barclaycard Global Payment Acceptance, Barclays Bank PLC.
Contents
INTENDED AUDIENCE ...................................................................................................... 4
CONTACTING US .............................................................................................................. 4
DOCUMENTATION ........................................................................................................... 4
GLOSSARY ....................................................................................................................... 5
GLOSSARY ....................................................................................................................... 5
HOW TO USE THIS DOCUMENT ...................................................................................... 6
INTRODUCTION................................................................................................................ 7
THE SCREENS .................................................................................................................. 8
STEP 1 – LOGIN .......................................................................................................................8
STEP 2 – TRANSACTION DETAILS ............................................................................................8
STEP 3 – PAYMENT OPTION.................................................................................................... 9
STEP 4 – ENTER PAYMENT DETAILS ....................................................................................... 9
STEP 5 – CONFIRM PAYMENT DETAILS ................................................................................... 10
STEP 6 – PAYMENT RESULT.................................................................................................. 10
AFTER PAYMENT COMPLETION ............................................................................................. 10
NOTIFICATIONS .............................................................................................................. 11
LINKING TO THE VIRTUAL TERMINAL PAGES................................................................ 12
DIRECT LINK TO THE CALL CENTRE PAGES ............................................................................. 12
POST VARIABLES TO THE VIRTUAL TERMINAL PAGES ............................................................. 12
COLLECTING THE CARDHOLDERS ADDRESS ............................................................... 14
MOTO AND RECURRING PAYMENTS ............................................................................. 15
VIRTUAL TERMINAL USERS ........................................................................................... 19
TROUBLE SHOOTING ..................................................................................................... 21
Error received when accessing the Call Centre pages ................................................. 21
Invalid Login error ............................................................................................................. 21
URL’S .............................................................................................................................. 22
URL’S FOR TEST ................................................................................................................... 22
URL’S FOR LIVE .................................................................................................................... 22
CURRENCY CODES ......................................................................................................... 23
Intended Audience
This document is intended for use by:
•
•
•
Merchants using Barclaycard SmartPay
Web developers working on behalf of merchants
Merchant Development Partners
It is recommended that the merchant responsible for the account reviews this document to
ensure appropriate configuration of the account.
This document will go through the flow and the screens of the Virtual Terminal and what
each step does, it will then explain how you can access the Virtual Terminal and then
explain the user permissions required to enable you and your staff to use the Virtual
Terminal.
Contacting us
Contact our support team via email at:[email protected]
Alternatively you can call our support team on the following numbers:From the UK Outside the UK -
01604 269518*
+441604269518*
Support hours:Monday to Friday:
8.00 to 18:00 GMT
* Calls may be monitored or recorded to maintain high levels of security and quality of
service
Documentation
This document and others which can help you with you integration and store setup can be
found at the support website. Please refer to your set up email.
Glossary
Term
Definition
HPP
Hosted Payment Page
SOAP
Simple Object Access Protocol – a generic message structure used by
programming languages to communicate data in a standard format.
HTML
Hypertext Mark up Language – language used to construct web pages
HTTP
HTTPS
HyperText Transfer Protocol – the protocol used most often to transfer
information from World Wide Web servers to browsers. Also called
HyperText Transport Protocol
HyperText Transfer Protocol, Secure. A version of http for secure
transactions
AVS
Address Verification Service
CSC
Card Security Code – also known as CV2, CVV2, CID and CVN
MOTO
Mail Order / Telephone Order
How to use this Document
This document combines essential integration and user information, plus tips on
how to get the most from the Barclaycard SmartPay products. For ease of use, it
is indexed by Section, Topic and Product as shown below:
Section
Topic
B
The Screens
This type of header will appear at the start of each new subject. There are 5
Sections.
The Topic provides information on what can be performed by Barclaycard
SmartPay within the section. You can “mix and match” the topics within the
sections to tailor this user guide to your specific needs.
Section
A
B
C
D
E
Content
Introduction
Description
What the Virtual Terminal is.
The Screens
The Virtual Terminal steps and
screens.
How to connect and access the
Virtual Terminal.
Setting up users to use the Virtual
Terminal
Linking to the Virtual
Terminal Pages
Virtual Terminal
Users
Appendix
Section
Topic
A
Introduction
The Virtual Terminal is designed to be used in a call centre environment or with merchant’s
who wish to take MOTO payments.
To use the Virtual Terminal the user requires a compatible internet browser and access to
the Internet, as the payments are processed via our securely hosted payment pages.
As this is separate from the main back office of your Barclaycard SmartPay account, users
will not need to login to the back office, keeping your administration of payments separate.
If you wish to use the Virtual Terminal to process MOTO transactions you will need to
contact the support team to set up an account. If you wish to discuss the Virtual Terminal
then please do not hesitate to contact the Barclaycard SmartPay support team.
Section
Topic
B
The Screens
In this section we will take you through each screen in the order that a user would
experience.
Step 1 – Login
Here the user accesses the Virtual Terminal where they will be asked to login via the
window below. Further details on accessing the Virtual Terminal can be found in the
Linking to the Virtual Terminal Pages section
To save you having to enter the Account each time you wish to access the Virtual Terminal
select the tick box to remember the account on this computer. Please note this does not
store the username or password.
Please Note: The Callcenter user should not log-in to the Backoffice at the same time they
are attempting to use the Virtual Terminal. Always click on the log-off in the backoffice
before going to the CallCenter. This will make sure that you have finished the backoffice
session so you can start a new session in the CallCenter. If you experience problems
logging in it is also suggested that you delete the internet history and cookies in your
browser and re-try.
Step 2 – Transaction Details
The user now enters the payment details, including the amount, the references and the
customers email address. Depending on the method used to connect to the Virtual
Terminal, these values can be pre-populated – further details of this can be found in the
Linking to the Virtual Terminal Pages section. Once complete the user selects ‘Submit’.
Step 3 – Payment Option
Here the user selects the customer’s payment method. Which payment options are
displayed can be controlled via the back office, further details of this can be found in the
Integration Guide.
Step 4 – Enter Payment Details
This screen prompts the user to ask for the necessary details to complete the transaction.
If the customer wants to use a different payment type the user selects the ‘Previous’
button to return to the previous screen. Once the form is completed the payment will
continue, if there are any issues with the payment an error message will appear and ask
the user to check/amend the details before continuing.
Step 5 – Confirm payment details
The user is now presented with the transaction details to confirm with the customer before
the transaction is processed. If the details are correct the user with then select ‘Submit’ to
send the payment for processing.
Step 6 – Payment Result
Once the payment is complete a result page will be displayed to the user to confirm the
outcome of the transaction. In the following example the payment was approved. The user
should inform the customer of the result.
After Payment Completion
If you need to perform an operation on a payment after it has been completed on the
Virtual Terminal then you will need to manage the payment via the back office and have the
relative permissions to action the change. This is covered in more detail in the Procedure
Guide which can be downloaded from the support website.
Section
Topic
D
Notifications
Whenever a payment is made or a modification is processed, we will notify you of
the event and whether or not it was performed successfully. Within your
SmartPay back-office you can configure a URL that you wish to receive these
messages. Notifications should be used to keep your own back-office systems up
to date with the status of each payment or modification to a payment is made.
Notifications allow you to receive updates on a payments status, for example you
will receive a notification when a payment is processed and authorised. If the
payment is then refunded using the back-office or a modification request you will
receive a further a notification confirming the payment status has changed.
If you choose to use the SmartPay subscription reports you will also receive a
notification to confirm the report is available.
The notification message also includes additional authorisation information that is
not included at other points in the payment process.
You must to ensure you have configured a Notification URL before you move your
account from Test to Live.
You can configure the Notification settings in the Barclaycard SmartPay
Backoffice. For more information please refer to the SmartPay Notifications Guide.
Section
Topic
C
Linking to the Virtual Terminal Pages
There are two preferred ways of linking to the Virtual Terminal. The first is to use a link
which will take your user to the Virtual Terminal where they can manually enter details. The
second option is to have a local webpage or application which you could use to post values
to the payment page, saving the call operator time and also helping to reduce entry
mistakes.
We will now go through each of these methods in the following section and how they could
be used.
Direct link to the Call Centre pages
A direct link to the Virtual Terminal would be similar to a link or shortcut on a computer
desktop or a bookmark/favourite in an internet browser, where users just select the link
and are taken straight to the Virtual Terminal. From there users log in and process the
payments.
The address that the link on your browser will need to point to is below. You will need to
replace [MOTOAccount] with the name of the merchant account set up to take MOTO
payments.
https://test.barclaycardsmartpay.com/callcenter/action/callcenter.shtml?merchantAccount
=[MOTOAccount]
One way to create a shortcut is to follow these steps:
1.
Right click on your desktop where you would like the shortcut and select ‘New’ and
then ‘ShortCut’, this will take you to the Create Shortcut screen.
2. In the location/address for the shortcut add the following replacing
[MOTOAccount] with the name of the account.
https://test.barclaycardsmartpay.com/callcenter/action/callcenter.shtml?merchant
Account=[MOTOAccount]
3. Then select apply or next, enter the name which you wish to be displayed on the
link, make this something easy to identify and remember as the link to the Virtual
Terminal, select Finish. You should then have a link on your desktop which when
selected will take you straight to the Virtual Terminal.
Please note: this may vary according to your operating system.
Post variables to the Virtual Terminal pages
If you are collecting information from the customer on your own system or creating a
reference for the order reference which you would like to be used for the payment you
may prefer to post these values to the Virtual Terminal to save user time and reduce the
chance of data entry errors.
To pass the call centre user and the variables to the Virtual Terminal you can use a simple
html post method, please find below an example of a post form which could be used.
<form name="adyenForm"
action="https://live.barclaycardsmartpay.com/callcenter/action/callcenter.shtml"
method="post">
<input type="hidden" name="merchantAccount" value="[MOTOAccount]" />
<input type="text" name="shopperLocale" value="en_GB" />
<input type="text" name="paymentAmount" value="101" />
<input type="text" name="currencyCode" value="GBP" />
<input type="text" name="merchantReference" value="MR1234512345" />
<input type="text" name="shopperReference" value="SR43211234" />
<input type="text" name="shopperEmail" value="[email protected]" />
<input type="submit" value="Process Payment">
</form>
The fields which can be passed using this method are:Field Name
Description
merchantAccount
This is a mandatory field and must be passed and will be the
name of the MOTO merchant account.
shopperLocale
This is a combination of a language and country code which
controls the language the Virtual Terminal is displayed in, for
example in the above this is set to en_GB for British English, but
could also be set to ‘fr’ for a French Virtual Terminal.
paymentAmount
The payment amount specified in minor units, for UK Sterling this
would be in pence.
currencyCode
The three letter capitalised ISO currency code to pay in, please
see the appendix for a list of supported currency codes.
merchantReference
The reference you give the payment to help you identify the
payment; this could be generated by your system.
shopperReference
An ID which refers uniquely to the shopper.
shopperEmail
The customer’s email address.
Please Note: If you do not pass a value then the field will remain editable on the Virtual
Terminal.
Section
Topic
D
Collecting the cardholders address
If you have a requirement to collect the cardholder’s address you can add address fields to
the Virtual Terminal pages simply selecting Billing Address Fields (AVS) within the Skin
Options section of the Edit Skin Configuration page in your MOTO Skin.
Section
Topic
E
MOTO and Recurring Payments
According to a merchants requirements they may need to setup recurring payments from
MOTO (Mail Order/Telephone Order) transactions allowing the merchant to take
subscriptions or repeat payments for differing amounts in the future.
What account setup to request
When requesting a SmartPay account it will need to be a MOTO Account (Call Centre
Interface) with recurring payments selected. If you need this service adding on then please
contact the SmartPay support team who will arrange for this functionality to be set on
your account.
The Payment Process
On the Virtual Terminal Page you will be offered the option to store the card details that
you are entering. By ticking the box you are opting to store the card details on SmartPay
(see below).
After submitting a transaction, you can then call the recurring payment contract that has
been created.
Submitting Recurring Payments
Submitting recurring payments is implemented as a SOAP service similar to the way
modifications are submitted. The URL (and WSDL) for submitting the recurring transaction
listed in the Appendix.
To submit recurring payments, you must supply HTTP basic authentication credentials
(username/password). For the username you should use
“[email protected]”, you can set the password for this user in the
Barclaycard SmartPay Backoffice (under “Settings”->”Users”).
Please Note: It is typically possible to submit a subsequent recurring transaction after 5
minutes from the contract being created.
To submit a recurring transaction you will need to call the authorise action in the payment
service. Within this action there are two different requests according to the payment type
used for the transaction:
•
•
paymentRequest
directDebitRequest
For card, ELV and direct ebanking you will use the “paymentRequest”,
Please see the following pages for a break down on the recurringPayment request and the
response listing the possible values.
Recurring paymentRequest Payments
The “paymentRequest“ has the following fields:
Field Name
Description
selectedRecurringDetailReference
This is the recurringDetailReference you want to use
for this payment. You can use the value “LATEST” to
select the most recently used recurring detail.
recurring
The contract value of the recurring object should be
present and contain value “RECURRING” for the
contract field.
merchantAccount
The merchant account you want to process this
payment with.
amount
The amount to authorise. This consists of a
currencyCode and a value which is the amount in
minor units (see explanation for the paymentAmount
session).
reference
Your reference for this payment. This (merchant)
reference will be used in all communication to you
about the status of the payment. Although it is not a
requirement it is a good idea to make this unique.
shopperEmail
The email address of the shopper. This does not have
to match the email address supplied with the initial
payment, since it may have changed in the mean time.
shopperReference
The reference to the shopper. This shopperReference
must be the same as the shopperReference used in
the initial payment.
shopperInteraction
The shopperInteraction of the recurring payment must
be set to “ContAuth”,
fraudOffset (optional)
A integer that is added to normal fraud score. The
value can be either positive or negative.
shopperIP (optional)
The IP address of the shopper. Used in various risk
checks (number of payment attempts, location, etc.)
An example of a SOAP request is below showing how the above can be used to submit a recurring
payment.
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<ns1:authorise xmlns:ns1="http://payment.services.adyen.com">
<ns1:paymentRequest>
<amount xmlns="http://payment.services.adyen.com">
<currency xmlns="http://common.services.adyen.com">EUR</currency>
<value xmlns="http://common.services.adyen.com">100</value>
</amount>
<ns1:merchantAccount>YourMerchantAccount</ns1:merchantAccount>
<ns1:reference>RecurringPayment-0001</ns1:reference>
<ns1:shopperIP>1.1.1.1</ns1:shopperIP>
<ns1:shopperEmail>[email protected]</ns1:shopperEmail>
<ns1:shopperReference>TheShopperReference</ns1:shopperReference>
<ns1:selectedRecurringDetailReference>LATEST</ns1:selectedRecurringDetailReference>
<ns1:recurring>
<ns1:contract>RECURRING</ns1:contract>
</ns1:recurring>
<ns1:shopperInteraction>ContAuth</ns1:shopperInteraction>
</ns1:paymentRequest>
</ns1:authorise>
</soap:Body>
</soap:Envelope>
Example of a Recurring Payment SOAP request
Recurring paymentRequest response
If the message passes validation a risk analysis will be done and, depending on the
outcome, authorisation will be attempted.
You will receive a payment response with the following fields:
Field Name
Description
pspReference
The reference we assigned to the payment. This is guaranteed to
be globally unique and must be used when communicating about
this payment to us.
resultCode
The result of the payment. One of Authorised, Refused or Error
authCode
If the payment was successful the authCode (authorisation code)
field will contain a value. In all other cases it will be blank.
refusalReason
If the payment was refused, the refusal reason will be specified
here.
Please see the following page for an example of the soap recurring payment response.
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<ns1:authoriseResponse xmlns:ns1="http://payment.services.adyen.com">
<ns1:paymentResult>
<additionalData xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
<authCode xmlns="http://payment.services.adyen.com">50472</authCode>
<dccAmount xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
<dccSignature xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
<fraudResult xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
<issuerUrl xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
<md xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
<paRequest xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
<pspReference xmlns="http://payment.services.adyen.com">
AnewPspReference
</pspReference>
<refusalReason xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
<resultCode xmlns="http://payment.services.adyen.com">Authorised</resultCode>
</ns1:paymentResult>
</ns1:authoriseResponse>
</soap:Body>
</soap:Envelope>
Example of a Recurring Payment SOAP response
You will be informed of the authorisation result via a notification sent to your Notification
URL. Please see the SmartPay Notification Guide for further information.
Section
Topic
F
Virtual Terminal Users
With the Virtual Terminal a login screen is presented to control who can access your Virtual
Terminal. We will now take you through setting up a user to access the Virtual Terminal for
your account. Full details on setting up users and the role permissions can be found in the
user guide.
1.
Log in to the back office.
2. Select ‘Settings’ from the options on the left and then select ‘Users’ from the options
on screen.
3. Select the ’New’ tab from the choice along the top of the page. You will then be shown
the ‘Create New User’ screen.
4. Enter the Username and Password you wish.
Note: Please ensure that your User Name should only consist of standard
alpha/numeric characters.
5. In the Roles section select the role ‘CallCenter user role’ by putting a tick in the box next
to the role under the ‘+’.
6. Navigate down to Associated Accounts, this will list all your accounts, select the
account which has been setup for MOTO payments and put a tick in the box next to
the account under the ‘+’.
7.
Once you are happy with your selection please select ‘Save’. This will create your new
user for the Virtual Terminal.
8. Once the account is created, add the user contact information. Select “Edit User
Contact Details” at the bottom of the page.
9. Then enter your contact information.
Section
Topic
G
Trouble Shooting
Appendix
Below we’ve listed some of the common errors you may receive which connecting to the
Virtual Terminal. If you receive an error or have any difficulties which are not covered by the
following then please do not hesitate to contact the support team.
Error received when accessing the Call Centre pages
Error Message
Description
If when a user clicks on the link or bookmark to open the Virtual
Terminal pages, tries to log in and receives this error – An Error has
Occurred – please check that the merchant account value, which is
being passed in the string, is correct and is enabled to take MOTO
payments. Please contact our support team to check if you are not
sure.
Invalid Login error
Error Message
Description
When logging in, if Invalid Login appears the user should check their
log in details and the URL. Users should login using the live URL;
details of the different URL’s can be found at the end of this document.
Section
G
Appendix
Topic
URL’s
URL’s for test
Callcenter URL –
https://callcenter-test.barclaycardsmartpay.com/callcenter/action/login.shtml
Payment SOAP Service –
https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Payment
Payment SOAP Service WSDL –
https://pal-test.barclaycardsmartpay.com/pal/Payment.wsdl
Modification SOAP Service –
https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Payment
Modification SOAP Service WSDL –
https://pal-test.barclaycardsmartpay.com/pal/Payment.wsdl
URL’s for Live
Callcenter URL –
https://callcenter-live.barclaycardsmartpay.com/callcenter/action/login.shtml
Payment SOAP Service –
https://pal-live.barclaycardsmartpay.com/pal/servlet/soap/Payment
Payment SOAP Service WSDL –
https://pal-live.barclaycardsmartpay.com/pal/Payment.wsdl
Modification SOAP Service –
https://pal-live.barclaycardsmartpay.com/pal/servlet/soap/Payment
Modification SOAP Service WSDL –
https://pal-live.barclaycardsmartpay.com/pal/Payment.wsdl
Notification SOAP Service WSDL –
https://ca-live.barclaycardsmartpay.com/ca/services/Notification?wsdl
Section
E
Appendix
Topic
Currency Codes
Currency
United Arab Emirates Dirham
Argentinean Peso
Australian Dollar
Bolivia Boliviano
Brazilian Real
Bulgarian Lev
Canadian Dollar
Swiss Franc
Chilean Peso
Chinese Yuan
Colombian Peso
Croatian Kuna
Czech Republic Koruna
Danish Krone
Estonia Kroon
Euro
British Pound
Hong Kong Dollar
Hungarian Forint
Israeli Shekel
Indian Rupee
Icelandic Krona
Japan Yen
South Korea Won
Lithuania Litas
Latvia Lats
Malaysian Ringgits
Morocco Dirham
Nepalese Rupee
(New) Mexican Peso
(New) Taiwan Dollar
Norwegian Krone
New Zealand Dollar
Pakistan Rupee
Paraguayan Guarani
Peruvian Sol
Poland Zloty
Romanian Leu
Russian Ruble
Saudi Arabia Riyal
Sweden Krona
Singapore Dollar
Slovakia EUR
Sri Lanka Rupee
Thailand Baht
Turkey Lira
Currency Code
AED
ARS
AUD
BOB
BRL
BGN
CAD
CHF
CLP
CNY
COP
HRK
CZK
DKK
EEK
EUR
GBP
HKD
HUF
ILS
INR
ISK
JPY
KRW
LTL
LVL
MYR
MAD
NPR
MXN
TWD
NOK
NZD
PKR
PYG
PEN
PLN
RON
RUB
SAR
SEK
SGD
SKK
LKR
THB
TRY
Country
Uruguayan Peso
US Dollar
Venezuelan Bolivar
South African Rand
Currency Code
UYU
USD
VEF
ZAR
If the country or currency you require does not appear in the above then please contact
our support team.