Recurring Payments Manual

Transcription

1 Recurring Payments Manual Version: 3.2 Contact details Simon Carmiggeltstraat DJ Amsterdam P.O. Box EB Amsterdam The Netherlands T E support@adyen.com

2 Table of Contents 1. Introduction What is a recurring contract? Recurring vs One-Click Standard Workflow Creating a Recurring Contract Retrieving the Recurring Contract Details listrecurringdetails request listrecurringdetails response tokenlookup Service Expiry Date Update on Card Submitting a Recurring Transaction Payment Request One-Click Payments Recurring Payments Payment Response Updating Stored Details Disabling a Recurring Transaction Disable Request Disable Response Supported Payment Methods Card directebanking giropay ideal PayPal SEPA Direct Debit FAQ...16 Appendix B: Complete workflow example...17 Appendix C: Examples of a listrecurringdetails request and response...21 Appendix D: Examples of a recurring payment request and response...23 Appendix E: Examples for updating stored details...25 Appendix F: Examples of a disable recurring contract request and response...27 Appendix G: Examples of tokenlookup request and response / 29

3 Changelog Version Date Changes Fixed: JSON recurring payment request in Appendix D; footer caption; minor edits Modifying reference to correct external manual Redesign of the manual Audience This is a technical manual aimed at IT personnel involved in integrating merchants' systems with those at Adyen. General Tips/Warnings Defensive Programming Adyen strongly recommends the use of defensive programming when integrating with the Adyen Services. This implies that automated decisions programmed into your systems should be defaulted to non-delivery of products and services. In other words, program your systems to only deliver products and/or services after receiving an explicit authorization of the requested payment and NOT to deliver in situations where an explicit response is not received. Feedback The latest version of this document is available on request. Please direct any comments or suggestions about this manual to support@adyen.com. ADYEN CONFIDENTIAL INFORMATION Copyright (c) 2015 Adyen B.V. 3 / 29

4 1. Introduction The purpose of this manual is to enable you to create and submit recurring payments to the Adyen Payment System. Recurring payments re-use payment details, previously stored by the shopper, to complete 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. Please contact the Adyen Support Team (support@adyen.com) if you would like to start processing recurring payments. This document is an addendum to the Adyen API Manual and will reference, without citation, concepts explained there. The latest version of the API Manual can be found here To submit Recurring Payment requests you must supply authentication credentials. The username is ws@company. [YourCompanyAccount] and you set the password for this user in the Adyen Customer Area (CA) under Settings Users. 4 / 29

5 2. 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, for Hosted Payment Pages (HPP) or the payment request for Direct API. The recurring details each have a unique 16 digit reference number called the recurringdetailreference. A recurring detail reference number can be used in place of the actual payment details to submit a payment to the system. Please note, the default recurring behaviour is for recurring contracts to be established and used within a single merchant account. However, your account can be configured to allow you to use stored details across all merchant accounts associated with your company account. Please contact the Adyen Support Team (support@adyen.com) if you would like to have this feature enabled on your account Recurring vs One-Click One-Click functionality gives the shopper the option to store their payment details with the merchant, within the Adyen environment. The shopper makes this choice during their first payment by checking a checkbox. For card payments, One-Click differs from Recurring as follows: The shopper chooses whether their card data can be stored or not. For subsequent transactions, the shopper is always present and must supply their card's security code (CVC/CVV). 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 Standard Workflow The usual workflow is as follows: 1. Create your recurring contract by performing an initial Payment with the additional fields defined in section 3, ensuring that you store the shopper , shopperreference, and the recurringcontract fields in your system for later use. If you receive a successful AUTHORISATION notification for the payment then you know the recurring contract has been created. You do not receive the recurringdetailreference at this time and need do nothing more in our system. 2. When you're ready to process a subsequent payment, set the value of the selectedrecurringdetailreference to either: 1. The recurringdetailreference returned from the list of all stored recurring details based on the shopperreference provided in step The word LATEST, which uses the most recently stored recurring detail. Set other fields as per section 5, taking into account the recurringcontract value that was set in step 1. If the subsequent payment is successful you will receive an AUTHORISATION notification with success= true. Please refer to section 8 for the list of supported payment methods. Please refer to Appendix B for sample requests & responses for an entire workflow. 5 / 29

