Recurring payments manual - Barclaycard · 2020-03-15 · Recurring payments Page 3 Introduction It...

SmartPay

Recurring payments manual

Recurring payments Page 2

Contents

Introduction 3

Audience 3

What is a recurring contract? 4

Recurring vs One-Click 4

Usualworkflow 4

Creating a recurring contract 5

Setting up the payment 5

Retrieving the recurring contract details 6

List recurring details request 6

List recurring details response 7

Submit a recurring transaction 9

Payment request 9

Payment response 11

Updating stored details 12

Disabling a recurring contract (detail) 13

Disable request 13

Disable response 13

Supported payment methods 14

Login credentials 14

Frequently asked questions 15

Appendix A: Test and production URLs 16

Appendix B: Deprecated functionality 17

Direct debit request 17

Direct debit response 18

Appendix C: Example scenario 19

Step1:firstinitialrecurringpayment 19

Step 2: recurring details for a shopper 20

Step 3: subsequent payment 22

Step 4: second recurring detail 23

Step 5: subsequent payment #2 24


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 SmartPayroutinelychangestheirDNSconfigurationand,ifyourimplementation caches the DNS lookup, your ability to submit modificationsand/orpaymentsmaybeimpacted.

The latest version of this document is available at: www.barclaycard.com/smartpay/documentation/

AudienceThis 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


What is a recurring contract?

ThecontractisidentifiedusingtheshopperReference and merchantAccountfieldswhicharespecifiedaspartofthepayment 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-ClickOne-Click functionality allows a shopper to optionally allow a merchant to store their credit card data within Barclaycard SmartPayTheshoppermakesthischoiceduringtheirfirstpayment by checking a checkbox For subsequent payments the shopper must be present to enter the CVC of their card.

One-Clickdiffersfromrecurringasfollows:

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

