Adyen Merchant Integration Manual

Adyen Merchant Integration Manual

Version 1.60

Adyen B.V.

Table of ContentsIntroduction.............................................................................................................................................................3

Audience............................................................................................................................................................3Changelog..........................................................................................................................................................4

1 Hosted Payment Pages (HPPs)..............................................................................................................................5Setting Up the Payment......................................................................................................................................5

Payment Session Example.............................................................................................................................5Redirect Versus Form POST...........................................................................................................................6

Explanation of the Session Fields........................................................................................................................6Payment Flow Selection.....................................................................................................................................8Payment Completion..........................................................................................................................................9Billing Address Pre-Population and AVS............................................................................................................11Using an iFrame................................................................................................................................................12Payment Methods.............................................................................................................................................12

2 Custom Payment Methods..................................................................................................................................143 CVC-Only Repeat Payments................................................................................................................................15

Setting Up the Payment....................................................................................................................................154 Modifications......................................................................................................................................................16

SOAP................................................................................................................................................................16Capture.............................................................................................................................................................16Cancel...............................................................................................................................................................18Refund..............................................................................................................................................................19Cancel or Refund...............................................................................................................................................19SOAP Faults.....................................................................................................................................................20

5 Notifications........................................................................................................................................................21Notification Message Fields..............................................................................................................................21Accepting Notifications.....................................................................................................................................25

6 Reporting............................................................................................................................................................25Appendix A: Production and Test URLs..................................................................................................................26

Test URLs.........................................................................................................................................................26Production URLs...............................................................................................................................................26

Appendix B: Computing the HMAC........................................................................................................................27Payment Setup.................................................................................................................................................27Test HMAC Calculation.....................................................................................................................................27Payment Result................................................................................................................................................28Custom Payment Method Redirect...................................................................................................................28

2 Copyright © Adyen B.V. 2010

Introduction

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

● Hosted Payment Pages: integrate with the Adyen Hosted Payment Pages (HPPs)

● Modifications: capture/cancel and refund payments

● Notifications: use the notification service to keep track of payments and modifications

For a minimal, low-volume integration, the chapters on modifications and notifications are not required for processing payments.

In this manual we will refer to code samples with reference implementations in various programming languages. These can be found on our support site at:

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

This document does specifically does not cover:

● the life-cycle of a payment

● the Adyen Merchant Backoffice

● basic architecture of the Adyen systems

● creating and customising a “Skin”

