Recurring Manual

Here we describe how 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.

This document is an addendum to the API Manual and its references, without citation, concepts explained there.

Audience

This manual targets developers who integrate merchants' systems with the Adyen payment platform.

While integrating the Adyen platform of products and services with a third-party system, we strongly recommend you follow defensive programming best practices.
This means, for example, that system-automated decisions should have defaulted to non-delivery of products and services:
  • Your system should deliver products and services only after receiving an explicit authorisation response to a corresponding payment request.
  • Your system should not deliver any products or services when it does not receive any explicit response.

PCI compliance

Due to strict industry regulations, submitting card payments using the direct API is only available to merchants with full Payment Card Industry Data Security Standard ( PCI DSS) compliance Level 1 or Level 2. Furthermore, certain implementations of the API may require that you process at least a specified minimum amount of transactions per year.

Adyen sales representatives are available to help you with your questions about PCI DSS regulations, and they can advise you on API matters and transaction volume requirements. Don't hesitate and get in touch with your Adyen sales representative to learn more.

Feedback

We strive to provide you with clear, concise, and complete documentation. We are committed to improving it continuously to make it accessible and easy to understand.

We appreciate your comments, and we'd love to hear your voice: drop us a line and share your thoughts with us!

  Adyen Support Team

Recurring last update

Version

Date

Changes

4.2 2016-09-14 API version updated to 18.

Version

Date

Changes

4.2 2016-09-14 API version updated to 18.
4.1.2 2016-04-21

Added a new field shopperIP in One-click card payments.

4.1.1

2015-10-14

Added the firstPspReference field.

4.1.0 2015-09-14

Introduced merchant-specific URL endpoints for API calls to provide improved security.

4.0 2015-05-13
  • Documentation migration from PDF to web-based online deliverable as main distributable asset.
  • Versioning: version reset and adoption of semantic versioning as per v. 4.0.0.

3.2

2015-04-21

  • Updating examples and URL end points.

  • Some minor fixes.

3.1

2015-03-10

Modifying reference to correct external manual.

3.0

2015-01-14

Redesign of the manual.

Recurring API communication

You can communicate with the Adyen Recurring API and Payments API in one of these ways:

 JSON should be the default way to integrate to Adyen unless there is a strong preference to use another data representation. The data representations are treated exactly the same by Adyen, the only difference is the way they are mapped to/from Adyen's internal object structures.

JSON (JavaScript Object Notation) is an open standard format that uses human-readable text to transmit data objects consisting of key-value pairs. It is used primarily to transmit data between a server and web application, as an alternative to XML.
To submit JSON messages to our API endpoint over HTTPS:

 

SOAP is a messaging protocol to send data in a standardized XML format to web services.

SOAP implementations can automatically handle a number of edge cases around encoding, type safety and validation, resulting in a very robust integration (at the cost of being somewhat more cumbersome and complex).

To submit SOAP messages to our API endpoint over HTTPS:

  • Set the Content-Type HTTP header field of the request to text/XML.

SOAP can be beneficial to high-volume merchants, particularly as far as notifications are concerned: if there are many pending notifications, Adyen can transfer multiple notifications in a single SOAP message. For example, when compared to FORM messages, SOAP notifications use fewer requests and improve throughput.

Contrary to other representations, the SOAP standard does not support HTTP status other than 500 for error/exception handling.

A request can also be submitted as standard HTML Form key-value pairs. Note that for complex data structures, a JSON representation is more readable, easier to code and less error prone. 

To submit HTML Form data to our API endpoint over HTTPS:

  • Set the Content-Type HTTP header field of the request to application/x-www-form-urlencoded.
  • Special care needs to be taken to URL encode the parameter keys and values using UTF-8 character encoding.

Recurring API endpoints

This is an overview of the test and live URLs to communicate with the Recurring API using JSON, FORM or SOAP.

This is an overview of the test URL endpoints to communicate with our Recurring API using JSON or FORM. Use them to test your implementation and run QA checks.

JSON/FORM

