Integration Manual: Contact Details

Integration
Manual
Version: 1.80
Contact details
Simon Carmiggeltstraat 6-50
1011 DJ Amsterdam
P.O. Box 10095
1001 EB Amsterdam
The Netherlands
T +31 20 240 1240

E support@adyen.com
Table of Contents
1. Introduction...............................................................................................................................................................................................................................................................................................................................................
6
2. Hosted Payment Pages.......................................................................................................................................................................................................................................................................................................................7
2.1. Setting Up The Payment.....................................................................................................................................................................................................................................................................................................7
2.1.1. Redirect Versus Form POST................................................................................................................................................................................................................................................................................7
2.1.2. Payment Session Example..................................................................................................................................................................................................................................................................................7
2.2. Explanation of the Session Fields.................................................................................................................................................................................................................................................................................8
2.3. Payment Flow Selections................................................................................................................................................................................................................................................................................................10
2.3.1. One-Page Payment Flow...................................................................................................................................................................................................................................................................................10
2.3.2. Multi-Page Payment Flow................................................................................................................................................................................................................................................................................10
2.3.3. Skip the Hosted Payment Page (Directory Lookup)...........................................................................................................................................................................................................................11
2.4. Payment Completion..........................................................................................................................................................................................................................................................................................................
11
2.5. Error Handling........................................................................................................................................................................................................................................................................................................................
12
2.6. Billing Address Pre-Population and AVS.................................................................................................................................................................................................................................................................12
2.7. Shopper Information...........................................................................................................................................................................................................................................................................................................13
2.8. Using an iFrame....................................................................................................................................................................................................................................................................................................................
14
2.9. Payment Methods................................................................................................................................................................................................................................................................................................................
15
2.10. Custom Payment Methods...........................................................................................................................................................................................................................................................................................
15
3. CVC-Only Repeat Payments...........................................................................................................................................................................................................................................................................................................17
3.1. Setting Up the Payment...................................................................................................................................................................................................................................................................................................
17
4. Testing.......................................................................................................................................................................................................................................................................................................................................................
18
4.1. Testing AVS Results.............................................................................................................................................................................................................................................................................................................
18
4.2. Testing CVC/CVV Results..................................................................................................................................................................................................................................................................................................18
4.3. Testing Error Codes.............................................................................................................................................................................................................................................................................................................18
5. Modifcations.........................................................................................................................................................................................................................................................................................................................................20
5.1. Capture.......................................................................................................................................................................................................................................................................................................................................20
5.2. Cancel..........................................................................................................................................................................................................................................................................................................................................
21
5.3. Refund.........................................................................................................................................................................................................................................................................................................................................22
5.4. Cancel or Refund...................................................................................................................................................................................................................................................................................................................23
6. API Fault Codes....................................................................................................................................................................................................................................................................................................................................24
7. Notifcations...........................................................................................................................................................................................................................................................................................................................................25
7.1. Notifcation Message Fields...........................................................................................................................................................................................................................................................................................25
7.2. Accepting Notifcations......................................................................................................................................................................................................................................................................................................
27
7.3. Retrying Notifcations.........................................................................................................................................................................................................................................................................................................27
Appendix A: TEST and LIVE URLs...................................................................................................................................................................................................................................................................................................
28
Appendix B: JSON Response To Directory Lookup................................................................................................................................................................................................................................................................29
Appendix C: Computing the HMAC................................................................................................................................................................................................................................................................................................31
Payment Setup................................................................................................................................................................................................................................................................................................................................31
Test HMAC Calculation...............................................................................................................................................................................................................................................................................................................31
Payment Result...............................................................................................................................................................................................................................................................................................................................
32
Custom Payment Method Redirect.....................................................................................................................................................................................................................................................................................
32
Appendix D: SOAP Modifcation Request and Response - Capture.............................................................................................................................................................................................................................33
Appendix E: REST Modifcation Request and Response - Capture..............................................................................................................................................................................................................................34
Appendix F: SOAP Modifcation Request and Response - Cancel................................................................................................................................................................................................................................35
Appendix G: REST Modifcation Request and Response - Cancel................................................................................................................................................................................................................................36
Appendix H: SOAP Modifcation Request and Response - Refund...............................................................................................................................................................................................................................37
Appendix I: REST Modifcation Request and Response - Refund.................................................................................................................................................................................................................................
38
2 / 48
Integration Manual
Appendix J: SOAP Modifcation Request and Response - CancelOrRefund............................................................................................................................................................................................................39

Appendix K: REST Modifcation Request and Response - CancelOrRefund...........................................................................................................................................................................................................40
Appendix L: CVC/CVV and AVS Result Values..........................................................................................................................................................................................................................................................................41
Appendix M: SOAP Notifcation Request and Response....................................................................................................................................................................................................................................................
42
Appendix N: REST Notifcation Request and Response.....................................................................................................................................................................................................................................................
44
Appendix O: Fault Codes.....................................................................................................................................................................................................................................................................................................................45
3 / 48
Integration Manual
ADYEN CONFIDENTIAL INFORMATION

Copyright (c) Adyen B.V. 2014
Changelog
Version
Date
Changes
1.80
2014-03-05
Added testing error codes section

Updated REST modifcation appendices
1.79
2014-01-28
Updated document to conform to Adyen brand guidelines

Added testing AVS and CVC section
Added SOAP and REST modifcation and notifcation examples to appendices
1.78
2013-08-14
Added Directory Lookup, shopper Information signature
1.77
2013-07-23
Updated Modifcation response
1.76
2013-06-24
Updated Appendix B section
1.75
2013-06-10
Added (merchant) reference to modifcations
1.74
2013-06-07
Updated AUTHORISATION notifcation reason feld
1.73
2012-08-24
Updated CHARGEBACK_REVERSED notifation success feld to true
1.72
2012-08-16
Added duplicate notifcation information
1.71
2012-08-03
Changed default payment fow

Altered iFrame content
1.70
2011-09-29
Added merchantReturnData to Custom Payment Methods
1.69
2011-08-03
Added information about reason feld for creditcards
1.68
2011-07-14
Corrected eventCode for cancel-or-refund modifcation

Added entries to the Payment Methods table
1.67
2011-05-24
Corrected SOAP message in Example 8 ([accepted])

Added optional feld to HMAC Computation
1.66
2011-03-17
Added REFUNDED_REVERSED notifcation
1.65
2011-02-16
Added entries to the Payment Methods table
1.64
2011-02-04
Corrections to value parameter description for capture and refunds
1.63
2011-01-17
Added Error Handling section
1.62
2011-01-16
Correction of merchantReturnData feld
1.61
2010-12-16
Clarifed AVS
1.60
2010-12-03
Added general Tips and Warnings
1.56
2010-11-08
Added skin option settings to billing address information
1.55
2010-09-07
Corrected link to checkhmac.shtml in Appendix B
1.54
2010-07-27
Added audience section

Manual reviewed for English and layout consistency
1.53
2010-07-05
Added existing max length for the merchantReference feld
1.52
2010-05-14
Added Test HMAC Calculation section
1.51
2010-03-31
Added additional information
1.50
2010-03-31
Added additional information about redirect payment methods and optional

felds
1.49
2010-03-31
Added Payment Methods section
4 / 48
Integration Manual
1.48
2010-03-09
Correction of oferEmail parameter value
1.47
2010-02-24
Correction of parameters passed back in result URL.

Added description of placeholders in shopperStatement.
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://support.adyen.com/links/documentation
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
You can provide feedback about this document by sending an email to the following address:
support@adyen.com
We appreciate your comments.
5 / 48
Integration Manual
1. Introduction
The purpose of this manual is to facilitate the integration of your platform with the Adyen Payment System. In the
following chapters we will cover how you can use the:
Hosted Payment Pages: to integrate with the Adyen Hosted Payment Pages (HPPs).
Modifcations: to capture/cancel and refund payments.
Notifcations: to keep track of payments and modifcations.
Adyen has code samples in various programming languages available for your reference; these can be found here:
https://github.com/adyenpayments
This document does not cover:
The life-cycle of a payment
The Adyen Merchant Backofce
The basic architecture of the Adyen systems
Creating and customising a Skin
These are documented in other manuals, which are available here:

6 / 48
Integration Manual
2. Hosted Payment Pages

The Adyen Hosted Payment Pages (HPP) provide a fexible, secure and easy way to allow shoppers to pay for goods or
services. Once a shopper has added items to their shopping cart and needs to pay to complete their order, they will be
redirected from your site to the HPP, where they will submit their payment details. Once complete, the shopper is
redirected back to your site along with the result of the payment.
You may implement Adyen's Skin technology to customise the HPP and create a seamless checkout experience for your
shoppers. Please refer to the Adyen Skin Creation Manual for more details; this can be found here:
2.1. Setting Up The Payment

