Recurring Payments Manual

(1)

Recurring

Payments

Manual

Contact details

Simon Carmiggeltstraat 6-50 1011 DJ Amsterdam P.O. Box 10095 1001 EB Amsterdam The Netherlands Version: 3.2

(2)

Changelog

Version Date Changes

3.2 2015-04-08 • Fixed: JSON recurring payment request in Appendix D; footer caption; minor edits.

3.1 2015-03-10 • Modifying reference to correct external manual 3.0 2015-01-14 • 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 [email protected].

ADYEN CONFIDENTIAL INFORMATION

(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 ([email protected]) 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 https://www.adyen.com/home/support/manuals.html

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

(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 ([email protected]) if you would like to have this feature enabled on your account.

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

2.2. 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 shopperEmail, 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 1.

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

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

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

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.

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

4.1. listRecurringDetails request

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.

4.2. listRecurringDetails response

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

(8)

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

◦ cvc

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.

• bank

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

The name of the bank.

◦ bic

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.

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

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

(9)

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

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

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

The field should be null.

◦ cvc

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.

• recurring

◦ 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”.

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

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

• shopperEmail

The shopper's email address. This does not have to match the email 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”.

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

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

(13)

7. Disabling a Recurring Transaction

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

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

7.2. 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].

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

8.1. Card

All credit and debit cards support recurring with the exception of maestro, these cards cannot be used for recurring payments.

8.2. 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”.

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

8.4. iDeal

Recurring via iDEAL is not enabled by default. Please contact the Adyen Support Team ([email protected]) 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.

8.5. PayPal

(15)

permission to your PayPal account.

Please note, PayPal places a limit on the transaction amount of subsequent payments.

8.6. SEPA Direct Debit

In order to be correctly processed, the recurring payment request must include the selectedBrand element with a value of “sepadirectdebit”.

(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 ([email protected]) 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.

(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

• shopperEmail: [email protected]

• recurringContract: RECURRING

The payment request might look as follows:

<input type="hidden" name="orderData"

value="H4sIAAAAAAAAALMpsOPlCkssyswvLVZIz89PKVZIzEtRKE4tKstMTi3W4+Wy0S+wAwDOGUCXJgAAAA==" /> <input type="hidden" name="sessionValidity" value="2014-01-02T11:00:00Z" />

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" }

(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": "2014-01-01T01:50:12.178+01:00", "details": [ { "RecurringDetail": { "creationDate": "2014-01-01T01:50:16.353+01:00", "recurringDetailReference": "8313147988756818", "card": { "expiryYear": "2016", "expiryMonth": "12", "number": "1111",

"holderName": "Grass Hopper" }, "variant": "visa" } } ], "shopperReference": "grashopper77", "lastKnownShopperEmail": "[email protected]" }

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 “8313147988756818”

• 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": "SubscriptionOrder031-241", "shopperReference": "grasshopper77", "shopperEmail": "[email protected]", "selectedRecurringDetailReference": "8313147988756818", "recurring": { "contract": "RECURRING" }, "shopperInteraction": "ContAuth" }

(19)