listRecurringDetails
https://pal-test.adyen.com/pal/servlet/Recurring/v25/listRecurringDetails
disable
https://pal-test.adyen.com/pal/servlet/Recurring/v25/disable

This is an overview of the live URL endpoints to communicate with our Recurring API using JSON or FORM. Use them in your live/production environment.

JSON/FORM

listRecurringDetails
https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Recurring/v25/listRecurringDetails
disable
https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Recurring/v25/disable

This is an overview of the test URL endpoints to communicate with our Recurring API using the SOAP messaging protocol. Use them to test your implementation and run QA checks.

SOAP

Recurring service

https://pal-test.adyen.com/pal/servlet/Recurring/v25

Recurring service WSDL

https://pal-test.adyen.com/pal/servlet/Recurring/v25?wsdl

This is an overview of the live URL endpoints to communicate with our Recurring API using the SOAP messaging protocol. Use them in your live/production environment.

SOAP

Recurring service

https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Recurring/v25

Recurring service WSDL

https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Recurring/v25?wsdl

Although generic URL endpoints for our APIs are still supported (payment API, recurring API), we recommend setting up merchant-specific endpoints. This is the default endpoint configuration option for new merchants.

Merchant-specific endpoints are available only for API integrations, and only in our live environment.

For test purposes, you can use our generic test points.

Merchant-generic API URL endpoint

The standard, generic payment API URL endpoints to communicate with the Adyen payment API are built as shown in this example:

https://pal-live.adyen.com/pal/servlet/Payment/v25/capture

The example shows the standard, generic URL endpoint to make a payment capture request.

Merchant-specific API URL endpoint

Each company account is provided with a unique hostname to communicate with Adyen's APIs.

By connecting to this merchant-specific hostname, Adyen has more control over the routing of transactions. This allows Adyen to improve service robustness and availability for our merchants.

By default all transactions for a merchant-specific endpoint are routed to the same infrastructure as the standard endpoint, however in case of an infrastructure problem on the standard endpoint, especially if the cause is outside of Adyen's scope of control, alternative routing can be enabled to backup infrastructure and new infrastructure can be provisioned on demand.

Example

Convert the generic API endpoint with path “/pal/servlet/Payment/v25/authorise” from:

https://pal-live.adyen.com/pal/servlet/Payment/v25/authorise

to:

https://f96e63be5147-TestCompany.pal-live.adyenpayments.com/pal/servlet/Payment/v25/authorise

Endpoint format

The custom endpoint has the following format:

https://[random]-[company name].pal-live.adyenpayments.com
random

A random string of hex-encoded bytes to make the hostname unpredictable.

company name

The company name is included in the URL endpoint.

  • If the name is too long:
    it is shortened.
  • If the name includes underscores or hyphens:
    any underscores and/or hyphens are stripped.

Endpoint settings

You can access the API endpoint(s) of your company account through the Adyen Customer Area (CA):

  • Log in to the Adyen Customer Area (CA) using your credentials.
  • In the left navigation sidebar, select Settings.
  • On the Settings page, click API URLs.
  • On the API URLs page, you can see the configured endpoint(s) for your company account.

Click API URLs to access the endpoint overview page.

In this example, the TestCompany account has two API URL endpoints: one is configured to communicate with our European servers, whereas the other is set up to exchange data with our US-based servers.
This setup allows you to optimize data traffic depending on the region you operate in.

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.

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. Contact our support team if you would like to have this feature enabled on your account.

You can choose to create either of the recurring contracts:

  • Shopper present transactions: In this type of transaction the shopper needs to enter the CVC code for the transaction to get through. This can be done online or at the store by the shopper depending on the merchant. It is also referred as one click payments. 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. 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 to supply their card's security code (CVC/CVV).
  • Shopper not present transactions: In this type of transaction the shopper allows the merchant to deduct the said amount using shopper's bank account or credit card at the agreed timeframe. Shopper's details are stored within the Adyen environment. This is referred to as recurring transactions where the card's security code is not needed for subsequent payments.

 

Creating a recurring contract