The hand of between your site and the HPP skin is achieved by setting up a payment session for the shopper, as a
standard HTML form, and transferring the shopper with this payment session to the HPP. To avoid the possibility of a
shopper tampering with payment session data it is cryptographically signed using a shared secret. This is a simple
process and we have code samples in common programming languages available here:
2.1.1.
Redirect Versus Form POST
It is possible to set up a payment session using a generated URL, for example for a browser redirect (HTTP 302). Please
keep in mind the following:
Not all browsers are capable of handling large URLs. Specifcally for Microsoft Internet Explorer the size of the
URL should not exceed 2083 characters. It is your responsibility to ensure that this limit is not exceeded.
All parameters and their values should be URL-encoded using UTF-8 character encoding, as recommended by
W3C.
2.1.2.
Payment Session Example
You have a shopper who has to pay a total of GBP100 for an order which is identifed in your backofce systems as
Internet Order 12345.
The goods will be shipped to the shopper before or on October 20th, 2014
You want to present the text 1 Digital Camera as an order summary on the payment review page.
The shopper is using British English as their language.
The Skin name you will be using is 4aD37dJA
The Merchant Account is TestMerchant.
Furthermore, you want this payment ofer to expire today at 11 am, assuming it is 10:30 am on October 11th
2014 in the UTC time zone.
The following is an example of a complete payment session for the example above:
7 / 48
Integration Manual
<!DOCTYPE html>
<html>
<body>
<form method="post" action="https://live.adyen.com/hpp/select.shtml" id="adyenForm"
name="adyenForm" target="_parent">
<input
<input
<input
<input
<input
<input
<input
<input
<input
<input
<input
<input
<input
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
name="merchantSig" value="3iWDU/V5RMtdaiZC4YRIpoX9/v0=" />

name="sessionValidity" value="2014-09-23T12:09:39Z" />
name="shipBeforeDate" value="2013-12-03" />
name="shopperLocale" value="en_GB" />
name="merchantAccount" value="SupportAdyenDemo" />
name="paymentAmount" value="100" />
name="currencyCode" value="EUR" />
name="skinCode" value="TOuEXu2m" />
name="merchantReference" value="Internet Order 12345" />
name="shopperReference" value="test102@gmail.com" />
name="recurringContract" value="RECURRING,ONECLICK" />
name="shopperEmail" value="test102@gmail.com" />
name="offset" value="0" />
<input type="submit" value="Send" />

<input type="reset" />
<body>
<html>
2.2. Explanation of the Session Fields

Some detail about the contents of the felds:
merchantReference
This is your reference for this payment, it will be used in all communication to you regarding the status of the
payment. We recommend using a unique value per payment but this is not a requirement. If you need to provide
multiple references for a transaction you may use this feld to submit them with the transaction, separating each
with -.
This feld has a maximum of 80 characters.
paymentAmount
The payment amount specifed in minor units, without the decimal separator. For example, GBP100 is specifed
as 10000 and EUR199.95 is specifed as 19995. Most currencies are like this and have 100 minor units to a major
unit, e.g. pennies to the pound, cents to the euro. However, some currencies are exceptions in that they do not
have minor units, such as Japanese yen, or they have 3 decimal places, such as BHD. For example, JPY1001 is
specifed as 1001 and BD 10.900 is specifed as 10900.
currencyCode
The three character ISO currency code1.
shipBeforeDate
The date by which the goods or services specifed in the order must be shipped or rendered. The format for
submission is YYYY-MM-DD. Please see www.w3.org/TR/NOTE-datetime for more information.
skinCode
The code of the skin to be used for the payment. You may have more than one skin associated with your account
if you require a diferent branding. Please refer to the Adyen Skin Creation Manual for more information:
https://support.adyen.com/index.php?/Knowledgebase/List/Index/101/documentation
merchantAccount
The merchant account for which you want to process the payment.
shopperLocale (optional)
A complete list of currency codes can be found here: http://www.currency-iso.org/en/home/tables/table-a1.html
8 / 48
Integration Manual
A combination of language code and country code used to specify the language to be used in the payment
session, for example en_GB for British English. Use just the language code when the country distinction is not
required, i.e. fr not fr_FR. Default locale is en_GB.
orderData (optional)
A fragment of HTML which will be displayed to the shopper on the review payment page just before fnal
confrmation of the payment. In order to guarantee the correct transmission of this data, including the sending
of non-western characters, such as Japanese or Cyrillic character sets, the data is compressed and encoded in
the session (GZIP compressed and Base64 encoded). Code samples in common programming languages are
available here:
sessionValidity
The time by which a payment needs to have been made. This is especially useful for tickets/reservations, where
you want to hold the item for sale for only a short period of time. The format for submission is YYYY-MMDDThh:mm:ssTZD. TZD is the Time Zone Designator which can either be the letter 'Z' or +hh:mm or -hh:mm.
Please see www.w3.org/TR/NOTE-datetime for more information.
merchantReturnData
This feld will be appended as-is to the return URL when the shopper completes, or abandons, the payment and
returns to your shop; it is typically used to transmit a session ID. This feld has a maximum of 128 characters.
Please note, Adyen cannot guarantee that all payment methods will work when using the
merchantReturnData parameter. For redirect payment methods, such as iDEAL, the request may have a
limited size. If, with the merchantReturnData added, the size of the request is too large, the payment can fail.
merchantSig
The signature in Base64 encoded format. The signature is generated by concatenating the values of a number of
the payment session felds and computing the HMAC using the shared secret as confgured in the skin. Please
refer to Appendix C for details on computing the signature.
countryCode (optional)
By default the payment methods ofered to a shopper are fltered based upon the country that the shopper's IP
address is mapped to. This prevents a UK shopper from being presented with a German payment method such
as SOFORT berweisung. This IP-to-country mapping is not 100% accurate, so if you have already established
the country of the shopper you may set it explicitly using the countryCode parameter. Note that this parameter is
optional and is not used as part of the signing data. It uses the ISO 3166-1 alpha-2 format - see
http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for more information2.
shopperEmail (optional)
The shopper's email address. We recommend that you provide this data, as it is used in a velocity fraud check.
Please note, this feld is mandatory for Recurring payments.
shopperReference (optional)
An ID that uniquely identifes the shopper, such as a customer id. We recommend that you provide this data, as
it is used in a velocity fraud check and is the key for recurring payments.
Please note, this feld is mandatory for Recurring payments.
allowedMethods (optional)
A comma-separated list of allowed payment methods, please refer to section 2.9 for more details. This acts as a
flter on the payment methods which would normally be available in the skin. Only the payment methods in this
list will be shown, if available, and all others will be ignored. Spaces are not allowed.
Please note, this parameter is optional. If it is not used, the value for this feld in the merchantSignature
computation is an empty String.
More information can be found here: http://www.iso.org/iso/home/standards/country_codes.htm
9 / 48
Integration Manual
blockedMethods (optional)
A comma-separated list of allowed payment methods, please refer to section 2.9 for more details. This acts as a
flter on the payment methods which would normally be available in the skin. The methods listed will be
removed from the list of available payment methods. Spaces are not allowed.
Please note, this parameter is optional. If it is not used, the value for this feld in the merchantSignature
computation is an empty String.
ofset (optional)
An integer that is added to the normal fraud score. The value can be either positive or negative.
brandCode (optional)
The code that identifes the specifc payment that is to be used to process the payment.
issuerId (optional)
The code that identifes the specifc issuerId that is to be used to process the payment.
shopperStatement (optional)
To submit a variable shopper statement you can set the shopperStatement feld in the payment request. You can
also include place holders for the various references: ${reference} for the merchant reference and $
{pspReference} for the psp reference.
Please note:
Not all acquirers support dynamic shopper statements.

The shopperStatement feld may not exceeds 135 characters and can only contain the characters: a-zA-Z09.,-?|
Note that if the shopperStatement feld is set it is also included in the HMAC computation.
oferEmail (optional)
If the value for oferEmail is prompt an extra payment method is added to the list of payment methods called
Pay by Email. If a shopper selects this payment method, an email will be sent to the shopper which can be used
to pay later. The sessionValidity time must lie in the future if the shopper wants to use this link to pay.
2.3. Payment Flow Selections

You have the option of choosing between two diferent payment fows - the One-Page Payment fow which reduces the
payment process to a single page, and the Multi-Page Payment fow which splits the payment process into two or three
discrete steps. Optionally, you may choose to host the payment selection on your website and skip the HPP.
2.3.1.
One-Page Payment Flow
The One-Page Payment fow uses Javascript extensively to manipulate and validate the page content. It is suited for use
on modern browsers and when page complexity is not an issue. Some presentation and validation occurs automatically.
For example, the credit card logo is highlighted when the shopper enters the frst digits of their card, and an error
appears, prior to payment submission, if the card number is invalid.
Using the One-Page Payment fow is achieved by calling pay.shtml
Please refer to Appendix A for a list of all URLs for submitting payment session requests.
2.3.2.
Multi-Page Payment Flow
The Multi-Page Payment fow is lightweight and doesn't require Javascript, ensuring maximum compatibility with a wide
range of browsers and devices, including mobile phones and PDAs.
Using the Multi-Page Payment fow is achieved by calling select.shtml
Please refer to Appendix A for a list of all URLs for submitting payment session requests.
10 / 48
Integration Manual
2.3.3.
Skip the Hosted Payment Page (Directory Lookup)
You may decide to skip the Adyen payment method selection page so that the shopper starts directly on the payment
details entry page. This is done by calling details.shtml instead of select.shtml. An additional parameter, brandCode and
where applicable issuerId, should be provided with the selected payment method listed, please refer to section 2.9 for
more details.
The directory service can also be used to determine which payment methods are available for the shopper on your
Merchant Account. This is done by calling directory.shtml, with a normal payment request.
Please note that the countryCode feld is mandatory to receive back the correct payment methods.
Please refer to Appendix B for an example of a JSON response to the directory lookup.
2.4. Payment Completion