The response might look as follows: { "authCode": "64158", "pspReference": "8613147994700690", "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="orderData"

value="H4sIAAAAAAAAALMpsOPlCkssyswvLVZIz89PKVZIzEtRKE4tKstMTi3W4+Wy0S+wAwDOGUCXJgAAAA==" /> <input type="hidden" name="sessionValidity" value="2014-01-18T11:00:00Z" />

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

(20)

{ "amount": { "currency": "EUR", "value": "1000" }, "merchantAccount": "TestMerchant", "reference": "SubscriptionOrder031-241", "shopperReference": "grasshopper77", "shopperEmail": "[email protected]", "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": "2014-01-01T01:50:12.178+01:00", "details": [ { "RecurringDetail": { "creationDate": "2014-01-17T08:31:07.583+01:00", "recurringDetailReference": "8313148012347491", "card": { "expiryYear": "2016", "expiryMonth": "12", "number": "4444",

"holderName": "Grass Hopper" }, "variant": "mc" } }, { "RecurringDetail": { "creationDate": "2014-01-01T01:50:16.353+01:00", "recurringDetailReference": "8313147988756818", "card": { "expiryYear": "2016", "expiryMonth": "12", "number": "1111",

"holderName": "Grass Hopper" }, "variant": "visa" } } ], "shopperReference": "grashopper77", "lastKnownShopperEmail": "[email protected]" }

(21)

Appendix C: Examples of a listRecurringDetails request and

response

JSON Request { "merchantAccount": "TestMerchant", "recurring": { "contract": "RECURRING" }, "shopperReference": "grasshopper77" } JSON Response { "creationDate": "2011-09-01T01:50:12.178+01:00", "details": { "RecurringDetail": { "card": { "expiryMonth": "12", "expiryYear": "2012",

"holderName": "Grass Hopper", "number": "1111" }, "creationDate": "2011-09-01T01:50:16.353+01:00", "recurringDetailReference": "8313147988756818", "variant": "visa" } }, "lastKnownShopperEmail": "[email protected]", "shopperReference": "grasshopper77" } SOAP Request <?xml version="1.0"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance">

<soap:Body>

<ns1:listRecurringDetails xmlns:ns1="http://recurring.services.adyen.com"> <ns1:request>

<ns1:recurring>

<contract xmlns="http://payment.services.adyen.com">RECURRING</contract> </ns1:recurring>

<ns1:merchantAccount>TestMerchant</ns1:merchantAccount> <ns1:shopperReference>grasshopper77</ns1:shopperReference> </ns1:request>

</ns1:listRecurringDetails> </soap:Body>

</soap:Envelope>

(22)

<?xml version="1.0"?>

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Body> <ns1:listRecurringDetailsResponse xmlns:ns1="http://recurring.services.adyen.com"> <ns1:result> <creationDate xmlns="http://recurring.services.adyen.com"> 2011-09-01T01:50:12.178+01:00</creationDate> <details xmlns="http://recurring.services.adyen.com"> <RecurringDetail>

<holderName xmlns="http://payment.services.adyen.com">Grass Hopper</holderName> <number xmlns="http://payment.services.adyen.com">1111</number>

</card>

</RecurringDetail> </details>

<lastKnownShopperEmail

xmlns="http://recurring.services.adyen.com">[email protected]</lastKnownShopperEmail> <shopperReference xmlns="http://recurring.services.adyen.com">grasshopper77</shopperReference> </ns1:result>

</ns1:listRecurringDetailsResponse> </soap:Body>

</soap:Envelope> REST Request

merchantAccount=TestMerchant&shopperReference=grasshopper&recurring.contract=RECURRING REST Response

creationDate=2014-01-01T15%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=2014-01-22T15%3A02%3A08%2B01%3A00& details.0.recurringDetailReference=8413903993289958&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=2014-01-24T10%3A37%3A16%2B01%3A00&

details.1.recurringDetailReference=8313905562367504&details.1.variant=mc& lastKnownShopperEmail=test%40shopper.nl&shopperReference=grasshopper

(23)

Appendix D: Examples of a recurring payment request and

response

JSON Request { "amount": { "currency": "EUR", "value": "4000" }, "merchantAccount": "TestMerchant", "reference": "RecurringPayment-0001", "shopperEmail": "[email protected]", "shopperReference": "shopper_001", "selectedRecurringDetailReference": "LATEST", "recurring": { "contract": "RECURRING" }, "shopperInteraction": "ContAuth" } JSON Response { "authCode": "64158", "pspReference": "8613147994700690", "resultCode": "Authorised" } SOAP Request <?xml version="1.0"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance">

<soap:Body>

<ns1:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest>

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

(24)

SOAP Response

<?xml version="1.0"?>

<soap:Body>

<ns1:authoriseResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentResult>

<resultCode xmlns="http://payment.services.adyen.com">Authorised</resultCode> </ns1:paymentResult>

</ns1:authoriseResponse> </soap:Body>

amount.currency=EUR& amount.value=1234&

merchantAccount=TestMerchant&

reference=test1234&shopperReference=gras.shopper77&

[email protected]&shopperIP=1.1.1.1& selectedRecurringDetailReference=RecurringDetailReference1& recurring.contract=RECURRING&shopperInteraction=ContAuth REST Response

authCode=64158&

pspReference=8613147994700690&

(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", "shopperEmail": "[email protected]", "shopperIP": "1.1.1.1", "shopperInteraction": "ContAuth", "shopperReference": "grasshopper77", "selectedRecurringDetailReference": "RecurringDetailReference1" } JSON Response { "authCode": "79688", "pspReference": "8613904894998224", "resultCode": "Authorised" } SOAP Request <?xml version="1.0"?>

<soap:Body>

<ns1:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest>

<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>1.1.1.1</ns1:shopperIP>

<ns1:shopperEmail>[email protected]</ns1:shopperEmail>

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

(26)

SOAP Response

<?xml version="1.0"?>

<soap:Body>

<ns1:authoriseResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentResult>

<resultCode xmlns="http://payment.services.adyen.com">Authorised</resultCode> </ns1:paymentResult>

</ns1:authoriseResponse> </soap:Body>

amount.currency=EUR& amount.value=1234& card.expiryMonth=06& card.expiryYear=2016&

merchantAccount=TestMerchant&

reference=test1234&shopperReference=gras.shopper77&

[email protected]&shopperIP=1.1.1.1& selectedRecurringDetailReference=RecurringDetailReference1& recurring.contract=RECURRING&shopperInteraction=ContAuth REST Response

(27)

Appendix F: Examples of a disable recurring contract request

and response

JSON Request { "merchantAccount": "TestMerchant", "shopperReference": "grasshopper77", "recurringDetailReference": "8313147988756818" } JSON Response { "response": "[detail-successfully-disabled]" } SOAP Request <?xml version="1.0"?>

<soap:Body>

<ns1:disable xmlns:ns1="http://recurring.services.adyen.com"> <ns1:request>

<ns1:merchantAccount>TestMerchant</ns1:merchantAccount>

<ns1:shopperReference>grasshopper77</ns1:shopperReference>

<ns1:recurringDetailReference>8313147988756818</ns1:recurringDetailReference> </ns1:request> </ns1:disable> </soap:Body> </soap:Envelope> SOAP Response <?xml version="1.0"?>

<soap:Body>

<ns1:disableResponse xmlns:ns1="http://recurring.services.adyen.com"> <ns1:result>

<response xmlns="http://recurring.services.adyen.com"> [detail-successfully-disabled]</response> </ns1:result> </ns1:disableResponse> </soap:Body> </soap:Envelope> REST Request

merchantAccount=TestMerchant& shopperReference=grasshopper77&

recurringDetailReference=8313147988756818

REST Response

(28)

Appendix G: Examples of tokenLookup request and response

JSON Request { "merchantAccount": "TestMerchant", "card": { "expiryMonth": "06", "expiryYear": "2016", "holderName": "T. Est", "number": "4444333322221111" } } JSON Response { "pspReference": "9913848498374230", "tokens": { "tokenDetail": [ { "creationDate": "2013-09-12T10:13:09+02:00", "lastKnownShopperEmail": "[email protected]", "shopperReference": "shopperReference001" }, { "creationDate": "2013-04-20T13:22:01+02:00", "lastKnownShopperEmail": "[email protected]", "shopperReference": "shopperReference002" }, { "creationDate": "2012-03-25T14:59:27+01:00", "lastKnownShopperEmail": "[email protected]", "shopperReference": "shopperReference008" } ] } } SOAP Request

<?xml version="1.0" encoding="UTF-8"?>

<soap:Body>

<ns1:tokenLookup xmlns:ns1="http://recurring.services.adyen.com"> <ns1:request>

<merchantAccount

xmlns="http://recurring.services.adyen.com">TestMerchant</merchantAccount> <card xmlns:ns1="http://recurring.services.adyen.com">

</card>

</ns1:request> </ns1:tokenLookup> </soap:Body>

(29)

SOAP Response

<?xml version="1.0" encoding="UTF-8"?>

<soap:Body>

<ns1:tokenLookupResponse xmlns:ns1="http://recurring.services.adyen.com"> <ns1:result>

<lastKnownShopperEmail>[email protected]</lastKnownShopperEmail> <shopperReference>shopperReference001</shopperReference>

</tokenDetail> <tokenDetail>

</tokenDetail> </tokens> </ns1:result> </ns1:tokenLookupResponse> </soap:Body> </soap:Envelope>

Recurring Payments Manual

Recurring

Payments

Manual

Contact details

Table of Contents

Changelog

Audience

General Tips/Warnings

Feedback

1. Introduction











2. What is a recurring contract?

2.1. Recurring vs One-Click





2.2. Standard Workflow

3. Creating a Recurring Contract

4. Retrieving the Recurring Contract Details

4.1. listRecurringDetails request

4.2. listRecurringDetails response

4.3. tokenLookup Service

4.3.1.

Expiry Date Update on Card

5. Submitting a Recurring Transaction

5.1. Payment Request

5.1.1.

One-Click Payments

5.1.2.