Recurring payments manual

(1)

Recurring

payments

manual

(2)

Introduction

It is important to respect the DNS Time-To-Live (TTL) when communicating with Barclaycard SmartPay. Some frameworks, Java in particular, cache DNS lookups by default. Barclaycard SmartPay routinely changes their DNS configuration and, if your implementation caches the DNS lookup, your ability to submit modifications and/or payments may be impacted.

The latest version of this document is available at:

www.barclaycard.com/smartpay/documentation/

Audience

This is a technical manual aimed at IT personnel involved in integrating merchants’ systems with those at Barclaycard SmartPay.

In the following chapters we cover how you can: – create a recurring contract using an initial payment – retrieve the recurring contracts for a shopper – submit a recurring transaction

– update stored details

– deactivate a recurring contract or detail.

Recurring payments are not enabled by default If you would like to start processing recurring payments please contact Barclaycard SmartPay Support This document discusses the new recurring platform and is not compatible with the old recurring platform. Please note that SOAP calls to Barclaycard SmartPay may change, and are based on our WSDLs (listed in Appendix A).

The purpose of this manual is to enable you to create and submit recurring payments to the

Barclaycard SmartPay Payment System Recurring payments re-use payment details submitted

earlier by the shopper to perform the payment

(4)

What is a recurring contract?

The contract is identified using the shopperReference and merchantAccount fields which are specified as part of the payment session (Hosted Payment Pages) or the payment request (Direct API).

The recurring details each have a unique 16 digit reference number A recurring detail reference number can be used in place of the ‘real’ details to submit a payment to the system.

Recurring vs One-Click

One-Click functionality allows a shopper to optionally allow a merchant to store their credit card data within Barclaycard SmartPay The shopper makes this choice during their first payment by checking a checkbox For subsequent payments the shopper must be present to enter the CVC of their card. One-Click differs from recurring as follows:

– the shopper chooses whether their card data can be stored or not

– the shopper is always present for subsequent payments to supply their card’s security code (CSC/CVC).

One-Click has the advantage of ensuring full card

authorisation takes place for each payment, including card security code checks and 3D secure (if applicable), with the potential disadvantage that the shopper must be present for all payments.

Usual workflow

The usual workflow is as follows.

1 Create your recurring contract by performing an initial Payment with additional fields (Chapter 3), ensuring you store the shopperEmail, shopperReference, and recurringContract fields in your own system for later use. If you receive a successful AUTHORISED notification for

the payment then you know the recurring contract has been created (since you flagged the payment request as such) You do not receive the recurring detail reference at this time and need do nothing more in our system. 2 When you’re ready to do a subsequent payment,

optionally retrieve a list of all recurring details based on the shopperReference (provided in the first step of Chapter 6). Then create a Payment, with the selectedRecurringDetailReference set to either the selected value from the list just obtained or the word LATEST which uses the most recently stored recurring detail Set other fields (as per Chapter 7), taking into account what value recurringContract was set to in step 1. If the subsequent payment is successful you will receive a

successful AUTHORISATION notification.

Please see Appendix C for sample requests and responses for an entire workflow.

A recurring contract is a set of one or more recurring payment details linked to a unique

shopper on your merchant account.

(5)

Creating a recurring contract

Setting up the payment

The payment session is set up like a regular payment There are two previously optional fields which become compulsory and one new field which needs to be provided in the payment session form:

– shopperEmail: the email address of the shopper (previously optional)

– shopperReference: an ID that uniquely refers to the shopper (previously optional)

– recurringContract: the type of recurring contract is used. • One-Click – the shopper chooses whether to allow

their credit card data to be 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.

• One-click, 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.

Example 1 – recurring initial payment setup

If the payment is successful the details will be stored. Please note that shoppers are uniquely identified using the shopperReference parameter. It is very important that shoppers are securely logged in on your site and that the shopperReference parameter cannot be modified by the shopper.