When a shopper has completed the payment, they are directed to a default result page. However, you may specify your
own result page in the Skin confguration. We append parameters to the resultURL to inform you of the status of the
payment. Just as you cryptographically signed the payment session when sending the shopper to us, we will use the same
shared secret to sign the data we return to you. In this way you can ensure that the data has not been tampered with.
Here is an example of a resultURL where the URL was set to: http://yourSite.com/pRes.jsp:
http://yourSite.com/pRes.jsp?merchantReference=Internet%20Order
%2012345&skinCode=4aD37dJA&shopperLocale=en_GB&authResult=AUTHORISED&pspReference=1211992213193029
&merchantSig=CPb2cObMxmIIE0khO8WhEYyKDJs%3D
The parameters that are passed back are:
authResult
The result of the payment. One of:
AUTHORISED
Payment authorisation was successfully completed.
REFUSED
Payment was refused / payment authorisation was unsuccessful.
CANCELLED
Payment attempt was cancelled by the shopper or the shopper requested to return to the merchant by
pressing the back button on the initial page.
PENDING
Final status of the payment attempt could not be established immediately. This can happen if the systems
providing fnal payment status are unavailable or the shopper needs to take further action to complete the
payment.
ERROR
An error occurred during the payment processing.
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. For PENDING, ERROR and CANCELLED results the
pspReference may not (yet) be known and will therefore be empty or not present.
merchantReference
This is the reference that you assigned to the original payment.
skinCode
The code of the Skin used to process the payment.
11 / 48
Integration Manual
merchantSig
The signature computed over the above values in Base64 encoded format. See Appendix C for details on
computing the signature.
paymentMethod
The payment method used. For CANCELLED results, the payment method may not be known and will therefore
not be present.
shopperLocale
The shopperLocale that you provided in the payment request.
merchantReturnData
If you set this feld in the payment session setup, the value will be passed back as-is.
This information is useful in constructing a custom result page and can integrate seamlessly with the shopper's session
on your server.
The moment the status of the payment is established we will also send you a server-to-server notifcation. This
notifcation is the recommended way to update the status of the payment in your back ofce. The notifcation system is
more reliable in its delivery because the resultURL method described above relies on the shopper's
browser/computer/internet connection, any of which could fail at any time. Please refer to section 7 for more information
regarding Notifcations.
Although we strongly recommend a fxed resultURL that is specifed in the Skin confguration, there may be situations
where it is desirable to set the result URL on a per-payment basis. To override the resultURL that is specifed in the Skin's
confguration, you will need to specify the URL in the payment session using the resURL parameter. The resURL parameter
does not need to be included in the signature.
Please note, Adyen cannot guarantee that all payment methods will work when using the resURL parameter. For
redirect payment methods, such as iDEAL, the request may have a limited size. If, with the resURL added, the size of
the request is too large, the payment can fail.
2.5. Error Handling

When an error condition occurs, there are some cases where Adyen cannot determine which Skin and language to use to
display the error message with. To enhance the shopper experience you have the option to include the following felds in
the URL that the shopper is directed to:
skinCode
The code of the Skin used.
shopperLocale
A combination of language code and country code to specify the language used in the session.
These felds are prepended to pay.shtml or select.shtml and separated by a forward slash resulting in the following format:
<skinCode>/pay.shtml or <skinCode>/<shopperLocale>/pay.shtml. These values will be used as a fallback when Adyen is
unable to determine the skin and language.
2.6. Billing Address Pre-Population and AVS

Address Verifcation Service (AVS) is a security feature that verifes the billing address of the card holder. It does so by
comparing the numeric portions of the card holder's registered billing address to those entered by the shopper. AVS is
only supported on a limited set of acquiring connections and only for a limited set of countries (United States, Great
Britain and Canada) and card types (MasterCard and Visa). AMEX supports AVS as an additional fraud check in all
countries that issue AMEX cards.
To enable AVS the Billing Address Fields (AVS) feld must be checked under Skin Options for each Skin you wish to use.
12 / 48
Integration Manual
You can choose to have the payment pages collect the billing address and/or pre-populate these values from your own
system. If you wish to pre-populate these felds you can add them to the payment session using the following parameters:
billingAddress.street
The street name.
billingAddress.houseNumberOrName
The house number (or name).
billingAddress.city
The city.
billingAddress.postalCode
The postal/zip code.
billingAddress.stateOrProvince
The state or province.
billingAddress.country
The countrycode in ISO 3166-1 alpha-2 format - see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for more
information.
billingAddressSig
A separate merchant signature that is required for these felds. The protocol and shared secret is the same as
the normal merchant signature, but for the following felds:
billingAddress.street + billingAddress.houseNumberOrName + billingAddress.city +
billingAddress.postalCode + billingAddress.stateOrProvince + billingAddress.country
You can specify whether the shopper is allowed to view and/or modify these personal details. For this the
billingAddressType can be specifed. Please note that the billingAddressType feld is part of the merchantSignature. Please
refer to Appendix C for more information regarding Computing the HMAC.
BillingAddressType
billingAddressType
Description
Not supplied
modifable / visible
unmodifable / visible
unmodifable / invisible
If you want to have the shopper enter the billing address on the payment pages you need to select the checkbox Billing
Address Fields (AVS) on the Skin edit page in the Adyen Customer Area (CA) and not supply a billingAddressType. Please
refer to the Adyen Skin Creation Manual for more details; this can be found here:
The billing address details are stored with the transaction and visible in the CA when either a billingAddressType is provided
or when Billing Address Fields (AVS) is confgured in the Skin.
2.7. Shopper Information

Shopper details can be sent to Adyen and be also encrypted using a signature.
These are the felds Adyen recognize as shopper information:
shopper.frstName
The shopper's frstname.
shopper.infx
The shopper infx.
shopper.lastName
13 / 48
Integration Manual
The shopper's lastname.
shopper.gender
The shopper's gender.
shopper.dateOfBirthDayOfMonth
The day of the month of the shopper's birth.
shopper.dateOfBirthMonth
The month of the shopper's birth.
shopper.dateOfBirthYear
The year of the shopper's birth.
shopper.telephoneNumber
The shopper's telephone number.
shopperType
This feld can be used if validation of the shopper felds is desired. If you are including shopperType in the
payment session, you will need to include the shopperSig. The following table describes the possible values:
shopperType
Description
Not supplied
Validation is not required (not included in the shopperSig)
unmodifable / visible
unmodifable / invisible
shopperSig (optional)
shopper.firstName + shopper.infix + shopper.lastName + shopper.gender +
shopper.dateOfBirthDayOfMonth + shopper.dateOfBirthMonth + shopper.dateOfBirthYear +
shopper.telephoneNumber
2.8. Using an iFrame

Whilst possible, the use of iFrames can introduce known usability, security and cross-browser issues. Please keep the
following in mind:
Some redirect payment methods, such as iDEAL, do not permit their pages to be viewed via an iFrame and will
break out of it. Other redirect payment methods may require more available screen space than your iFrame
permits. You should also be prepared to handle the diference in behaviour for the payment result URL, as once
the payment completes you may not be in an iFrame any more.
Another problem you may face is the browser's cookie policy. Cookies are required on the HPP; using an iFrame
means that the browser may impose restrictions regarding the conditions in which cookies are allowed to be set
within the iFrame. While there are workarounds for getting cookies accepted in the default confguration for
most browsers, the shopper may have confgured a more restrictive policy. The most common problem is with
the Safari (Apple) and Chrome (Google) browsers which require, by default, that the loading of the page in the
iFrame is user initiated. This means that frst the iFrame needs to be loaded with a page hosted at the parent
domain. Secondly, on this page the user needs to actively click on a button submitting the redirect to the Hosted
Payment Pages.
As a result Adyen cannot guarantee that all payment methods will work when using an iFrame, nor that the behaviour of a
payment method will remain the same. Furthermore, the exact operation of a redirect payment method can difer
between the TEST environment and the LIVE environment.
For more information on implementing iFrames in your environment please refer to the Adyen Skin Creation Manual
found here:
14 / 48
Integration Manual
2.9. Payment Methods

