API Sepa Migration - Payment terminal Adyen - Free user manual and instructions

USER MANUAL API Sepa Migration Adyen

API Payments – Migration from Dutch Direct Debit and ELV to SEPA Direct Debit

Version: 1.00

Contact details

Simon Carmiggeltstraat 6-50

1011 DJ Amsterdam

P.O.Box 10095

1001 EB Amsterdam

The Netherlands

T+31202401240

E support @adyen.co m

Table of Contents

1. Introduction 4
2. Updates to One-Off Dutch Direct Debit Payments 5

2.1. Sample directdebit NL authorise Payment Request 5
2.2. Sample sepadirectdebit authorise Payment Request.. 6

1. Updates to One-Off ELV Payments.. 7

3.1. Sample ELV authorise Payment Request
3.2. Sample sepadirectdebit authorise Payment Request.. 8

1. Updates to Recurring API Payment Requests 9
   4.1. Sample sepadirectdebit recurring Payment Request.. 9

2. API Payment Response and Notifications 10

5.1. Sample sepadirectdebit Authorise Response 10
5.2. Sample sepadirectdebit Pending Notification 11
5.3. Sample sepdirectdebit Standard Notification 12

1. SDD Settlement Timeline 13

6.1. Core 13
6.2. Core 1 13

1. SDD Chargebacks 14

Appendix A: TEST and LIVE URLs. 15

Changelog

Version Date Changes
1.00 2013-12-21	•Manual created

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 authorisation of the requested payment and NOT to deliver in situations where an explicit rejection is not received.

Feedback

The latest version of this document is available here:

https://support.adyen.com/links/documentation

Please direct any comments or suggestions about this manual to [e-mail].

ADYEN CONFIDENTIAL INFORMATION

Copyright (c) Adyen B.V. 2013

3/17

1. Introduction

The European Payments Council (EPC) has mandated that as of 1^st February 2014, all merchants that are currently processing ELV or Incasso (Dutch Direct Debit) payments, must have implemented SEPA Direct Debits (SDD).

The purpose of this manual is to provide you with some guidance on updating your API payment integration to SEPA Direct Debit from:

1. Dutch Direct Debit (directdebit_NL)
2. ELV to SEPA Direct Debit

Please note, there is still some ongoing development and as a result this document is subject to change.

2. -Updates to One-Off Dutch Direct Debit Payments

If you are processing Incasso payments, the payment request has to be updated to accommodate the new SDD requirements, the bankAccount container will no longer include bankAccountNumber, this has been replaced by:

-iban

The IBAN.

·bic

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

• BankName (optional)

The name of the bank.

In addition to the change to the bankaccount container, you must also include:

-selectedBrand (mandatory)

The value should be sepadirectdebit.

Please note, Direct Debit payments were previously submitted using the directdebit action rather than the authorise action. The directdebit action has been deprecated since 1st January 2011 and cannot be used for SDD payment requests.

2.1. -Sample directdebit_NL authorise Payment Request

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchemaSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchemaSchema-instance">
<soap:Body>
<ns1:authorise xmlns:ns1="http://payment/services.adyen.com">
<ns1:paymentRequest>
<ns1:amount>
<currency xmlns="http://common/services.adyen.com">EUR</currency>
<value xmlns="http://common/services.adyen.com">1500</value>
</ns1:amount>
<ns1:bankAccount>
<ns1:bankAccountNumber>123456789</ns1:bankAccountNumber>
<ns1:bankName>Rabobank</ns1:bankName>
<ns1:ownerName>Klaas T. Jansen</ns1:ownerName>
<ns1:countryCode>NL</ns1:countryCode>
</ns1:bankAccount>
<ns1:merchantAccount>YourMerchant</ns1:merchantAccount>
<ns1:reference>Your Reference Here</ns1:reference>
<ns1:shopperEmail@[e-mail]</ns1:shopperEmail>
<ns1:shopperReference>TheShopperReference</ns1:shopperReference>
<ns1:shopperIP>10.10.100.200</ns1:shopperIP>
<ns1:shopperStatement>UW ORDER 122345677889</ns1:shopperStatement>
</ns1:paymentRequest>
</ns1:authorise>
</soap:Body>
</soap:Envelope> 