A recurring contract is created along with a payment request, similar to a regular payment request, except the below fields to be provided in the payment session HPP form or in the API request. A recurring contract with your shopper is created with this initial transaction. 

  • The details are only stored, and the recurringDetailReference is created, if the payment is successful.
  • Shoppers are uniquely identified using the shopperReference parameter. It is important that shoppers are securely logged in on your site and that the shopperReference parameter cannot be modified by the shopper.
Name Type Required Description
shopperEmail String (error) Shopper's email address.
shopperReference String (tick) Shopper's reference for the payment transaction.
recurring Class (tick)

A container for the type of recurring contract to be retrieved.

Recurring contains the following child:

  • contract
contract String (tick)

The type of recurring contract to be used.

Types:

  • ONECLICK
    • The shopper opts to store 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. This is used for shopper not present transactions.
  •  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.

The following code examples show the creation of recurring contracts together with a payment request in JSON, FORM, and SOAP.

{
    "card" : {
        "number" : "4111111111111111",
        "expiryMonth" : "8",
        "expiryYear" : "2018",
        "cvc" : "737",
        "holderName" : "John Smith"
    },
    
    "amount" : {
        "value" : 2000,
        "currency" : "EUR"
    },
    
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "s.hopper@test.com",
    "shopperIP" : "61.294.12.12",
    "shopperReference" : "Simon Hopper",
    
    "recurring" : {
        "contract" : "RECURRING,ONECLICK"
    }
}
<?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>
        <amount xmlns="http://payment.services.adyen.com">
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
          <value xmlns="http://common.services.adyen.com">2000</value>
        </amount>
        <card xmlns="http://payment.services.adyen.com">
          <cvc>737</cvc>
          <expiryMonth>08</expiryMonth>
          <expiryYear>2018</expiryYear>
          <holderName>Adyen Test</holderName>
          <number>4111111111111111</number>
        </card>
        <merchantAccount xmlns="http://payment.services.adyen.com" >SupportAdyenTest</merchantAccount>
        <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference>
        <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail>
        <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP>
        <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference>
        <recurring>
          <contract>RECURRING,ONECLICK</contract>
        </recurring>
      </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>
merchantAccount=TestMerchant&amount.value=2000&amount.currency=EUR&card.expiryYear=2018&card.cvc=737&card.number=4111111111111111&card.holderName=John+Smith&card.expiryMonth=08&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com&shopperIP=61.294.12.12&recurring.contract=RECURRING,ONECLICK

Name Type Required Description
shopperEmail String (tick) Shopper's email address.
shopperReference String (tick) Shopper's reference for the payment transaction.
recurringContract String (tick)

The type of recurring contract to be used.

Types:

  • ONECLICK
    • The shopper opts to store 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="shopperEmail" value="gras.shopper@somewhere.org" />
<input type="hidden" name="shopperReference" value="grasshopper52" />
<input type="hidden" name="recurringContract" value="RECURRING" />

When you are ready to process a subsequent payment, set the value of the selectedRecurringDetailReference to either:

  • The recurringDetailReference returned from the list of all stored recurring details based on the shopperReference provided during the recurring contract. Or

  • The word LATEST, which uses the most recently stored recurring detail.

On AUTHORISATION you receive a notification with success=”true”.

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.

listRecurringDetails request

The request has the following fields:

Name Type Required Description
merchantAccount String (tick)
The merchant account identifier you want to process the (transaction) request with.
shopperReference String (tick) The shopper's reference for the payment transaction.
recurring String (tick)

A container for the type of recurring contract to be retrieved.

recurring contains the following child element:

  • contract
contract   (tick)

The type of recurring contract to be used.

This value needs to match the value submitted with recurringContract in the payment transaction used to create the recurring contract.

However, if ONECLICK,RECURRING is the original contract definition in the initial payment, then contract should take either ONECLICK or RECURRING, depending on whether or not you want the shopper to enter their card's security code when they finalise their purchase.

Examples

 

{
  "merchantAccount": "TestMerchant",
  "recurring": {
    "contract": "RECURRING"
  },
  "shopperReference": "grasshopper77"
}

merchantAccount=TestMerchant&shopperReference=grasshopper77&recurring.contract=RECURRING

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