These are documented separately in other manuals and at our support site (https://support.adyen.com/).

The latest version of this document is available at:

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

AudienceThis is a technical manual aimed at IT personnel involved in integrating merchants' systems with those at Adyen.

General Tips/WarningsDEFENSIVE PROGRAMMING: Adyen strongly advises to use “defensive programming” when integrating with the Adyen Services. This implies for example that automated decisions programmed into the systems of Merchants should be defaulted to non-delivery of products and services. E.g. program your systems only to deliver products or services after receiving an express authorization of the payment requested and not program you system to deliver in case no explicit rejection is received.

MEANING OF PAYMENT STATUS “ AUTHORISED” If a payment request receives the status “authorised”, this means the payment transaction is likely to be successful. However, this is not 100% certain. Payment may still be blocked. The likelihood of a payment marked as “authorised” being blocked or unsuccessful depends on the payment method which is used. For example for direct debit transactions this risk is significant because in most cases the status “authorised” only means the bank account exists and not that there are enough funds on the bank account to actually perform the payment.

Copyright © Adyen B.V. 2010 3

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


https://support.adyen.com/

Introduction

ChangelogVersion Date Changes

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 lenght for the merchantReference field

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 fields

1.49 2010-03-31 • Added Payment Methods section

1.48 2010-03-09 • Correction of offerEmail parameter value

1.47 2010-02-24 • Correction of parameters passed back in result URL.• Added description of placeholders in shopperStatement.


Hosted Payment Pages (HPPs)

1 Hosted Payment Pages (HPPs)The Adyen Hosted Payment Pages (HPPs) provide a flexible, secure and easy way to allow customers to pay for goods or services. When a customer needs to pay to complete an order they will be transferred from your site to the HPP where the customer will perform the payment. The customer is then directed back to your site along with the result of the payment.

In order to integrate seamlessly into your site the HPP is fully customisable in look and feel. We refer to a set of look-and-feel customisations as a “Skin”, and each one consists of a set of custom HTML/JavaScript fragments, images and CSS style sheets. Creation and management of skins is covered in the Skin Creation Manual.

Setting Up the PaymentThe hand off between your site and the HPP skin is achieved by setting up a payment session for the customer (as a standard HTML form) and transferring the customer with this payment session to the HPP. To avoid the possibility of a customer tampering with payment session data it is cryptographically signed using a “shared secret”. This is a simple process and we provide code examples in common programming languages (see Introduction).

Payment Session ExampleYou have a customer who has to pay a total of GBP100 for an order which is known to you in your backoffice systems as “Internet Order 12345”. The goods will be shipped to the customer before or on October 20th, 2007 and you want to present the text “1 Digital Camera” as an order summary on the payment review page. The customer is using (British) English as their language. The Skin name you will be using is “4aD37dJA” and the (financial) account you have with us is “TestMerchant”. Furthermore, you want this payment offer to expire today at 11 am. (assuming it is 10:30 am on October 11th 2007 in the UTC time zone).

The following is an example of a complete payment session for the example above:

<input type="hidden" name="merchantReference" value="Internet Order 12345" /><input type="hidden" name="paymentAmount" value="10000" /><input type="hidden" name="currencyCode" value="GBP" /><input type="hidden" name="shipBeforeDate" value="2007-10-20" /><input type="hidden" name="skinCode" value="4aD37dJA" /><input type="hidden" name="merchantAccount" value="TestMerchant" /><input type="hidden" name="shopperLocale" value="en_GB" /><input type="hidden" name="orderData" value="H4sIAAAAAAAAALMpsOPlCkssyswvLVZIz89PKVZIzEtRKE4tKstMTi3W4+Wy0S+wAwDOGUCXJgAAAA==" /> <input type="hidden" name="sessionValidity" value="2007-10-11T11:00:00Z" /><input type="hidden" name="merchantSig" value="33syARtfsxD47jeXzOlEyZ0j3pg=" />

Example 1: Complete Payment Session



Redirect Versus Form POSTIt is possible to set up a payment session using a generated URL (e.g. for a browser redirect (HTTP 302)). Please keep in mind the following:

● not all browsers are capable of handling large URLs. Specifically for Microsoft Internet Explorer (MS-IE) the size of the URL should not exceed 2083 characters. It is your own responsibility to make sure this limit is not exceeded.

● All parameters and their values should be URL-encoded using UTF-8 character encoding (as recommended by W3C).

Explanation of the Session FieldsSome detail about the contents of the fields:

● merchantReferenceThe (merchant) reference for this payment. This reference will be used in all communication to the merchant about the status of the payment. Although it is a good idea to make sure it is unique, this is not a requirement. The maximum length is 80 characters.

● paymentAmountThe payment amount specified in minor units (without decimal separator). For example GBP100 is specified as 10000 and EUR199.95 is specified 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 the Japanese yen is an exception and doesn't have any minor units (e.g. 1001 yen is specified as 1001).

● currencyCodeThe three-letter capitalised ISO currency code to pay in1.

● shipBeforeDateThe date by which the goods or services specified in the order must be shipped or rendered. Format is YYYY-MM-DD. See http://www.w3.org/TR/NOTE-datetime for more information.

● skinCodeThe code of the skin to be used. You can have more than one skin associated with your account if you require a different branding.

● merchantAccountThe merchant account you want to process this payment with.

● shopperLocale (optional)A combination of language code and country code to specify the language used in the session (e.g. 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.

1 A complete list of currency codes can be found at: http://www.iso.org/iso/support/faqs/faqs_widely_used_standards/widely_used_standards_other/currency_codes/currency_codes_list-1.htm


http://www.w3.org/TR/NOTE-datetime

http://www.iso.org/iso/support/faqs/faqs_widely_used_standards/widely_used_standards_other/currency_codes/currency_codes_list-1.htm

http://www.iso.org/iso/support/faqs/faqs_widely_used_standards/widely_used_standards_other/currency_codes/currency_codes_list-1.htm


● orderData (optional)A fragment of HTML which will be displayed to the customer on a “review payment” page just before final confirmation of the payment. In order to guarantee correct transmission of this data, including the sending of non-western characters (e.g. the Japanese or Cyrillic character sets), the data is compressed and encoded in the session (GZIP compressed and Base64 encoded). We provide code examples in common programming languages for this (see link in the Introduction).

● sessionValidityThe final time by which a payment needs to have been made. This is especially useful for tickets/reservations, where you want to “lock” the item for sale for only a short time and payments made after this time would lead to extra costs and administrative hassle. Format is YYYY-MM-DDThh:mm:ssTZD. TZD is the Time Zone Designator which can either be the letter 'Z' or +hh:mm or -hh:mm. See http://www.w3.org/TR/NOTE-datetime for more information.

● merchantReturnDataThis field willl be passed back as-is on the return URL when the shopper completes (or abandons) the payment and returns to your shop. Typically used to transmit a session ID (max. 128 characters).N.B. Adyen cannot guarantee that all payment methods will work when using the merchantReturnData parameter. Especially for redirect payment methods, such as iDEAL, the merchantReturnData parameter is added to the request which may have a limited size. If, with the merchantReturnData, the size of the request is too large, the payment can fail.

● merchantSigThe signature in Base64 encoded format. The signature is generated by concatenating the values of a number of the payment session fields and computing the HMAC over this using the shared secret (configured in the skin). See Appendix B for details on computing the signature. We provide code examples in common programming languages for this (see link in the Introduction).

● countryCode (optional)By default the payment methods offered to the shopper are filtered based on the country which the IP address of the shopper is mapped to. This prevents a UK shopper from being presented with a German payment method like ELV. 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 information.

● shopperEmail (optional)The email address of the shopper. Recommended as it is used in a velocity fraud check.

● shopperReference (optional)An ID that uniquely identifies the shopper (e.g. a customer id in a shopping cart system). Recommended as it is used in a velocity fraud check.

● allowedMethods (optional)A comma-separated list of allowed payment methods (see Payment Methods section for more details). This acts as a filter on the payment methods which would normally be available in the skin. Only the ones in this list will be shown (if available); all others will be ignored. No spaces are allowed. Note that this parameter is optional. If the parameter is not used the value for this field in the merchantSignature computation is an empty String.


http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

http://www.w3.org/TR/NOTE-datetime


● blockedMethods (optional) A comma-separated list of payment methods which should not be made available (see Payment Methods section for more details). This acts as a filter 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. No spaces are allowed. Note that this parameter is optional. If the parameter is not used the value for this field in the merchantSignature computation is an empty String.

● offset (optional)This numeric value will be added to the fraud scoring making the payment more likely (or if negative, less likely) to be refused by the fraud scoring. If set to a high negative value (e.g. -150), the payment attempt will almost certainly be allowed to continue even if the payment details are blocked. Do not set the value to 100 or more as this will block all payments.

● shopperStatement (optional)Some acquirers support a variable shopper statement. To submit a variable shopper statement you can set the shopperStatement field in the payment request.

In the shopperStatment you can also include place holders for the various references: ${reference} for the merchant reference and ${pspReference} for the psp reference. The shopperStatement field may not exceeds 135 characters and can only contain the characters: a-zA-Z0-9.,-?| Note that if the shopperStatement field is set it is also included in the HMAC computation.

● offerEmail (optional) If the value for offerEmail is “prompt” an extra payment method is added to the list of payment methods called “Pay by Email”. If a shopper selects this payment an email will be sent to the shopper which can be used to pay later. The sessionValidity time must still lie well into the future if the shopper wants to use this link to pay. It is advisable to use a sessionValidity time of, for example, 2 days.

Payment Flow SelectionAs a merchant you can choose between two different payment flows - the default flow which splits the payment process into two or three discrete steps (depending on the payment method) and the “One Page Payment” flow which attempts to reduce the payment process to a single page.

The default flow is lightweight, doesn't require JavaScript, and uses little screen estate. This makes it ideally suited for maximum compatibility with a wide range of browsers and devices, including mobile phones and PDAs. Optionally you can skip the payment method selection page in this flow and start directly on the payment details entry page.

The “One Page Payment” flow, on the other hand, uses JavaScript extensively to manipulate the page content and is suited for use on modern browsers and when page complexity is not an issue and there is enough screen estate.

Switching to the “One Page Payment” flow is achieved by changing the URL the shopper is directed to from select.shtml to pay.shtml. No other changes are required.

To use the default flow, but skip the payment method selection screen, change the URL the shopper is directed to from select.shtml to details.shtml. A further parameter, brandCode, should be supplied with the payment method chosen (see Payment Methods section for more details, but note that the group values are not valid).



Payment CompletionWhen a customer has completed the payment they are directed to a default result page. Your own result page can be specified in the skin to be used instead of the default. We append parameters to the resultURL to inform of the status of the payment. Just as you cryptographically signed the payment session when sending the customer to us, we will use the same shared secret to sign the date we return to you. Therefore you can check that the data has not been tampered with. An example of such a result request for the example above is (assumes you set your resultURL 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

Example 2: Result Request URL

The parameters passed back are:

● authResultThe result of the payment. One of:

• AUTHORISEDPayment authorisation was successfully completed.

• REFUSEDPayment was refused / payment authorisation was unsuccessful.

• CANCELLEDPayment attempt was cancelled by the shopper or the shopper requested to return to the merchant (e.g. by pressing the back button on the initial page).

• PENDINGFinal status of the payment attempt could not be established immediately. This can happen if the systems providing final payment status are unavailable or the shopper needs to take further action to complete the payment.

• ERRORAn error occurred during the payment processing.

● pspReferenceThe reference we have assigned to 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.

● merchantReferenceThis reference you assigned to the original payment.

● skinCodeThe code of the skin used.

● merchantSigThe signature computed over the above values in Base64 encoded format. See Appendix B for details on computing the signature.



● paymentMethodThe payment method used. For CANCELLED results the payment method may not be known and will therefore be empty

● shopperLocaleUseful if you don't have the customer's language in-session.

● merchantReturnDataIf set 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 smoothly with the customer's session on your server.

The moment the status of the payment is established by us we will also immediately send a “notification” (server-to-server) to you. This notification is the recommended way to update the status of the payment in your backoffice. The notification system should be more reliable in its delivery because the resultURL method described above relies on the customer's browser/computer/internet connection, any of which could fail at any time. Notifications are discussed separately in Chapter 5.

Although we strongly recommend a fixed result URL, specified in the skin, there are situations where it is desirable to set the result URL on a per-payment basis. To override the skin's result URL specify the URL in the parameter resURL in the payment session. The resURL parameter does not need to be included in the signature.

Please note that Adyen cannot guarantee that all payment methods will work when using the resURL parameter. Especially for redirect payment methods, such as iDEAL, the resURL parameter is added to the request, which may have a limited size. If, with the resURL, the size of the request is too large, the payment can fail.



Billing Address Pre-Population and AVSAddress Verification System (AVS) is a security feature that verifies 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 for MasterCard and Visa) and card types. Please check with your technical contact which AVS options are supported for your account.

To enable AVS the Billing Address Fields (AVS) field must be checked under Skin Options for each skin you wish to use.

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 fields you can add them to the payment session as follows:

● billingAddress.streetThe street name.

● billingAddress.houseNumberOrNameThe house number (or name).

● billingAddress.cityThe city.

● billingAddress.postalCodeThe postal/zip code.

● billingAddress.stateOrProvinceThe state or province.

● billingAddress.countryThe country 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 fields. The protocol and shared secret is the same as the normal merchant signature, but for the following fields:

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 specified. Please note that the billingAddressType field is part of the merchantSignature (see Appendix B: Computing the HMAC).

● billingAddressType

billingAddressType description

Not supplied modifiable / visible

1 unmodifiable / visible

2 unmodifiable / invisible


http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2


If you want to have the shopper enter the billing address on the payment pages you can add the billing address data entry fields on the skin “edit” page. In this case you should not supply a billingAddressType so that the fields are modifiable.

Using an iFrameWe do not support displaying the Hosted Payment Pages in an iFrame. The use of iFrames introduces known usability, security and cross-browser issues. However if you do choose to put the Hosted Payment Pages in an iFrame please keep the following in mind:

Some (redirect) payment methods like iDEAL do not permit their pages to be viewed in an iFrame and will break out of it. Other redirect payment methods will assume more available screen space than your iFrame permits. You should also prepare to handle the difference in behaviour for the payment result URL, since when the payment completes you may not be in an iFrame any more.

Another problem you will face is the browser's cookie policy. Cookies are required on the Hosted Payment Page. Using an iFrame means that the browser may impose restrictions under what conditions cookies are allowed to be set within the iFrame. While there are workarounds for getting cookies accepted in the default configuration for most browsers, the shopper may have configured 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 first 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 stay the same. Furthermore, the exact operation of a (redirect) payment method can differ between the Test environment and the Live environment.

Payment MethodsFor some payment request fields you have to use payment method values to indicate certain payment methods. For example for the allowedMethods field, or the brandCode field. Below a list of the most common used payment methods names with their value. Please note that the value is case sensitive.

Payment Method name value

Visa visa

Master Card mc

Amex amex

iDEAL ideal

Dutch Banktransfer bankTransfer_NL

German Banktransfer bankTransfer_DE

Elv elv

Direct Debit (Netherlands) directdebit_NL

SofortUberweisung directEbanking

PayPal paypal



For the allowedMethods and blockedMethods fields you can use a group payment method value:

Payment Group name value

Cards (includes all debit and credit cards)

card

Bank Transfers (includes all bank transfers from all countries)

bankTransfer

All the payment methods that are configured for your account, including the value you use to indicate the specific payment method, are available in the CA interface. Under Settings > Payment Methods a list of all your payment methods. The value to use is set in the column Name.

Some payment methods are not available in all countries. For example iDEAL is only offered if the shopper is from The Netherlands. If the payment methods 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 to set the countryCode parameter as well. Otherwise it could be that, when the shopper does not originate from the country where this payment method is displayed, that no payment methods are displayed. 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 displayed is also available in the payment methods list in the CA interface in the column Available Countries.

Please note that the list of payment methods on the Test environment can be different than the list of payment methods on the Live environment. This means that a payment method which is configured on Test is not automatically also available on Live.


Custom Payment Methods

2 Custom Payment MethodsAdyen offers an option to display custom payment methods on your Hosted Payment Pages. Please contact Adyen Support to configure 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 HPPs. This also means that you can add extra charges to the payment method, change the order, etc. For more details about styling the custom payment method on your HPPs, please see the Skin Creation Manual.

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 (like the result URL):

● pspReferenceThe reference we assigned to the payment. This is guaranteed to be globally unique and must be used when communicating about this payment to us.


● skinCodeThe skin code used.

● paymentAmountThe payment amount as specified in your initial payment request.

● currencyCodeThe three-letter capitalised ISO currency code to pay in.

● additionalAmount (optional)An additional amount when there are extra charges configured for this custom payment method in your skin. The amount is specified in minor units (without decimal separator), like the paymentAmount.

● customPaymentMethodThe Custom Payment Method used.

● paymentMethodThe payment method used (this is the same value as customPaymentMethod)

● merchantSigThe signature computed over the above values in Base64 encoded format. See Appendix B for details on computing the signature.

The customPaymentMethod and paymentMethod parameters will contain the same value but both are in the URL to be more consistent with the resultUrl. Because there are extra fields in the custom payment URL the attached merchantSig is also calculated differently (see Appendix B: Computing the HMAC).

authResult is not one of the parameters because this is not known (yet). 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 “handled externally”.


CVC-Only Repeat Payments

3 CVC-Only Repeat PaymentsIf a significant 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 card they have previously used by simply filling in the card's security code (CSC/CVC) and confirming the purchase.

Setting Up the PaymentThe payment session is set up just like a regular payment. There are two previously optional fields which become compulsory and one new field which needs to be provided in the payment session form.

● shopperEmail The email address of the shopper (previously optional).

● shopperReferenceAn ID that uniquely refers to the shopper (previously optional).

● recurringContractWhat type of recurring contract is used. For the CVC-Only payments the value ONECLICK should be used.

<input type="hidden" name="shopperEmail" value="[email protected]" /><input type="hidden" name="shopperReference" value="grasshopper52" /><input type="hidden" name="recurringContract" value="ONECLICK" />

Example 3: CVC-Only Repeat Payment Additional Parameters

Please see Appendix B: Computing the HMAC for 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 allow the shopper to opt-out 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 field underneath in which to enter their card's security code (CSC/CVC).

Please note that shoppers are uniquely identified using the shopperReference parameter. It is important that shoppers are securely logged in on your site and that the shopperReference parameter cannot be modified by the shopper.


Modifications

4 ModificationsIt is possible to perform modifications using your account on the Adyen Merchant Backoffice. It is generally a good idea to automate this if you are processing more than a handful of payments daily. For this we offer a Simple Object Access Protocol (SOAP ) web service which accepts the modification requests from your backoffice systems. To submit modification messages you supply HTTP basic authentication credentials (username/password). The username is ws@Company.[YourCompanyAccount] and you set the password for this user in the Merchant Backoffice (under Settings > Users).

Please note that for all messages if you receive either a captureReceived, cancelReceived, or refundReceived response this doesn't mean that the payment was actually modified. Instead it means that the request has been accepted. Once the request has been processed by Adyen you will receive a notification which tells you whether the modification was successful.

N.B. 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 configuration and, if your implementation caches the DNS lookup, your ability to submit modifications and/or payments may be impacted.

SOAPSOAP is a common and well-supported method to communicate with web services. All modern programming languages have toolkits available which make it simple to interact with SOAP web services without ever needing to manually generate the messages. In the next section we will describe the possible modification actions.

It is important that your system is able to handle requests/responses which contain additional fields.

CaptureIn order to capture an authorised (card) payment you send a modification request to the capture action using the following fields:

● merchantAccountThe merchant account the payment was processed with.

● modificationAmountThe amount to capture. This consists of a currencyCode and a value which is the amount in minor units (see “Explanation of the Session Fields” chapter for more information). The value and currencyCode must match the original payment.

● originalReferenceThis is the pspReference that was assigned to the authorisation. You will have received it with the payment status or the authorisation notification.


Modifications

If the message was syntactically valid and merchantAccount is correct you will receive a captureReceived response with the following fields:

● pspReferenceA new reference we have assigned to uniquely identify this modification request. This is guaranteed to be globally unique.

● responseThe response. In case of success this will be [capture-received] or, in case of an error, an informational message will be returned.

<?xml version="1.0"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Body> <ns1:capture xmlns:ns1="http://payment.services.adyen.com"> <ns1:modificationRequest> <merchantAccount xmlns="http://payment.services.adyen.com"> YourMerchantAccount </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"> ThePaymentPspReference </originalReference> </ns1:modificationRequest> </ns1:capture> </soap:Body></soap:Envelope>

Example 4: SOAP Capture Request

The result of the capture is sent via a notification with eventCode CAPTURE. The pspReference of this notification is the same as the pspReference in the SOAP response. The success field indicates if the capture was successful (true) or not (false). If false the reason field of the notification will give a short description why.

Our Customer Area (CA) provides the option to configure an automated capture process, capturing payments automatically after a configured number of days, ranging from immediate up to 14 days.


http://payment.services.adyen.com/


http://www.w3.org/2001/XMLSchema-instance

http://www.w3.org/2001/XMLSchema

http://schemas.xmlsoap.org/soap/envelope/

Modifications

<?xml version="1.0"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Body> <ns1: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] </response> </ns1:captureResult> </ns1:captureResponse> </soap:Body> </soap:Envelope>

Example 5: SOAP Capture Response

CancelSimilarly to the capture modification, in order to cancel an authorised (card) payment you send a modification request to the cancel action using the following fields:



If the message was syntactically valid and merchantAccount is correct you will receive a cancelReceived response with the following fields:

● pspReferenceA new reference to uniquely identify this modification request. This is guaranteed to be globally unique.

● responseThe response. In case of success, this will be [cancel-received] or, in case of an error, an informational message will be returned.

The result of the cancellation is sent via a notification with eventCode CANCELLATION. The pspReference of this notification is the same as the pspReference in the SOAP response. The success field indicates if the cancellation was successful (true) or not (false). If false the reason field of the notification will give a short description why.







Modifications

RefundIn order to refund a payment, you will send a modification request to the refund action using the following fields:


● modificationAmountThe amount to refund. This consists of a currencyCode and a value which is the amount in minor units (see “Explanation of the Session Fields” chapter for more information). The currencyCode must match the value in the original payment.


If the message was syntactically valid and merchantAccount is correct you will receive a refundReceived response with the following fields:


● responseThe response. In case of success this will be [refund-received] or, in case of an error, an informational message will be returned.

The result of the refund is sent via a notification with eventCode REFUND. The pspReference of this notification is the same as the pspReference in the SOAP response. The success field indicates if the refund was successful (true) or not (false). If false the reason field of the notification will give a short description why.

Cancel or RefundIf you do not know if the payment is captured but you want to reverse the authorisation you can send a modification request to the cancelOrRefund action using the following fields:




Modifications

If the message was syntactically valid and merchantAccount is correct you will receive a cancelOrRefundReceived response with the following fields:


● responseThe response. In case of success this will be [cancelOrRefund-received] or, in case of an error, an informational message will be returned.

If the payment is authorised, but not yet captured, it will be cancelled. In other cases the payment will be fully refunded (if possible).

The actual result of the cancel or refund is sent via a notification with eventCode REFUND or CANCELLATION (depending on the action that is taken). The pspReference of this notification is the same as the pspReference in the SOAP response. The success field indicates if the action was successful (true) or not (false). If false the reason field of the notification will give a short description why.

SOAP FaultsIf a modification request does not pass validation or violates a security or configuration constraint the platform does not accept, and does not store, the request. Instead you receive a SOAP Fault which contains a description of the problem. Generally this will be handled as an Exception in your SOAP toolkit. Example 6 shows a SOAP fault message.

The way to check the description this is to read the faultstring. If the modification was rejected by our platform the fault string will start with one of validation, security, or configuration followed a descriptive message.

<?xml version="1.0"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Body> <soap:Fault> <faultcode>soap:Server</faultcode> <faulstring>validation Invalid Request: Modification messages require the original pspReference!</faultstring> </soap:Fault> </soap:Body></soap:Envelope>

Example 6: SOAP Fault






Notifications

5 NotificationsWhenever a payment is made or a modification is processed we will notify you of the event and whether or not it was performed successfully. Notifications should be used to keep your backoffice systems up to date with the status of each payment and modification.

Notifications are sent using a SOAP call or using HTTP POST parameters to a server of your choice. This means that you will host a service to receive the notifications. We provide code examples in common programming languages for this (see link in the Introduction). Your system should be able to handle requests/responses which contain additional fields.

Notifications 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 notification twice. You should therefore make sure that you can receive duplicate notifications without error. A duplicate notification is one where the eventCode and pspReference fields are the same (see below). If a duplicate is received with the success field set to true it overrules the previous notification. In all other cases you do not need to act on duplicate notifications.

Notification settings are configured in the Customer Backoffice. 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.

Notification Message FieldsA notification item (which we will refer to as a notification) contains the following fields:

● liveboolean (true/false) indicating if the notification originated from the LIVE or TEST payment systems.

● eventCodeThe event type of the notification. Values include:

Normal Payment Events

● AUTHORISATION

Modification Payment Events

● CANCELLATION

● REFUND

● CAPTURE

For more information please see the Modifications chapter.


Notifications

Dispute Events

● REQUEST_FOR_INFORMATION

● NOTIFICATION_OF_CHARGEBACK

● ADVICE_OF_DEBIT

● CHARGEBACK

● CHARGEBACK_REVERSED

For more information about Disputes please see the Merchant Manual.

Other Events

● REPORT_AVAILABLE

For more information please see the Reporting Manual V2.

For specialised applications (e.g. recurring payments) other values are possible. New codes may be added by Adyen at any time.

● pspReferenceThe reference we assigned to the payment or modification

● originalReferenceIf this is a notification for a modification request this will be the pspReference that was originally assigned to the authorisation. For a payment it will be blank.


● merchantAccountCodeThe merchant account the payment or modification was processed with.

● eventDateThe time the event was generated.

● successWhether or not the event succeeded (boolean true/false).

● paymentMethodThe payment method used (only for AUTHORISATION). e.g. visa, mc, ideal, elv, wallie, etc...

● operationsThe modification operations supported by this payment as a list of strings (only for AUTHORISATION). The operations will tell 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 notifications, the operations are sent as a single comma-separated string.


Notifications

● reasonText field which can contain an informational message, for example an error reason in the case of a failure, refusal or error; or the authorisation code for a card authorisation. For REPORT_AVAILABLE it contains the URL where the report can be downloaded from.

● amountThe amount (if relevant) associated with the payment or modification. This consists of a currencyCode and a value which is the amount in minor units (refer to “Explanation of the Session Fields” chapter for more information). In case of HTTP POST notifications you will instead receive currency and value as parameters.

For SOAP notifications a notification message is a container for an array of notification items. This means that you may receive multiple notifications contained in one notification message. See Example 7 for a sample SOAP request and Example 8 for a sample SOAP response.


Notifications

<?xml version="1.0"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Body> <ns1: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> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">1000</value> </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> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">995</value> </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> </notificationItems> </ns1:notification> </ns1:sendNotification> </soap:Body>





Notifications

</soap:Envelope>

Example 7: SOAP Notification Request

Please note that the eventCode AUTHORISATION does not necessarily mean that the authorisation is successful. The authorisation is successful if the success field has the value true. In case of an error or a refusal, it will be false and the reason field should be consulted for the cause of the authorisation failure.

Accepting NotificationsReceiving a notification message requires a response with the value [accepted]. When our systems receive this response all notifications contained in the message are marked as successfully sent. It is therefore important that receiving a notification message is not interrupted by an error while processing a single notification. We recommend that storing and processing notifications are done separately and that an [accepted] response is generated when storing of the notifications is completed. See Example 8 for a SOAP response.

The URL to send the SOAP notification messages to and the authentication are configurable in the Adyen merchant backoffice. It also has a testing facility so that you can verify that your server is able to correctly receive the notifications coming from the Adyen systems.

Please note that if you receive a notification 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 notifications.

<?xml version="1.0"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Body> <ns1:sendNotificationResponse xmlns:ns1="http://notification.services.adyen.com" soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <ns1:sendNotificationResponse xmlns:ns1="http://notification.services.adyen.com"> <ns1:notificationResponse>[accepted]</ns1:notificationResponse> </ns1:sendNotificationResponse> </soap:Body></soap:Envelope>

Example 8: SOAP Notification Response

6 ReportingFor information about reporting please refer to the separate reporting manual available at




http://notification.services.adyen.com/




Appendix A: Production and Test URLs

Appendix A: Production and Test URLs

Test URLs

Merchant Backoffice: 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

Modification SOAP Service https://pal-test.adyen.com/pal/servlet/soap/Payment

Modification SOAP Service WSDL https://pal-test.adyen.com/pal/Payment.wsdl

Notification SOAP Service WSDL https://ca-test.adyen.com/ca/services/Notification?wsdl

Production URLs

Merchant Backoffice: 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

Modification SOAP Service https://pal-live.adyen.com/pal/servlet/soap/Payment

Modification SOAP Service WSDL https://pal-live.adyen.com/pal/Payment.wsdl

Notification SOAP Service WSDL https://ca-live.adyen.com/ca/services/Notification?wsdl


Appendix B: Computing the HMAC

Appendix B: Computing the HMACThe signature is computed using the HMAC algorithm with the SHA-1 hashing function2. The data passed in the form fields is concatenated into a string (the “signing string”). The HMAC signature is then computed over this string using a key (which is set for the merchant's skin). The signature is passed along with the form data and checked at the other end to verify that the data has not been tampered with in transit. The HMAC signature is binary data, so we base64 encode it for transmission.

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.

Payment SetupWhen 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 + offset

The order of the fields must be exactly the same as described above. If you are not using one of the fields, for example allowedMethods, the value for this field in the signing string is an empty string.

In the example in chapter 1, this would provide us with the signing string:

10000GBP2007-10-20Internet Order 123454aD37dJATestMerchant2007-10-11T11:00:00Z

If the shared secret is Kah942*$7sdp0), the resulting signature is (base64 encoded):

x58ZcRVL1H6y+XSeBGrySJ9ACVo=

Please note that, as of March 1 2008, the orderData parameter is deprecated and no longer included in the signing string. Existing implementations which do sign the orderData will continue to work.

Test HMAC CalculationIf you are having trouble with the merchant signature you can check your HMAC calculation in our backoffice. You can enter the payment session fields 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 tohttps://ca-test.adyen.com/ca/ca/skin/checkhmac.shtml. In addition to the regular payment fields you can also submit the signing string in the signingString field.

2 See: http://en.wikipedia.org/wiki/Hmac


http://en.wikipedia.org/wiki/Hmac

Appendix B: Computing the HMAC

Payment ResultThe payment result uses the following signature string:

authResult + pspReference + merchantReference + skinCode + merchantReturnData

In the example from chapter 1 this would provide us with the signing string (parameter values are URL decoded, which your framework should do for you):

AUTHORISED1211992213193029Internet Order 123454aD37dJA

If the shared secret is Kah942*$7sdp0), the resulting signature is (base64 encoded):

ytt3QxWoEhAskUzUne0P5VA9lPw=

Please note that shopperLocale is passed as parameter but not used in the signing string.

Custom Payment Method RedirectThe redirect of the Custom Payment Method uses the following signature string:

pspReference + merchantReference + skinCode + paymentAmount + currencyCode + additionalAmount + customPaymentMethod

The order of the fields must be exactly the same as described above. If one of the fields is not set, for example additionalAmount, the value for this field in the signing string is an empty string.


Documents

Adyen Merchant Integration Manual