For some payment requests, you may decide to flter the payment methods that are displayed on the HPP or bypass the
HPP entirely. The allowedMethods feld is used to display specifc payment methods, the blockedMethods feld is used to
prevent specifc payment methods from being displayed, and the brandCode and issuerId felds are used take the
customer directly to specifc payment method.
All the payment methods that are confgured for your account, including the value you use to indicate the specifc
payment method, are available in the CA interface under Settings Payment Methods Name.
For the allowedMethods and blockedMethods felds you can use a group payment method value:
Payment Group name
value
Cards (includes all debit and credit cards)
card
Bank Transfers (from all countries)
bankTransfer
Some payment methods are not available in all countries. For example, iDEAL is only ofered if the shopper is from The
Netherlands. If the payment method selection is done on your website, and the allowedMethods parameter contains a
value for a payment method that is not available in all countries, we advise that you set the countryCode parameter. This
will ensure that the shopper only sees those payment methods that are relevant for their country. For example, if you set
allowedMethods to ideal you will have to set countryCode to NL to ensure that the iDEAL payment method is displayed.
The list of countries where a payment method is ofered is also available in the payment methods list in the CA interface
in the column Available Countries.
Please note, the list of payment methods on the TEST environment may difer from those on the LIVE environment. All
payment methods are not automatically confgured for the LIVE environment.
2.10.
Custom Payment Methods
Adyen ofers an option to display custom payment methods on the HPP. Please contact the Adyen Support Team
(support@adyen.com) to confgure custom payment methods for your Merchant Account.
The name of a custom payment method will always start with c_, for example c_invoice. The custom payment method
is displayed like all other payment methods on your HPP. This also means that you can add extra charges to the payment
method, change the display order, etc. Please refer to the Adyen Skin Creation Manual for more details about styling the
custom payment method on your HPP.
After a shopper has selected the custom payment method they are redirected to a static URL, which must be provided by
you during the setup of the custom payment method. The following parameters are passed back to this URL.
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.
merchantReference
This is the reference that you assigned to the original payment.
skinCode
The code of the Skin used to process the payment.
paymentAmount
The payment amount as specifed in your initial payment request.
currencyCode
The three character ISO currency code to pay in.
15 / 48
Integration Manual
additionalAmount (optional)
An additional amount when there are extra charges confgured for this custom payment method in your skin.
Similiar to the paymentAmount feld, the additionalAmount is specifed in minor units, without a decimal
separator.
customPaymentMethod
The Custom Payment Method used.
paymentMethod
The payment method used, this is the same value as customPaymentMethod.
merchantSig
The signature computed over the above values in Base64 encoded format. See Appendix C for details on
computing the signature.
merchantReturnData
If you set this feld in the payment session setup, the value will be passed back as-is.
The customPaymentMethod and paymentMethod parameters will contain the same value but both are in the URL to be
more consistent with the resultUrl. Given that there are extra felds in the custom payment URL the associated
merchantSig is also calculated diferently. Please refer to Appendix C for more details.
authResult is not one of the parameters because this is not known. It should be determined by the system that is behind
the redirect URL. After a shopper has selected the custom payment method the payment request will be stored in our
system with the status HandledExternally.
16 / 48
Integration Manual
3. CVC-Only Repeat Payments

If a signifcant portion of your business consists of returning shoppers you can use the CVC-Only functionality of the
Adyen Payment System to store the card details used by shoppers. Returning shoppers will have the option to pay using a
previously stored card by simply flling in the card's security code (CVC/CVV) and confrming the purchase.
3.1. Setting Up the Payment

The payment session is set up just like a regular payment. There are two previously optional felds which become
compulsory and one new feld which needs to be provided in the payment session form.
shopperEmail (required)
The shopper's email address.
shopperReference (required)
An ID that uniquely identifes the shopper.
recurringContract
Used to defne the type of recurring contract to be used. For CVC-Only payments the value ONECLICK should
be used.
<input type="hidden" name="shopperEmail" value="gras.shopper@somewhere.org" />

<input type="hidden" name="shopperReference" value="grasshopper52" />
<input type="hidden" name="recurringContract" value="ONECLICK" />
Please refer to Appendix C for more details on how to include these values in the signature.
The initial purchase will proceed just like a normal payment with a single exception, a checkbox will be displayed on the
HPP allowing the shopper to opt-out of having their details stored. For a subsequent payment, provided the shopper
didn't opt-out during the initial purchase, the shopper will see a graphic representation of their credit card with a blank
feld underneath in which to enter their card's security code (CVC/CVV).
Please note, shoppers are uniquely identifed using the shopperReference parameter. It is important that shoppers
are securely logged in to on your site and that they cannot modify the value of the shopperReference parameter.
17 / 48
Integration Manual
4. Testing
Adyen provides a number of card numbers and accounts for testing purposes. These can be found here:
https://support.adyen.com/index.php?/Knowledgebase/Article/View/11/0
4.1. Testing AVS Results

It is possible to test the 27 diferent AVS result codes. Set the street feld of the billingAddress element to the value Test
AVS result and specify the avsResult value that you want to test, in the houseNumberOrName feld. Note that all other
billingAddress felds are still required but their values do not impact the avsResult that is returned.
Please refer to Appendix L for the complete list of AVS result codes.
<input
<input
<input
<input
<input
<input
<input
<input
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="hidden"
name="billingAddress.city" value="TestCity" />

name="billingAddress.street" value="Test AVS result" />
name="billingAddress.houseNumberOrName" value="17" />
name="billingAddress.postalCode" value="1111" />
name="billingAddress.stateOrProvince" value="TestState" />
name="billingAddress.country" value="NL" />
name="billingAddressType" value="0" />
name="billingAddressSig" value="m+fDzztb/oMEO4BEGc4mvedlKHU=" />
Please note, when testing the AVS results it is important to ensure that you are using one of the AVS test card numbers
found here:
4.2. Testing CVC/CVV Results

It is possible to test the 7 diferent CVC/CVV result codes. When you are on the HPP you will need to enter the code you
want to simulate with a prefx of 00. For example, if you want to test the 2 Doesn't match result, you will need to
enter 002 in the CVV feld on the HPP.
Please refer to Appendix E for the complete list of CVC/CVV result codes.
Please note, when testing the CVC/CVV results it is important to ensure that you are using one of the test card numbers
that requires a CVC found here:
4.3. Testing Error Codes