listRecurringDetails response

The response is a result with a list with zero or more details containing:

Name Type Returned by Default Description
recurringDetailReference String (tick) The reference that uniquely identifies the recurring detail.
variant String (tick)

The payment method, such as “mc”, “visa”, “ideal”, “paypal”.

creationDate Date/Time (tick)

The date when the recurring details were created.

alias String (tick)

The alias of the credit card number.

Applies only to recurring contracts storing credit card details.

aliasType String (tick)

The alias type of the credit card number.

Applies only to recurring contracts storing credit card details.

firstPspReference String (tick) The pspreference of the first recurring payment that created the recurring detail.

The recurring contracts are stored in the same object types that were used to submit the initial payment.

Depending on the payment method, one or more fields may be blank or incomplete, for example CVC for card.

Only one of the details below is returned per detail block; the others are nil.

For wallets (Paypal, Moneybookers/Skrill, Neteller), there is not a detail block.

For Credit Cards

Name Type Returned by Default Description
card class
(tick)

A container object for credit card data.
This field holds the following child element(s):

  • expiryMonth
  • expiryYear
  • holderName
  • number
  • cvc
expiryMonth String
(tick)

The expiration date's month is a 2-digit string, zero-padded when necessary.
For example: 03; 12.

expiryYear String
(tick)

The expiration date's year.
Format: YYYY
For example: 2016.

holderName String
(tick)

The card holder's name, as embossed on the card.

number String
(tick)

The card number.

Only the last 4 digits of the card number are returned.

cvc String
(tick)

The card validation code.
This is the CVC2 code (for MasterCard), CVV2 (for Visa) or CID (for American Express).

The field value is always empty because it is not stored.

For Bank Accounts

Name Type Returned by Default Description
bank class
(tick)

A container object for bank account data.
This field holds the following child element(s):

  • bankAccountNumber
  • bankLocationId
  • bankName
  • bic
  • countryCode
  • iban
  • ownerName
bankAccountNumber String
(tick)

The account number.

bankLocationId String
(tick)

The location id of the bank.

The field value is nil in most cases.

bankName String
(tick)

The name of the bank.

bic String
(tick)

The unique identification code for both financial and non-financial institutions.

The field value is nil in most cases.

countryCode String
(tick)

The country of the bank details.

iban String
(tick)

The International Bank Account Number.

ownerName String
(tick)

The account holder name.

You can cache the shopper's recurring details.
Keep in mind that when the stored details are updated, the recurringDetailReference for the updated detail changes.
Therefore, the corresponding cached entry should be invalidated.

Examples

 

{
    "creationDate" : "2015-07-30T22:54:13+02:00",
    
    "details" : [
        {
           "RecurringDetail" : {     
               "additionalData" : {
                   "cardBin" : "492179"
               },
                   
               "card" : {
                   "expiryMonth" : "2",
                   "expiryYear" : "2017",
                   "holderName" : "John Doe",
                   "number" : "0380"
               },
 
               "alias" : "H123456789012345",
               "aliasType" : "Default",
               "creationDate" : "2015-07-30T22:54:13+02:00",
               "firstPspReference" : "1314362892522014",
               "recurringDetailReference" : "8313147988756818",
               "paymentMethodVariant" : "visadebit",
               "variant" : "visa"
           }
       }
   ],
  
    "lastKnownShopperEmail": "14194858@gmail.com",
    "shopperReference": "14194858"
}

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <SOAP-ENV:Body>
        <ns1:listRecurringDetailsResponse xmlns:ns1="http://recurring.services.adyen.com">
            <ns1:result>
                <creationDate xmlns="http://recurring.services.adyen.com">2015-07-30T22:54:13+02:00</creationDate>
                <details xmlns="http://recurring.services.adyen.com">
                    <RecurringDetail>
                        <additionalData>
                            <entry>
                                <key xsi:type="xsd:string">cardBin</key>
                                <value xsi:type="xsd:string">492179</value>
                            </entry>
                        </additionalData>
                        <alias>H123456789012345</alias>
                        <aliasType>Default</aliasType>
                        <bank xsi:nil="true"/>
                        <billingAddress xsi:nil="true"/>
                        <card>
                            <billingAddress xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
                            <cvc xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
                            <expiryMonth xmlns="http://payment.services.adyen.com">2</expiryMonth>
                            <expiryYear xmlns="http://payment.services.adyen.com">2017</expiryYear>
                            <holderName xmlns="http://payment.services.adyen.com">John Doe</holderName>
                            <issueNumber xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
                            <number xmlns="http://payment.services.adyen.com">0380</number>
                            <startMonth xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
                            <startYear xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
                        </card>
                        <creationDate>2015-07-30T22:54:13+02:00</creationDate>
                        <elv xsi:nil="true"/>
                        <firstPspReference>1314362892522014</firstPspReference>
                        <name xsi:nil="true"/>
                        <paymentMethodVariant>visadebit</paymentMethodVariant>
                        <recurringDetailReference>8313147988756818</recurringDetailReference>
                        <shopperName xsi:nil="true"/>
                        <socialSecurityNumber xsi:nil="true"/>
                        <tokenDetails xsi:nil="true"/>
                        <variant>visa</variant>
                    </RecurringDetail>
                </details>
                <lastKnownShopperEmail xmlns="http://recurring.services.adyen.com">14194858@gmail.com</lastKnownShopperEmail>
                <shopperReference xmlns="http://recurring.services.adyen.com">14194858</shopperReference>
            </ns1:result>
        </ns1:listRecurringDetailsResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

