Barclaycard SmartPay API Integration Guide

Version 3.0 released April 2012

DOC Version Control Version No. 1.0 2.0 3.0 Date Issued August 2010 February 2012 April 2012 Reason for Change Initial Document Update 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
Purpose of this Document................................................................................................... 4 Intended Audience ............................................................................................................... 4 Contacting us ...................................................................................................................... 4 Documentation & Code Examples ....................................................................................... 4 Glossary ...............................................................................................................................5 How to use this Document .................................................................................................. 6 Payment Process .................................................................................................................7 Introduction ............................................................................................................................. 7 Payment Process.................................................................................................................... 7 Step 1 Order Ready ............................................................................................................. 7 Step 2 Submitting Transaction Request........................................................................... 7 Step 3 Transaction Result..................................................................................................10 Notifications ....................................................................................................................... 11 Additional Payment Response Data ................................................................................... 12 Address Verification Service (AVS) .................................................................................... 13 Test AVS Result .................................................................................................................... 13 Modifications ......................................................................................................................14 Internet Authentication ...................................................................................................... 15 API - Oneclick Payments.....................................................................................................18 Retrieving the Stored Details for a Customer ................................................................... 19 Submitting a RECURRING Payment ...................................................................................22 API - Recurring Payments...................................................................................................23 The Initial Payment example RECURRING ......................................................................23 Retrieving the Stored Details for a Customer ...................................................................24 Submitting a RECURRING Payment ...................................................................................26 Updating Stored Details.......................................................................................................27 Disabling Stored Details.......................................................................................................27 API - Tokenisation.............................................................................................................. 28 Tokenising a Payment Detail .............................................................................................. 28 Processing a Refund Card Deposit................................................................................... 31 Independent Refund - Directly Depositing Funds on a Card...........................................33 Notification .............................................................................................................................33 iDEAL Payments................................................................................................................ 34 Retrieving the list of iDEAL issuers .................................................................................... 34 Setting up an iDEAL Payment Session ..............................................................................35 Checking the status of a payment......................................................................................37 ELV Payments ................................................................................................................... 40 Appendix Test and Live URLs .........................................................................................41 URLs for test......................................................................................................................... 41 URLs for Live.........................................................................................................................42 Appendix SOAP Faults.................................................................................................... 43

Purpose of this Document

This guide provides you with the essential information required to integrate your service to communicate with Barclaycard SmartPay using the API. It also provides details on how Barclaycard SmartPay handles transactions that can be authenticated under the Internet Authentication service. This document should be used in conjunction with the Barclaycard SmartPay Integration Guide, which covers aspects of the modification messages and other options which are available. A link to the latest documentation can found at the bottom of this page.

Intended Audience
This document is intended for use by: Merchants performing their own integrations Web developers working on behalf of merchants Merchant Development Partners

It is recommended that the merchant responsible for the merchant account reviews this document to ensure appropriate configuration of the account. A thorough knowledge of HTML, SOAP and web-based scripting language is required for successful integration of Barclaycard SmartPay. You must ensure that you have the necessary experience with the required skill sets in order to avoid problems with your integration. If you have any queries or questions whilst reading this document, please feel free to contact the support team.

Contacting us
Contact our support team via email at:Support.SmartPay@barclaycard.co.uk Alternatively you can call our support team on the following numbers:From the UK Outside the UK Support hours:Monday to Friday: 8.00 to 18:00 GMT 01604 269518* +441604269518*

* Calls may be monitored or recorded to maintain high levels of security and quality of service

Documentation & Code Examples

This guide and other useful documents, which can help you with you integration and store setup, can be found at the support website. Please refer to your set up email.

-4-

Glossary
Term 3D Secure API AVS CLIEOP CSC ELFPROEF GBP HMAC HPP HTML HTTP Definition Also referred to as Internet Authentication, this term is used to describe the process of Verified by Visa and MasterCard SecureCode Application Programming Interface Address Verification Service Dutch Direct Debit batch submission format Card Security Code also known as CV2, CVV2, CVC, CID and CVN Also known as the eleven test it is the format that all Dutch 9 digit bank account numbers conform to Great British Pound (Sterling) Hash Message Authentication Code a method of encrypting data Hosted Payment Page Barclaycard SmartPays payment pages which take the payment for you Hypertext Mark up Language language used to construct web pages 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 International Standards Organisation a recognised protocol for transaction transmission Payment Card Industry Data Security Standard The security standard for handling card data. Really Simple Syndication or Rich Site Summary MasterCards process to authenticate the customer as the cardholder during online purchases Barclaycards secure payment service Simple Object Access Protocol a generic message structure used by programming languages to communicate data in a standard format. Secure Sockets Layer a protocol designed to provide secure communications on the internet Uniform Resource Locator an internet address Verified by Visa Visas process to authenticate the customers as the cardholder for online purchases Web Service Definition Language XML based language that provides a structure to a web service

HTTPS ISO PCI DSS RSS MasterCard SecureCode Barclaycard SmartPay SOAP SSL URL VbV WSDL

-5-

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

Recurring Payments

This type of header will appear at the start of each new subject. There are 9 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 Content Payment Process Additional Response Data Address Verification Service Internet Authentication One Click Payments Card Deposit Payment methods Appendix Description How the payment pages can fit into the purchase process. Covers the additional fields and values that can be returned if required. How to pass the billing address as part of the transaction Explains the additional fields and steps to include Internet Authentication in the Authorisation request. Covers how payment details can be stored for repeat customers How to issue a credit without an original transaction Explains how to integrate with other payment methods such as ELV and iDEAL

A B C D E F G H

Section

Topic

A
Introduction

Payment Process

The Barclaycard SmartPay API enables you to submit payments to the Barclaycard SmartPay payment system using a SOAP API. There are some situations in which you may need to capture the payment details on your PCI DSS compliant site and then use the SOAP API to submit these to Barclaycard SmartPay. Please Note - API Payments are not enabled by default. Please contact the SmartPay support team to enable this functionality.

Payment Process
You will need to ensure that your site is PCI DSS compliant to capture payment details. This guide explains how your PCI DSS compliant site could be integrated with Barclaycard SmartPay and the steps involved.

Step 1 Order Ready

When one of your customers visits your website/shopping cart and adds the products or services they wish to purchase into their shopping basket, your site may then store this information in an orders database with a unique order reference which your system creates. This can be passed over with the customers payment details to Barclaycard SmartPay.

Step 2 Submitting Transaction Request

Submitting API payments is implemented as a SOAP service, using the same URL, WSDL, To submit modification messages, you must supply HTTP basic authentication credentials (username/password). The username you should use is ws@Company.YourCompanyAccount, you can set the password for this user in the SmartPay Backoffice (under settings->users). Please note that like modifications, API payments also require HTTP basic authentication. First we will explain a simple credit card submission. In subsequent sections we will explain how to implement Internet Authentication (Verified by Visa / MasterCard SecureCode) and other payment methods like ELV and iDEAL. The fields in the transaction request are: merchantAccount - the merchant account you want to process this payment with. amount - the amount to authorise. This consists of a currency code and a value which is the amount in minor units (please see the Barclaycard SmartPay Integration Guide for an explanation for the paymentAmount session fields). reference - your reference for this payment, this could be your shopping basket reference. Although it is a good idea to make sure it is unique, this is not a requirement. This reference will be used in all communication to you about the status of the payment. (max field length 80 characters) shopperIP (optional) - The IP address of the customer. Used in various risk checks (e.g. number of payment attempts, location based checks) so it is good practise to supply

this. card - A container for credit card data. This should contain the following items: o o o o o o o o expiryMonth - The expiration date's month part. Supply as a 2 digit string padded with 0 (e.g. 03 or 12) expiryYear - The expiration date's year part written in full (e.g. 2008) holderName - The card holder's name (as embossed on the card) number - The card number cvc - The card validation code, also known as Card Security Code (CSC). issueNumber - The issue number startMonth - same format as expiryMonth startYear - same format as expiryYear