6 3. Creating a Recurring Contract The payment session is set up like a regular payment. There are two previously optional fields that become compulsory and one new field that needs to be provided in the payment session form. shopper (required) Account of the merchant shopperreference (required) A reference that merchants can apply for the call recurringcontract (required) The type of recurring contract to be used. One of: ONECLICK The shopper opts in to storing their card details for future use. The shopper is present for the subsequent transaction, for cards the security code (CVC/CVV) is required. RECURRING Payment details are stored for future use. For cards, the security code (CVC/CVV) is not required for subsequent payments. ONECLICK, RECURRING Payment details are stored for future use. This allows the use of the stored payment details regardless of whether the shopper is on your site or not. <input type="hidden" name="shopper " value="gras.shopper@somewhere.org" /> <input type="hidden" name="shopperreference" value="grasshopper52" /> <input type="hidden" name="recurringcontract" value="recurring" /> Please refer to Appendix C of the Adyen HPP Manual for details on how to include these values in the signature. Please note: The details will only be stored, and the recurringdetailreference created, if the payment is successful. 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. 6 / 29

7 4. Retrieving the Recurring Contract Details When you want to submit a recurring payment, you may choose to query the Adyen system to return any stored payment details. This is done by submitting a request to the listrecurringdetails action listrecurringdetailsrequest The request has the following fields: merchantaccount Your merchant account. shopperreference Your unique ID for the shopper. This shopperreference must be the same as the shopperreference used in the initial payment. recurring The type of recurring contract to be used. One of: contract This should be the same value that was submitted using recurringcontract in the payment where the recurring contract was created. However, if ONECLICK,RECURRING was specified initially, then this field should be either ONECLICK or RECURRING depending on whether or not you want the shopper to enter their card's security code. Please refer to section 3 for more information listrecurringdetailsresponse The response will be a result with a list of zero or more details containing: recurringdetailreference Your merchant account. variant The payment method, such as mc, visa, ideal, paypal. creationdate The date when the recurring details were created. The recurring contracts are stored in the same object types that were used to submit the initial payment. Depending upon the payment method, one or more fields may be blank or incomplete, for example CVC for card. Only one of the details below will be returned per detail block, the others will be nil. For wallets (Paypal, Moneybookers/Skrill, Neteller) there is not a 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, for example 03 or 12. expiryyear The expiration date's year written in full, for example / 29

8 holdername The card holder's name as embossed on the card. number cvc bank The card number. Only the last 4 digits of the card number are returned. The card validation code. This is the CVC2 code (for MasterCard), CVV2 (for Visa) or CID (for American Express). The value will always be empty because it is not stored. A container for bankaccount data with the following fields: bankaccountnumber The account number. banklocationid The location id of the bank. The field will be nil in most cases. bankname bic The name of the bank. The unique identification code for both financial and non-financial institutions. The field will be nil in most cases. countrycode The country of the bank details. Iban The IBAN. ownername The account holder name. Caching of the recurring details for a shopper is encouraged, however, please keep in mind that if the stored details are updated, the recurringdetailreference for that detail will change and the cached entry should be invalidated. Please refer to Appendix C for a set of examples of a listrecurringdetails request and response tokenlookup Service Adyen will not automatically update your stored tokens to use the new details; you will need to submit an authorise request for the update to occur Expiry Date Update on Card In addition to the listrecurringdetails action, Adyen also offers the tokenlookup action which provides the ability to check the entered card details to see if there is another stored token that has the same card details on file. This is currently only available via a SOAP request. 8 / 29

9 Please refer to Appendix G for a SOAP tokenlookup API request and response. 9 / 29

10 5. Submitting 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 Payment Request You can submit a recurring payment by calling the authorise action on the Payment service with a paymentrequest. However, a One-Click payment session is set up like a regular payment and these additional fields are not required. Please refer to section 3.1 for more information on setting up the payment One-Click Payments The paymentrequest is set up like a regular payment with a couple of differences: card A container for credit card data. This contains the following items: expirymonth The field should be null. expiryyear The field should be null. holdername The field should be null. number cvc recurring The field should be null. The card validation code. This is the CVC2 code (for MasterCard), CVV2 (for Visa) or CID (for American Express). The value will always be empty because it is not stored. contract If ONECLICK,RECURRING was specified initially, then this field should be ONECLICK. Please refer to section 3 for more information. shopperinteraction Set to Ecommerce Recurring Payments 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 stored recurring detail. recurring 10 / 29