Creating a recurring contract is done by having the shopper perform a regular payment

We refer to this as the ‘initial payment’, the details of which will be used to perform the

recurring payments later.

(6)

Retrieving the recurring

contract details

List recurring details request

This is done by calling the listRecurringDetails action on the recurring service with a request (see Chapter 7 for the login credentials).

The request has the following fields:

– merchantAccount: your merchant account – shopperReference: the reference to the shopper.

This shopperReference must be the same as the shopperReference used in the initial payment. – recurring:

• contract: this should be the same value as recurringContract in the payment where the recurring contract was created (Chapter 3). However, if One-Click, recurring was specified initially then this field can be either One-Click or recurring.

When you want to perform a recurring payment you check with Barclaycard SmartPay to find

out if there are any recurring details available which can be used to complete the payment.

<?xml version=”10”?> <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>

(7)

List recurring details response

The response will be a result with a list of zero or more details containing:

– recurringDetailReference: the reference under which the details are stored

– variant: the payment method (eg. mc, visa, elv, paypal). – creationDate: the date when the recurring details

were created.

The recurring contracts 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 blank or incomplete (eg. CVC for card). Only one of the details below will be returned per detail block, the others will be nil. For PayPal there is no detail block.

– 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 (eg 2016)

• 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)

• 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: the issue number (Maestro UK only - deprecated) • startMonth: as per expiryMonth

(Maestro UK only - deprecated) • startYear: as per expiryYear

(Maestro UK only - deprecated)

– 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 of the bank • accountHolderName: the account holder name • bankAccountNumber: the account number. – 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.

Caching of the recurring details for a shopper is encouraged. However, keep in mind that if you update a stored detail (see below) the recurringDetailReference for that detail will change and the cache entry should be invalidated.

(8)

<?xml version=”10”?> <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:22203+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:12178+01:00</creationDate> <elv xsi:nil=”true”/> <name xsi:nil=”true”/> <recurringDetailReference>RecurringDetailReference1</recurringDetailReference> <variant>mc</variant> </RecurringDetail> <RecurringDetail> <bank> <bankAccountNumber xmlns=”http://payment.services.adyen.com”>1234567890 </bankAccountNumber> <bankLocationId xmlns=”http://payment.services.adyen.com” xsi:nil=”true”/> <bankName xmlns=”http://payment.services.adyen.com”>AdyenBank</bankName> <bic xmlns=”http://payment.services.adyen.com” xsi:nil=”true”/> <countryCode xmlns=”http://payment.services.adyen.com”>NL</countryCode> <iban xmlns=”http://payment.services.adyen.com” xsi:nil=”true”/> <ownerName xmlns=”http://payment.services.adyen.com”>Shop Per</ownerName> </bank> <card xsi:nil=”true”/> <creationDate>2009-10-27T12:46:13119+01:00</creationDate> <elv xsi:nil=”true”/> <name xsi:nil=”true”/> <recurringDetailReference>RecurringDetailReference2</recurringDetailReference> <variant>ideal</variant> </RecurringDetail> <RecurringDetail> <bank xsi:nil=”true”/> <card xsi:nil=”true”/> <creationDate>2009-10-27T11:26:22216+01:00</creationDate> <elv xsi:nil=”true”/> <name xsi:nil=”true”/> <recurringDetailReference>RecurringDetailReference3</recurringDetailReference> <variant>paypal</variant> </RecurringDetail> </details> <ns1:lastKnownShopperEmail>[email protected]</ns1:lastKnownShopperEmail> <ns1:shopperReference>TheShopperReference</ns1:shopperReference> </ns1:result> </ns1:listRecurringDetailsResponse> </soap:Body> </soap:Envelope>

(9)

Submit a recurring transaction

You can submit a recurring payment using a specific recurringDetails record or by using the last created recurringDetails record. The request for the recurring payment is done using a paymentRequest.

