Recurring payments manual

Transcription

1 Recurring payments manual SmartPay

2 Contents Introduction 3 Audience 3 What is a recurring contract? 4 Recurring vs One-Click 4 Usual workflow 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 Step 1: first initial recurring payment 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 Recurring payments Page 2

3 Introduction 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 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). 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: Audience This is a technical manual aimed at IT personnel involved in integrating merchants systems with those at Barclaycard SmartPay. Recurring payments Page 3

4 What is a recurring contract? A recurring contract is a set of one or more recurring payment details linked to a unique shopper on your merchant account. 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 shopper , 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. Recurring payments Page 4

5 Creating a recurring contract 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. 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: shopper the 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. Example 1 recurring initial payment setup <input type= hidden name= shopper 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. 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. 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. Recurring payments Page 5

6 Retrieving the recurring contract details 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. 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. Example 2 a SOAP sample of a recurring details request <ns1:listrecurringdetails xmlns:ns1= > <ns1:request> <ns1:recurring> <contract xmlns= >RECURRING</contract> </ns1:recurring> <ns1:merchantaccount>yourmerchantaccount</ns1:merchantaccount> <ns1:shopperreference>theshopperreference</ns1:shopperreference> </ns1:request> </ns1:listrecurringdetails> Recurring payments Page 6

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. Recurring payments Page 7

8 Example 3 recurring details SOAP response with two detail records <ns1:listrecurringdetailsresponse xmlns:ns1= > <ns1:result xmlns:ns2= > <ns1:creationdate> t11:26: :00</ns1:creationdate> <details xmlns= > <RecurringDetail> <bank xsi:nil= true /> <card> <cvc xmlns= xsi:nil= true /> <expirymonth xmlns= >12</expiryMonth> <expiryyear xmlns= >2012</expiryYear> <holdername xmlns= >Adyen Test</holderName> <issuenumber xmlns= xsi:nil= true /> <number xmlns= >1111</number> <startmonth xmlns= xsi:nil= true /> <startyear xmlns= xsi:nil= true /> </card> <creationdate> t11:50: :00</creationdate> <elv xsi:nil= true /> <name xsi:nil= true /> <recurringdetailreference>recurringdetailreference1</recurringdetailreference> <variant>mc</variant> </RecurringDetail> <RecurringDetail> <bank> <bankaccountnumber xmlns= > </bankaccountnumber> <banklocationid xmlns= xsi:nil= true /> <bankname xmlns= >AdyenBank</bankName> <bic xmlns= xsi:nil= true /> <countrycode xmlns= >NL</countryCode> <iban xmlns= xsi:nil= true /> <ownername xmlns= >Shop Per</ownerName> </bank> <card xsi:nil= true /> <creationdate> t12:46: :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> t11:26: :00</creationdate> <elv xsi:nil= true /> <name xsi:nil= true /> <recurringdetailreference>recurringdetailreference3</recurringdetailreference> <variant>paypal</variant> </RecurringDetail> </details> <ns1:lastknownshopper > @shopper.com</ns1:lastknownshopper > <ns1:shopperreference>theshopperreference</ns1:shopperreference> </ns1:result> </ns1:listrecurringdetailsresponse> Recurring payments Page 8

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 shopper the address of the shopper. This does not have to match the 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 Recurring payments Page 9

10 Example 4 recurring payment SOAP request <ns1:authorise xmlns:ns1= > <ns1:paymentrequest> <amount xmlns= > <currency xmlns= >EUR</currency> <value xmlns= >100</value> </amount> <ns1:merchantaccount>yourmerchantaccount</ns1:merchantaccount> <ns1:reference>recurringpayment-0001</ns1:reference> <ns1:shopperip>1111</ns1:shopperip> <ns1:shopper > @shopper.com</ns1:shopper > <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> Recurring payments Page 10

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. Example 5 recurring payment SOAP response (all extra SOAP fields which are nil can be ignored) <ns1:authoriseresponse xmlns:ns1= > <ns1:paymentresult> <additionaldata xmlns= xsi:nil= true /> <authcode xmlns= >50472</authCode> <dccamount xmlns= xsi:nil= true /> <dccsignature xmlns= xsi:nil= true /> <fraudresult xmlns= xsi:nil= true /> <issuerurl xmlns= xsi:nil= true /> <md xmlns= xsi:nil= true /> <parequest xmlns= xsi:nil= true /> <pspreference xmlns= > AnewPspReference </pspreference> <refusalreason xmlns= xsi:nil= true /> <resultcode xmlns= >Authorised</resultCode> </ns1:paymentresult> </ns1:authoriseresponse> Recurring payments Page 11

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 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 Example 6 recurring payment SOAP request overwriting expiry date <ns1:authorise xmlns:ns1= > <ns1:paymentrequest> <amount xmlns= > <currency xmlns= >EUR</currency> <value xmlns= >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:shopper > @shopper.com</ns1:shopper > <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> Recurring payments Page 12