It is possible to test Refused transactions and their specifc Refusal reasons by placing the following text in the Card
Holder Name:
[Response code] : [The refusal reason raw String that is tested]
For example:
DECLINED : 05 : ISSUER_UNAVAILABLE
Other response codes that are available for testing are:
REFERRAL
ERROR
BLOCK_CARD
CARD_EXPIRED
DECLINED
INVALID_AMOUNT
18 / 48
Integration Manual
INVALID_CARD
NOT_SUPPORTED
NOT_3D_AUTHENTICATED
NOT_ENOUGH_BALANCE
APPROVED
Please note:
There is a limit in characters of the Card Holder Name. The result may be:
DECLINED : 05 : ISSUER_UNAVAIL
You may have to lower the risk score for non-alphabetic characters in the card holder name as the ':' character
will trigger this check and may cause the payment to be declined with reason code "FRAUD".
An incorrect CVC or invalid expiry date will override the response code and always lead to a generic
"DECLINE".
19 / 48
Integration Manual
5. Modifcations
In this section we will describe the possible modifcation actions. It is possible to perform modifcations using your
account on the Adyen CA. However, we recommend automating this if you are processing more than a handful of
payments daily. For this we ofer a SOAP and REST web service which accepts the modifcation requests from your
backofce systems. To submit modifcation messages you must supply authentication credentials. The username is
ws@Company.[YourCompanyAccount] and you set the password for this user in the CA under Settings Users.
Please note, for all modifcation requests Adyen will respond with a message appropriate to the modifcation type such
as captureReceived, cancelReceived or refundReceived. This message is an acknowledgment of your modifcation
request, it does not signify that the payment was actually modifed. Once your request has been processed you will
receive a notifcation informing you whether or not the modifcation was successful.
It is important to respect the DNS Time-To-Live (TTL) when communicating with Adyen. Some frameworks, Java in
particular, cache DNS lookups by default. Adyen routinely changes their DNS confguration and, if your implementation
caches the DNS lookup, your ability to submit modifcations and/or payments may be impacted.
SOAP
SOAP is a communication protocol between two web services that uses XML for its message format. While you are free to
choose your preferred method of integration, SOAP/REST, in most cases we recommend that you implement a SOAP
integration to Adyen; SOAP implementations automatically handle a number of edge cases around encoding and
validation that will result in a more robust integration. You should use a SOAP toolkit to generate your SOAP requests.
SOAP is also benefcial for high volume merchants particularly with regards to notifcations; if there are many pending
notifcations, the SOAP format allows Adyen to transfer multiple notifcations in a single message. As such, when
compared to REST messages, SOAP notifcations reduce the number of requests and improve throughput. Please refer to
section 7 for more details regarding notifcation processing.
REST
Representational State Transfer (REST) is an architecture style for designing networked applications. The idea being that,
rather than using complex mechanisms such as CORBA, RPC or SOAP to connect machines, simple HTTP with name/value
pairs is used to make calls between machines, in much the same way that web browsers transfer requests between the
user and a web server. For example, a URL with the possibility of diferent parameters.
https://www.google.com/search?q=adyen
https:// indicates the secure HTTP protocol variant
www.google.com/search is the address of the platform/service
?q=adyen is a variable Name (q) / Value (adyen) pair that lets the service know information about adyen needs
to be queried and returned to the requesting service
An important component of REST is that it is stateless in nature. Each request from client to server must contain all of the
information necessary to understand the request, and cannot take advantage of any stored context on the server. Session
state is therefore kept entirely to the client.
5.1. Capture
In order to capture an authorised payment, you send a modifcation request to the capture action using the following
felds.
Please note, this is only applicable to payment methods that support separate authorisations and captures. You can
specify your capture delay via the CA Settings Merchant Setting Capture Delay.
merchantAccount
The merchant account used to process the payment.
20 / 48
Integration Manual
modifcationAmount
The amount to capture. This consists of a currency and a value which is the amount in minor units. Please refer
to section 2.2 for more information. The currency must match that of the original payment request, and the
value must be less than or equal to the authorised amount.
originalReference
This is the pspReference that was assigned to the authorisation. You will have received it with the payment
status or the authorisation notifcation.
reference (optional)
If you wish, you can to assign your own reference or description to the modifcation. The reference is visible in
the Merchant Backofce and in the reporting.
If the message was syntactically valid and the merchantAccount is correct you will receive a captureReceived response with
the following felds:
pspReference
This is a new unique reference that Adyen has associated with the modifcation request. This is guaranteed to be
globally unique.
response
The response. If successful, this will be [capture-received]. If there is an error, we will return a SOAP Fault.
In most cases the fnal result of the capture is sent via a notifcation with the eventCode CAPTURE. The pspReference of
this notifcation is the same as the pspReference in the SOAP response. The success feld indicates if the capture was
successful, true, or not, false. If false, the reason feld of the notifcation will give a short description why. For some
payment methods, where the capture process is handled ofine, we may subsequently receive a failure. In this situation
we will send you a notifcation with the eventCode CAPTURE_FAILED. The pspReference of this notifcation is the same as
the pspReference in the SOAP response. The success feld will have a value of true.
The Adyen CA provides the option to confgure an automated capture process, capturing payments automatically after a
confgured number of days, ranging from immediate up to 14 days.
Please refer to Appendix D for a sample SOAP capture modifcation request and response.
Please refer to Appendix E for a sample REST capture modifcation request and response.
5.2. Cancel
Similar to the capture modifcation, in order to cancel an authorised payment you send a modifcation request to the
cancel action using the following felds.
Please note, this is only applicable to payment methods that support separate authorisations and captures.
merchantAccount
originalReference
If the message was syntactically valid and the merchantAccount is correct you will receive a cancelReceived response with
21 / 48
Integration Manual
pspReference
globally unique.
response
The response. If successful, this will be [cancel-received]. If there is an error, we will return a SOAP Fault.
The fnal result of the cancellation is sent via a notifcation with the eventCode CANCELLATION. The pspReference of this
notifcation is the same as the pspReference in the SOAP response. The success feld indicates if the cancellation was
successful, true or not, false. If false, the reason feld of the notifcation will give a short description why.
Please refer to Appendix F for a sample SOAP cancel modifcation request and response.
Please refer to Appendix G for a sample REST cancel modifcation request and response.
5.3. Refund
A refund is initiated by sending a modifcation request using the refund action using the following felds:
merchantAccount
modifcationAmount
The amount to refund. This consists of a currency and a value which is the amount in minor units. Please refer
to section 2.2 for more information. The currency must match that of the original payment request, and the
value must be less than or equal to the authorised amount.
originalReference
If the message was syntactically valid and the merchantAccount is correct you will receive a refundReceived response with
pspReference
globally unique.
response
The response. If successful, this will be [refund-received]. If there is an error, we will return a SOAP Fault.
In most cases the fnal result of the refund is sent via a notifcation with the eventCode REFUND. The pspReference of this
notifcation is the same as the pspReference in the SOAP response. The success feld indicates if the refund was successful,
true or not, false. If false, the reason feld of the notifcation will give a short description why. For some payment
methods, where the refund process is handled ofine, we may subsequently receive a failure. In this situation we will
send you a notifcation with the eventCode REFUND_FAILED. The pspReference of this notifcation is the same as the
pspReference in the SOAP response. The success feld will have a value of true.
Please refer to Appendix H for a sample SOAP refund modifcation request and response.
Please refer to Appendix I for a sample REST refund modifcation request and response.
22 / 48
Integration Manual
5.4. Cancel or Refund

If you do not know if a payment has been captured but you want to reverse the authorisation you can send a modifcation
request to the cancelOrRefund action using the following felds:
merchantAccount
originalReference
If the message was syntactically valid and the merchantAccount is correct you will receive a cancelOrRefundReceived
response with the following felds:
pspReference
globally unique.
response
The response. If successful, this will be [cancelOrRefund-received]. If there is an error, we will return a SOAP Fault.
If the payment is authorised, but not yet captured, it will be cancelled. For those payment methods that do not support
cancellations, the transaction will be refunded in full.
If the request resulted in a cancellation, the fnal result is sent via a notifcation with the eventCode CANCELLATION. The
pspReference of this notifcation is the same as the pspReference in the SOAP response. The success feld indicates if the
cancellation was successful, true or not, false. If false, the reason feld will give a short description why.
If the request resulted in a refund, the fnal result is sent via a notifcation with the eventCode REFUND. The pspReference
of this notifcation is the same as the pspReference in the SOAP response. The success feld indicates if the refund was
successful, true or not, false. If false, the reason feld will give a short description why.
If the request fails a notifcation is sent with the eventCode CANCEL_OR_REFUND. WITH SUCCESS=FALSE The pspReference
of this notifcation is the same as the pspReference in the SOAP response. The success feld will contain the value false to
indicate that the request failed and the reason feld will give a short description why.
Please refer to Appendix J for a sample SOAP cancelOrRefund modifcation request and response.
Please refer to Appendix K for a sample REST cancelOrRefund modifcation request and response.
23 / 48
Integration Manual
6. API Fault Codes

In the following situations the Adyen platform does not accept or store a submitted request:
If the request does not pass validation.
If the request violates a security constraint.
If the request confguration constraint.
Instead you will receive a SOAP Fault which will contain a description of the problem. Generally this will be handled as an
Exception in your SOAP toolkit.
If the modifcation was rejected a faultstring is returned that adheres to the following syntax:
<faultstring> ::= <type> ' ' <message>
<type> ::= 'validation' | 'security' | 'confguration' | 'internal'
<message> ::= unicode
SOAP Example:
<?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/XMLSchemainstance">
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>security 901 Invalid Merchant Account</faultstring>
</soap:Fault>
</soap:Body>
</soap:Envelope>
REST Example:
HTTP/1.1 500 Internal Server Error
security 901 Invalid Merchant Account
Please refer to Appendix H for a list of the error codes and messages.
24 / 48
Integration Manual
7. Notifcations
Whenever a payment is made, a modifcation is processed or when a report is available for download, we will notify you
of the event and whether or not it was performed successfully. Notifcations should be used to keep your backofce
systems up to date with the status of each payment and modifcation.
Notifcations are sent using either a SOAP call or using HTTP POST parameters to a server, that you host, that will receive
and accept the notifcations. We provide code examples in common programming languages for this, please refer to the
link in the Introduction. Your system should be able to handle requests/responses which contain additional felds and
duplicate notifcations for the same transaction.
Due to the nature of the Adyen platform, an AUTHORISATION notifcation may be sent twice. The front end systems (HPP)
will attempt to send the notifcation as soon as the payment is made. However our front-end systems do not register if
this notifcation is received successfully by your servers. This is done on a central application and hardware instance
which updates the accounting journal entries for each transaction. This system not only sends at least one notifcation, it
also records whether or not it was successfully received, this is determined by your server responding to the notifcation
with a message indicating that the notifcation has been [accepted]. Please refer to section 7.2 for more details regarding
accepting notifcations.
Notifcations will be resent if their delivery has failed or if the delivery is uncertain. This at-least-once delivery rule implies
that you may receive the same notifcation twice. A duplicate notifcation is one where the eventCode and pspReference
felds are the same. If a duplicate is received with the success feld set to true it overrules the previous notifcation. In all
other cases you do not need to act on duplicate notifcations.
Notifcation settings are confgured in the Adyen CA. You can set the method (HTTP POST/SOAP), URL to submit to, and
user name/password for HTTP Basic authentication. Default HTTP (TCP port 80) and HTTPS (TCP port 443) are allowed, as
well as extra TCP ports 8080, 8888 (for HTTP) and 8443, 8843 (for HTTPS) if needed.
Please note, you will only receive a CAPTURE notifcation for CAPTURE requests submitted via your web service or the
CA. This does not include automatic captures initiated by the Adyen platform.
7.1. Notifcation Message Fields