shopperEmail (optional) - The email address of the customer. If available it is useful to specify it as it is used in a velocity fraud check. shopperReference (optional) - An ID that refers uniquely to the customer (e.g. a customer ID in a shopping cart system). If supplied the shopperReference can be used in velocity fraud checking. (max field length 80 characters)

Please Note: Example soap payment request and response on the following page.

-8-

You should use a SOAP toolkit to generate the actual SOAP request. Below is an example of a SOAP API request. <?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">2000</value> </amount> <card xmlns="http://payment.services.adyen.com"> <cvc>737</cvc> <expiryMonth>12</expiryMonth> <expiryYear>2012</expiryYear> <holderName>Mr Test</holderName> <number>4111111111111111</number> </card> <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchant</merchantAccount> <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference> <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail> <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP> <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference> </ns1:paymentRequest> </ns1:authorise> </soap:Body> </soap:Envelope> Example SOAP Payment Request <?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> <authCode xmlns="http://payment.services.adyen.com">64158</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">8313547924770610</authCode> <refusalReason xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <resultCode xmlns="http://payment.services.adyen.com">Authorised</authCode> </ns1:paymentResult> </ns1:authoriseResponse> </soap:Body> </soap:Envelope> Example SOAP Payment Result

-9-

Step 3 Transaction Result

If the message passes validation a risk analysis will be performed and, depending on the outcome, authorisation attempted. You will receive a response with the following fields: pspReference The unique reference assigned by Barclaycard SmartPay to the payment. This is globally unique and must be used when communicating about this payment to us. (max field length 16 characters) resultCode - The result of the payment: Authorised, Refused, Error". authCode - If the payment was successful, this field contains the authorisation code. In all other cases it will be blank. refusalReason - If the payment was refused, the refusal reason will be specified here. A list of the possible return values and their meaning can be found in the following table. refusalReason Refused Referral Acquirer Error Blocked Card Expired Card Invalid Amount Invalid Card Number Issuer Unavailable Fraud Description Declined by issuer (eg insufficient funds or not suitable for this use) Declined by issuer (card holder needs to contact bank) Declined because of an error with the acquirer Declined because the card is blocked (e.g. lost or stolen) Declined because card is no longer valid Declined because amount is incorrect Declined because card number does not exist Declined because of a system error at the issuer side Declined by Barclaycard SmartPay due to fraud suspicion

In addition to the result returned you can also receive a notification message to you specify notification script. Further details on notifications can be found in the Barclaycard SmartPay Integration Guide.

- 10 -

Section

Topic

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.

- 11 -

Section

Topic

Additional Payment Response Data

Extra response fields can be added to the SOAP response in the additionalData field. These extra response fields are not enabled by default; if you require them please contact Barclaycard SmartPay support to enable this for your Merchant Account. Referred If the issuer has referred the payment then this field will have the value of true, otherwise the field will not be available. authCode - If the payment was successful, the authCode (authorisation code) field will contain a value. In all other cases it will be blank. cvcResult - The CSC result of the payment. All possible values: Value 0 1 2 3 4 5 6 Description Unknown Matches Does not match Not checked No CSC provided, but was required Issuer not certified for CSC No CSC Provided

avsResult - The AVS result of the payment. All possible values: Value 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 Description Unknown Address matches, postal code doesn't Neither postal code nor address match AVS unavailable AVS not supported for this card type No AVS data provided Postal code matches, address doesn't match Both postal code and address match Address not checked, postal code unknown Address matches, postal code unknown Address doesn't match, postal code unknown Postal code not checked, address unknown Address matches, postal code not checked Address doesn't match, postal code not checked Postal code matches, address unknown Postal code matches, address not checked Postal code doesn't match, address unknown Postal code doesn't match, address not checked Neither postal code nor address were checked

If available, it is also possible to receive the raw results that we receive from the acquirer. This is an extra setting that must be enabled for your Merchant Account. This setting will add the following fields to the additionalData field of the SOAP response. cvcResultRaw - The raw CSC result received from the Acquirer, if available. avsResultRaw - The raw AVS result received from the Acquirer, if available. refusalReasonRaw - The raw refusal reason received from the Acquirer, if available.

- 12 -

Section

Topic

Address Verification Service (AVS)

Address Verification System (AVS) is a security feature that verifies the billing address of the card holder. It does so by comparing the numeric portions of the card holder's registered billing address to those entered by the customer. AVS is only supported on a limited set of acquiring connections and only for a limited set of countries (United States, Great Britain and Canada) and card types. Please check which AVS options are supported with your technical contact at Barclaycard. You should supply the full address of the customer as a billingAddress sub-element of the card element. Billing Address Example (AVS) <billingAddress xmlns="http://payment.services.adyen.com"> <city xmlns="http://common.services.adyen.com">Burbank</city> <street xmlns="http://common.services.adyen.com">South Buena Vista Street</street> <houseNumberOrName xmlns="http://common.services.adyen.com">500</houseNumberOrName> <postalCode xmlns="http://common.services.adyen.com">91521</postalCode> <stateOrProvince xmlns="http://common.services.adyen.com">California</stateOrProvince> <country xmlns="http://common.services.adyen.com">US</country> </billingAddress> Note that the country is the 2-letter ISO country code (e.g. GB for the Great Britain). Please note: an invalid country code will result in the payment request being rejected.

Test AVS Result

It is possible to test the 19 different AVS result codes. If the street billingAddress field has the value: Test AVS result You can specify the avsResult value in the houseNumberOrName field. Note that all other billing address fields are still required, but the value does not matter. The avsResult for the following example returns 17. Test avsResult Billing Address Example <billingAddress xmlns="http://payment.services.adyen.com"> <city xmlns="http://common.services.adyen.com">TestCity</city> <street xmlns="http://common.services.adyen.com">Test AVS result</street> <houseNumberOrName xmlns="http://common.services.adyen.com">17</houseNumberOrName> <postalCode xmlns="http://common.services.adyen.com">1111</postalCode> <stateOrProvince xmlns="http://common.services.adyen.com">TestState</stateOrProvince> <country xmlns="http://common.services.adyen.com">NL</country> </billingAddress>

Section

Topic

Modifications

It is possible to perform modifications using your account on the Barclaycard SmartPay Backoffice. It is generally a good idea to automate this if you are processing more than a handful of payments daily. For this we offer a SOAP web service which accepts the modification requests from your Backoffice systems. The modification types include: capture refund cancel cancelOrRefund

To submit modification messages, you must supply HTTP basic authentication credentials (username/password). The username you should use is ws@Company.YourCompanyAccount, you can set the password for this user in the Merchant Backoffice (under settings->users). For more information please refer to the SmartPay Modifications Guide.

- 14 -

Section

Topic

Internet Authentication

In order to process Internet Authentication (Verified by Visa/MasterCard SecureCode) payments, the payment process can include the customer being redirected to their card issuer to authenticate themselves before the payment can be authorised. In order for you to start processing Internet Authenticated transactions, the following changes are required. 1. Your processing account needs to be configured by Barclaycard SmartPay to support Internet Authentication.