2.2. Sample sepadirectdebit authorise Payment Request

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchemaSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchemaSchema-instance">
<soap:Body>
<ns1:authorise xmlns:ns1="http://payment/services.adyen.com">
<ns1:paymentRequest>
<ns1:amount>
<currency xmlns="http://common/services.adyen.com">EUR</currency>
<value xmlns="http://common/services.adyen.com">1500</value>
</ns1:amount>
<ns1:bankAccount>
<ns1:bic>RABONL2U</ns1:bic>
<ns1:iban>NL48RAB00132394782</ns1:iban>
<ns1:ownerName>Klaas T. Jansen</ns1:ownerName>
<ns1:countryCode>NL</ns1:countryCode>
</ns1:bankAccount>
<ns1:merchantAccount>YourMerchant</ns1:merchantAccount>
<ns1:reference>Your Reference Here</ns1:reference>
<ns1:shopperEmail@[e-mail]</ns1:shopperEmail>
<ns1:shopperReference>TheShopperReference</ns1:shopperReference>
<ns1:shopperIP>10.10.100.200</ns1:shopperIP>
<ns1:shopperStatement>UW ORDER 122345677889</ns1:shopperStatement>
<ns1:selectedBrand>sepadirectdebit</ns1:selectedBrand>
</ns1:paymentRequest>
</ns1:authorise>
</soap:Body>
</soap:Envelope> 

2.3. Sample Oneoff sepadirectdebit Authorise Response

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchemaScheme"
xmlns:xsi="http://www.w3.org/2001/XMLSchemaScheme-instance">
<soap:Body>
<ns1:authoriseResponse xmlns:ns1="http://payment/services.adyen.com">
<ns1:paymentResult>
<additionalData xmlns="http://payment/services.adyen.com">
<entry>
    <key xsi:type="xsd:string">sepadirectdebit.dateOfSignature</key>
    <value xsi:type="xsd:string">2013-11-28</value>