– the shopper is always present for subsequent payments tosupplytheircard’ssecuritycode(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 workflowTheusualworkflowisasfollows.

1 Create your recurring contract by performing an initial Paymentwithadditionalfields(Chapter3),ensuringyou store the shopperEmail, shopperReference, and recurringContractfieldsinyourownsystemforlateruse.

IfyoureceiveasuccessfulAUTHORISEDnotificationforthe payment then you know the recurring contract has beencreated(sinceyouflaggedthepaymentrequestassuch) 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(providedinthefirststep 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 detailSetotherfields(asperChapter7),takingintoaccount what value recurringContract was set to in step 1.

If the subsequent payment is successful you will receive a successfulAUTHORISATIONnotification.

Please see Appendix C for sample requests and responses foranentireworkflow.

A recurring contract is a set of one or more recurring payment details linked to a unique shopper on your merchant account.


Creating a recurring contract

Setting up the paymentThe payment session is set up like a regular payment There aretwopreviouslyoptionalfieldswhichbecomecompulsoryandonenewfieldwhichneedstobeprovidedinthepaymentsession 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’ssecuritycode(CSC/CVC)mustbeprovidedduring subsequent payments.

• Recurring – credit card data is stored for future use Thecard’ssecuritycode(CSC/CVC)isnotrequiredforsubsequent payments.

• One-click, recurring – credit card data is stored for future use The merchant decides whether the card’ssecuritycode(CSC/CVC)isrequiredduringsubsequent payments.

Example 1 – recurring initial payment setup

<input type=”hidden” name=”shopperEmail” value=”[email protected]”/>

<input type=”hidden” name=”shopperReference” value=”grasshopper52”/>

<input type=”hidden” name=”recurringContract” value=”RECURRING”/>

If the payment is successful the details will be stored.

Pleasenotethatshoppersareuniquelyidentifiedusingthe shopperReference parameter. It is very important that shoppers are securely logged in on your site and that the shopperReferenceparametercannotbemodifiedbytheshopper.

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.


Retrieving the recurring contract details

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

Therequesthasthefollowingfields:

– 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,ifOne-Click,recurringwasspecified initiallythenthisfieldcanbeeitherOne-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.

<?xmlversion=”10”?><soap:Envelopexmlns: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:listRecurringDetailsxmlns:ns1=”http://recurring.services.adyen.com”> <ns1:request> <ns1:recurring> <contractxmlns=”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 2 – a SOAP sample of a recurring details request


List recurring details responseThe 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. Dependingonthepaymentmethodoneormorefieldsmaybe 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 (forMasterCard),CVV2(forVisa)orCID(forAmericanExpress) The value should always be empty because it will not be stored

• issueNumber: the issue number (MaestroUKonly-deprecated)

• startMonth: as per expiryMonth (MaestroUKonly-deprecated)

• startYear: as per expiryYear (MaestroUKonly-deprecated)

– elv:acontainerforELVdatawiththefollowingfields:

• bankLocation:thecityinwhichthebank/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 followingfields:

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


<?xmlversion=”10”?><soap:Envelopexmlns: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:listRecurringDetailsResponsexmlns:ns1=”http://recurring.services.adyen.com”> <ns1:resultxmlns:ns2=”http://payment.services.adyen.com”> <ns1:creationDate>2009-10-27T11:26:22203+01:00</ns1:creationDate> <detailsxmlns=”http://recurring.services.adyen.com”> <RecurringDetail> <bankxsi:nil=”true”/> <card> <cvcxmlns=”http://payment.services.adyen.comxsi:nil=”true””/> <expiryMonthxmlns=”http://payment.services.adyen.com”>12</expiryMonth> <expiryYearxmlns=”http://payment.services.adyen.com”>2012</expiryYear> <holderNamexmlns=”http://payment.services.adyen.com”>AdyenTest</holderName> <issueNumberxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <numberxmlns=”http://payment.services.adyen.com”>1111</number> <startMonthxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <startYearxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> </card> <creationDate>2009-10-27T11:50:12178+01:00</creationDate> <elvxsi:nil=”true”/> <namexsi:nil=”true”/> <recurringDetailReference>RecurringDetailReference1</recurringDetailReference> <variant>mc</variant> </RecurringDetail> <RecurringDetail> <bank> <bankAccountNumberxmlns=”http://payment.services.adyen.com”>1234567890 </bankAccountNumber> <bankLocationIdxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <bankNamexmlns=”http://payment.services.adyen.com”>AdyenBank</bankName> <bicxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <countryCodexmlns=”http://payment.services.adyen.com”>NL</countryCode> <ibanxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <ownerNamexmlns=”http://payment.services.adyen.com”>ShopPer</ownerName> </bank> <cardxsi:nil=”true”/> <creationDate>2009-10-27T12:46:13119+01:00</creationDate> <elvxsi:nil=”true”/> <namexsi:nil=”true”/> <recurringDetailReference>RecurringDetailReference2</recurringDetailReference> <variant>ideal</variant> </RecurringDetail> <RecurringDetail> <bankxsi:nil=”true”/> <cardxsi:nil=”true”/> <creationDate>2009-10-27T11:26:22216+01:00</creationDate> <elvxsi:nil=”true”/> <namexsi: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>

Example 3 – recurring details SOAP response with two detail records


Submit a recurring transaction

YoucansubmitarecurringpaymentusingaspecificrecurringDetails 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 requestSubmitting 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 thepayment).Thefieldsmentionedbelowshouldbepresentin the payment request.

ThepaymentRequesthasthefollowingfields:

– 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, recurringwasspecifiedinitiallythenthisfieldshouldbeOne-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 shopperStatementfieldinthepayment request.

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

• ${reference}forthemerchantreference

• ${pspReference}forthepspreference.

The shopperStatementfieldmaynotexceed 135 characters and can only contain the characters: a-zA-Zo-9,-?|:/Wecannotguaranteethatallspecialcharacters will appear on the shopper’s statement


<?xmlversion=”10”?><soap:Envelopexmlns: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:authorisexmlns:ns1=”http://payment.services.adyen.com”> <ns1:paymentRequest> <amountxmlns=”http://payment.services.adyen.com”> <currencyxmlns=”http://common.services.adyen.com”>EUR</currency> <valuexmlns=”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>

Example 4 – recurring payment SOAP request


Payment responseIf the recurring payment message passes validation, a risk analysis will be done and, depending on the outcome, an authorisation willbeattempted.ThisisnotapplicabletoOne-ClickpaymentsYoureceiveapaymentresponsewiththefollowingfields:

– 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.

<?xmlversion=”10”?><soap:Envelopexmlns: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:authoriseResponsexmlns:ns1=”http://payment.services.adyen.com”> <ns1:paymentResult> <additionalDataxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <authCodexmlns=”http://payment.services.adyen.com”>50472</authCode> <dccAmountxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <dccSignaturexmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <fraudResultxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <issuerUrlxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <mdxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <paRequestxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <pspReferencexmlns=”http://payment.services.adyen.com”> AnewPspReference </pspReference> <refusalReasonxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <resultCodexmlns=”http://payment.services.adyen.com”>Authorised</resultCode> </ns1:paymentResult> </ns1:authoriseResponse> </soap:Body></soap:Envelope>

Example 5 – recurring payment SOAP response(allextraSOAPfieldswhicharenilcanbeignored)


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 paymentmethodspecificobjectForacardthismeansthat the expiryMonth and expiryYearfieldsshouldcontain the new values You need to specify the exact selectedRecurringDetailReference of the card which you want to update

<?xmlversion=”10”?><soap:Envelopexmlns: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:authorisexmlns:ns1=”http://payment.services.adyen.com”> <ns1:paymentRequest> <amountxmlns=”http://payment.services.adyen.com”> <currencyxmlns=”http://common.services.adyen.com”>EUR</currency> <valuexmlns=”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


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

Disable requestDisabling 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).