2. Your software should support redirecting the customer to the card issuer and submitting a second API call to complete the payment. The initial API call is the same as a standard authorise/paymentRequest (please see Payment Process section of the guide) except that you are also required to supply a browserInfo element as a sub-element of the payment request which is a container for the acceptHeader and userAgent of the customer's browser, e.g.: BrowserInfo Example
<browserInfo xmlns="http://payment.services.adyen.com"> <acceptHeader xmlns="http://common.services.adyen.com">text/html,application/xhtml+xml, application/xml;q=0.9,*/*;q=0.8</acceptHeader> <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0</userAgent> </browserInfo>

When your account is configured for Internet Authentication, Barclaycard SmartPay performs a directory inquiry to check if the card is enrolled for Internet Authentication. If the card isn't enrolled, the response will be the same as a normal API authorisation. However, if the card is enrolled, the response will contain the following fields: paRequest - The Internet Authentication request data for the issuer md - The payment session issuerUrl - The URL to direct the customer to resultCode - The resultCode will be RedirectShopper

On receiving a response you should create a HTML form with the following fields. It is recommended that the form is self-submitting with a fallback in case JavaScript is disabled. PaReq Taken from the paRequest. TermUrl The URL you wish the customer to be returned to after completing the Internet Authentication process. MD Taken from the md response.

The form should be configured to submit to the issuerUrl supplied in the response. An example form which does this is presented below:

- 15 -

<body onload="document.getElementById('3dform').submit();"> <form method="POST" action="${issuerUrl}" id="3dform"> <input type="hidden" name="PaReq" value="${paRequest}" /> <input type="hidden" name="TermUrl" value="${termUrl}" /> <input type="hidden" name="MD" value="${md}" /> <noscript> <br/> <br/> <div style="text-align: center"> <h1>Processing your 3-D Secure Transaction </h1> <p>Please click continue to continue the processing of your 3-D Secure transaction.</p> <input type="submit" class="button" value="continue"/> </div> </noscript> </form> </body> Example 3-D Secure HTML Form After the customer authenticates with their issuer, the issuer will return the customer to your site by sending an HTTP POST request to the TermUrl containing the MD and PaRes parameters which you will need to complete the payment. To complete the payment these parameters should be submitted to the authorise3d action. The following fields should be submitted: merchantAccount The merchant account you want to process this payment with (this should be the same as in the original authorise request) browserInfo The browser info element as explained above. It is safe to use the values from the current request, as they are unlikely to change during the course of a payment. md The value of the MD parameter received from the issuer paResponse The value of the PaRes parameter received from the issuer. shopperIP (not required) The IP address of the customer. Used in various risk checks (e.g. number of payment attempts, location based checks) so it is good practise to supply this.

- 16 -

Again, although you should use a SOAP toolkit to generate the actual SOAP request, the authorise3d request will look something like the following example. The response to this request is the same as a normal authorisation and the resultcode will be one of: authorised, refused or error. <?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:authorise3d xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest3d> <browserInfo xmlns="http://payment.services.adyen.com"> <acceptHeader xmlns="http://common.services.adyen.com">text/html,appli.../*;q=0.8</acceptHeader> <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 ... Firefox/3.0</userAgent> </browserInfo> <md xmlns="http://payment.services.adyen.com">31h..........vOXek7w=</md> <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchant</merchantAccount> <paResponse xmlns="http://payment.services.adyen.com">eNqtmF........wGVA4Ch</paResponse> <shopperIP xmlns="http://payment.services.adyen.com">62.194.82.12</shopperIP> </ns1:paymentRequest3d> </ns1:authorise3d> </soap:Body> </soap:Envelope> Authorise3D Request Example

- 17 -

Section

Topic

API - Oneclick Payments

One-Click Payments can be used to allow repeat/known customers to pay without the customer re-entering their payment details each time. This is achieved by allowing your customers to store their payment details during their first payment and using these details for subsequent requests. Depending on the payment method, the customer may have to enter a validation code (such as their credit card's CSC code). Currently One-Click payments work with card and ELV payments.

The Initial Payment

The initial payment (or subsequent payments with different details) are normal payment requests as described in Section A Payment Process. The only difference is the addition of the Recurring object to the payment request and that the shopperReference and shopperEmail are required. The Recurring object contains the following fields: contract - This should be set to the value ONECLICK recurringDetailName (optional) - This is a short description the customer can enter to identify their payment details. (e.g. My Visa card).

If the payment is successful, the details will be stored. Payment example on following page.

- 18 -

<?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">GBP</currency> <value xmlns="http://common.services.adyen.com">5000</value> </amount> <card xmlns="http://payment.services.adyen.com"> <cvc>737</cvc> <expiryMonth>12</expiryMonth> <expiryYear>2012</expiryYear> <holderName>Test Test</holderName> <number>4111111111111111</number> </card> <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchantAccount</merchantAccount> <reference xmlns="http://payment.services.adyen.com">YourMerchantReference</reference> <shopperEmail xmlns="http://payment.services.adyen.com">test@test.com</shopperEmail> <shopperReference xmlns="http://payment.services.adyen.com">TheShopperReference</shopperReference> <Recurring xmlns="http://payment.services.adyen.com"> <contract>ONECLICK</contract> </Recurring> </ns1:paymentRequest> </ns1:authorise> </soap:Body> </soap:Envelope> Example ONECLICK Payment Request

Retrieving the Stored Details for a Customer

When a known customer wants to make a payment, you will check with Barclaycard SmartPay to find out if there are any stored details available which could be used to complete their payment. Please Note: You should always wait a few minutes before doing a listRecurringDetail call. There is no need to do this directly after the payment. This is done by calling the listRecurringDetails action on the Recurring service with a RecurringDetailsRequest. The RecurringDetailsRequest has two fields: merchantAccount - Your merchant account shopperReference - The reference to the customer

Example listRecurringDetails request can be found on the following page.

- 19 -

<?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:listRecurringDetails xmlns:ns1="http://recurring.services.adyen.com"> <ns1:request> <ns1:recurring> <contract xmlns="http://payment.services.adyen.com">ONECLICK</contract> </ns1:recurring> <ns1:merchantAccount>YourMerchantAccount</ns1:merchantAccount> <ns1:shopperReference>TheShopperReference</ns1:shopperReference> </ns1:request> </ns1:listRecurringDetails> </soap:Body> </soap:Envelope> Example listRecurringDetails SOAP Request for ONECLICK

The response will be a listRecurringDetailsResponse with a list of zero or more details containing: recurringDetailReference - The reference the details are stored under (max field length 16 characters) name - The name given to the details by the customer (can be empty). Variant - The payment method (e.g. mc, visa or elv) creationDate The date when the recurring details were created

The customer payment detail summaries are stored in the same object types as you would have submitted in the initial payment. Depending on the payment method, one or more fields may be left blank or incomplete (e.g. CSC for card). Only one of the details below will be returned, the others will be nil. card - If the payment method is a card payment, this field will contain a Card object as you would have submitted this in a payment, with only the last four digits present in the card number and without a CSC value. elv - If the payment method is an ELV payment, this will contain a fully populated ELV object. You should decide how many details you would like to disclose to the customer, for example the full bank details are returned for ELV, but you may choose to display only the last 2 digits. You could also use this as a verification mechanism by asking the customer for the last two digits of their bank account number for verification. An example listRecurringDetailsResponse response can be found on the following page

- 20 -

<?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:listRecurringDetailsResponse xmlns:ns1="http://recurring.services.adyen.com"> <ns1:result xmlns:ns2="http://payment.services.adyen.com"> <ns1:creationDate>2009-10-27T11:26:22.203+01:00</ns1:creationDate> <details xmlns="http://recurring.services.adyen.com"> <RecurringDetail> <bank xsi:nil="true"/> <card> <cvc xmlns="http://payment.services.adyen.com xsi:nil="true""/> <expiryMonth xmlns="http://payment.services.adyen.com>12</expiryMonth> <expiryYear xmlns="http://payment.services.adyen.com>2012</expiryYear> <holderName xmlns="http://payment.services.adyen.com> Adyen Test </holderName> <issueNumber xmlns="http://payment.services.adyen.com xsi:nil="true"/> <number xmlns="http://payment.services.adyen.com>1111</number> <startMonth xmlns="http://payment.services.adyen.com xsi:nil="true"/> <startYear xmlns="http://payment.services.adyen.com xsi:nil="true"/> </card> <creationDate>2009-10-27T11:50:12.178+01:00</creationDate> <elv xsi:nil="true"/> <name/> <recurringDetailReference> RecurringDetailReference1 </recurringDetailReference> <variant>mc</variant> </RecurringDetail> <RecurringDetail> <bank xsi:nil="true"/> <card> <cvc xmlns="http://payment.services.adyen.com xsi:nil="true""/> <expiryMonth xmlns="http://payment.services.adyen.com>12</expiryMonth> <expiryYear xmlns="http://payment.services.adyen.com>2012</expiryYear> <holderName xmlns="http://payment.services.adyen.com> Adyen Test2 </holderName> <issueNumber xmlns="http://payment.services.adyen.com xsi:nil="true"/> <number xmlns="http://payment.services.adyen.com>1111</number> <startMonth xmlns="http://payment.services.adyen.com xsi:nil="true"/> <startYear xmlns="http://payment.services.adyen.com xsi:nil="true"/> </card> <creationDate>2009-10-27T11:26:22.216+01:00</creationDate> <elv xsi:nil="true"/> <name/> <recurringDetailReference> RecurringDetailReference2 </recurringDetailReference> <variant>visa</variant> </RecurringDetail> </details> <ns1:lastKnownShopperEmail>email@shopper.com</ns1:lastKnownShopperEmail> <ns1:shopperReference>TheShopperReference</ns1:shopperReference> </ns1:result> </ns1:listRecurringDetailsResponse> </soap:Body> </soap:Envelope>

- 21 -

Please note - that if you update a stored detail (see below) the recurringDetailReference for that detail will change and that cache entry should be invalidated.

Submitting a ONECLICK Payment

When submitting a payment using a payment detail returned from the listRecurringDetails, a normal payment request is generated, which follows the same rules as the initial payment and should be submitted to the Payment service. This means that the shopperReference and shopperEmail are required and that a Recurring object should be present and contain value ONECLICK for the contract field. However, the recurringDetailName should not be supplied. One additional field is added to the standard payment request: selectedRecurringDetailReference - This is the recurringDetailReference you need to use for this payment. The value LATEST can be used to select the most recently used recurring detail.

In case of a card payment, you should supply a Card object in the payment request with only the CSC value populated (see below). Other payment methods do not require you to supply an empty payment method specific object (e.g. you do not need to supply an empty ELV object for an ELV 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">GBP</currency> <value xmlns="http://common.services.adyen.com">5000</value> </amount> <card xmlns="http://payment.services.adyen.com"> <cvc>737</cvc> </card> <ns1:merchantAccount>YourMerchantAccount</ns1:merchantAccount> <ns1:reference>YourMerchantReference</ns1:reference> <ns1:shopperEmail>test@test.com</ns1:shopperEmail> <ns1:shopperReference>testtest</ns1:shopperReference> <ns1:selectedRecurringDetailReference>LATEST</ns1:selectedRecurringDetailReference> <ns1:recurring> <ns1:contract>ONECLICK</ns1:contract> </ns1:recurring> <ns1:shopperInteraction>ContAuth</ns1:shopperInteraction> </ns1:paymentRequest> </ns1:authorise> </soap:Body> </soap:Envelope> Example ONECLICK Payment Request

- 22 -

Section

Topic

API - Recurring Payments

Creating a recurring contract is done by having the shopper perform a regular payment and storing the card details. We refer to this as the initial payment. Recurring payments reuse payment details submitted earlier in the initial payment by the shopper to perform the payment.

The Initial Payment example RECURRING

The only difference to a standard payment request is the addition of the Recurring object to the payment request and that the shopperReference and shopperEmail are required. The Recurring object contains the following fields: contract - This should be set to the value RECURRING recurringDetailName (optional) - This is a short description the customer can enter to identify their payment details. (e.g. My Visa card).

If the payment is successful, the details will be stored. Please see initial payment example below. <?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">GBP</currency> <value xmlns="http://common.services.adyen.com">5000</value> </amount> <card xmlns="http://payment.services.adyen.com"> <cvc>737</cvc> <expiryMonth>12</expiryMonth> <expiryYear>2012</expiryYear> <holderName>Test Test</holderName> <number>4111111111111111</number> </card> <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchantAccount</merchantAccount> <reference xmlns="http://payment.services.adyen.com">YourMerchantReference</reference> <shopperEmail xmlns="http://payment.services.adyen.com">test@test.com</shopperEmail> <shopperReference xmlns="http://payment.services.adyen.com">TheShopperReference</shopperReference> <Recurring xmlns="http://payment.services.adyen.com"> <contract>RECURRING</contract> </Recurring> </ns1:paymentRequest> </ns1:authorise> </soap:Body> </soap:Envelope> Example RECURRING Payment Request

Retrieving the Stored Details for a Customer

When a known customer wants to make a payment, you will check with Barclaycard SmartPay to find out if there are any stored details available which could be used to complete their payment. Please Note: You should always wait a few minutes before doing a listRecurringDetail call. There is no need to do this directly after the payment. This is done by calling the listRecurringDetails action on the Recurring service with a RecurringDetailsRequest. The RecurringDetailsRequest has two fields: merchantAccount - Your merchant account shopperReference - The reference to the customer

<?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:listRecurringDetails xmlns:ns1="http://recurring.services.adyen.com"> <ns1:request> <ns1:recurring> <contract xmlns="http://payment.services.adyen.com">RECURRING</contract> </ns1:recurring> <ns1:merchantAccount>YourMerchantAccount</ns1:merchantAccount> <ns1:shopperReference>TheShopperReference</ns1:shopperReference> </ns1:request> </ns1:listRecurringDetails> </soap:Body> </soap:Envelope> Example listRecurringDetails SOAP Request for RECURRING The response will be a listRecurringDetailsResponse with a list of zero or more details containing: recurringDetailReference - The reference the details are stored under (max field length 16 characters) name - The name given to the details by the customer (can be empty). Variant - The payment method (e.g. mc, visa or elv) creationDate The date when the recurring details were created

The customer payment detail summaries are stored in the same object types as you would have submitted in the initial payment. Depending on the payment method, one or more fields may be left blank or incomplete (e.g. CSC for card). Only one of the details below will be returned, the others will be nil. card - If the payment method is a card payment, this field will contain a Card object as you would have submitted this in a payment, with only the last four digits present in the card number and without a CSC value. elv - If the payment method is an ELV payment, this will contain a fully populated ELV object. You should decide how many details you would like to disclose to the customer, for example the full bank details are returned for ELV, but you may choose to display only the last 2 digits. You could also use this as a verification mechanism by asking the customer for the last two digits of their bank account number for verification.

- 24 -

<?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:listRecurringDetailsResponse xmlns:ns1="http://recurring.services.adyen.com"> <ns1:result xmlns:ns2="http://payment.services.adyen.com"> <ns1:creationDate>2009-10-27T11:26:22.203+01:00</ns1:creationDate> <details xmlns="http://recurring.services.adyen.com"> <RecurringDetail> <bank xsi:nil="true"/> <card> <cvc xmlns="http://payment.services.adyen.com xsi:nil="true""/> <expiryMonth xmlns="http://payment.services.adyen.com>12</expiryMonth> <expiryYear xmlns="http://payment.services.adyen.com>2012</expiryYear> <holderName xmlns="http://payment.services.adyen.com> Adyen Test </holderName> <issueNumber xmlns="http://payment.services.adyen.com xsi:nil="true"/> <number xmlns="http://payment.services.adyen.com>1111</number> <startMonth xmlns="http://payment.services.adyen.com xsi:nil="true"/> <startYear xmlns="http://payment.services.adyen.com xsi:nil="true"/> </card> <creationDate>2009-10-27T11:50:12.178+01:00</creationDate> <elv xsi:nil="true"/> <name/> <recurringDetailReference> RecurringDetailReference1 </recurringDetailReference> <variant>mc</variant> </RecurringDetail> <RecurringDetail> <bank xsi:nil="true"/> <card> <cvc xmlns="http://payment.services.adyen.com xsi:nil="true""/> <expiryMonth xmlns="http://payment.services.adyen.com>12</expiryMonth> <expiryYear xmlns="http://payment.services.adyen.com>2012</expiryYear> <holderName xmlns="http://payment.services.adyen.com> Adyen Test2 </holderName> <issueNumber xmlns="http://payment.services.adyen.com xsi:nil="true"/> <number xmlns="http://payment.services.adyen.com>1111</number> <startMonth xmlns="http://payment.services.adyen.com xsi:nil="true"/> <startYear xmlns="http://payment.services.adyen.com xsi:nil="true"/> </card> <creationDate>2009-10-27T11:26:22.216+01:00</creationDate> <elv xsi:nil="true"/> <name/> <recurringDetailReference> RecurringDetailReference2 </recurringDetailReference> <variant>visa</variant> </RecurringDetail> </details> <ns1:lastKnownShopperEmail>email@shopper.com</ns1:lastKnownShopperEmail> <ns1:shopperReference>TheShopperReference</ns1:shopperReference> </ns1:result> </ns1:listRecurringDetailsResponse> </soap:Body> </soap:Envelope>

- 25 -

Please note - that if you update a stored detail (see below) the recurringDetailReference for that detail will change and that cache entry should be invalidated.

Submitting a RECURRING Payment

When submitting a payment using a payment detail returned from the listRecurringDetails, a normal payment request is generated, which follows the same rules as the initial payment and should be submitted to the Payment service. This means that the shopperReference and shopperEmail are required and that a Recurring object should be present and contain value RECURRING for the contract field. However, the recurringDetailName should not be supplied. One additional field is added to the standard payment request: selectedRecurringDetailReference - This is the recurringDetailReference you need to use for this payment. The value LATEST can be used to select the most recently used recurring detail.

In case of a card payment, you should supply a Card object in the payment request with only the CSC value populated. Other payment methods do not require you to supply an empty payment method specific object (e.g. you do not need to supply an empty ELV object for an ELV 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">GBP</currency> <value xmlns="http://common.services.adyen.com">5000</value> </amount> <ns1:merchantAccount>YourMerchantAccount</ns1:merchantAccount> <ns1:reference>YourMerchantReference</ns1:reference> <ns1:shopperEmail>test@test.com</ns1:shopperEmail> <ns1:shopperReference>testtest</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 RECURRING Payment Request

- 26 -

Updating Stored Details

The stored payment details may need to be updated (e.g. when the card expiry date changes). Simply submit the One-Click payment and add the details to change to the payment method specific object. For a card, this means that (for the example above) as well as the CSC, the expiryMonth and expiryYear fields should contain the new values. In case of a payment method like ELV, you should supply an empty ELV object with the values that need to be changed populated. If the payment is successful, the details will be updated. Note that the recurringDetailReference for the detail will change (and the old one is no longer valid). Therefore the stored details must be retrieved again for the next payment.

Disabling Stored Details

Disabling a stored payment detail for a customer (or all of their stored payment details) is done by calling the disable action on the recurring service. This action takes a DisableRequest with the following fields: merchantAccount - Your merchant account shopperReference - The reference to the customer recurringDetailReference (optional) - The recurringDetailReference of the details you wish to disable. If you do not supply this field, all details for your customer will be disabled, including the contract. This means that you cannot add new details anymore.

The response will be a DisableResult object with a single field response. If a single detail was disabled the value of this field will be [detail-successfully-disabled], if all details are disabled the value is [all-details-successfully-disabled].

- 27 -

Section

Topic

API - Tokenisation

Tokenising a Payment Detail

Rather than using an initial payment to create a recurring contract you can submit the details directly to the storeToken action on the Recurring service. Using this method you can transfer the existing cards in your own records/existing payment gateway to SmartPay. Full validation does not occur when storing tokens since payment is not yet taking place. For example, if an expired credit card is provided, it will be stored and not rejected. Please Note: Tokenisation is not enabled by default. Please contact the SmartPay Support Team if you would like to this functionality enabled. The request has the following fields: merchantAccount - The merchant account you want to store this details for. shopperEmail - The email address of the shopper. shopperReference - An ID that uniquely refers to the shopper (e.g. a customer ID in a shopping cart system). recurring contract - What type of recurring contract is used. One of: ONECLICK - Credit card data is stored for future use. The card's security code (CSC/CVC) must be provided during subsequent payments. RECURRING - Credit card data is stored for future use. The card's security code (CSC/CVC) is not required for subsequent payments. ONECLICK, RECURRING - Credit card data is stored for future use. The merchant decides whether the card's security code (CSC/CVC) is required during subsequent payments. recurringDetailName (optional) - An optional name that can be added to the recurring contract.

Depending on the payment method one or more fields may be left blank or incomplete (e.g. CVC for card). Only one of the details below will be returned, the others will be nil. card - A container for credit card data. This contains the following items: expiryMonth - The expiration date's month written as a 2-digit string, padded with 0 if required (e.g. 03 or 12). expiryYear - The expiration date's year part written in full (e.g. 2008). holderName - The card holder's name (as embossed on the card). number - The card number. Only the last 4 digits of the card number are returned (card summary)

- 28 -

cvc - The card validation code. This is the the CVC2 code (for MasterCard), CVV2 (for Visa) or CID (for American Express). The value should always be empty because it will not be stored. issueNumber (Maestro UK only - deprecated) - The issue number. startMonth (Maestro UK only - deprecated) - As per expiryMonth. startYear (Maestro UK only - deprecated) - As per expiryYear.

elv - A container for ELV data with the following fields: bankLocation - The city in which the bank (branch) is located. bankName - The name of the bank. bankLocationId - The location ID (Bankleitzahl) of the bank. accountHolderName - The account holder name. bankAccountNumber - The account number (Kontonummer).

bank - A container for BankAccount data with the following fields: bankAccountNumber - The account number. bankLocationId - The location id of the bank (will be nil in most cases). bankName - The name of the bank. bic -The BIC code of the bank details (will be nil in most cases). countryCode - The country of the bank details. iban - The IBAN of the bank details (will be nil in most cases). ownerName - The account holder name.

The response contains: rechargeReference - This is an Adyen internal value only. It should not be used for subsequent recurring methods. recurringDetailReference - The reference the details are stored under. result - This returns Success if the token has been stored.

Please see following page for an example of a storeToken request and response.

- 29 -

<?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:storeToken xmlns:ns1="http://recurring.services.adyen.com"> <ns1:request> <bank xmlns="http://recurring.services.adyen.com" xsi:nil="true"/> <card xmlns="http://recurring.services.adyen.com"> <expiryMonth xmlns="http://payment.services.adyen.com">12</expiryMonth> <expiryYear xmlns="http://payment.services.adyen.com">2012</expiryYear> <holderName xmlns="http://payment.services.adyen.com">Adyen Test</holderName> <number xmlns="http://payment.services.adyen.com">4111111111111111</number> </card> <elv xmlns="http://recurring.services.adyen.com" xsi:nil="true"/> <merchantAccount xmlns="http://recurring.services.adyen.com"> YourMerchantAccount </merchantAccount> <recurring xmlns="http://recurring.services.adyen.com"> <contract xmlns="http://payment.services.adyen.com">RECURRING</contract> <recurringDetailName xmlns="http://payment.services.adyen.com" xsi:nil="true"/> </recurring> <shopperEmail xmlns="http://recurring.services.adyen.com">email@shopper.com</shopperEmail> <shopperReference xmlns="http://recurring.services.adyen.com"> TheShopperReference </shopperReference> </ns1:request> </ns1:storeToken> </soap:Body> </soap:Envelope> Store Token Request

<?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:storeTokenResponse xmlns:ns1="http://recurring.services.adyen.com"> <ns1:result> <rechargeReference xmlns="http://recurring.services.adyen.com"> RechargeReference</rechargeReference> <recurringDetailReference xmlns="http://recurring.services.adyen.com"> RecurringDetailReference</recurringDetailReference> <result xmlns="http://recurring.services.adyen.com">Success</result> </ns1:result> </ns1:storeTokenResponse> </soap:Body> </soap:Envelope> Store Token Response

- 30 -

Section

Topic

Processing a Refund Card Deposit

A Refund or Card Deposit allows you to transfer funds directly onto a card. There are 2 methods to do this: 1. Refund against an existing payment using a modification request.

2. Independent Refund allows you to directly deposit funds on a card without an existing transaction. This requires you to submit the card details and is much like the process for submitting a direct payment.

Refund using an existing payment

In order to refund a payment, you will send a modification request to the refund action using the following fields: merchantAccount - The merchant account the payment was processed with. modificationAmount - The amount to refund. This consists of a currencyCode and a value which is the amount in minor units (see explanation for the paymentAmount session field in the Hosted Payment Pages chapter). The currencyCode must match the value in the original payment. originalReference - This is the pspReference that was assigned to the authorisation. You will have received it with the payment status or with the authorisation notification.

If the message was syntactically valid and merchantAccount is correct you will receive a refundReceived response with the following fields: pspReference - A new reference to uniquely identify this modification request. response - The response. In case of success, this will be [refund-received]. In case of an error, an informational message will be returned.

The actual result of the refund is sent via a notification with eventCode REFUND. The pspReference of this notification is the same as the pspReference in the SOAP response. The success field indicates if the refund was successful, yes or no. If not (when success is false), the reason field of the notification will give a short description why. To submit a Refund modification request, you must supply HTTP basic authentication credentials (username/password). The username you should use is ws@Company.YourCompanyAccount, you can set the password for this user in the Merchant Backoffice (under settings->users). An example of a refund request is included on the following page.

31

<?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:refund xmlns:ns1="http://payment.services.barclaycardsmartpay.com"> <ns1:modificationRequest> <merchantAccount xmlns="http://payment.services.barclaycardsmartpay.com"> YourMerchantAccount </merchantAccount> <modificationAmount xmlns="http://payment.services.barclaycardsmartpay.com"> <currency xmlns="http://common.services.barclaycardsmartpay.com"> EUR </currency> <value xmlns="http://common.services.barclaycardsmartpay.com">500</value> </modificationAmount> <originalReference xmlns="http://payment.services.barclaycardsmartpay.com"> ThePaymentPspReference </originalReference> </ns1:modificationRequest> </ns1:refund> </soap:Body> </soap:Envelope> Example Refund Modification Request

- 32 -

Independent Refund - Directly Depositing Funds on a Card

In order to use this method of refunding your merchant account must have API enabled, please contact our support team if you would like to submit this type of payment. To directly deposit funds onto a card (without reference to an existing transaction) is similar to submitting a payment to the API (please see section a Payment Process). The request is exactly the same as for a payment, however you will submit the request to the refundWithData method rather than the authorise method. <?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:refundWithData 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">2000</value> </amount> <card xmlns="http://payment.services.adyen.com"> <cvc>737</cvc> <expiryMonth>12</expiryMonth> <expiryYear>2012</expiryYear> <holderName>Mr Test</holderName> <number>4111111111111111</number> </card> <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchant</merchantAccount> <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference> <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail> <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP> <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference> </ns1:paymentRequest> </ns1:refundWithData> </soap:Body> </soap:Envelope> Example SOAP Independent Refund Request To submit a Independent Refund request, you must supply HTTP basic authentication credentials (username/password). The username you should use is ws@Company.YourCompanyAccount, you can set the password for this user in the Merchant Backoffice (under settings->users).

Notification
Notifications for card deposits (using both methods) are the same as for payments, but the eventCode is REFUND_WITH_DATA (see the Notifications chapter in the Integration Guide). Similarly to regular payments, you should check the success parameter to find out if the deposit succeeded.

- 33 -

Section

Topic

I
Payment Methods

iDEAL Payments

You may decide to use our API for processing iDEAL payments. The following sections describe the process and explain the various SOAP calls you need to implement. Please note - that this API is relatively complex and that it is far easier to use the Hosted Payment Pages (HPP) to process iDEAL.

Retrieving the list of iDEAL issuers

When starting the iDEAL payment, your customer will select their bank (iDEAL issuer) on the payment page. You can use the retrieveIdealIssuerList action on the Ideal service to get a list of the iDEAL issuers. This list rarely changes and the results should be cached for at least 24 hours. It is acceptable to retrieve the list at (web) application startup (or first use) and cache it in memory for the lifecycle of the web application (assuming the web application normally runs for at least a day). <?xml version="1.0" encoding="UTF-8"?> <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:retrieveIdealIssuerList xmlns:ns1="http://payment.services.adyen.com"/> </soap:Body> </soap:Envelope> Example Retrieve iDEAL Issuer List Request The result will be a retrieveIdealIssuerListResponse containing a list of iDEAL issuers. This list should be presented to the customer preferably with the appropriate logos, these are available to download from our support site: https://support.barclaycardsmartpay.com). When the customer has selected their bank, the corresponding issuer ID is used in the subsequent request.

<?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:retrieveIdealIssuerListResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:idealIssuerList> <ns1:IdealIssuer> <issuerId xmlns="http://payment.services.adyen.com">0081</issuerId> <issuerList xmlns="http://payment.services.adyen.com">Short</issuerList> <issuerName xmlns="http://payment.services.adyen.com">Fortis</issuerName> </ns1:IdealIssuer> <ns1:IdealIssuer> <issuerId xmlns="http://payment.services.adyen.com">0021</issuerId> <issuerList xmlns="http://payment.services.adyen.com">Short</issuerList> <issuerName xmlns="http://payment.services.adyen.com">Rabobank</issuerName> </ns1:IdealIssuer> <ns1:IdealIssuer> <issuerId xmlns="http://payment.services.adyen.com">0721</issuerId> <issuerList xmlns="http://payment.services.adyen.com">Short</issuerList>

- 34 -

<issuerName xmlns="http://payment.services.adyen.com">Postbank</issuerName> </ns1:IdealIssuer> <ns1:IdealIssuer> <issuerId xmlns="http://payment.services.adyen.com">0031</issuerId> <issuerList xmlns="http://payment.services.adyen.com">Short</issuerList> <issuerName xmlns="http://payment.services.adyen.com">ABN Amro</issuerName> </ns1:IdealIssuer> <ns1:IdealIssuer> <issuerId xmlns="http://payment.services.adyen.com">0751</issuerId> <issuerList xmlns="http://payment.services.adyen.com">Short</issuerList> <issuerName xmlns="http://payment.services.adyen.com">SNS Bank</issuerName> </ns1:IdealIssuer> </ns1:idealIssuerList> </ns1:retrieveIdealIssuerListResponse> </soap:Body> </soap:Envelope> Example iDEAL Issuers List Response

Setting up an iDEAL Payment Session

The next stage in processing an iDEAL payment is setting up the payment session and retrieving the URL the customer should be redirected to. This is done by submitting a BeginIdealRequest request object to the beginIdealPayment action. The request is rather like a normal payment request for a card payment, except that no card details are supplied and it contains the following extra fields: issuerId - The issuer ID as selected by the customer. entranceCode - Data of your choice, e.g. a session ID. This will be passed back in the return URL when the customer returns as a parameter ec. Maximum length is 40 characters and valid characters are limited to uppercase/lowercase letters and digits. merchantReturnUrl - The return URL that the customer should be redirected to back to your site. Maximum length is 512 characters. The iDEAL system will append extra parameters to this. language - Language preference, currently limited to nl or en. We recommend you use nl as many iDEAL implementations only support Dutch and all customers using iDEAL are expected to be able to operate their own home banking solution in Dutch.

<?xml version="1.0" encoding="UTF-8"?> <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:beginIdealPayment xmlns:ns1="http://payment.services.adyen.com"> <ns1:request> <additionalAmount xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <amount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">1000</value> </amount> <entranceCode xmlns="http://payment.services.adyen.com">49dce25b</entranceCode> <issuerId xmlns="http://payment.services.adyen.com">0721</issuerId> <language xmlns="http://payment.services.adyen.com">en</language> <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchant</merchantAccount> <merchantReturnUrl xmlns="http://payment.services.adyen.com">https://www.yourwebshop.com/completeIdeal .php?shopperLocale=en_GB&amp;merchantReference=Your%20Reference%20Here</merch antReturnUrl>

- 35 -

<reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference> <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail> <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP> <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference> </ns1:request> </ns1:beginIdealPayment> </soap:Body> </soap:Envelope> Example iDEAL Payment Setup Request The response to this message will contain a parameter returnURL which you will use to redirect the shopper to their bank. Please note that, depending on your software toolkit, the ampersand sign (&) may be XML escaped to (&amp;) as in the example shown below.

<?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:beginIdealPaymentResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:response> <acquirerId xmlns="http://payment.services.adyen.com">0030</acquirerId> <fraudResult xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <issuerId xmlns="http://payment.services.adyen.com">0721</issuerId>

<pspEchoData

xmlns="http://payment.services.adyen.com">1412340428467237:1000:0721:241:lT9d1r3Jje gFkTJNpC0zBmDCnYM=</pspEchoData> <pspReference xmlns="http://payment.services.adyen.com">1412340428467237</pspReference> <refusalReason xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <resultCode xmlns="http://payment.services.adyen.com">RedirectShopper</resultCode> <returnUrl xmlns="http://payment.services.adyen.com">https://mijn.postbank.nl/internetbankieren/Ses amLoginServlet?sessie=ideal&amp;trxid=0030902022738225&amp;random=3c7c81ffbe5af aba</returnUrl> <transactionId xmlns="http://payment.services.adyen.com">0030902022738225</transactionId> </ns1:response> </ns1:beginIdealPaymentResponse> </soap:Body> </soap:Envelope> Example Response to an iDEAL Payment Setup

- 36 -

Checking the status of a payment

When you have set up the iDEAL payment and redirected the customer to their bank, the customer can complete the payment. Barclaycard SmartPay will setup the payment session and will then take the responsibility to update the status of the payment. Therefore no further action is required by you for the payment to show up in the Barclaycard SmartPay Backoffice. If the payment was successful you will receive an authorisation notification. If you would like to know the status of the payment in real-time, when the customer returns to the merchantReturnURL, the following logic can be implemented to check the payment status: 1. If the customer returns to the merchantReturnURL, check the status of the payment. Normally the final status of the payment will be available immediately. If the resultCode is Pending, wait for Barclaycard SmartPay to send the notification. 2. If the customer does not return after 30 minutes and you have not received a notification from Barclaycard SmartPay, you may check the status of the payment. If the resultCode is Pending, wait for Barclaycard SmartPay to send the notification. Please Note - due to limitations of the iDEAL system, in exceptional cases, it can take payment sessions an extended period to receive a final status. If after twenty four hours no notification has been received the payment can be marked unsuccessful. To check the status of the payment when the customer returns you will call the retrieveStatusIdealPayment action with a request consisting of: entranceCode - The same value for this parameter as was specified by you when setting up the iDEAL payment. This is also passed as a parameter ec in the URL the shopper returns with. merchantAccount - Your merchant account. (Please see Section A Payment Process for more detail) pspEchoData - The value of this parameter was passed back in the response to the iDEAL payment setup. The data for this field is also passed as a parameter pspEchoData in the URL the customer returns with. Reference - Your reference for this payment (Please see Section A Payment Process for more detail) transactionId - The transactionId you received when setting up the payment. This is also passed as a parameter trxid in the URL the customer returns with.

<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:retrieveStatusIdealPayment xmlns:ns1="http://payment.services.adyen.com"> <ns1:request> <entranceCode xmlns="http://payment.services.adyen.com">49dce25b</entranceCode> <merchantAccount xmlns="http://payment.services.adyen.com">YourMerchant</merchantAccount> <pspEchoData xmlns="http://payment.services.adyen.com">1412340428467237:1000:0721:241:lT9d1r3Jje gFkTJNpC0zBmDCnYM=</pspEchoData> <reference xmlns="http://payment.services.adyen.com">TMRef1234</reference> <transactionId xmlns="http://payment.services.adyen.com">0030902022738225</transactionId> </ns1:request> </ns1:retrieveStatusIdealPayment> </soap:Body> </soap:Envelope>

- 37 -

The response to this request will tell you what the status is of the payment session. The resultCode tells you what the payment is in the SmartPay system. The iDEAL specific status code is relayed using the transactionStatus parameter. resultCode Authorised Pending Refused Refused Refused iDEAL transactionStatus Success Open Cancelled Expired Failure Description Payment completed successfully Payment status unknown at this time

Customer cancelled the transaction

The payment process didn't complete in time The payment failed for another reason

Please Note - that the Barclaycard SmartPay system only stores an iDEAL payment as a payment visible in the Backoffice on an Authorised resultCode. The Refused resultCode is ignored since it represents all abandoned/failed payment sessions, and not true refusals. If the payment is successful, the consumerAccountNumber, consumerName and consumerCity will be returned. If the result of the status request is Pending (Open), there is an issue was the iDEAL system preventing the determination of the final status. In this case the customer should be informed that the final status of their payment is not yet known. The Barclaycard SmartPay system will keep polling for the status of the payment and inform you using a standard authorisation notification when the final status becomes known and the payment completed successfully. After 24 hours the payment attempt can be considered closed. In the event of a customer not returning to your result page at all, as mentioned above, the Barclaycard SmartPay system will (at regular intervals) continue to attempt to establish the final result of the payment. This is done with the maximum allowed frequency by the iDEAL system so you should not attempt to duplicate this. If you have not received a notification within 30 minutes (and the customer hasn't returned to your result page) you may submit a single status request. If the resultCode is still Pending, you can consider the payment attempt closed after 24 hours (this is an exceptional case, but may happen if, for example, the iDEAL system is undergoing maintenance). Example of a Status Response for a Successful iDEAL transaction on the following page:

- 38 -

<?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:retrieveStatusIdealPaymentResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:response> <acquirerId xmlns="http://payment.services.adyen.com">0030</acquirerId> <consumerAccountNumber xmlns="http://payment.services.adyen.com">123456789</consumerAccountNumber> <consumerCity xmlns="http://payment.services.adyen.com">Amsterdam</consumerCity> <consumerName xmlns="http://payment.services.adyen.com">Jan Klaassen</consumerName> <fraudResult xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <issuerId xmlns="http://payment.services.adyen.com">0751</issuerId> <pspReference xmlns="http://payment.services.adyen.com">1312350556460138</pspReference> <refusalReason xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <resultCode xmlns="http://payment.services.adyen.com">Authorised</resultCode> <transactionId xmlns="http://payment.services.adyen.com">0030905060041370</transactionId> <transactionStatus xmlns="http://payment.services.adyen.com">Success</transactionStatus> </ns1:response> </ns1:retrieveStatusIdealPaymentResponse> </soap:Body> </soap:Envelope> Example of a Status Response for a Successful iDEAL transaction

- 39 -

Section

Topic

I
Payment Methods

ELV Payments

ELV (elektronisches Lastschriftverfahren) payments are a form of Electronic Direct Debit which is very popular in Germany. The request is the same as for a credit card request, but rather than supplying a card container, you supply an elv container with the following fields: bankLocation The city in which the bank (branch) is located bankName The name of the bank bankLocationId The location id (Bankleitzahl) of the bank accountHolderName The account holder name bankAccountNumber The account number (Kontonummer)

An example elv element is shown below: Example ELV Element

<elv xmlns="http://payment.services.adyen.com"> <accountHolderName>S. Hopper</accountHolderName> <bankAccountNumber>123123123</bankAccountNumber> <bankLocation>Hamburg</bankLocation> <bankLocationId>20010020</bankLocationId> <bankName>Postbank Hamburg</bankName> </elv>

40

Section

Topic

Appendix Test and Live URLs

Please find below a list of the URLs used by Barclaycard SmartPay, please note these have been divided between test and live, to access the corresponding account.

URLs for test

Payment SOAP Service https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Payment Payment SOAP Service WSDL https://pal-test.barclaycardsmartpay.com/pal/Payment.wsdl iDEAL SOAP Service https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Ideal iDEAL SOAP Service WSDL https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Ideal?wsdl Backoffice URL https://ca-test.barclaycardsmartpay.com/ca/ca/login.shtml Hosted Payment Pages (Multiple): https://test.barclaycardsmartpay.com/hpp/select.shtml Hosted Payment Pages (Single) https://test.barclaycardsmartpay.com/hpp/pay.shtml RSS Feed URL https://ca-test.barclaycardsmartpay.com/reports/rss/lasttxrss/MerchantAccount/** https://ca-test.barclaycardsmartpay.com/reports/rss/lasttxrss/Company/*** Reports URL https://ca-test.barclaycardsmartpay.com/reports/download/MerchantAccount/**/ https://ca-test.barclaycardsmartpay.com/reports/download/Company/***/ Modification SOAP Service https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Payment Modification SOAP Service WSDL https://pal-test.barclaycardsmartpay.com/pal/Payment.wsdl Notification SOAP Service WSDL https://ca-test.barclaycardsmartpay.com/ca/services/Notification?wsdl Open Invoice SOAP Service WSDL https://ca-test.barclaycardsmartpay.com/ca/services/OpenInvoiceDetail?wsdl Recurring SOAP Service URL https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Recurring Recurring SOAP Service WSDL https://pal-test.barclaycardsmartpay.com/pal/Recurring.wsdl