Please note that direct debit payments were formerly submitted to the direct debit request rather than the payment request. The direct debit request was deprecated on 01 January 2011 and will be maintained until further notice for backward compatibility. Please see Appendix B for more information.

Payment request

Submitting a recurring payment is done by calling the authorise action on the payment service with a paymentRequest (see Chapter 7 for the login credentials). However a One-Click payment session is set up like a regular payment (see Chapter 2 for more information on setting up the payment). The fields mentioned below should be present in the payment request.

The paymentRequest has the following fields: – selectedRecurringDetailReference: the

recurringDetailReference you want to use for this payment The value LATEST can be used to select the most recently used recurring detail

– recurring:

• contract: this should be the same value as

recurringContract in the payment where the recurring contract was created (Chapter 3). However if

One-Click, recurring was specified initially then this field should be One-Click or recurring depending on whether it is desired for the shopper to enter their card’s security code or not.

– merchantAccount: the merchant account you want to process this payment with.

– amount: the amount to authorise. This consists of a currencyCode and a paymentAmount

– reference: the (merchant) reference for this payment.

This reference will be used in all communication to the merchant about the status of the payment. Although it is a good idea to make sure it is unique, this is not a requirement

– 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: set to ContAuth if the contract value is recurring, or Ecommerce if the contract value is One-Click – fraudOffset (optional): an integer that is added to the

normal fraud score. The value can be either positive or negative

– shopperIP (optional): the IP address of the shopper. Recommended as it is used in various risk checks

(e.g. number of payment attempts, location based checks) – shopperStatement (optional): some acquirers support a

variable shopper statement. To submit a variable shopper statement you can set the shopperStatement field in the payment request.

In the shopperStatement you can also include place holders for the various references:

• ${reference} for the merchant reference • ${pspReference} for the psp reference.

The shopperStatement field may not exceed 135 characters and can only contain the characters: a-zA-Zo-9,-?|:/ We cannot guarantee that all special characters will appear on the shopper’s statement

(10)

<?xml version=”10”?> <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>1111</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>

(11)

Payment response

If the recurring payment message passes validation, a risk analysis will be done and, depending on the outcome, an authorisation will be attempted. This is not applicable to One-Click payments You receive a payment response with the following fields:

– 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: an authorisation code if the payment was successful, or blank otherwise – refusalReason: if the payment was refused, the refusal reason.

<?xml version=”10”?> <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>

(12)

Updating stored details

The stored payment details may need to be updated, for example when the card expiry date changes Submit the recurring payment and add the details to change to the payment method specific object For a card this means that the expiryMonth and expiryYear fields should contain the new values You need to specify the exact selectedRecurringDetailReference of the card which you want to update

<?xml version=”10”?> <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:card> <ns1:expiryMonth>11</ns1:expiryMonth> <ns1:expiryYear>2014</ns1:expiryYear> </ns1:card> <ns1:merchantAccount>YourMerchantAccount</ns1:merchantAccount> <ns1:reference>RecurringPayment-0001</ns1:reference> <ns1:shopperIP>1111</ns1:shopperIP> <ns1:shopperEmail>[email protected]</ns1:shopperEmail> <ns1:shopperReference>TheShopperReference</ns1:shopperReference> <ns1:selectedRecurringDetailReference> RecurringDetailReference1 </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 6 – recurring payment SOAP request overwriting expiry date

If the payment is successful, the details will be updated Please 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

(13)

You can disable a single recurringDetail or the whole recurring contract for a shopper.

Disable request

Disabling a recurring contract (detail) can be done by calling the disable action on the recurring service with a request (see Chapter 7 for the login credentials).

The request has the following fields:

– merchantAccount: your merchant account – shopperReference: the reference to the shopper

This shopperReference must be the same as the shopperReference used in the initial payment – recurringDetailReference (optional): the

recurringDetailReference of the details you wish to disable If you do not supply this field all details for the shopper will be disabled including the contract. This means that you can not add new details anymore