13 Disabling a recurring contract (detail) 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 Example 7 SOAP sample of a recurring disable request <ns1:disable xmlns:ns1= > <ns1:request> <ns1:merchantaccount>yourmerchantaccount</ns1:merchantaccount> <ns1:shopperreference>theshopperreference</ns1:shopperreference> <ns1:recurringdetailreference> RecurringDetailReference </ns1:recurringdetailreference> </ns1:request> </ns1:disable> 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 [detailsuccessfully-disabled] or, if all details are disabled, the value is [all-details-successfullydisabled]. Example 8 SOAP sample of a recurring disable response <ns1:disableresponse xmlns:ns1= > <ns1:result> <response xmlns= > [detail-successfully-disabled] </response> </ns1:result> </ns1:disableresponse> Recurring payments Page 13

14 Supported payment methods 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. 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. 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. 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). Recurring payments Page 14

15 Frequently asked questions 1 What does response 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. Recurring payments Page 15

16 Appendix A: Test and production URLs Test URLs Recurring SOAP Service Recurring SOAP Service WSDL Payment SOAP Service Payment SOAP Service WSDL Production URLs Recurring SOAP Service Recurring SOAP Service WSDL Payment SOAP Service Payment SOAP Service WSDL Recurring payments Page 16

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. Example 9 recurring Direct Debit SOAP request <ns1:directdebit xmlns:ns1= > <ns1:request> <amount xmlns= > <currency xmlns= >EUR</currency> <value xmlns= >100</value> </amount> <ns1:merchantaccount>yourmerchantaccount</ns1:merchantaccount> <ns1:reference>recurringpayment-0001</ns1:reference> <ns1:shopperip>1111</ns1:shopperip> <ns1:shopper > @shopper.com</ns1:shopper > <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> Recurring payments Page 17

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. Example 10 recurring Direct Debit SOAP response <ns1:directdebitresponse xmlns:ns1= > <ns1:response> <additionaldata xmlns= xsi:nil= true /> <pspreference xmlns= > AnewPspReference </pspreference> <refusalreason xmlns= xsi:nil= true /> <resultcode xmlns= >Received</resultCode> </ns1:response> </ns1:directdebitresponse> 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. Recurring payments Page 18

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 shopper [email protected] recurringcontract: RECURRING Example 11 complete payment sessions for a first initial recurring payment <input type= hidden name= merchantreference value= ProductOrder /> <input type= hidden name= paymentamount value= 5000 /> <input type= hidden name= currencycode value= EUR /> <input type= hidden name= shipbeforedate value= /> <input type= hidden name= skincode value= 4aD37dJA /> <input type= hidden name= merchantaccount value= TestMerchant /> <input type= hidden name= shopperlocale value= en_gb /> <input type= hidden name= orderdata value= H4sIAAAAAAAAALMpsOPlCkssyswvLVZIz89PKVZIzEtRKE4tKstMTi3W4+Wy0S+wAwDOGUCXJgAAAA== /> <input type= hidden name= sessionvalidity value= T11:00:00Z /> <input type= hidden name= merchantsig value= 33syARtfsxD47jeXzOlEyZ0j3pg= /> <input type= hidden name= shopper 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. *Content is correct at time of publishing Recurring payments Page 19

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 <ns1:listrecurringdetails xmlns:ns1= > <ns1:request> <ns1:recurring> <contract xmlns= >RECURRING</contract> </ns1:recurring> <ns1:merchantaccount>testmerchant</ns1:merchantaccount> <ns1:shopperreference>grasshopper77</ns1:shopperreference> </ns1:request> </ns1:listrecurringdetails> Recurring payments Page 20

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) <ns1:listrecurringdetailsresponse xmlns:ns1= > <ns1:result> <creationdate xmlns= > T01:50: :00</creationDate> <details xmlns= > <RecurringDetail> <bank xsi:nil= true /> <card> <cvc xmlns= xsi:nil= true /> <expirymonth xmlns= >12</expiryMonth> <expiryyear xmlns= >2012</expiryYear> <holdername xmlns= >Grass Hopper</holderName> <number xmlns= >1111</number> </card> <creationdate> t01:50: :00</creationdate> <elv xsi:nil= true /> <name xsi:nil= true /> <recurringdetailreference> </recurringdetailreference> <variant>visa</variant> </RecurringDetail> </details> <lastknownshopper xmlns= </lastknownshopper > <shopperreference xmlns= >grasshopper77</shopperreference> </ns1:result> </ns1:listrecurringdetailsresponse> Recurring payments Page 21

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 (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: <ns1:authorise xmlns:ns1= > <ns1:paymentrequest> <amount xmlns= > <currency xmlns= >EUR</currency> <value xmlns= >4000</value> </amount> <ns1:merchantaccount>testmerchant</ns1:merchantaccount> <ns1:reference>subscriptionorder </ns1:reference> <ns1:shopper >[email protected]</ns1:shopper > <ns1:shopperreference>grasshopper77</ns1:shopperreference> <ns1:selectedrecurringdetailreference> </ns1:selectedrecurringdetailreference> <ns1:recurring> <ns1:contract>recurring</ns1:contract> </ns1:recurring> <ns1:shopperinteraction>contauth</ns1:shopperinteraction> </ns1:paymentrequest> </ns1:authorise> The response might look as follows (truncated to remove lines with nil results) Notifications are also sent, as in Step 1 <ns1:authoriseresponse xmlns:ns1= > <ns1:paymentresult> <authcode xmlns= >64158</authCode> <pspreference xmlns= > </authCode> <resultcode xmlns= >Authorised</authCode> </ns1:paymentresult> </ns1:authoriseresponse> Recurring payments Page 22

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= merchantreference value= ProductOrder /> <input type= hidden name= paymentamount value= 3133 /> <input type= hidden name= currencycode value= EUR /> <input type= hidden name= shipbeforedate value= /> <input type= hidden name= skincode value= 4aD37dJA /> <input type= hidden name= merchantaccount value= TestMerchant /> <input type= hidden name= shopperlocale value= en_gb /> <input type= hidden name= orderdata value= H4sIAAAAAAAAALMpsOPlCkssyswvLVZIz89PKVZIzEtRKE4tKstMTi3W4+Wy0S+wAwDOGUCXJgAAAA== /> <input type= hidden name= sessionvalidity value= T11:00:00Z /> <input type= hidden name= merchantsig value= 33syWRtfDxDwq3235zOlEyZ0j3pg= /> <input type= hidden name= shopper 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. Recurring payments Page 23

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 <ns1:authorise xmlns:ns1= > <ns1:paymentrequest> <amount xmlns= > <currency xmlns= >EUR</currency> <value xmlns= >1000</value> </amount> <ns1:merchantaccount>testmerchant</ns1:merchantaccount> <ns1:reference>subscriptionorder </ns1:reference> <ns1:shopper >[email protected]</ns1:shopper > <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> Recurring payments Page 24

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): <ns1:listrecurringdetailsresponse xmlns:ns1= > <ns1:result> <creationdate xmlns= > T01:50: :00</creationDate> <details xmlns= > <RecurringDetail> <bank xsi:nil= true /> <card> <cvc xmlns= xsi:nil= true /> <expirymonth xmlns= <expiryyear xmlns= <holdername xmlns= Hopper</holderName> <number xmlns= </card> <creationdate> t08:31: :00</creationdate> <elv xsi:nil= true /> <name xsi:nil= true /> <recurringdetailreference> </recurringdetailreference> <variant>mc</variant> </RecurringDetail> <RecurringDetail> <bank xsi:nil= true /> <card> <cvc xmlns= xsi:nil= true /> <expirymonth xmlns= <expiryyear xmlns= <holdername xmlns= Hopper</holderName> <number xmlns= </card> <creationdate> t01:50: :00</creationdate> <elv xsi:nil= true /> <name xsi:nil= true /> <recurringdetailreference> </recurringdetailreference> <variant>visa</variant> </RecurringDetail> </details> <lastknownshopper xmlns= >[email protected] </lastknownshopper > <shopperreference xmlns= >grasshopper77</shopperreference> </ns1:result> </ns1:listrecurringdetailsresponse> Recurring payments Page 25

26 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 call * or from abroad * Support hours are Monday Friday 09:00 to 18:00 GMT. This information is available in large print, Braille or audio format by calling ** *Calls may be monitored or recorded to maintain high levels of security and quality of service. **For BT business customers, calls to 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: ) and subscribes to the Lending Code which is monitored and enforced by the Lending Standards Board. Registered in England No: Registered Office: 1 Churchill Place, London E14 5HP BCD100962SP01. Created 01/ BD v1.0 Recurring payments Page 26