41

URLs for Live

Payment SOAP Service https://pal-live.barclaycardsmartpay.com/pal/servlet/soap/Payment Payment SOAP Service WSDL https://pal-live.barclaycardsmartpay.com/pal/Payment.wsdl iDEAL SOAP Service https://pal-live.barclaycardsmartpay.com/pal/servlet/soap/Ideal iDEAL SOAP Service WSDL https://pal-live.barclaycardsmartpay.com/pal/servlet/soap/Ideal?wsdl Backoffice URL https://ca-live.barclaycardsmartpay.com/ca/ca/login.shtml Hosted Payment Pages (Multiple): https://live.barclaycardsmartpay.com/hpp/select.shtml Hosted Payment Pages (Single) https://live.barclaycardsmartpay.com/hpp/pay.shtml RSS Feed URL https://ca-live.barclaycardsmartpay.com/reports/rss/lasttxrss/MerchantAccount/** https://ca-live.barclaycardsmartpay.com/reports/rss/lasttxrss/Company/*** Reports URL https://ca-live.barclaycardsmartpay.com/reports/download/MerchantAccount/**/ https://ca-live.barclaycardsmartpay.com/reports/download/Company/***/ 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 Open Invoice SOAP Service WSDL https://ca-live.barclaycardsmartpay.com/ca/services/OpenInvoiceDetail?wsdl Recurring SOAP Service URL https://pal-live.barclaycardsmartpay.com/pal/servlet/soap/Recurring Recurring SOAP Service WSDL https://pal-live.barclaycardsmartpay.com/pal/Recurring.wsdl ** - replace this marker with your Merchant Account name. *** - replace this marker with your Company Account name.