11 contract This should be the same value that was submitted using recurringcontract in the payment where the recurring contract was created. However, if ONECLICK,RECURRING was specified initially, then this field should be RECURRING. Please refer to section 3 for more information. merchantaccount The merchant account for which you want to process the payment. amount The amount to authorise. This consists of a currencycode and a paymentamount. Please refer to section 2.2 of the Adyen HPP API Manual for more information. shopper The shopper's address. This does not have to match the address supplied with the initial payment. shopperreference An ID that uniquely identifies the shopper. This shopperreference must be the same as the shopperreference used in the initial payment. shopperinteraction Set to ContAuth 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 This is Adyen's unique reference that is associated with the payment. This is guaranteed to be globally unique and is used when communicating with us about this payment. resultcode The result of the payment. The possible values are Authorised, Refused, Error. authcode An authorisation code if the payment was successful. Blank otherwise. refusalreason Adyen's mapped refusal reason, if the payment was refused. Please refer to Appendix D for a set of examples of a Recurring payment request and response. 11 / 29

12 6. 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 that need 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 that you want to update. Please note: Updating of stored details is only applicable to cards. The details will only be updated If the payment is successful. A new recurringdetailreference is created and the old one is no longer valid. As such the stored details must be retrieved again for the next payment. Please refer to Appendix E for a set of examples of a Recurring Payment Request which overwrites the expiry date of the card. 12 / 29

13 7. Disabling a Recurring Transaction 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. The request has the following fields: merchantaccount Your merchant account. shopperreference The ID that uniquely identifies the shopper. This shopperreference must be the same as the shopperreference used in the initial payment. recurringdetailreference (optional) The ID that uniquely identifies the shopper. This shopperreference must be the same as the shopperreference used in the initial payment 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 the details were disabled, the value is [all-details-successfully-disabled]. Please refer to Appendix F for a set of examples of request and response calls to disable a recurring contract. 13 / 29

14 8. Supported Payment Methods For most payment methods the recurring payment is processed using the same payment method as the initial payment. There are a few exceptions that are outlined below. Please note, it must be clear to your shoppers that their details are to be used for recurring payments. We recommend adding verbiage to your website advising shoppers of this Card All credit and debit cards support recurring with the exception of maestro, these cards cannot be used for recurring payments directebanking directebanking is a payment method that requires some form of shopper interaction, which is not possible for recurring payments. As such, the initial payment is completed via directebanking and the recurring payments are processed as SEPA Direct Debit. directebanking, and SEPA Direct Debit must be enabled for your Merchant Account for processing recurring payments. If you do not want to display SEPA Direct Debit on your HPP, you will need to deactivate them in your skin. In order to correctly process SEPA Direct Debit recurring payments, the recurring request must include the selectedbrand element with a value of sepadirectdebit giropay Recurring is only supported when the shopper has used a German bank account. giropay is a payment method that requires some form of shopper interaction, which is not possible for recurring payments. As such, the initial payment is completed via giropay and the recurring payments are processed as SEPA Direct Debit. giropay, and SEPA Direct Debit must be enabled for your Merchant Account for processing recurring payments. If you do not want to display SEPA Direct Debit on your HPP, you will need to deactivate it in your skin. In order to correctly process SEPA Direct Debit recurring payments, the recurring request must include the selectedbrand element with a value of sepadirectdebit ideal Recurring via ideal is not enabled by default. Please contact the Adyen Support Team (support@adyen.com) if you would like to have this enabled. ideal is a payment method that requires some form of shopper interaction, which is not possible for recurring payments. As such, the initial payment is completed via ideal and the recurring payments are processed as SEPA Direct Debit. Both ideal and SEPA Direct Debit must be enabled for your Merchant Account for processing recurring payments. If you do not want to display SEPA Direct Debit on your HPP, you will need to deactivate it in your skin. In order to correctly process SEPA Direct Debit recurring payments, the recurring request must include the selectedbrand element with a value of sepadirectdebit PayPal The recurring functionality has to be approved by PayPal and they will need to add the merchantinitiatedbilling 14 / 29

15 permission to your PayPal account. Please note, PayPal places a limit on the transaction amount of subsequent payments SEPA Direct Debit In order to be correctly processed, the recurring payment request must include the selectedbrand element with a value of sepadirectdebit. 15 / 29