<?xml version=”10”?> <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:disable xmlns:ns1=”http://recurring.services.adyen.com”> <ns1:request> <ns1:merchantAccount>YourMerchantAccount</ns1:merchantAccount> <ns1:shopperReference>TheShopperReference</ns1:shopperReference> <ns1:recurringDetailReference> RecurringDetailReference </ns1:recurringDetailReference> </ns1:request> </ns1:disable> </soap:Body> </soap:Envelope>

Example 7 – SOAP sample of a recurring disable request

Disabling a recurring contract (detail)

Disable response

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

<?xml version=”10”?>

(14)

Login credentials

To submit requests to the Recurring service or the Payment service you supply HTTP basic authentication credentials (username/password). The username is ws@Company[YourCompanyAccount] and you set the password for this user in the Merchant Back office (under Settings > Users).

If the initial payment is performed with one of the following payment methods it is possible to use the details for recurring payments:

– card: all credit and debit cards The only exception is maestro – these cards cannot be used for recurring payments

– paypal: only when PayPal has approved and added recurring functionality on your PayPal account (merchantInitiatedBilling) PayPal places a limit on the transaction amount of subsequent payments.

When the initial payment is directEbanking or giropay the recurring payments are processed as elv.

Note that this payment method must also be enabled for your Merchant Account for processing these recurring payments. If you do not want to enable the payment method on your Hosted Payment Page, like directdebit_NL, then you will deactivate it in your skin.

For all other supported payment methods the payment method of the recurring payment is the same as the initial payment.

Please note that it must be clear to the shopper that his details are used for recurring payments. Therefore you should add a message to your website like:

I understand that my subscription will be prolonged automatically at the end of each subscription period. The recurring subscription fee will be charged from my credit card. I can cancel the subscription at any time via my account on this website and will then not be charged again.

Supported payment methods

(15)

1 What does response ‘107 - Recurring is not enabled’ mean? Recurring is not enabled by default. Please contact

Barclaycard SmartPay Support and request to have recurring activated for your account. Please specify what your Company Account is.

2 What does response ‘905 Payment details are not supported’ mean?

You receive this error if you try to make a recurring payment when the payment method is not available. For example if you attempt a uSD payment when only EuR is enabled on the merchant account. To check payment methods for a merchant in the CA navigate Settings > Payment Methods.

3 What does response ‘The server sent HTTP status code 401: Unauthorised’ mean?

Your webservice was not able to login properly. Double check if:

– you use the correct Service uRL (payment or recurring) – you use the correct username (see Chapter 7)

– you’re using the configured password (see Chapter 7)

4 Is it possible to set up a recurring contract without a payment?

This is possible in one of two ways:

– Tokenisation: this method assumes your own systems already have stored, authorised credit card details Please discuss this option further with your account manager

– The workaround listed below. The workaround is as follows:

• ensure the Capture Delay is not set to ‘immediate’ in Settings > Merchant Settings

• create an initial payment for a small amount (eg EuR1,00) and set the recurringContract field to ‘recurring’ or ‘One-Click recurring’

• check that the payment is authorised

• cancel the authorisation before the capture delay time period is met (if any).

The outcome is as follows:

• full authorisation takes place on the card, including CVC checks, 3D secure authentication (if applicable), etc. • the shopper is not charged (if cancellation occurs

before capture)

• the card details are stored/tokenised in Barclaycard SmartPay.

The shopper should be warned that a small authorisation will take place on their card if using this workaround.

(16)

Test URLs Recurring SOAP Service https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Recurring Recurring SOAP Service WSDL https://pal-test.barclaycardsmartpay.com/pal/Recurring.wsdl Payment SOAP Service https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Payment Payment SOAP Service WSDL https://pal-test.barclaycardsmartpay.com/pal/Payment.wsdl

Appendix A:

Test and production URLs

Production URLs