</entry>
<entry>
    <key xsi:type="xsd:string">sepadirectdebit(sequenceType</key>
    <value xsi:type="xsd:string">First</value>
</entry>
<entry>
    <key xsi:type="xsd:string">sepadirectdebit.mandateID</key>
    <value xsi:type="xsd:string">9913856361050084</value>
</entry>
</additionalData>
<authCode xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<dccAmount xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<dccSignature xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<fraudResult xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<issuerUrl xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<md xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<paRequest xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<pspReference xmlns="http://payment/services.adyen.com">9913856361050084</pspReference>
<refusalReason xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<ns1:resultCode>Received</ns1:resultCode>
</ns1:paymentResult>
</ns1:authoriseResponse>
</soap:Body>
</soap:Envelope> 

3. -Updates to One-Off ELV Payments

If you are processing ELV payments, the payment request has to be updated to accommodate the new SDD requirements, the ELV container will be removed and replaced by the bankAccount container.

• BankName (optional)

The name of the bank.

In addition to adding the bankaccount container, you must also include:

-selectedBrand (mandatory)

The value should be sepadirectdebit.

There is also a change to the flow of SDD transactions:

1. The response returned for submitted SDD transaction is Received and not Authorised.
2. When the money has been received by Adyen, the transaction will be booked to Authorised immediately followed by SentForSettle, followed by Settled.

For further information, please read the "Incasso Response" paragraph of the API manual.

Please note, we are in the process of investigating if and how we can provide an authorisation/capture alternative.

3.1.-Sample ELV authorise Payment Request

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchemaSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchemaSchema-instance">
<soap:Body>
<ns1:authorise xmlns:ns1="http://payment/services.adyen.com">
<ns1:paymentRequest>
<ns1:amount>
<currency xmlns="http://common/services.adyen.com">EUR</currency>
<value xmlns="http://common/services.adyen.com">1500</value>
</ns1:amount>
<ns1:elv>
<ns1:accountHolderName>S.Hopper</ns1:accountHolderName>
<ns1:bankAccountNumber>1234567890</ns1:bankAccountNumber>
<ns1:bankLocation>Hamburg</ns1:bankLocation>
<ns1:bankLocationId>12345678</ns1:bankLocationId>
<ns1:bankName>Postbank Hamburg</ns1:bankName>
</ns1:elv>
<ns1:merchantAccount>YourMerchant</ns1:merchantAccount>
<ns1:reference>Your Reference Here</ns1:reference>
<ns1:shopperEmail@[e-mail]</ns1:shopperEmail>
<ns1:shopperReference>TheShopperReference</ns1:shopperReference>
<ns1:shopperIP>10.10.100.200</ns1:shopperIP>
<ns1:shopperStatement>UW ORDER 122345677889</ns1:shopperStatement>
</ns1:paymentRequest>
</ns1:authorise>
</soap:Body>
</soap:Envelope> 

3.2. Sample sepadirectdebit authorise Payment Request

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchemaSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchemaSchema-instance">
<soap:Body>
<ns1:authorise xmlns:ns1="http://payment/services.adyen.com">
<ns1:paymentRequest>
<ns1:amount>
<currency xmlns="http://common/services.adyen.com">EUR</currency>
<value xmlns="http://common/services.adyen.com">1500</value>
</ns1:amount>
<ns1:bankAccount>
<ns1:bic>TESTDE01</ns1:bic>
<ns1:iban>DE87123456781234567890</ns1:iban>
<ns1:ownerName>S.Hopper</ns1:ownerName>
<ns1:countryCode>DE</ns1:countryCode>
</ns1:bankAccount>
<ns1:merchantAccount>YourMerchant</ns1:merchantAccount>
<ns1:reference>Your Reference Here</ns1:reference>
<ns1:shopperEmail@[e-mail]</ns1:shopperEmail>
<ns1:shopperReference>TheShopperReference</ns1:shopperReference>
<ns1:shopperIP>10.10.100.200</ns1:shopperIP>
<ns1:shopperStatement>UW ORDER 122345677889</ns1:shopperStatement>
<ns1:selectedBrand>sepadirectdebit</ns1:selectedBrand>
</ns1:paymentRequest>
</ns1:authorise>
</soap:Body>
</soap:Envelope> 

4. Updates to Recurring API Payment Requests

The only change for Recurring API payment requests is the addition of the following mandatory field:

-selectedBrand (mandatory)

The value should be sepadirectdebit.

4.1. Sample sepadirectdebit recurring Payment Request

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchemaSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchemaSchema-instance">
<soap:Body>
<ns1:authorise xmlns:ns1="http://payment/services.adyen.com">
<ns1:paymentRequest>
<ns1:amount>
<currency xmlns="http://common/services.adyen.com">EUR</currency>
<value xmlns="http://common/services.adyen.com">2150</value>
</ns1:amount>
<ns1:merchantAccount>YourMerchant</ns1:merchantAccount>
<ns1:reference>Your Reference Here</ns1:reference>
<ns1:shopperEmail@[e-mail]</ns1:shopperEmail>
<ns1:shopperReference>TheShopperReference</ns1:shopperReference>
<ns1:shopperInteraction>ContAuth</ns1:shopperInteraction>
<ns1:recurring>
<ns1:contract>RECURRING</ns1:contract>
</ns1:recurring>
<ns1:selectedRecurringDetailRetail>LAST</ns1:selectedRecurringDetailRetail>
<ns1:selectedBrand>sepadirectdebit</ns1:selectedBrand>
</ns1:paymentRequest>
</ns1:authorise>
</soap:Body>
</soap:Envelope> 

5. API Payment Response and Notifications

The synchronous API response will contain key/value pair responses containing pertinent information regarding the SDD payment.

5.1. Sample sepadirectdebit Authorise Response

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchemaSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchemaSchema-instance">
<soap:Body>
<ns1:authoriseResponse xmlns:ns1="http://payment/services.adyen.com">
<ns1:paymentResult>
<additionalData xmlns="http://payment/services.adyen.com">
<entry>
    <key xsi:type="xsd:string">sepadirectdebit.dateOfSignature</key>
    <value xsi:type="xsd:string">2013-11-28</value>
</entry>
<entry>
    <key xsi:type="xsd:string">sepadirectdebit(sequenceType</key>
    <value xsi:type="xsd:string">First</value>
</entry>
<entry>
    <key xsi:type="xsd:string">sepadirectdebit.mandateID</key>
    <value xsi:type="xsd:string">9913856361050084</value>
</entry>
</additionalData>
<authCode xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<ddAmount xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<ddSignature xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<fraudResult xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<issuerUrl xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<md xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<paRequest xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<pspReference xmlns="http://payment/services.adyen.com">9913856361050084</pspReference>
<refusalReason xmlns="http://payment/services.adyen.com" xsi-nil="true"/>
<ns1:resultCode>Received</ns1:resultCode>
</ns1:paymentResult>
</ns1:authoriseResponse>
</soap:Body>
</soap:Envelope> 

In the case that this is a subsequent payment, you will receive 'Recurring' back as sepadirectdebit(sequenceType.

5.2. Sample sepadirectdebit Pending Notification

<com.adyen/services.Notification.NotificationRequestItem> <pspReference>9913856361050084</pspReference> <merchantReference>Test Payment Reference</merchantReference> <merchantAccountCode>TestMerchant</merchantAccountCode> <eventDate>2013-11-28 11:55:05.934 CET</eventDate> <eventCode>PENDING</eventCode> <amount> <value>1500</value> <currency>EUR</currency> </amount> <success>true</success> <paymentMethod>sepadirectdebit</paymentMethod> <additionalData> <entry> <string>sepadirectdebit.dateOfSignature</string> <string>2013-11-28</string> </entry> <entry> <string>sepadirectdebit.sequenceType</string> <string>First</string> </entry> <entry> <string>sepadirectdebit.mandateID</string> <string>9913856361050084</string> </entry> </additionalData> <com.adyen/services.Notification.RequestItem> 

The Pending notification is not enabled by default. Once enabled, the notification is sent out at the moment the payment is created. Please contact Adyen support ([e-mail]) if you want to receive this additional notification.

5.3. Sample sepadirectdebit Standard Notification

<com.adyen/services.Notification.NotificationRequestItem> <pspReference>9913856361050084</pspReference> <merchantReference>Test Payment Reference</merchantReference> <merchantAccountCode>TestMerchant</merchantAccountCode> <eventDate>2013-11-28 11:55:05.934 CET</eventDate> <eventCode>AUTHORIZATION</eventCode> <amount> <value>1500</value> <currency>EUR</currency> </amount> <success>true</success> <reason/> <paymentMethod>sepadirectdebit</paymentMethod> <com.adyen/services.Notification.NotificationRequestItem> 

5.4. Sample sepadirectdebit Extended Notification

<com.adyen/services.Notification.NotificationRequestItem> <pspReference>9913856361050084</pspReference> <merchantReference>Test Payment Reference</merchantReference> <merchantAccountCode>TestMerchant</merchantAccountCode> <eventDate>2013-11-28 11:55:05.934 CET</eventDate> <eventCode>AUTHORISATION</eventCode> <amount> <value>1500</value> <currency>EUR</currency> </amount> <success>true</success> <reason/> <paymentMethod>sepadirectdebit</paymentMethod> <additionalData> <entry> <string>sepadirectdebit.dateOfSignature</string> <string>2013-11-28</string> </entry> <entry> <string>sepadirectdebit.sequenceType</string> <string>First</string> </entry> <entry> <string>sepadirectdebit.mandateID</string> <string>9913856361050084</string> </entry> </additionalData> <com.adyen/services.Notification.RequestItem> 

The extended notification is not enabled by default. Please contact Adyen support ([e-mail]) if you want to receive the extended notification.

6. -SDD Settlement Timeline

Prior to initiating the DD, you will need to inform the customer that the payment is due.

6.1. -Core

Event: SDD First SDD Recurring
Pre-notification-(T-14) T-5 - (T-14) T-2
Submit SDD instructions (Moment of payment request)-T-5 -T-2
Latest moment to revoke (cancel) SDD-T-1 -T-1
SDD instruction processed by bank -T-T
Reconciliation by Adyen PSP -T+1 -T+1

6.2. -Core 1

Core 1 is automatically used in Germany, Spain and Austria.

Event:	SDD
Pre-notification	(T-14) T-1
Submit SDD instructions	T-1
Latest moment to revoke (cancel) SDD	N/A
SDD instruction processed by bank	T
Reconciliation by Adyen PSP	T+1

7. SDD Chargebacks

The chargeback process is standardised for all SEPA DD variants. The SDD schemes ensure more protection and refund rights for consumers:

The shopper can have the authorised SEPA DD payment returned within 8 weeks.

The shopper has 13 months to report incorrect unauthorised SEPA DD with their bank and request a reversal, as the debit was not authorised or the mandate was expired or had been cancelled.

Both scenarios result in a payment status of Chargeback. The process is comparable with a Credit Card chargeback but without the possibility to defend against the dispute.

Appendix A: TEST and LIVE URLs

TEST URLs

SOAP	Payment Service https://pal-test.adyen.com/pal/servlet/soap/Payment
	Payment Service WSDL https://pal-test.adyen.com/pal/Payment.wsdl
REST	HTTP Adapter (Browser) https://pal-test.adyen.com/pal/adapter/httppost?Payment
	Authorisation https://pal-test.adyen.com/pal/adapter/httppost?Payment(authorise
	Test Capture https://pal-test.adyen.com/pal/adapter/httppost?Paymentcapture
	Test Refund https://pal-test.adyen.com/pal/adapter/httppost?Payment.refund
	Test Cancel https://pal-test.adyen.com/pal/adapter/httppost?Payment.cancel

LIVE URLs

SOAP	Payment Service https://pal-live.adyen.com/pal/servlet/soap/Payment
	Payment Service WSDL https://pal-live.adyen.com/pal/Payment.wsdl
REST	HTTP Adapter (Browser) https://pal-live.adyen.com/pal/adapter/httppost?Payment
	Authorisation https://pal-live.adyen.com/pal/adapter/httppost?Payment(authorise
	Test Capture https://pal-live.adyen.com/pal/adapter/httppost?Payment+capture
	Test Refund https://pal-live.adyen.com/pal/adapter/httppost?Payment.refund
	Test Cancel https://pal-live.adyen.com/pal/adapter/httppost?Payment.cancel