16 9. FAQ 1. What does response '107 Recurring is not enabled' mean? Recurring is not enabled by default. Please contact the Adyen Support Team to have recurring activated for your account. Please specify your Company Account in your request. 2. What does response '905 Payment details are not supported' mean? You receive this error if you try to submit a recurring payment where the payment method or currency are not available. For example, if you attempt a USD payment when only EUR is enabled on your merchant account. To check the payment methods for your merchant account in the CA, navigate to Settings Payment Methods. 3. What does response 'The server sent HTTP status code 401: Unauthorized' mean? Your webservice was not able to login properly. Verify that you are using: The correct Service URL (Payment or Recurring). The correct username. The configured password. 4. Is it possible to setup a recurring contract without a payment? This is possible in one of three ways: 1. Tokenisation. This method assumes your own systems have already stored authorised credit card details. Please discuss this option further with your account manager. 2. Dynamic Zero Value Auth. For card transactions, you may submit an authorisation request with an amount value of 0, the currency should match the eventual transaction currency. This will result in the Adyen system submitting a card verification call, also referred to as a Zero Value Auth, to the Acquirer, the resultcode will return either Authorised or Refused. Not all Acquirers support card verification, in the situation where your transactions are routed to an Acquirer that does not support this feature, the Adyen system will automatically submit a EUR 1 authorisation followed by an automatic cancel of the authorisation. For other currencies, the EUR 1 approximate equivalent value is used, for example, 1000 Korean Won (KRW) as 1 KRW is too low an amount to be authorised. 3. The following workaround: 1. In the Adyen CA, ensure the Capture Delay is not set to "immediate" in Settings Merchant Settings. 2. Create an initial payment for a small amount, such as EUR1,00 and set the recurringcontract field to "RECURRING" or "ONECLICK,RECURRING". 3. Check that the payment is authorised. 4. 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. If cancellation occurs before the capture, the shopper is not charged. The card details are stored/tokenised in Adyen. 16 / 29

17 Appendix B: Complete workflow example To help understand the principles outlined in this manual, we will walk through a scenario, from the initial payment through to subsequent recurring payments. The Merchant has two offerings products and subscriptions. For products, the shopper selects a product, pays, and then has the item delivered to them. The Merchant has decided that, for certain products, they will allow the shopper to choose from an existing stored card, if it exists, or the option to add a new one. For subscriptions, the shopper selects 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 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 the 1st of January 2014 a shopper signs up with the Merchant and is making their first purchase of a product. The Merchant creates a Payment request including the required additional fields as follows: shopperreference: grasshopper77 shopper gras.shopper77@somewhere.org recurringcontract: RECURRING The payment request might look as follows: <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="gras.shopper77@somewhere.org" /> <input type="hidden" name="shopperreference" value="grasshopper77" /> <input type="hidden" name="recurringcontract" value="recurring" /> Once on the HPP, the shopper successfully uses a Visa card ending 1111, and the Merchant receives an AUTHORISATION notification of successful payment. The merchant now knows the recurring detail has been stored, with a new recurring contract created. The Merchant does not receive any information about the recurring details, as these are not needed at this point. Step 2: listrecurringdetails for a shopper A week later, on 8th January 2014, the same shopper returns to the website and purchases a subscription. The Merchant decides to check to see if the shopper has any stored recurring details: "merchantaccount": "TestMerchant", "recurring": "contract": "RECURRING", "shopperreference": "grasshopper77" 17 / 29

18 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: "creationdate": " T01:50: :00", "details": [ "RecurringDetail": "creationdate": " T01:50: :00", "recurringdetailreference": " ", "card": "expiryyear": "2016", "expirymonth": "12", "number": "1111", "holdername": "Grass Hopper", "variant": "visa" ], "shopperreference": "grashopper77", "lastknownshopper ": "gras.hopper77@somewhere.org" Step 3: Subsequent payment Based upon the results of step 2, the Merchant offers the shopper the choice of using the previously stored card ending with 1111 or a new card. The shopper chooses to use the existing card ending with 1111, so the Merchant can now submit a Payment without the shopper needing to enter their card details again. The merchant submits a Payment request with the following additional fields: selectedrecurringdetailreference: n this case it is recurring / contract: RECURRING since it was set this way in Step 1 shopperinteraction: ContAuth since the contract is RECURRING The payment request, this time sent via SOAP, might look as follows: "amount": "currency": "EUR", "value": "4000", "merchantaccount": "TestMerchant", "reference": "SubscriptionOrder ", "shopperreference": "grasshopper77", "shopper ": "gras.shopper77@somewhere.org", "selectedrecurringdetailreference": " ", "recurring": "contract": "RECURRING", "shopperinteraction": "ContAuth" 18 / 29