Recurring SOAP Service https://pal-live.barclaycard.smartpaycom/pal/servlet/soap/Recurring Recurring SOAP Service WSDL https://pal-live.barclaycardsmartpay.com/pal/Recurring.wsdl

Payment SOAP Service https://pal-live.barclaycardsmartpay.com/pal/servlet/soap/Payment Payment SOAP Service WSDL https://pal-live.barclaycardsmartpay.com/pal/Payment.wsdl

(17)

Appendix B:

Deprecated functionality

Information presented here is for informational and archival purposes only.

For new integrations, this code should not be used.

Direct debit request

Submitting a recurring payment for directdebit_NL is done by calling the directdebit action on the Payment service with a request of type DirectDebitRequest (see Chapter 7 for the login credentials). The fields for the directDebitRequest are the same as the fields for the paymentRequest. <?xml version=”10”?> <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:directdebit xmlns:ns1=”http://payment.services.adyen.com”> <ns1:request> <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>1111</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:request> </ns1:directdebit> </soap:Body> </soap:Envelope>

(18)

Direct debit response

If the message passes validation a risk analysis will be done and, depending on the outcome, a received status will be returned You will receive a response with the following fields:

– 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 RECEIVED, REFuSED or ERROR – refusalReason: if the payment was refused, the refusal reason.

<?xml version=”10”?> <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:directdebitResponse xmlns:ns1=”http://payment.services.adyen.com”> <ns1:response> <additionalData 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”>Received</resultCode> </ns1:response> </ns1:directdebitResponse> </soap:Body> </soap:Envelope>

Example 10 – recurring Direct Debit SOAP response

Please note that the payment method directdebit_NL is not a direct payment method. This means that the result of the payment (AuTHORISED or REFuSED) is not directly know at the time of your request (except when the payment is refused by fraud). You are informed about the authorisation result via a notification.

(19)

Appendix C:

Example scenario

To help understand the principles mentioned in this manual, an example scenario is presented

below, from initial recurring payments through to subsequent recurring payments

*

_.

The merchant has two offerings – products and subscriptions. For products, the shopper chooses products, pays, and then has the item delivered to them. The merchant has decided that, for products only, they will always let the shopper choose from an existing stored card, if it exists, or the option to add a new one.

For subscriptions, the shopper chooses a service, pays upfront for the first month (with the option to select from existing stored cards if they exist), and agrees to be automatically charged every additional month until they cancel. The merchant has decided that, for subscriptions only, they will always use the last stored card details for the shopper in subsequent months.

Step 1: first initial recurring payment

On 01 September 2011 a shopper signs up with a merchant and is making their first purchase of a product. As per Chapter 3, the merchant creates a payment with additional fields as follows:

– shopperReference: grasshopper77

– shopperEmail: [email protected] – recurringContract: RECuRRING

Example 11 – complete payment sessions for a first initial recurring payment

<input type=”hidden” name=”orderData”

value=”H4sIAAAAAAAAALMpsOPlCkssyswvLVZIz89PKVZIzEtRKE4tKstMTi3W4+Wy0S+wAwDOGUCXJgAAAA==” /> <input type=”hidden” name=”sessionValidity” value=”2011-09-02T11:00:00Z” /> <input type=”hidden” name=”merchantSig” value=”33syARtfsxD47jeXzOlEyZ0j3pg=” /> <input type=”hidden” name=”shopperEmail” value=”[email protected]” /> <input type=”hidden” name=”shopperReference” value=”grasshopper77” /> <input type=”hidden” name=”recurringContract” value=”RECURRING” /> Once on our HPP, the shopper successfully uses a Visa card ending 1111, and the merchant receives a notification of successful payment. The merchant now knows the recurring detail is stored, with a new recurring contract created if applicable (as is the case here). The merchant does not receive any information about recurring details, as these are logically not needed at this point.

(20)

Step 2: recurring details for a shopper