creationDate=2015-07-30T22%3A54%3A13%2B02%3A00&details.0.additionalData.cardBin=492179&details.0.card.expiryMonth=2&details.0.card.expiryYear=2017&details.0.card.holderName=John+Doe&details.0.card.number=0380&details.0.alias=H123456789012345&details.0.aliasType=Default&details.0.creationDate=2015-07-30T22%3A54%3A13%2B02%3A00&details.0.firstPspReference=1314362892522014&details.0.recurringDetailReference=8313147988756818&details.0.paymentMethodVariant=visadebit&details.0.variant=visa&lastKnownShopperEmail=14194858@gmail.com&shopperReference= 14194858

Submitting a recurring payment transaction

You can submit a recurring payment using a specific recurringDetails record or by using the last created recurringDetails record. This recurring payment request can be submitted by calling the authorise action on the Payment service, as described in the API manual.

One-click card payment

A one-click payment session is set up like a regular payment except the below fields. 

Card payment request

Name Type Required Description

card

class
(tick)

A container for credit card data.

This field takes the following children:

  • cvc
cvc String  (tick)

The card validation code. This is the CVC2 code (for MasterCard), CVV2 (for Visa) or CID (for American Express).

If you are using Easy Encryption, the CVC code is present in the encrypted data. You should never post the card details to the server.

recurring

Class  (tick)

A container for the type of recurring contract to be used.

recurring contains the following child

  • contract
contract String (tick)

The type of recurring contract to be used.

If “ONECLICK,RECURRING” was specified when creating the recurring contract, then this field should be “ONECLICK”.

shopperEmail String (tick)

The shopper's email address.

This does not have to match the email address supplied with the initial payment.

shopperIP String (error)

The IP address the shopper used to carry out the transaction.

This field is mandatory for some merchants depending on your business model, contact the Adyen Support Team for more information.

shopperReference String (tick)

An ID that uniquely identifies the shopper.

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

shopperInteraction String (tick)

The shopper interaction

Set to “Ecommerce”.

selectedRecurringDetailReference

String (tick)

The recurringDetailReference you want to use for this payment.

The value “LATEST” can be used to select the most recently stored recurring detail.

The following code examples show the request of a one-click payment in JSON, FORM, and SOAP.

