Adyen Merchant Integration Manual Version 1.60 Adyen B.V.
Table of Contents Introduction...3 Audience...3 Changelog...4 1 Hosted Payment Pages (HPPs)...5 Setting Up the Payment...5 Payment Session Example...5 Redirect Versus Form POST...6 Explanation of the Session Fields...6 Payment Flow Selection...8 Payment Completion...9 Billing Address Pre-Population and AVS...11 Using an iframe...12 Payment Methods...12 2 Custom Payment Methods...14 3 CVC-Only Repeat Payments...15 Setting Up the Payment...15 4 Modifications...16 SOAP...16 Capture...16 Cancel...18 Refund...19 Cancel or Refund...19 SOAP Faults...20 5 Notifications...21 Notification Message Fields...21 Accepting Notifications...25 6 Reporting...25 Appendix A: Production and Test URLs...26 Test URLs...26 Production URLs...26 Appendix B: Computing the HMAC...27 Payment Setup...27 Test HMAC Calculation...27 Payment Result...28 Custom Payment Method Redirect...28 2 Copyright Adyen B.V. 2010
Introduction 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: 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: Audience https://support.adyen.com/links/documentation This is a technical manual aimed at IT personnel involved in integrating merchants' systems with those at Adyen. General Tips/Warnings DEFENSIVE PROGRAMMING: Adyen strongly 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
Introduction Changelog Version 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. 4 Copyright Adyen B.V. 2010
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 Payment The 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 Example You 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 20 th, 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 11 th 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 Copyright Adyen B.V. 2010 5
Hosted Payment Pages (HPPs) Redirect Versus Form POST It 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 Fields Some detail about the contents of the fields: merchantreference The (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. paymentamount The 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). currencycode The three-letter capitalised ISO currency code to pay in 1. shipbeforedate The 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. skincode The code of the skin to be used. You can have more than one skin associated with your account if you require a different branding. merchantaccount The 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_l ist-1.htm 6 Copyright Adyen B.V. 2010
Hosted Payment Pages (HPPs) 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). sessionvalidity The 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. merchantreturndata This 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. merchantsig The 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. Copyright Adyen B.V. 2010 7
Hosted Payment Pages (HPPs) 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 Selection As 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). 8 Copyright Adyen B.V. 2010
Hosted Payment Pages (HPPs) Payment Completion When 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: 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 (e.g. 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 final 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 The 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. merchantreference This reference you assigned to the original payment. skincode The code of the skin used. merchantsig The signature computed over the above values in Base64 encoded format. See Appendix B for details on computing the signature. Copyright Adyen B.V. 2010 9
Hosted Payment Pages (HPPs) paymentmethod The payment method used. For CANCELLED results the payment method may not be known and will therefore be empty shopperlocale Useful if you don't have the customer's language in-session. merchantreturndata If 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. 10 Copyright Adyen B.V. 2010
Hosted Payment Pages (HPPs) Billing Address Pre-Population and AVS Address 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.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 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 Not supplied description modifiable / visible 1 unmodifiable / visible 2 unmodifiable / invisible Copyright Adyen B.V. 2010 11
Hosted Payment Pages (HPPs) 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 iframe We 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 Methods For 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 Visa Master Card Amex ideal Dutch Banktransfer German Banktransfer Elv Direct Debit (Netherlands) SofortUberweisung PayPal value visa mc amex ideal banktransfer_nl banktransfer_de elv directdebit_nl directebanking paypal 12 Copyright Adyen B.V. 2010
Hosted Payment Pages (HPPs) For the allowedmethods and blockedmethods fields you can use a group payment method value: Payment Group name Cards (includes all debit and credit cards) Bank Transfers (includes all bank transfers from all countries) value card 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. Copyright Adyen B.V. 2010 13
Custom Payment Methods 2 Custom Payment Methods Adyen 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): pspreference The reference we assigned to the payment. This is guaranteed to be globally unique and must be used when communicating about this payment to us. merchantreference This reference you assigned to the original payment. skincode The skin code used. paymentamount The payment amount as specified in your initial payment request. currencycode The 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. 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 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. 14 Copyright Adyen B.V. 2010
CVC-Only Repeat Payments 3 CVC-Only Repeat Payments If 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 Payment The 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). shopperreference An ID that uniquely refers to the shopper (previously optional). recurringcontract What type of recurring contract is used. For the 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" /> 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. Copyright Adyen B.V. 2010 15
Modifications 4 Modifications It 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. SOAP SOAP 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. Capture In order to capture an authorised (card) payment you send a modification request to the capture action using the following fields: merchantaccount The merchant account the payment was processed with. modificationamount The 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. originalreference This is the pspreference that was assigned to the authorisation. You will have received it with the payment status or the authorisation notification. 16 Copyright Adyen B.V. 2010
Modifications If the message was syntactically valid and merchantaccount is correct you will receive a capturereceived response with the following fields: pspreference A new reference we have assigned to uniquely identify this modification request. This is guaranteed to be globally unique. response The 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. Copyright Adyen B.V. 2010 17
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 Cancel Similarly 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: merchantaccount The merchant account the payment was processed with. originalreference This is the pspreference that was assigned to the authorisation. You will have received it with the payment status or the authorisation notification. If the message was syntactically valid and merchantaccount is correct you will receive a cancelreceived response with the following fields: pspreference A new reference to uniquely identify this modification request. This is guaranteed to be globally unique. response The 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. 18 Copyright Adyen B.V. 2010
Modifications Refund In order to refund a payment, you will send a modification request to the refund action using the following fields: merchantaccount The merchant account the payment was processed with. modificationamount The 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. originalreference This is the pspreference that was assigned to the authorisation. You will have received it with the payment status or the authorisation notification. If the message was syntactically valid and merchantaccount is correct you will receive a refundreceived response with the following fields: pspreference A new reference to uniquely identify this modification request. This is guaranteed to be globally unique. response The 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 Refund If 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: merchantaccount The merchant account the payment was processed with. originalreference This is the pspreference that was assigned to the authorisation. You will have received it with the payment status or the authorisation notification. Copyright Adyen B.V. 2010 19
If the message was syntactically valid and merchantaccount is correct you will receive a cancelorrefundreceived response with the following fields: Modifications pspreference A new reference to uniquely identify this modification request. This is guaranteed to be globally unique. response The 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 Faults If 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/xmlschemainstance"> <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 20 Copyright Adyen B.V. 2010