Therequesthasthefollowingfields:

– 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 Ifyoudonotsupplythisfieldalldetailsfortheshopperwillbe disabled including the contract. This means that you can not add new details anymore

<?xmlversion=”10”?><soap:Envelopexmlns: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:disablexmlns: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 responseTheresponsewillbearesultobjectwithasinglefieldresponseIfasingledetailwasdisabledthevalueofthisfieldwillbe[detail-successfully-disabled] or, if all details are disabled, the value is [all-details-successfullydisabled].

<?xmlversion=”10”?><soap:Envelopexmlns: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:disableResponsexmlns:ns1=”http://recurring.services.adyen.com”> <ns1:result> <responsexmlns=”http://recurring.services.adyen.com”> [detail-successfully-disabled] </response> </ns1:result> </ns1:disableResponse> </soap:Body></soap:Envelope>

Example 8 – SOAP sample of a recurring disable response


Login credentialsTo submit requests to the Recurring service or the Payment service you supply HTTP basic authentication credentials (username/password).Theusernameisws@Company[YourCompanyAccount] and you set the password for this user in theMerchantBackoffice(underSettings>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 MerchantAccountforprocessingtheserecurringpayments.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


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 methodsforamerchantintheCAnavigateSettings>PaymentMethods.

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’reusingtheconfiguredpassword(seeChapter7)

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:

• ensuretheCaptureDelayisnotsetto‘immediate’inSettings>MerchantSettings

• createaninitialpaymentforasmallamount (eg EuR1,00) and set the recurringContractfieldto‘recurring’ or ‘One-Click recurring’

• checkthatthepaymentisauthorised

• canceltheauthorisationbeforethecapturedelaytimeperiod is met (if any).

The outcome is as follows:

• fullauthorisationtakesplaceonthecard,includingCVCchecks, 3D secure authentication (if applicable), etc.

• theshopperisnotcharged(ifcancellationoccursbefore capture)

• thecarddetailsarestored/tokenisedinBarclaycardSmartPay.

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

Frequently asked questions


Test URLs

RecurringSOAPService https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Recurring

RecurringSOAPServiceWSDL https://pal-test.barclaycardsmartpay.com/pal/Recurring.wsdl

PaymentSOAPService https://pal-test.barclaycardsmartpay.com/pal/servlet/soap/Payment

PaymentSOAPServiceWSDL https://pal-test.barclaycardsmartpay.com/pal/Payment.wsdl

Appendix A:Test and production URLs

Production URLs

RecurringSOAPService https://pal-live.barclaycard.smartpaycom/pal/servlet/soap/Recurring

RecurringSOAPServiceWSDL https://pal-live.barclaycardsmartpay.com/pal/Recurring.wsdl

PaymentSOAPService https://pal-live.barclaycardsmartpay.com/pal/servlet/soap/Payment

PaymentSOAPServiceWSDL https://pal-live.barclaycardsmartpay.com/pal/Payment.wsdl


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 requestSubmitting a recurring payment for directdebit_NL is done by calling the directdebit action on the Payment service with a request of type DirectDebitRequest(seeChapter7forthelogincredentials).ThefieldsforthedirectDebitRequest are the sameasthefieldsforthepaymentRequest.

<?xmlversion=”10”?><soap:Envelopexmlns: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:directdebitxmlns:ns1=”http://payment.services.adyen.com”> <ns1:request> <amountxmlns=”http://payment.services.adyen.com”> <currencyxmlns=”http://common.services.adyen.com”>EUR</currency> <valuexmlns=”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>

Example 9 – recurring Direct Debit SOAP request


Direct debit responseIf the message passes validation a risk analysis will be done and, depending on the outcome, a received status will be returned Youwillreceivearesponsewiththefollowingfields:

– 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.

<?xmlversion=”10”?><soap:Envelopexmlns: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:directdebitResponsexmlns:ns1=”http://payment.services.adyen.com”> <ns1:response> <additionalDataxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <pspReferencexmlns=”http://payment.services.adyen.com”> AnewPspReference </pspReference> <refusalReasonxmlns=”http://payment.services.adyen.com”xsi:nil=”true”/> <resultCodexmlns=”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 byfraud).Youareinformedabouttheauthorisationresultviaanotification.


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*.

Themerchanthastwoofferings–productsandsubscriptions.Forproducts,theshopperchoosesproducts,pays,andthenhas 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.

Forsubscriptions,theshopperchoosesaservice,paysupfrontforthefirstmonth(withtheoptiontoselectfromexistingstored 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 paymentOn01September2011ashoppersignsupwithamerchantandismakingtheirfirstpurchaseofaproduct.AsperChapter3,themerchantcreatesapaymentwithadditionalfieldsasfollows:

– shopperReference: grasshopper77

– shopperEmail: [email protected]

– recurringContract: RECuRRING

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

<inputtype=”hidden”name=”merchantReference”value=”ProductOrder041-201”/><inputtype=”hidden”name=”paymentAmount”value=”5000”/><inputtype=”hidden”name=”currencyCode”value=”EUR”/><inputtype=”hidden”name=”shipBeforeDate”value=”2011-10-01”/><inputtype=”hidden”name=”skinCode”value=”4aD37dJA”/><inputtype=”hidden”name=”merchantAccount”value=”TestMerchant”/><inputtype=”hidden”name=”shopperLocale”value=”en_GB”/><input type=”hidden” name=”orderData”value=”H4sIAAAAAAAAALMpsOPlCkssyswvLVZIz89PKVZIzEtRKE4tKstMTi3W4+Wy0S+wAwDOGUCXJgAAAA==”/><inputtype=”hidden”name=”sessionValidity”value=”2011-09-02T11:00:00Z”/><inputtype=”hidden”name=”merchantSig”value=”33syARtfsxD47jeXzOlEyZ0j3pg=”/><inputtype=”hidden”name=”shopperEmail”value=”[email protected]”/><inputtype=”hidden”name=”shopperReference”value=”grasshopper77”/><inputtype=”hidden”name=”recurringContract”value=”RECURRING”/>

OnceonourHPP,theshoppersuccessfullyusesaVisacardending1111,andthemerchantreceivesanotificationof 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.

*Content is correct at time of publishing


Step 2: recurring details for a shopperA 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

<?xmlversion=”10”?><soap:Envelopexmlns: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:listRecurringDetailsxmlns:ns1=”http://recurring.services.adyen.com”> <ns1:request> <ns1:recurring> <contractxmlns=”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>


Theresponsecomesbackthatthereisonestoredcardfortheshopper–theVisafromthefirstpayment.HerewecanseetherecurringDetailReferenceforthefirsttime.

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

<?xmlversion=”10”?><soap:Envelopexmlns: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:listRecurringDetailsResponsexmlns:ns1=”http://recurring.services.adyen.com”> <ns1:result> <creationDatexmlns=”http://recurring.services.adyen.com”>2011-09-01T01:50:12178+01:00</creationDate> <detailsxmlns=”http://recurring.services.adyen.com”> <RecurringDetail> <bankxsi:nil=”true”/> <card> <cvcxmlns=”http://payment.services.adyen.com”xsi:nil=”true””/> <expiryMonthxmlns=”http://payment.services.adyen.com”>12</expiryMonth> <expiryYearxmlns=”http://payment.services.adyen.com”>2012</expiryYear> <holderNamexmlns=”http://payment.services.adyen.com”>GrassHopper</holderName> <numberxmlns=”http://payment.services.adyen.com”>1111</number> </card> <creationDate>2011-09-01T01:50:16353+01:00</creationDate> <elvxsi:nil=”true”/> <namexsi:nil=”true”/> <recurringDetailReference>8313147988756818</recurringDetailReference> <variant>visa</variant> </RecurringDetail> </details> <lastKnownShopperEmailxmlns=”http://recurring.services.adyen.com”>[email protected] </lastKnownShopperEmail> <shopperReferencexmlns=”http://recurring.services.adyen.com”>grasshopper77</shopperReference> </ns1:result> </ns1:listRecurringDetailsResponse> </soap:Body></soap:Envelope>


Step 3: subsequent paymentThemerchantofferstheshopperthechoiceofusingacardending1111(fromtheresultsinStep2),oranewcard.Theshopperchooses 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.

AsperChapter7,theMerchantsubmitsaPaymentrequestwithsomeadditionalfields:

– 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:

<?xmlversion=”10”?><soap:Envelopexmlns: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:authorisexmlns:ns1=”http://payment.services.adyen.com”> <ns1:paymentRequest> <amountxmlns=”http://payment.services.adyen.com”> <currencyxmlns=”http://common.services.adyen.com”>EUR</currency> <valuexmlns=”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>

<?xmlversion=”10”?><soap:Envelopexmlns: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:authoriseResponsexmlns:ns1=”http://payment.services.adyen.com”> <ns1:paymentResult> <authCodexmlns=”http://payment.services.adyen.com”>64158</authCode> <pspReferencexmlns=”http://payment.services.adyen.com”>8613147994700690</authCode> <resultCodexmlns=”http://payment.services.adyen.com”>Authorised</authCode> </ns1:paymentResult> </ns1:authoriseResponse> </soap:Body></soap:Envelope>

Theresponsemightlookasfollows(truncatedtoremovelineswithnilresults)Notificationsarealsosent,asinStep1


Step 4: second recurring detailOn17September2011,theshopperpurchasesanotherproductfromtheMerchantAswasthecaseinStep2,theMerchantretrievesalistofstoredrecurringdetailsandgetsthesameresultaspresentedthereTheMerchantofferstheshopperthechoice 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,sotheMerchantmustnowsubmitaPaymentwheretheywillcreateanadditionrecurringdetailonanexistingrecurringcontract The payment request might look as follows:

Example 16 – complete payment session for a second recurring detail

<inputtype=”hidden”name=”merchantReference”value=”ProductOrder053-204”/><inputtype=”hidden”name=”paymentAmount”value=”3133”/><inputtype=”hidden”name=”currencyCode”value=”EUR”/><inputtype=”hidden”name=”shipBeforeDate”value=”2011-10-17”/><inputtype=”hidden”name=”skinCode”value=”4aD37dJA”/><inputtype=”hidden”name=”merchantAccount”value=”TestMerchant”/><inputtype=”hidden”name=”shopperLocale”value=”en_GB”/><input type=”hidden” name=”orderData”value=”H4sIAAAAAAAAALMpsOPlCkssyswvLVZIz89PKVZIzEtRKE4tKstMTi3W4+Wy0S+wAwDOGUCXJgAAAA==”/><inputtype=”hidden”name=”sessionValidity”value=”2011-10-18T11:00:00Z”/><inputtype=”hidden”name=”merchantSig”value=”33syWRtfDxDwq3235zOlEyZ0j3pg=”/><inputtype=”hidden”name=”shopperEmail”value=”[email protected]”/><inputtype=”hidden”name=”shopperReference”value=”grasshopper77”/><inputtype=”hidden”name=”recurringContract”value=”RECURRING”/>

OnceonourHPP,theshoppersuccessfullyusesaMastercardending4444,andthemerchantreceivesanotificationofsuccessful 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.

Sonowthereisonerecurringcontractwithtworecurringdetails–theVisacardfromthefirstpurchase,andtheMastercardfrom this purchase.


Step 5: subsequent payment #2On08October2011amonthhaspassedandtheMerchantnowneedstochargetheshopperthenextinstallmentoftheirsubscriptionSincetheMerchanthaschosentousethelateststoreddetailsoftheshopper(seestartofchapter)theydonotneedtogothroughStep2InsteadtheycanimmediatelysubmitthePaymentasperChapter7withtheseadditionalfields:

– 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

<?xmlversion=”10”?><soap:Envelopexmlns: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:authorisexmlns:ns1=”http://payment.services.adyen.com”> <ns1:paymentRequest> <amountxmlns=”http://payment.services.adyen.com”> <currencyxmlns=”http://common.services.adyen.com”>EUR</currency> <valuexmlns=”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>


TheresponseissimilartothatinStep3.Pleasenote,however,thattheMastercardfromStep4isusedforthePaymentandnot the Visa card from Steps 1 and 3, since it was the most recently used recurring detail for this shopper.

ThiscanbeverifiedbylookinguptherecurringdetailsfortheshopperandnotingthecreationDate in each RecurringDetail (truncated to remove some lines with nil results):

<?xmlversion=”10”?><soap:Envelopexmlns: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:listRecurringDetailsResponsexmlns:ns1=”http://recurring.services.adyen.com”> <ns1:result> <creationDatexmlns=”http://recurring.services.adyen.com”>2011-09-01T01:50:12178+01:00</creationDate> <detailsxmlns=”http://recurring.services.adyen.com”> <RecurringDetail> <bankxsi:nil=”true”/> <card> <cvcxmlns=”http://payment.services.adyen.comxsi:nil=”true””/> <expiryMonthxmlns=”http://payment.services.adyen.com>12</expiryMonth> <expiryYearxmlns=”http://payment.services.adyen.com>2012</expiryYear> <holderNamexmlns=”http://payment.services.adyen.com>GrassHopper</holderName> <numberxmlns=”http://payment.services.adyen.com>4444</number> </card> <creationDate>2011-09-17T08:31:07583+01:00</creationDate> <elvxsi:nil=”true”/> <namexsi:nil=”true”/> <recurringDetailReference>8313148012347491</recurringDetailReference> <variant>mc</variant> </RecurringDetail> <RecurringDetail> <bankxsi:nil=”true”/> <card> <cvcxmlns=”http://payment.services.adyen.comxsi:nil=”true””/> <expiryMonthxmlns=”http://payment.services.adyen.com>12</expiryMonth> <expiryYearxmlns=”http://payment.services.adyen.com>2012</expiryYear> <holderNamexmlns=”http://payment.services.adyen.com>GrassHopper</holderName> <numberxmlns=”http://payment.services.adyen.com>1111</number> </card> <creationDate>2011-09-01T01:50:16353+01:00</creationDate> <elvxsi:nil=”true”/> <namexsi:nil=”true”/> <recurringDetailReference>8313147988756818</recurringDetailReference> <variant>visa</variant> </RecurringDetail> </details> <lastKnownShopperEmailxmlns=”http://recurring.services.adyen.com”>[email protected] </lastKnownShopperEmail> <shopperReferencexmlns=”http://recurring.services.adyen.com”>grasshopper77</shopperReference> </ns1:result> </ns1:listRecurringDetailsResponse> </soap:Body></soap:Envelope>


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 maybedifferent.Callsmaybemonitoredand/orrecorded.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. RegisteredOffice:1ChurchillPlace,LondonE145HP

BCD100962SP01.Created01/14.34366BDv1.0

Find out moreTo see the latest versions of our Barclaycard SmartPay support manuals, please refer to our resource centre website: barclaycard.com/smartpay/documentationTo contact our support team email: [email protected] call 01604 269518* or from abroad +441604 269518.*

SupporthoursareMonday–Friday 09:00to18:00GMT.

Date post:	23-Mar-2020
Category:	Documents
Upload:	others
View:	1 times
Download:	0 times

Recurring payments manual - Barclaycard · 2020-03-15 · Recurring payments Page 3 Introduction It...

Documents