{
    "amount" : {
        "value" : 2000,
        "currency" : "EUR"
    },

   "card" : {
        "cvc" : "737"
    },
     
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "s.hopper@test.com",
    "shopperIP" : "61.294.12.12",
    "shopperReference" : "Simon Hopper",
    "selectedRecurringDetailReference" : "LATEST",
    "recurring": {
        "contract" : "ONECLICK"
    },

    "shopperInteraction" : "Ecommerce"
}
<?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>
        <amount xmlns="http://payment.services.adyen.com">
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
          <value xmlns="http://common.services.adyen.com">2000</value>
        </amount>
        <card xmlns="http://payment.services.adyen.com">
          <cvc xmlns="http://payment.services.adyen.com">737</cvc>
        </card>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference>
        <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail>
        <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP>
        <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference>
        <selectedRecurringDetailReference xmlns="http://payment.services.adyen.com">LATEST</selectedRecurringDetailReference>
        <recurring xmlns="http://payment.services.adyen.com">
          <contract xmlns="http://payment.services.adyen.com">ONECLICK</contract>
        </recurring>
        <shopperInteraction xmlns="http://payment.services.adyen.com">Ecommerce</shopperInteraction>
       </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>
merchantAccount=TestMerchant&amount.value=2000&amount.currency=EUR&card.cvc=737&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com&shopperIP=61.294.12.12&recurring.contract=ONECLICK&selectedRecurringDetailReference=LATEST&shopperInteraction=Ecommerce

Recurring payment

A recurring payment session is set up like a regular payment. However, you need to include in the payment request a set of additional fields:

Name Type Required Description
recurring Class  (tick)

A container for the type of recurring contract to be used.

recurring contains the following child:

  • contract
contract String (tick)

The type of recurring contract to be used.

If ONECLICK,RECURRING was specified when creating the recurring contract, then this field should be RECURRING.

shopperEmail String (error)

The shopper's email address.

It does not need to match the email address supplied with the initial payment.

shopperReference String (tick)

An ID that uniquely identifies the shopper.

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

shopperInteraction String (tick)

The shopper interaction.

Set to ContAuth.

selectedRecurringDetailReference

String (tick)

The recurringDetailReference you want to use for this payment.

The value LATEST can be used to select the most recently stored recurring detail.

selectedBrand String (error)

The targeted payment method that you want to use for the recurring transaction.

Required for non-card recurring transactions, such as recurring payments for iDeal and Sofort, as these require a value of sepadirectdebit in the recurring payment to force their processing as SEPA direct debit transactions.

The following code examples show the request of a recurring payment in JSON, FORM, and SOAP.

{
    "amount" : {
        "value" : 2000,
        "currency" : "EUR"
    },
     
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "s.hopper@test.com",
    "shopperIP" : "61.294.12.12",
    "shopperReference" : "Simon Hopper",
    "selectedRecurringDetailReference" : "LATEST",
	"selectedBrand" : "",
    "recurring": {
        "contract" : "RECURRING"
    },

    "shopperInteraction" : "ContAuth"
}
<?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>
        <amount xmlns="http://payment.services.adyen.com">
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
          <value xmlns="http://common.services.adyen.com">2000</value>
        </amount>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference>
        <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail>
        <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP>
        <selectedBrand xmlns="http://payment.services.adyen.com" xsi:nil="true"/>
        <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference>
        <selectedRecurringDetailReference xmlns="http://payment.services.adyen.com">LATEST</selectedRecurringDetailReference>
        <recurring xmlns="http://payment.services.adyen.com">
          <contract xmlns="http://payment.services.adyen.com">RECURRING</contract>
        </recurring>
        <shopperInteraction xmlns="http://payment.services.adyen.com">ContAuth</shopperInteraction>
       </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>
merchantAccount=TestMerchant&amount.value=2000&amount.currency=EUR&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com&shopperIP=61.294.12.12&recurring.contract=RECURRING&selectedRecurringDetailReference=LATEST&shopperInteraction=ContAuth&selectedBrand=

Updating stored details

The stored payment details may need to be updated, for example when the card expiry date or the billing/delivery address 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.

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

Examples:

{
  "amount": {
    "currency": "EUR",
    "value": "100"
  },
  "card": {
    "expiryMonth": "11",
    "expiryYear": "2018"
  },
  "merchantAccount": "TestMerchant",
  "recurring": {
    "contract": "RECURRING"
  },
  "reference": "RecurringPayment-0001",
  "shopperEmail": "gras.shopper77@somewhere.org",
  "shopperIP": "1.1.1.1",
  "shopperInteraction": "ContAuth",
  "shopperReference": "grasshopper77",
  "selectedRecurringDetailReference": "RecurringDetailReference1"
}