A notifcation contains the following felds for each transaction that it references:
live
boolean (true/false) indicating if the notifcation originated from the LIVE or TEST payment systems.
eventCode
The event type of the notifcation. The most common values include:
Normal Payment Events
AUTHORISATION.
Modifcation Payment Events
CANCELLATION.
REFUND.
CANCEL_OR_REFUND.
CAPTURE.
REFUNDED_REVERSED.
Please note that the success feld in a REFUNDED_REVERSED notifcation will always be set to false.
CAPTURE_FAILED.
REFUND_FAILED.
Dispute Events
25 / 48
Integration Manual
REQUEST_FOR_INFORMATION.
NOTIFICATION_OF_CHARGEBACK.
ADVICE_OF_DEBIT.
CHARGEBACK.
CHARGEBACK_REVERSED.
For more information about Disputes please refer to the Merchant Manual.
Please note that the success feld in a CHARGEBACK_REVERSED notifcation will always be set to true.
Other Events
REPORT_AVAILABLE.
For more information please refer to the Adyen Reporting Manual.
Please note, it is important that you do not code your acceptance of notifcations to these specifc eventCodes as we
may add additional eventCodes in the future.
For specialised applications, such as recurring payments, other values are possible. Please note, Adyen may add new
codes at any time and, as such, your listening service should not be coded to expect a fxed set of values.
pspReference
The unique reference that Adyen assigned to the payment or modifcation.
originalReference
If this is a notifcation for a modifcation request this will be the pspReference that was originally assigned to the
authorisation, for a payment it will be blank.
merchantReference
This is the reference you assigned to the original payment.
merchantAccountCode
The merchant Account the payment or modifcation was processed with.
eventDate
The time the event was generated.
success
Whether or not the event succeeded (boolean true/false).
paymentMethod
The payment method used, this is only populated for an AUTHORISATION. e.g. visa, mc, ideal, elv, wallie, etc.
operations
This feld displays the modifcation operations supported by this payment as a list of strings, this is only
populated for AUTHORISATION notifcations. The operations will inform you whether you need to capture the
payment (if you don't have auto-capture set up), whether you can cancel the payment (before capture) or if you
can refund the payment (after it has been captured). Values include:
CAPTURE.
REFUND.
CANCEL.
For HTTP POST notifcations, the operations are sent as a single comma-separated string.
reason
Text feld with information depending on whether the result is successful or not. For AUTHORISATION events with
the success feld set to true and a payment method of visa, mc or amex this feld contains the authorisation
code, the last 4 digits of the card, and the expiry date in the following format:
6 digit Authorisation Code:Last 4 digits:Expiry Date. For example, e.g. 874574:1935:11/2012.
When the success feld is set to false it gives a reason as to why it was refused. For REPORT_AVAILABLE it contains
26 / 48
Integration Manual
the URL where the report can be downloaded from.
amount
The amount, if applicable, associated with the payment or modifcation. This consists of a currencyCode and a
value which is the amount in minor units. For HTTP POST notifcations, you will receive the currency and value as
parameters.
For SOAP notifcations a notifcation message is a container for an array of notifcation items, meaning that you may
receive multiple notifcations within a single message. Please refer to Appendix M for a sample SOAP notifcation and
response. Please refer to Appendix N for a sample REST notifcation and response.
Please note that the eventCode AUTHORISATION does not necessarily mean that the authorisation is successful. The
authorisation is successful if the success feld has the value true. In case of an error or a refusal, it will be false and the
reason feld should be consulted for the cause of the authorisation failure.
7.2. Accepting Notifcations

The Adyen notifcation system requires a response within 30 seconds of receipt of the notifcation, the server is expecting
a response of [accepted], including the brackets. When our systems receive this response all notifcations contained in the
message are marked as successfully sent. It is important that Adyen receives the [accepted] message within 30 seconds
and that this process is not interrupted by any errors in processing the notifcation. As such, we recommend that the
acceptance of notifcations is handled separately from the processing of the notifcations, and that an [accepted]
response is generated when a notifcation has been stored. Please refer to Appendix M for a SOAP notifcation and
response. Please refer to Appendix N for a sample REST notifcation and response.
The URL to send the SOAP notifcation messages to and the authentication are confgurable in the Adyen CA. There is also
a testing facility that you can use to verify that your server is able to correctly receive the notifcations coming from the
Adyen systems.
Please note that if you receive a notifcation which you cannot handle, either because the original transaction is not
recognised or because the eventCode is unknown, you should accept the message and store, or at least log, the item. Not
accepting the message may cause our system to halt sending notifcations.
7.3. Retrying Notifcations

Notifcations will be resent if their delivery has failed or if the delivery is uncertain. They are resent at the following
durations:
5 minutes
10 minutes
15 minutes
30 minutes
1 hour
2 hours
4 hours
8 hours
A system message is placed on the CA after the 3rd unsuccessful attempt, i.e. after 5 + 10 + 15 minutes.
The system will continue to retry every 8 hours until 7 days have passed.
If you wish to trigger a resend attempt, you may send yourself a test notifcation via the CA at Settings Notifcations.
If it is successful all the queued notifcations will be resent. Otherwise you will be advised of the current errors our system
is recording.
27 / 48
Integration Manual
Appendix A: TEST and LIVE URLs

TEST URLs
Adyen Customer Area (CA)
https://ca-test.adyen.com/
Hosted Payment Pages (Multiple):
https://test.adyen.com/hpp/select.shtml
Hosted Payment Pages (Single):
https://test.adyen.com/hpp/pay.shtml
Directory Lookup:
https://test.adyen.com/hpp/directory.shtml
Modifcation SOAP Service
https://pal-test.adyen.com/pal/servlet/soap/Payment
Modifcation SOAP Service WSDL
https://pal-test.adyen.com/pal/Payment.wsdl
Notifcation SOAP Service WSDL
https://ca-test.adyen.com/ca/services/Notifcation?wsdl
LIVE URLs
Adyen Customer Area (CA)
https://ca-live.adyen.com/
Hosted Payment Pages (Multiple):
https://live.adyen.com/hpp/select.shtml
Hosted Payment Pages (Single):
https://live.adyen.com/hpp/pay.shtml
Directory Lookup:
https://live.adyen.com/hpp/directory.shtml
Modifcation SOAP Service
https://pal-live.adyen.com/pal/servlet/soap/Payment
Modifcation SOAP Service WSDL
https://pal-live.adyen.com/pal/Payment.wsdl
Notifcation SOAP Service WSDL
https://ca-live.adyen.com/ca/services/Notifcation?wsdl
28 / 48
Integration Manual
Appendix B: JSON Response To Directory Lookup

{
"paymentMethods" : [
{
"brandCode" : "paypal",
"name" : "PayPal"
},
{
"brandCode" : "ideal",
"name" : "iDEAL",
"issuers" : [
{
"name" : "Test Issuer 7",
"issuerId" : "1156"
},
{
"issuerId" : "1155"
},
{
"issuerId" : "1158"
},
{
"issuerId" : "1157"
},
{
"issuerId" : "1159"
},
{
"name" : "Test Issuer",
"issuerId" : "1121"
},
{
"issuerId" : "1153"
},
{
"issuerId" : "1154"
},
{
"issuerId" : "1151"
},
{
"name" : "Test Issuer Refused",
"issuerId" : "1160"
},
{
"issuerId" : "1152"
},
29 / 48
Integration Manual
{
"name" : "Test Issuer Pending",
"issuerId" : "1161"
},
{
"name" : "Test Issuer Cancelled",
"issuerId" : "1162"
}
]
},
{
"brandCode" : "mc",
"name" : "MasterCard"
},
{
"brandCode" : "visa",
"name" : "VISA"
}
]
}
30 / 48
Integration Manual
Appendix C: Computing the HMAC

The signature is computed using the HMAC algorithm with the SHA-1 hashing function3. The data passed, in the form
felds, is concatenated into a string, referred to as the signing string. The HMAC signature is then computed over using a
key that is specifed in the Skin settings. The signature is passed along with the form data and once Adyen receives it, we
use the key to verify that the data has not been tampered with in transit. The signing string should be packed into a binary
format containing hex characters, and then base64 encoded for transmission. We have coded a detailed example for your
review that can be found here:
https://github.com/adyenpayments/php/blob/master/1.HPP/create-payment-on-hpp-advanced.php
We use HMAC signing for setting up the payment in our systems and you should use it to verify the payment result when
the shopper returns to your site.
Payment Setup
When setting up a payment the signing string is as follows:
paymentAmount + currencyCode + shipBeforeDate + merchantReference + skinCode + merchantAccount +
sessionValidity + shopperEmail + shopperReference + recurringContract + allowedMethods +
blockedMethods + shopperStatement + merchantReturnData + billingAddressType + deliveryAddressType +
shopperType + offset
The order of the felds must be exactly as described above. If you are not using one of the felds, such as allowedMethods,
the value for this feld in the signing string is an empty string. The deliveryAddressType feld is only necessary when using
the openinvoice payment method. Please see the Open Invoice Manual for more details:
https://support.adyen.com/index.php?/Knowledgebase/List/Index/101/documentation
The example in section 2.1.2 would provide us with the following signing string:
10000GBP2007-10-20Internet Order 123454aD37dJATestMerchant2007-10-11T11:00:00Z
If the shared secret is Kah942*$7sdp0), the resulting base64 encoded signature is:
x58ZcRVL1H6y+XSeBGrySJ9ACVo=
Special care needs to be taken if the signing string contains any line breaks. According to the W3C HTML 4 Specifcation 4
when submitting forms, line breaks are represented as "CR LF" pairs, i.e., '\r\n'.
If felds use a single "LF" character as a line break some browsers will convert this to a "CR LF" pair. We have no way of
detecting if this conversion has taken place. This means the signing string you are using will be diferent from the signing
string we will be receiving. As a precaution, you should change all line breaks to a "CR LF" pair when composing the
signing string.
Test HMAC Calculation

