Recurring payments manual Version: 2.30 Copyright (c) Adyen B.V.
1. Introduction ................................................................................................................................................ 6 2. What is a recurring contract? .................................................................................................................... 7 2.1. Recurring vs One-Click ................................................................................................................................................................
Appendix K: Sample Account Updater batch file ...................................................................................... 35 Appendix L: SOAP tokenLookup request and response ........................................................................... 36 Appendix M: SOAP listRecurringDetails response with updated expiry date ......................................... 37 Appendix N: REST listRecurringDetails response with updated expiry date ..........................................
Changelog Version Date Changes • Updated document to conform to Adyen brand guidelines • Added account updater section and appendices • Updated One-Click definition • Updated supported payment methods 2012-10-03 • Updated Chapter 5 to always use a selectedRecurringDetailReference 2.28 2012-05-08 • Added information about PayPal with list recurring details calls • Expanded Example 3 (response details) 2.27 2012-01-10 • Clarified where to send ONECLICK subsequent payments 2.
Audience This is a technical manual aimed at IT personnel involved in integrating merchants' systems with those at Adyen. The latest version of this document is available here: https://www.adyen.com/home/support/manuals.html 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.
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.
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.
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) The shopper's email address. • shopperReference (required) An ID that uniquely identifies the shopper. • recurringContract (required) The type of recurring contract to be used.
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.
o bankLocationId The location ID (Bankleitzahl) of the bank. o accountHolderName The name of the account holder. o bankAccountNumber The account number (Kontonummer). bank • A container for bankAccount data with the following fields: o bankAccountNumber The account number. o bankLocationId The location id of the bank. The field will be nil in most cases. o bankName The name of the bank. o bic The unique identification code for both financial and non-financial institutions.
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 OneClick payment session is set up like a regular payment and these additional fields are not required.
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.
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.
7. Disabling a recurring contract 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.
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.
In order to correctly process SEPA Direct Debit recurring payments, the recurring request must include the selectedBrand element with a value of “sepadirectdebit”. Please note, with the introduction of SEPA Direct Debits (SDD), directdebit_NL will be deprecated and no longer supported. We recommend implementing SDD as described in section 8.8. 8.7.
9. Account Updater Visa and Mastercard offer merchants the ability to register for their Account Updater services; Adyen has developed additional functionality to support this. The service allows you to receive updates on: • • • cards that have expired and a new expiry date is available. cards that have been replaced by a new card. cards that have been reported stolen or where the customer has informed their issuer that they no longer authorise a merchant to automatically charge their card.
The additionalData fields will be populated with the updated details according to the reason value. For example, where the reason is CardExpiryChanged, the additionalData will be only populated with the updated expiry data, and where the reason is CardChanged, the additionalData will be populated with the new alias and expiry data.
Please refer to Appendix O for a SOAP example of a List Recurring Details response with updated card information. Please refer to Appendix P for a REST example of a List Recurring Details response with updated card information.
10. FAQ 1. What does response '107 – Recurring is not enabled' mean? Recurring is not enabled by default. Please contact the Adyen Support Team (support@adyen.com) 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.
Appendix A: TEST and LIVE URLs Test URL’s Hosted Payment Pages (Multiple): https://test.adyen.com/hpp/select.shtml Hosted Payment Pages (Single): https://test.adyen.com/hpp/pay.shtml SOAP Payment Service https://pal-test.adyen.com/pal/servlet/soap/Payment SOAP Payment Service WSDL https://pal-test.adyen.com/pal/Payment.wsdl HTTP Adapter (Browser) https://pal-test.adyen.com/pal/adapter/httppost?Payment SOAP Recurring Service v6 https://pal-test.adyen.
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.
SupportAdyenTest grasshopper77 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: PAGE 24 EUR PAGE 25 PAGE 26
2014-01-01T01:50:12.178+01:00 PAGE 27Appendix C: REST example of a listRecurringDetails request and response Request action=Recurring.listRecurringDetails &recurringDetailsRequest.merchantAccount=SupportAdyenTest&recurringDetailsRequest.shopperReference=grasshopper& recurringDetailsRequest.recurring.contract=RECURRING Response recurringDetailsResult.creationDate=2014-01-01T15%3A02%3A08%2B01%3A00& recurringDetailsResult.details.0.card.expiryMonth=6& recurringDetailsResult.details.0.card.expiryYear=2016& recurringDetailsResult.details.0.card.
Appendix D: REST example of a recurring payment request and response Request action=Payment.authorise &paymentRequest.amount.currency=EUR&paymentRequest.amount.value=1234&paymentRequest.merchantAccount= SupportAdyenTest&paymentRequest.reference=test1234&paymentRequest.shopperReference=gras.shopper77& paymentRequest.shopperEmail=gras.shopper77@somewhere.org&paymentRequest.shopperIP=1.1.1.1& paymentRequest.selectedRecurringDetailReference=RecurringDetailReference1& paymentRequest.recurring.
Appendix E: SOAP example for updating stored details Request EUR PAGE 30Appendix F: REST example for updating stored details Request action=Payment.authorise &paymentRequest.amount.currency=EUR&paymentRequest.amount.value=1234& paymentRequest.card.expiryMonth=06&paymentRequest.card.expiryYear=2016&paymentRequest.merchantAccount= SupportAdyenTest&paymentRequest.reference=test1234&paymentRequest.shopperReference=gras.shopper77& paymentRequest.shopperEmail=gras.shopper77@somewhere.org&paymentRequest.shopperIP=1.1.1.1& paymentRequest.
Appendix G: SOAP example of a disable recurring contract request and response Request PAGE 32Appendix H: REST example of a disable recurring contract request and response Request action=Recurring.disable &disableRequest.merchantAccount=SupportAdyenTest&disableRequest.shopperReference=grasshopper77&disableRequest. recurringDetailReference=8313147988756818 Response disableResult.
Appendix I: SOAP account updater request and response using card data Request PAGE 34Appendix J: SOAP account updater request and response using token data Request PAGE 35Appendix K: Sample Account Updater batch file Request FH,1.0,TEST,Company,SupportAdyen,Default,1,ws@Company.
Appendix L: SOAP tokenLookup request and response Request SupportAdyenTest PAGE 37Appendix M: SOAP listRecurringDetails response with updated expiry date 2012-12-03T17:43:42+01:00 PAGE 38Appendix N: REST listRecurringDetails response with updated expiry date recurringDetailsResult.creationDate=2014-01-01T15%3A02%3A08%2B01%3A00& recurringDetailsResult.details.0.card.expiryMonth=6& recurringDetailsResult.details.0.card.expiryYear=2016& recurringDetailsResult.details.0.card.holderName=test& recurringDetailsResult.details.0.card.number=1111& recurringDetailsResult.details.0.creationDate=2014-01-22T15%3A02%3A08%2B01%3A00& recurringDetailsResult.details.0.
Appendix O: SOAP listRecurringDetails response with updated card information 2012-12-03T17:43:42+01:00 PAGE 40Appendix P: REST listRecurringDetails response with updated card information recurringDetailsResult.creationDate=2014-01-01T15%3A02%3A08%2B01%3A00& recurringDetailsResult.details.0.card.expiryMonth=6& recurringDetailsResult.details.0.card.expiryYear=2016& recurringDetailsResult.details.0.card.holderName=test& recurringDetailsResult.details.0.card.number=1111& recurringDetailsResult.details.0.creationDate=2014-01-22T15%3A02%3A08%2B01%3A00& recurringDetailsResult.details.0.
Appendix Q: SOAP payment request with updated expiry date PAGE 42Appendix R: REST payment request with updated expiry date Request action=Payment.authorise &paymentRequest.amount.currency=EUR&paymentRequest.amount.value=1234&paymentRequest.card.cvc=&paymentRequest. card.expiryMonth=06&paymentRequest.card.expiryYear=2016&paymentRequest.card.holderName=&paymentRequest.card. number=&paymentRequest.merchantAccount=SupportAdyenTest&paymentRequest.reference=test1234&paymentRequest. selectedRecurringDetailReference=LATEST&paymentRequest.recurring.
Appendix S: SOAP payment request with new card details PAGE 44Appendix T: REST payment request with new card details Request action=Payment.authorise &paymentRequest.amount.currency=EUR&paymentRequest.amount.value=1234&paymentRequest.card.cvc=&paymentRequest. card.expiryMonth=06&paymentRequest.card.expiryYear=2016&paymentRequest.card.holderName=Adyen+Test& paymentRequest.card.number=AliasHere&paymentRequest.merchantAccount=SupportAdyenTest&paymentRequest. reference=test1234&paymentRequest.selectedRecurringDetailReference=LATEST&paymentRequest.recurring.