19 The response might look as follows: "authcode": "64158", "pspreference": " ", "resultcode": "Authorised" Notifications are also sent, as was the case in Step 1. Step 4: Storing a second recurring detail On 17 January 2014, the shopper purchases another product from the Merchant. As with Step 2, the Merchant retrieves a list of the stored recurring details and gets the same result as presented there. The Merchant offers the shopper the choice of using the previously stored card ending with 1111 or a new card. This time the shopper chooses to use a new card, so the Merchant must now submit a Payment where they will create another recurring detail on an existing recurring contract. The payment request might look as follows: <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="gras.shopper77@somewhere.org" /> <input type="hidden" name="shopperreference" value="grasshopper77" /> <input type="hidden" name="recurringcontract" value="recurring" /> Once on the HPP, the shopper successfully uses a Mastercard ending 4444, and the Merchant receives an AUTHORISATION notification of successful payment. The merchant now knows the recurring detail has been stored against the existing recurring contract. The Merchant does not receive any information about the recurring details, as these are not needed at this point. There is now one recurring contract with two recurring details the Visa card from the first purchase, and the Mastercard from this purchase. Step 5: Second subsequent payment On 08 February 2014, 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 they do not need to go through Step 2. Instead they can immediately submit the Payment request with the following additional fields: selectedrecurringdetailreference: LATEST recurring / contract: RECURRING since it was set this way in Step 1 shopperinteraction: ContAuth since the contract is RECURRING The payment request, this time sent via SOAP, might look as follows: 19 / 29

20 "amount": "currency": "EUR", "value": "1000", "merchantaccount": "TestMerchant", "reference": "SubscriptionOrder ", "shopperreference": "grasshopper77", "shopper ": "selectedrecurringdetailreference": "LATEST", "recurring": "contract": "RECURRING", "shopperinteraction": "ContAuth" The response is similar to that of Step 3, except that the Mastercard from Step 4 is used for the Payment, and not the Visa card from Steps 1 & 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: "creationdate": " T01:50: :00", "details": [ "RecurringDetail": "creationdate": " T08:31: :00", "recurringdetailreference": " ", "card": "expiryyear": "2016", "expirymonth": "12", "number": "4444", "holdername": "Grass Hopper", "variant": "mc", "RecurringDetail": "creationdate": " T01:50: :00", "recurringdetailreference": " ", "card": "expiryyear": "2016", "expirymonth": "12", "number": "1111", "holdername": "Grass Hopper", "variant": "visa" ], "shopperreference": "grashopper77", "lastknownshopper ": "gras.hopper77@somewhere.org" The above listrecurringdetails Response has been truncated to remove some lines with nil results. 20 / 29

21 Appendix C: Examples of a listrecurringdetails request and response JSON Request "merchantaccount": "TestMerchant", "recurring": "contract": "RECURRING", "shopperreference": "grasshopper77" JSON Response "creationdate": " T01:50: :00", "details": "RecurringDetail": "card": "expirymonth": "12", "expiryyear": "2012", "holdername": "Grass Hopper", "number": "1111", "creationdate": " T01:50: :00", "recurringdetailreference": " ", "variant": "visa", "lastknownshopper ": "gras.shopper77@somewhere.org", "shopperreference": "grasshopper77" SOAP Request <?xml version="1.0"?> <soap:envelope xmlns:soap=" xmlns:xsd=" xmlns:xsi=" <soap:body> <ns1:listrecurringdetails xmlns:ns1=" <ns1:request> <ns1:recurring> <contract xmlns=" </ns1:recurring> <ns1:merchantaccount>testmerchant</ns1:merchantaccount> <ns1:shopperreference>grasshopper77</ns1:shopperreference> </ns1:request> </ns1:listrecurringdetails> </soap:body> </soap:envelope> SOAP Response 21 / 29