If you are having trouble with the merchant signature you can check your HMAC calculation in the Adyen CA. You can
enter the payment session felds and check if your merchant signature matches the merchant signature computed by
Adyen. You can also check your HMAC calculation by submitting a payment request to https://catest.adyen.com/ca/ca/skin/checkhmac.shtml. In addition to the regular payment felds you can also submit the signing
string in the signingString feld.
Please note, you must be logged in to the CA in order for the checkhmac to work.
Please refer to: http://en.wikipedia.org/wiki/Hmac for more information.

Please refer to: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4
31 / 48
Integration Manual
Payment Result
The payment result uses the following signature string:
authResult + pspReference + merchantReference + skinCode + merchantReturnData
The example from section 2.1.2 would provide us with the following signing string.
AUTHORISED1211992213193029Internet Order 123454aD37dJA
If the shared secret is Kah942*$7sdp0), the resulting signature is (base64 encoded):

ytt3QxWoEhAskUzUne0P5VA9lPw=
Please note, shopperLocale is passed as a parameter but is not used in the signing string.
Custom Payment Method Redirect

The redirect of the Custom Payment Method uses the following signature string:
pspReference + merchantReference + skinCode + paymentAmount + currencyCode + additionalAmount
+ customPaymentMethod + merchantReturnData
The order of the felds must be exactly as described above. If one of the felds, such as additionalAmount, is not set, then
the value for this feld in the signing string is an empty string.
32 / 48
Integration Manual
Appendix D: SOAP Modifcation Request and Response Capture

Modifcation Request
<soap:Body>
<ns1:capture xmlns:ns1="http://payment.services.adyen.com">
<ns1:modificationRequest>
<merchantAccount xmlns="http://payment.services.adyen.com">YourMerchant</merchantAccount>
<modificationAmount xmlns="http://payment.services.adyen.com">
<currency xmlns="http://common.services.adyen.com">EUR</currency>
<value xmlns="http://common.services.adyen.com">500</value>
</modificationAmount>
<originalReference
xmlns="http://payment.services.adyen.com">8313547924770610</originalReference>
<reference xmlns="http://payment.services.adyen.com">YourModificationReference</reference>
</ns1:modificationRequest>
</ns1:capture>
</soap:Body>
</soap:Envelope>
Modifcation Response
<soap:Body>
<ns1:captureResponse xmlns:ns1="http://payment.services.adyen.com">
<ns1:captureResult>
<pspReference
xmlns="http://payment.services.adyen.com">NewCapturePspReference</pspReference>
<response xmlns="http://payment.services.adyen.com">[capture-received]</authCode>
</ns1:captureResult>
</ns1:captureResponse>
</soap:Body>
</soap:Envelope>
33 / 48
Integration Manual
Appendix E: REST Modifcation Request and Response Capture

Modifcation Request
modificationRequest.merchantAccount=SupportAdyenTest&action=Payment.capture&modificationRequest.or
iginalReference=8513939253477759&modificationRequest.reference=test1234&modificationRequest.modifi
cationAmount.currency=EUR&modificationRequest.modificationAmount.value=1234
modificationResult.pspReference=8813939274346857&modificationResult.response=%5Bcapture-received
%5D
34 / 48
Integration Manual
Appendix F: SOAP Modifcation Request and Response Cancel

Modifcation Request
<soap:Body>
<ns1:cancel xmlns:ns1="http://payment.services.adyen.com">
<originalReference
</ns1:cancel>
</soap:Body>
</soap:Envelope>
<soap:Body>
<ns1:cancelResponse xmlns:ns1="http://payment.services.adyen.com">
<ns1:cancelResult>
<pspReference
xmlns="http://payment.services.adyen.com">NewCancelPspReference</pspReference>
<response xmlns="http://payment.services.adyen.com">[cancel-received]</authCode>
</ns1:cancelResult>
</ns1:cancelResponse>
</soap:Body>
</soap:Envelope>
35 / 48
Integration Manual
Appendix G: REST Modifcation Request and Response Cancel

Modifcation Request
modificationRequest.merchantAccount=SupportAdyenTest&modificationRequest.reference=test1234&action
=Payment.cancel&modificationRequest.originalReference=7913939284323855
modificationResult.pspReference=7913939287424924&modificationResult.response=%5Bcancel-received%5D
36 / 48
Integration Manual
Appendix H: SOAP Modifcation Request and Response Refund

Modifcation Request
<soap:Body>
<ns1:refund xmlns:ns1="http://payment.services.adyen.com">
<modificationAmount xmlns="http://payment.services.adyen.com">
</modificationAmount>
<originalReference
</ns1:refund>
</soap:Body>
</soap:Envelope>
<soap:Body>
<ns1:refundResponse xmlns:ns1="http://payment.services.adyen.com">
<ns1:refundResult>
<pspReference
xmlns="http://payment.services.adyen.com">NewCapturePspReference</pspReference>
<response xmlns="http://payment.services.adyen.com">[refund-received]</authCode>
</ns1:refundResult>
</ns1:refundResponse>
</soap:Body>
</soap:Envelope>
37 / 48
Integration Manual
Appendix I: REST Modifcation Request and Response Refund

Modifcation Request
modificationRequest.merchantAccount=SupportAdyenTest&action=Payment.refund&modificationRequest.ori
ginalReference=8513939253477759&modificationRequest.reference=test1234&modificationRequest.modific
ationAmount.currency=EUR&modificationRequest.modificationAmount.value=1234
modificationResult.pspReference=7913939278088951&modificationResult.response=%5Brefund-received%5D
38 / 48
Integration Manual
Appendix J: SOAP Modifcation Request and Response CancelOrRefund

Modifcation Request
<soap:Body>
<ns1:cancelOrRefund xmlns:ns1="http://payment.services.adyen.com">
<originalReference
</ns1:cancelOrRefund>
</soap:Body>
</soap:Envelope>
<soap:Body>
<ns1:cancelOrRefundResponse xmlns:ns1="http://payment.services.adyen.com">
<ns1:cancelOrRefundResult>
<pspReference
xmlns="http://payment.services.adyen.com">NewCancelOrRefundPspReference</pspReference>
<response xmlns="http://payment.services.adyen.com">[cancelOrRefund-received]</authCode>
</ns1:cancelOrRefundResult>
</ns1:cancelOrRefundResponse>
</soap:Body>
</soap:Envelope>
39 / 48
Integration Manual
Appendix K: REST Modifcation Request and Response CancelOrRefund

Modifcation Request
modificationRequest.merchantAccount=SupportAdyenTest&modificationRequest.reference=test1234&action
=Payment.cancelOrRefund&modificationRequest.originalReference=8613939281189367
modificationResult.pspReference=8613939284241702&modificationResult.response=%5BcancelOrRefundreceived%5D
40 / 48
Integration Manual
Appendix L: CVC/CVV and AVS Result Values

CVC/CVV Result Values
0
Unknown
Matches
Doesn't match
Not checked
No CVC/CVV provided, but was required
Issuer not certifed for CVC/CVV
No CVC/CVV provided
AVS Result
0
Unknown
Address matches, postal code doesn't
Neither postal code nor address match
AVS unavailable
AVS not supported for this card type
No AVS data provided
Postal code matches, address doesn't match
Both postal code and address match
Address not checked, postal code unknown
Address matches, postal code unknown
10
Address doesn't match, postal code unknown
11
Postal code not checked, address unknown
12
Address matches, postal code not checked
13
Address doesn't match, postal code not checked
14
Postal code matches, address unknown
15
Postal code matches, address not checked
16
Postal code doesn't match, address unknown
17
Postal code doesn't match, address not checked
18
Neither postal code nor address were checked
19
Name and postal code matches
20
Name, address and postal code matches
21
Name and address matches
22
Name matches
23
Postal code matches, name doesn't match
24
Both postal code and address matches, name doesn't match
25
Address matches, name doesn't match
26
Neither postal code, address nor name matches
41 / 48
Integration Manual
Appendix M: SOAP Notifcation Request and Response