A week later (08 September 2011) the same shopper returns to the website and purchases a subscription. As per Chapter 6, the merchant decides to check whether the shopper has any stored recurring details.

Example 12 – recurring details SOAP request

<?xml version=”10”?> <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>TestMerchant</ns1:merchantAccount> <ns1:shopperReference>grasshopper77</ns1:shopperReference> </ns1:request> </ns1:listRecurringDetails> </soap:Body> </soap:Envelope>

(21)

The response comes back that there is one stored card for the shopper – the Visa from the first payment. Here we can see the recurringDetailReference for the first time.

Example 13 – list recurring details SOAP response (truncated to remove some lines with nil results)

<?xml version=”10”?> <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> <creationDate xmlns=”http://recurring.services.adyen.com”>2011-09-01T01:50:12178+01:00</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”>Grass Hopper</holderName> <number xmlns=”http://payment.services.adyen.com”>1111</number> </card> <creationDate>2011-09-01T01:50:16353+01:00</creationDate> <elv xsi:nil=”true”/> <name xsi:nil=”true”/> <recurringDetailReference>8313147988756818</recurringDetailReference> <variant>visa</variant> </RecurringDetail> </details> <lastKnownShopperEmail xmlns=”http://recurring.services.adyen.com”>[email protected] </lastKnownShopperEmail> <shopperReference xmlns=”http://recurring.services.adyen.com”>grasshopper77</shopperReference> </ns1:result> </ns1:listRecurringDetailsResponse> </soap:Body> </soap:Envelope>

(22)

Step 3: subsequent payment

The merchant offers the shopper the choice of using a card ending 1111 (from the results in Step 2), or a new card. The shopper chooses to use the existing card ending 1111, so the merchant can now submit a Payment without the shopper needing to enter their card details again.

As per Chapter 7, the Merchant submits a Payment request with some additional fields: – selectedRecurringDetailReference: In this case it is 8313147988756818 (from Step 2) – recurring / contract: RECuRRING (since it was set this way in Step 1)

– shopperInteraction: ContAuth (since contract is RECuRRING) The payment request, this time sent via SOAP, might look as follows:

<?xml version=”10”?> <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”>4000</value> </amount> <ns1:merchantAccount>TestMerchant</ns1:merchantAccount> <ns1:reference>SubscriptionOrder031-241</ns1:reference> <ns1:shopperEmail>[email protected]</ns1:shopperEmail> <ns1:shopperReference>grasshopper77</ns1:shopperReference> <ns1:selectedRecurringDetailReference>8313147988756818 </ns1:selectedRecurringDetailReference> <ns1:recurring> <ns1:contract>RECURRING</ns1:contract> </ns1:recurring> <ns1:shopperInteraction>ContAuth</ns1:shopperInteraction> </ns1:paymentRequest> </ns1:authorise> </soap:Body> </soap:Envelope> <?xml version=”10”?> <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> <pspReference xmlns=”http://payment.services.adyen.com”>8613147994700690</authCode> <resultCode xmlns=”http://payment.services.adyen.com”>Authorised</authCode> </ns1:paymentResult> </ns1:authoriseResponse> </soap:Body> </soap:Envelope> The response might look as follows (truncated to remove lines with nil results) Notifications are also sent, as in Step 1

(23)

Step 4: second recurring detail

On 17 September 2011, the shopper purchases another product from the Merchant As was the case in Step 2, the Merchant retrieves a list of stored recurring details and gets the same result as presented there The Merchant offers the shopper the choice of using a card ending 1111 (from the results in Step 2), or a new card In this case the shopper chooses to use a new card, so the Merchant must now submit a Payment where they will create an addition recurring detail on an existing recurring contract The payment request might look as follows:

Example 16 – complete payment session for a second recurring detail

<input type=”hidden” name=”orderData”