<?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>
         <amount xmlns="http://payment.services.adyen.com">
           <currency xmlns="http://common.services.adyen.com">EUR</currency>
           <value xmlns="http://common.services.adyen.com">100</value>
         </amount>
         <ns1:card>
           <ns1:expiryMonth>11</ns1:expiryMonth>
           <ns1:expiryYear>2018</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>gras.shopper77@somewhere.org</ns1:shopperEmail>
         <ns1:shopperReference>grasshopper77</ns1:shopperReference> 
         <ns1:selectedRecurringDetailReference>RecurringDetailReference1</ns1:selectedRecurringDetailReference>
         <ns1:recurring>
           <ns1:contract>RECURRING</ns1:contract>
         </ns1:recurring>
         <ns1:shopperInteraction>ContAuth</ns1:shopperInteraction>
       </ns1:paymentRequest>
     </ns1:authorise>
   </soap:Body> 
</soap:Envelope>

amount.currency=EUR&amount.value=1234&card.expiryMonth=11&card.expiryYear=2018&merchantAccount=TestMerchant&reference=test1234&shopperReference=gras.shopper77&shopperEmail=gras.shopper77@somewhere.org&shopperIP=1.1.1.1&selectedRecurringDetailReference=RecurringDetailReference1&recurring.contract=RECURRING&shopperInteraction=ContAuth

Disabling a recurring contract

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

Request

Disabling a recurring contract (detail) can be done by calling the disable action on the Recurring service. The request has the following fields:

Name Type Required Description
merchantAccount String (tick)

Your merchant account.

shopperReference String (tick)

The ID that uniquely identifies the shopper.

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

recurringDetailReference

String (error)

The ID that uniquely identifies the recurring detail reference.

If it is not provided, the whole recurring contract of the shopperReference will be disabled, which includes all recurring details.

contract String (error)

Specify the contract if you only want to disable a specific use.

This field can be set to one of the following values, or to their combination (comma-separated):

  • ONECLICK
  • RECURRING
  • PAYOUT

Code examples

The example below illustrates how to disable a One-Click recurring detail only:

{
  "merchantAccount": "TestMerchant",
  "shopperReference": "test12345621217",
  "recurringDetailReference": "8313147988756818",
  "contract":"ONECLICK"
}
<?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:disable xmlns:ns1="http://recurring.services.adyen.com">
      <ns1:request>
        <ns1:merchantAccount>TestMerchant</ns1:merchantAccount>
        <ns1:shopperReference>test12345621217</ns1:shopperReference>
        <ns1:recurringDetailReference>8313147988756818</ns1:recurringDetailReference>
        <ns1:contract>ONECLICK</ns1:contract>
      </ns1:request>
    </ns1:disable>
  </soap:Body> 
</soap:Envelope>
merchantAccount=TestMerchant&shopperReference=test12345621217&recurringDetailReference=8314897374042210&contract=ONECLICK

The following example demonstrates how to disable all the details of a recurring contract:

{
  "merchantAccount": "TestMerchant",
  "shopperReference": "test12345621217",
  "recurringDetailReference": "8313147988756818"
}
<?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:disable xmlns:ns1="http://recurring.services.adyen.com">
      <ns1:request>
        <ns1:merchantAccount>TestMerchant</ns1:merchantAccount>
        <ns1:shopperReference>test12345621217</ns1:shopperReference>
        <ns1:recurringDetailReference>8313147988756818</ns1:recurringDetailReference>
      </ns1:request>
    </ns1:disable>
  </soap:Body> 
</soap:Envelope>
merchantAccount=TestMerchant&shopperReference=test12345621217&recurringDetailReference=8314897374042210

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

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.

It must be notified 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 and, Bancontact-MisterCash. 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 need to add the merchantInitiatedBilling permission to your PayPal account.

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.