22 <?xml version="1.0"?> <soap:envelope xmlns:soap=" xmlns:xsd=" xmlns:xsi=" <soap:body> <ns1:listrecurringdetailsresponse xmlns:ns1=" <ns1:result> <creationdate xmlns=" 01T01: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> t01:50: :00</creationdate> <elv xsi:nil="true"/> <name xsi:nil="true"/> <recurringdetailreference> </recurringdetailreference> <variant>visa</variant> </RecurringDetail> </details> <lastknownshopper <shopperreference xmlns=" </ns1:result> </ns1:listrecurringdetailsresponse> </soap:body> </soap:envelope> REST Request merchantaccount=testmerchant&shopperreference=grasshopper&recurring.contract=recurring REST Response creationdate= t15%3a02%3a08%2b01%3a00&details.0.card.expirymonth=6& details.0.card.expiryyear=2016&details.0.card.holdername=test& details.0.card.number=1111&details.0.creationdate= t15%3a02%3a08%2b01%3a00& details.0.recurringdetailreference= &details.0.variant=visa& details.1.card.expirymonth=6&details.1.card.expiryyear=2016&details.1.card.holdername=consumer&det ails.1.card.number=1111&details.1.creationdate= t10%3a37%3a16%2b01%3a00& details.1.recurringdetailreference= &details.1.variant=mc& lastknownshopper =test%40shopper.nl&shopperreference=grasshopper 22 / 29

23 Appendix D: Examples of a recurring payment request and response JSON Request "amount": "currency": "EUR", "value": "4000", "merchantaccount": "TestMerchant", "reference": "RecurringPayment-0001", "shopper ": " @shopper.com", "shopperreference": "shopper_001", "selectedrecurringdetailreference": "LATEST", "recurring": "contract": "RECURRING", "shopperinteraction": "ContAuth" JSON Response "authcode": "64158", "pspreference": " ", "resultcode": "Authorised" SOAP Request <?xml version="1.0"?> <soap:envelope xmlns:soap=" xmlns:xsd=" xmlns:xsi=" <soap:body> <ns1:authorise xmlns:ns1=" <ns1:paymentrequest> <amount xmlns=" <currency xmlns=" <value xmlns=" </amount> <ns1:merchantaccount>testmerchant</ns1:merchantaccount> <ns1:reference>subscriptionorder </ns1:reference> <ns1:shopper >gras.shopper77@somewhere.org</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> </soap:body> </soap:envelope> 23 / 29

24 SOAP Response <?xml version="1.0"?> <soap:envelope xmlns:soap=" xmlns:xsd=" xmlns:xsi=" <soap:body> <ns1:authoriseresponse xmlns:ns1=" <ns1:paymentresult> <authcode xmlns=" <pspreference xmlns=" <resultcode xmlns=" </ns1:paymentresult> </ns1:authoriseresponse> </soap:body> </soap:envelope> REST Request amount.currency=eur& amount.value=1234& merchantaccount=testmerchant& reference=test1234&shopperreference=gras.shopper77& selectedrecurringdetailreference=recurringdetailreference1& recurring.contract=recurring&shopperinteraction=contauth REST Response authcode=64158& pspreference= & resultcode=authorised 24 / 29

25 Appendix E: Examples for updating stored details JSON Request "amount": "currency": "EUR", "value": "100", "card": "expirymonth": "11", "expiryyear": "2016", "merchantaccount": "TestMerchant", "recurring": "contract": "RECURRING", "reference": "RecurringPayment-0001", "shopper ": "shopperip": " ", "shopperinteraction": "ContAuth", "shopperreference": "grasshopper77", "selectedrecurringdetailreference": "RecurringDetailReference1" JSON Response "authcode": "79688", "pspreference": " ", "resultcode": "Authorised" SOAP Request <?xml version="1.0"?> <soap:envelope xmlns:soap=" xmlns:xsd=" xmlns:xsi=" <soap:body> <ns1:authorise xmlns:ns1=" <ns1:paymentrequest> <amount xmlns=" <currency xmlns=" <value xmlns=" </amount> <ns1:card> <ns1:expirymonth>11</ns1:expirymonth> <ns1:expiryyear>2016</ns1:expiryyear> </ns1:card> <ns1:merchantaccount>testmerchant</ns1:merchantaccount> <ns1:reference>recurringpayment-0001</ns1:reference> <ns1:shopperip> </ns1:shopperip> <ns1:shopperreference>grasshopper77</ns1:shopperreference> <ns1:selectedrecurringdetailreference>recurringdetailreference1</ns1:selectedrecurringdetailrefere nce> <ns1:recurring> <ns1:contract>recurring</ns1:contract> </ns1:recurring> <ns1:shopperinteraction>contauth</ns1:shopperinteraction> </ns1:paymentrequest> </ns1:authorise> </soap:body> </soap:envelope> 25 / 29