SOAP Notifcation Request
<soap:Body>
<ns1:sendNotification xmlns:ns1="http://notification.services.adyen.com">
<ns1:Notification>
<live xmlns="http://notification.services.adyen.com">false</live>
<notificationItems xmlns="http://notification.services.adyen.com">
<NotificationRequestItem>
<additionalData xsi:ns1="true"/>
<amount>
</amount>
<eventCode>AUTHORISATION</eventCode>
<eventDate>2009-01-01T01:02:01.111+02:00</eventDate>
<merchantAccountCode>YourMerchantAccount</merchantAccountCode>
<merchantReference>YourMerchantReference1</merchantReference>
<operations>
<string>CANCEL</string>
<string>CAPTURE</string>
<string>REFUND</string>
</operations>
<originalReference xsi:ns1="true"/>
<paymentMethod>visa</paymentMethod>
<pspReference>8888777766665555</pspReference>
<reason>01234:1111:12/2012</reason>
<success>true</success>
</NotificationRequestItem>
<NotificationRequestItem>
<additionalData xsi:ns1="true"/>
<amount>
</amount>
<eventCode>AUTHORISATION</eventCode>
<eventDate>2009-01-01T01:01:01.111+02:00</eventDate>
<merchantAccountCode>YourMerchantAccount</merchantAccountCode>
<merchantReference>YourMerchantReference2</merchantReference>
<operations>
<string>CANCEL</string>
<string>CAPTURE</string>
<string>REFUND</string>
</operations>
<originalReference xsi:ns1="true"/>
<paymentMethod>mc</paymentMethod>
<pspReference>8888777766665556</pspReference>
<reason>56789:1111:12/2012</reason>
<success>true</success>
</NotificationRequestItem>
</ns1:Notification>
</ns1:sendNotification>
</soap:Body>
</soap:Envelope>
42 / 48
Integration Manual
SOAP Notifcation Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns1:sendNotificationResponse xmlns:ns1="http://notification.services.adyen.com"
xmlns:ns2="http://common.services.adyen.com">
<notificationResponse>[accepted]</notificationResponse>
</ns1:sendNotificationResponse>
</soap:Body>
</soap:Envelope>
43 / 48
Integration Manual
Appendix N: REST Notifcation Request and Response

REST Notifcation Request
eventDate=2012-0925T13%3A41%3A33.81Z&reason=2120%3A1111%3A12%2F2012&originalReference=&merchantReference=reference_
415579&currency=EUR&pspReference=8613485804662747&merchantAccountCode=TestMerchant&eventCode=AUTHO
RISATION&value=24205&operations=CANCEL%2CCAPTURE%2CREFUND&success=true&paymentMethod=mc&live=false
REST Notifcation Response

notificationResponse=&sBaccepted%5D
44 / 48
Integration Manual
Appendix O: Fault Codes

Error Code
Fault
000
Unknown
010
Not allowed
100
No amount specifed
101
Invalid card number
102
Unable to determine variant
103
CVC is not the right length
104
Billing address problem
105
Invalid paRes from issuer
106
This session was already used previously
107
Recurring is not enabled
108
Invalid bankaccount number
109
Invalid variant
110
BankDetails missing
111
Invalid BankCountryCode specifed
112
This bank country is not supported
113
No InvoiceLines provided
114
Received a incorrect InvoiceLine
115
Total amount is not the same as the sum of the lines
116
Invalid date of birth
117
Invalid billing address
118
Invalid delivery address
119
Invalid shopper name
120
ShopperEmail is missing
121
ShopperReference is missing
122
PhoneNumber is missing
123
The PhoneNumber should be mobile
124
Invalid PhoneNumber
125
Invalid recurring contract specifed
126
Bank Account or Bank Location Id not valid or missing
127
Account holder missing
128
Card Holder Missing
129
Expiry Date Invalid
130
Reference Missing
131
Billing address problem (City)
132
Billing address problem (Street)
45 / 48
Integration Manual
Error Code
Fault
133
Billing address problem (HouseNumberOrName)
134
Billing address problem (Country)
135
Billing address problem (StateOrProvince)
136
Failed to retrieve OpenInvoiceLines
137
Invalid amount specifed
138
Unsupported currency specifed
139
Recurring requires shopperEmail and shopperReference
140
Invalid expiryMonth[1..12] / expiryYear[>2000], or before now
141
Invalid expiryMonth[1..12] / expiryYear[>2000]
142
Bank Name or Bank Location not valid or missing
143
Submitted total iDeal merchantReturnUrl length is {0}, but max size is {1} for this request
144
Invalid startMonth[1..12] / startYear[>2000], or in the future
145
Invalid issuer countrycode
146
Invalid social security number
147
Delivery address problem (City)
148
Delivery address problem (Street)
149
Delivery address problem (HouseNumberOrName)
150
Delivery address problem (Country)
151
Delivery address problem (StateOrProvince)
152
Invalid number of installments
153
Invalid CVC
154
No additional data specifed
155
No acquirer specifed
156
No authorisation mid specifed
157
No felds specifed
158
Required feld {0} not specifed
159
Invalid number of requests
160
Not allowed to store Payout Details
161
Invalid iban
162
Inconsistent iban
163
Invalid bic
170
Generation Date required but missing
171
Unable to parse Generation Date
172
Encrypted data used outside of valid time period
173
Unable to load Private Key for decryption
174
Unable to decrypt data
175
Unable to parse JSON data
46 / 48
Integration Manual
Error Code
Fault
180
Invalid shopperReference
181
Invalid shopperEmail
182
Invalid selected brand
183
Invalid recurring contract
184
Invalid recurring detail name
185
Invalid additionalData
186
Missing additionalData feld
187
Invalid additionalData feld
188
Invalid pspEchoData
600
No InvoiceProject provided
601
No InvoiceBatch provided
602
No creditorAccount specifed
603
No projectCode specifed
604
No creditorAccount found
605
No project found
606
Unable to create InvoiceProject
607
InvoiceBatch already exists
608
Unable to create InvoiceBatch
609
InvoiceBatch validity period exceeded
690
Error while storing debtor
691
Error while storing invoice
692
Error while checking if invoice already exists for creditorAccount
693
Error while searching invoices
694
No Invoice Confguration confgured for creditAccount
695
Invalid Invoice Confguration confgured for creditAccount
800
Contract not found
801
Too many PaymentDetails defned
802
Invalid contract
803
PaymentDetail not found
804
Failed to disable
805
RecurringDetailReference not available for provided recurring-contract
806
No applicable contractTypes left for this payment-method
901
Invalid Merchant Account
902
Shouldn't have gotten here without a request!
903
Internal error
904
Unable To Process
905
Payment details are not supported
47 / 48
Integration Manual
Error Code
Fault
906
Invalid Request: Original pspReference is invalid for this environment!
950
Invalid AcquirerAccount
951
Confguration Error (acquirerIdentifcation)
952
Confguration Error (acquirerPassword)
953
Confguration Error (apiKey)
954
Confguration Error (redirectUrl)
955
Confguration Error (AcquirerAccountData)
956
Confguration Error (currencyCode)
957
Confguration Error (terminalId)
958
Confguration Error (serialNumber)
959
Confguration Error (password)
960
Confguration Error (projectId)
961
Confguration Error (merchantCategoryCode)
962
Confguration Error (merchantName)
48 / 48
Integration Manual

Integration Manual: Contact Details

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Integration Manual: Contact Details

Загружено:

Авторское право:

Доступные форматы

Integration

T +31 20 240 1240

Appendix J: SOAP Modifcation Request and Response - CancelOrRefund............................................................................................................................................................................................................39

ADYEN CONFIDENTIAL INFORMATION

Added testing error codes section

Updated document to conform to Adyen brand guidelines

Added Directory Lookup, shopper Information signature

Updated Modifcation response

Updated Appendix B section

Added (merchant) reference to modifcations

Updated AUTHORISATION notifcation reason feld

Updated CHARGEBACK_REVERSED notifation success feld to true

Added duplicate notifcation information

Changed default payment fow

Added merchantReturnData to Custom Payment Methods

Added information about reason feld for creditcards

Corrected eventCode for cancel-or-refund modifcation

Corrected SOAP message in Example 8 ([accepted])

Added REFUNDED_REVERSED notifcation

Added entries to the Payment Methods table

Corrections to value parameter description for capture and refunds

Added Error Handling section

Correction of merchantReturnData feld

Added general Tips and Warnings

Added skin option settings to billing address information

Corrected link to checkhmac.shtml in Appendix B

Added audience section

Added existing max length for the merchantReference feld

Added Test HMAC Calculation section

Added additional information

Added additional information about redirect payment methods and optional

Added Payment Methods section

Correction of oferEmail parameter value

Correction of parameters passed back in result URL.

Modifcations: to capture/cancel and refund payments.

Notifcations: to keep track of payments and modifcations.

The life-cycle of a payment

The Adyen Merchant Backofce

The basic architecture of the Adyen systems

Creating and customising a Skin

These are documented in other manuals, which are available here:

2. Hosted Payment Pages

2.1. Setting Up The Payment

Redirect Versus Form POST

Payment Session Example

The shopper is using British English as their language.

The Skin name you will be using is 4aD37dJA

The Merchant Account is TestMerchant.

name="merchantSig" value="3iWDU/V5RMtdaiZC4YRIpoX9/v0=" />

<input type="submit" value="Send" />

2.2. Explanation of the Session Fields

A complete list of currency codes can be found here: http://www.currency-iso.org/en/home/tables/table-a1.html

More information can be found here: http://www.iso.org/iso/home/standards/country_codes.htm

Not all acquirers support dynamic shopper statements.

2.3. Payment Flow Selections

One-Page Payment Flow

Multi-Page Payment Flow

Skip the Hosted Payment Page (Directory Lookup)

2.4. Payment Completion

The parameters that are passed back are:

2.5. Error Handling

2.6. Billing Address Pre-Population and AVS

2.7. Shopper Information