value=”H4sIAAAAAAAAALMpsOPlCkssyswvLVZIz89PKVZIzEtRKE4tKstMTi3W4+Wy0S+wAwDOGUCXJgAAAA==” /> <input type=”hidden” name=”sessionValidity” value=”2011-10-18T11:00:00Z” /> <input type=”hidden” name=”merchantSig” value=”33syWRtfDxDwq3235zOlEyZ0j3pg=” /> <input type=”hidden” name=”shopperEmail” value=”[email protected]” /> <input type=”hidden” name=”shopperReference” value=”grasshopper77” /> <input type=”hidden” name=”recurringContract” value=”RECURRING” /> Once on our HPP, the shopper successfully uses a Mastercard ending 4444, and the merchant receives a notification of successful payment. The merchant now knows the recurring detail is stored, with a new recurring contract created if applicable (which is not the case here). The merchant does not receive any information about recurring details, as these are logically not needed at this point.

So now there is one recurring contract with two recurring details – the Visa card from the first purchase, and the Mastercard from this purchase.

(24)

Step 5: subsequent payment #2

On 08 October 2011 a month has passed and the Merchant now needs to charge the shopper the next installment of their subscription Since the Merchant has chosen to use the latest stored details of the shopper (see start of chapter) they do not need to go through Step 2 Instead they can immediately submit the Payment as per Chapter 7 with these additional fields: – selectedRecurringDetailReference: LATEST

– recurring / contract: RECuRRING (since it was set this way in Step 1) – shopperInteraction: ContAuth (since contract is RECuRRING) The payment request, this time sent via SOAP, might look as follows:

Example 17 – recurring payment SOAP request with LATEST

<?xml version=”10”?> <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”>1000</value> </amount> <ns1:merchantAccount>TestMerchant</ns1:merchantAccount> <ns1:reference>SubscriptionOrder031-241</ns1:reference> <ns1:shopperEmail>[email protected]</ns1:shopperEmail> <ns1:shopperReference>grasshopper77</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>

(25)

The response is similar to that in Step 3. Please note, however, that the Mastercard from Step 4 is used for the Payment and not the Visa card from Steps 1 and 3, since it was the most recently used recurring detail for this shopper.

This can be verified by looking up the recurring details for the shopper and noting the creationDate in each RecurringDetail (truncated to remove some lines with nil results):

<?xml version=”10”?> <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> <creationDate xmlns=”http://recurring.services.adyen.com”>2011-09-01T01:50:12178+01:00</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>Grass Hopper</holderName> <number xmlns=”http://payment.services.adyen.com>4444</number> </card> <creationDate>2011-09-17T08:31:07583+01:00</creationDate> <elv xsi:nil=”true”/> <name xsi:nil=”true”/> <recurringDetailReference>8313148012347491</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>Grass Hopper</holderName> <number xmlns=”http://payment.services.adyen.com>1111</number> </card> <creationDate>2011-09-01T01:50:16353+01:00</creationDate> <elv xsi:nil=”true”/> <name xsi:nil=”true”/>

(26)

This information is available in large print, Braille or audio format by calling

0844 811 6666

**

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

**For BT business customers, calls to 0844 811 numbers will cost no more than 5.5p per minute, min call charge 6p (current at January 2014). The price on non-BT phone lines may be different. Calls may be monitored and/or recorded. Barclaycard is a trading name of Barclays Bank PLC Barclays Bank PLC is authorised by the Prudential Regulation Authority and regulated by the Financial Conduct Authority and the Prudential Regulation Authority (Financial Services Register Number: 122702) and subscribes to the Lending Code which is monitored and enforced by the Lending Standards Board. Registered in England No: 1026167. Registered Office: 1 Churchill Place, London E14 5HP

BCD100962SP01. Created 01/14. 34366BD v1.0

Find out more

To see the latest versions of our Barclaycard

SmartPay support manuals, please refer to

our resource centre website:

barclaycard.com/smartpay/documentation

To contact our support team email:

[email protected]

call 01604 269518

*

_{or from abroad}

+441604 269518.

*