26 SOAP Response <?xml version="1.0"?> <soap:envelope xmlns:soap=" xmlns:xsd=" xmlns:xsi=" <soap:body> <ns1:authoriseresponse xmlns:ns1=" <ns1:paymentresult> <authcode xmlns=" <pspreference xmlns=" <resultcode xmlns=" </ns1:paymentresult> </ns1:authoriseresponse> </soap:body> </soap:envelope> REST Request amount.currency=eur& amount.value=1234& card.expirymonth=06& card.expiryyear=2016& merchantaccount=testmerchant& reference=test1234&shopperreference=gras.shopper77& selectedrecurringdetailreference=recurringdetailreference1& recurring.contract=recurring&shopperinteraction=contauth REST Response authcode=79688&pspreference= &resultcode=authorised 26 / 29

27 Appendix F: Examples of a disable recurring contract request and response JSON Request "merchantaccount": "TestMerchant", "shopperreference": "grasshopper77", "recurringdetailreference": " " JSON Response "response": "[detail-successfully-disabled]" SOAP Request <?xml version="1.0"?> <soap:envelope xmlns:soap=" xmlns:xsd=" xmlns:xsi=" <soap:body> <ns1:disable xmlns:ns1=" <ns1:request> <ns1:merchantaccount>testmerchant</ns1:merchantaccount> <ns1:shopperreference>grasshopper77</ns1:shopperreference> <ns1:recurringdetailreference> </ns1:recurringdetailreference> </ns1:request> </ns1:disable> </soap:body> </soap:envelope> SOAP Response <?xml version="1.0"?> <soap:envelope xmlns:soap=" xmlns:xsd=" xmlns:xsi=" <soap:body> <ns1:disableresponse xmlns:ns1=" <ns1:result> <response xmlns=" </ns1:result> </ns1:disableresponse> </soap:body> </soap:envelope> REST Request merchantaccount=testmerchant& shopperreference=grasshopper77& recurringdetailreference= REST Response response=%5bdetail-successfully-disabled%5d 27 / 29

28 Appendix G: Examples of tokenlookup request and response JSON Request "merchantaccount": "TestMerchant", "card": "expirymonth": "06", "expiryyear": "2016", "holdername": "T. Est", "number": " " JSON Response "pspreference": " ", "tokens": "tokendetail": [ "creationdate": " T10:13:09+02:00", "lastknownshopper ": "test.shopper1@adyen.com", "shopperreference": "shopperreference001", "creationdate": " T13:22:01+02:00", "lastknownshopper ": "test.shopper2@adyen.com", "shopperreference": "shopperreference002", "creationdate": " T14:59:27+01:00", "lastknownshopper ": "test.shopper3@adyen.com", "shopperreference": "shopperreference008" ] SOAP Request <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:soap=" xmlns:xsd=" xmlns:xsi=" <soap:body> <ns1:tokenlookup xmlns:ns1=" <ns1:request> <merchantaccount xmlns=" <card xmlns:ns1=" <expirymonth xmlns=" <expiryyear xmlns=" <holdername xmlns=" Est</holderName> <number xmlns=" </card> </ns1:request> </ns1:tokenlookup> </soap:body> </soap:envelope> 28 / 29

29 SOAP Response <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:soap=" xmlns:xsd=" xmlns:xsi=" <soap:body> <ns1:tokenlookupresponse xmlns:ns1=" <ns1:result> <additionaldata xmlns=" xsi:nil="true"/> <pspreference xmlns=" <tokens xmlns=" <tokendetail> <creationdate> t10:13:09+02:00</creationdate> <shopperreference>shopperreference001</shopperreference> </tokendetail> <tokendetail> <creationdate> t13:22:01+02:00</creationdate> <shopperreference>shopperreference002</shopperreference> </tokendetail> <tokendetail> <creationdate> t14:59:27+01:00</creationdate> <shopperreference>shopperreference008</shopperreference> </tokendetail> </tokens> </ns1:result> </ns1:tokenlookupresponse> </soap:body> </soap:envelope> 29 / 29