- 42 -

Section

Topic

Appendix SOAP Faults

If a payment request does not pass validation (or violates a security or configuration constraint) the platform does not accept (and does not store) the request. Instead you will receive a SOAP Fault which will contain a description of the problem. Generally this will be handled as an Exception in your SOAP toolkit. Below is an example of a SOAP fault message. Note that payment requests which are rejected with a SOAP Fault will not be charged. The way to check the description this is to read the faultstring. If the payment was rejected by our platform the fault string will start with one of "validation", "security" or "configuration" followed by a code and its descriptive message. The list of codes and messages are below, please check the latest version of this document for the latest list. <?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> <soap:Fault> <faultcode>soap:Server</faultcode> <faultstring>validation 101 Invalid card number</faultstring> </soap:Fault> </soap:Body> </soap:Envelope> Example of a SOAP Fault Error Code 000 010 100 101 102 103 104 105 107 108 Message Unknown Not allowed No amount specified Invalid card number Unable to determine variant CVC is not the right length Billing address problem Invalid PaRes from issuer Recurring is not enabled Invalid bankaccount number Description An unknown error occurred You are not allowed to perform this action There is no amount specified in the request The specified card number is not valid The system was not able to determine the variant of the card number The length of the CVC code is not correct for the given card number There was an error in the specified billing address fields The submitted PaRes (Internet Authentication Response) from the issuer is not correct Recurring is not configured on the merchant account The specified bankaccount number is not valid

109 110 111 112 117 125 126

Invalid variant BankDetails missing Invalid BankCountryCode specified This bank country is not supported Invalid billing addresss Invalid recurring contract specified Bank Account or Bank Location Id not valid or missing Account holder missing Card Holder Missing Expiry Date Invalid Billing address problem (Country) E.g country missing Invalid amount specified Unsupported currency specified Recurring requires shopperEmail and shopperReference

The determined variant of the card is not valid No bank details specified The specified bankCountryCode is not valid (bank payment) The specified bankCountryCode is not supported (bank payment) The specified billing address is not valid The specified recurring contract value is not valid The specified bank account or bank location Id is not valid or missing (elv payment) No account holder specified No card holder specified The specified expiry data is not a valid date Not all address information is being supplied. If you chose to supply address fields, you must supply all address fields. The specified amount is invalid, or above the equivalent of 50,000.00 EUR. The specified currency is not supported No shopperEmail or shopperReference specified

127 128 129 134

137 138 139

140

Invalid expiryMonth[1..12] / The specified expiry month/year is not valid or in the past expiryYear[>2000], or before now Invalid expiryMonth[1..12] / expiryYear[>2000] Bank Name or Bank Location not valid or missing Invalid startMonth[1..12] / startYear[>2000], or in the future Contract not found Invalid contract The specified expiry month/year is not valid The specified bank name or bank location Id is not valid or missing (elv payment) The specified start month/year is not valid or in the future The specified recurring contract could not be found The specified recurring contract is not valid

141 142

144

800 802

Barclaycard Global Payment Acceptance is a trading name of Barclay Bank PLC.. Barclays Bank PLC is authorised and regulated by the Financial Services Authority. Registered in England. Registered No: 1026167. Registered Office: 1 Churchill Place, London E14 5HP.

803 804 805

PaymentDetail not found Failed to disable RecurringDetailReference not available for provided recurringcontract Invalid Merchant Account Shouldn't have gotten here without a request! Internal error Unable To Process Payment details are not supported

The specified paymentdetails could not be found Unable to disable the specified recurring details The specified recurringDetailReference is not available for the specified recurring contract The specified merchant account is not valid No request specified, or invalid namespace An internal error occurred while processing the request The request could not be processed The specified payment details are not available for the specified action

901 902 903 904 905

Barclaycard Global Payment Acceptance is a trading name of Barclay Bank PLC.. Barclays Bank PLC is authorised and regulated by the Financial Services Authority. Registered in England. Registered No: 1026167. Registered Office: 1 Churchill Place, London E14 5HP.