-
Integration Manual Version: 1.80 Contact details Simon Carmiggeltstraat 6-50 1011 DJ Amsterdam P.O. Box 10095 1001 EB Amsterdam The Netherlands T +31 20 240 1240 E support@adyen.
-
Table of Contents 1. Introduction............................................................................................................................................................................................................................................................................................................................................... 6 2. Hosted Payment Pages......................................................................................................................
-
Appendix J: SOAP Modifcation Request and Response - CancelOrRefund............................................................................................................................................................................................................39 Appendix K: REST Modifcation Request and Response - CancelOrRefund.............................................................................................................................................................................
-
Changelog Version Date Changes 1.80 2014-03-05 • Added testing error codes section • Updated REST modifcation appendices 1.79 2014-01-28 • Updated document to conform to Adyen brand guidelines • Added testing AVS and CVC section • Added SOAP and REST modifcation and notifcation examples to appendices 1.78 2013-08-14 • Added Directory Lookup, shopper Information signature 1.77 2013-07-23 • Updated Modifcation response 1.76 2013-06-24 • Updated Appendix B section 1.
-
1.48 2010-03-09 • Correction of oferEmail parameter value 1.47 2010-02-24 • Correction of parameters passed back in result URL. • Added description of placeholders in shopperStatement. Audience This is a technical manual aimed at IT personnel involved in integrating merchants' systems with those at Adyen. The latest version of this document is available here: https://support.adyen.
-
1. Introduction The purpose of this manual is to facilitate the integration of your platform with the Adyen Payment System. In the following chapters we will cover how you can use the: • Hosted Payment Pages: to integrate with the Adyen Hosted Payment Pages (HPPs). • Modifcations: to capture/cancel and refund payments. • Notifcations: to keep track of payments and modifcations.
-
2. Hosted Payment Pages The Adyen Hosted Payment Pages (HPP) provide a fexible, secure and easy way to allow shoppers to pay for goods or services. Once a shopper has added items to their shopping cart and needs to pay to complete their order, they will be redirected from your site to the HPP, where they will submit their payment details. Once complete, the shopper is redirected back to your site along with the result of the payment.
-
-
• blockedMethods (optional) A comma-separated list of allowed payment methods, please refer to section 2.9 for more details. This acts as a flter on the payment methods which would normally be available in the skin. The methods listed will be removed from the list of available payment methods. Spaces are not allowed. Please note, this parameter is optional. If it is not used, the value for this feld in the merchantSignature computation is an empty String.
-
2.3.3. Skip the Hosted Payment Page (Directory Lookup) You may decide to skip the Adyen payment method selection page so that the shopper starts directly on the payment details entry page. This is done by calling details.shtml instead of select.shtml. An additional parameter, brandCode and where applicable issuerId, should be provided with the selected payment method listed, please refer to section 2.9 for more details.
-
• merchantSig The signature computed over the above values in Base64 encoded format. See Appendix C for details on computing the signature. • paymentMethod The payment method used. For CANCELLED results, the payment method may not be known and will therefore not be present. • shopperLocale The shopperLocale that you provided in the payment request. • merchantReturnData If you set this feld in the payment session setup, the value will be passed back as-is.
-
You can choose to have the payment pages collect the billing address and/or pre-populate these values from your own system. If you wish to pre-populate these felds you can add them to the payment session using the following parameters: • billingAddress.street The street name. • billingAddress.houseNumberOrName The house number (or name). • billingAddress.city The city. • billingAddress.postalCode The postal/zip code. • billingAddress.stateOrProvince The state or province. • billingAddress.
-
The shopper's lastname. • shopper.gender The shopper's gender. • shopper.dateOfBirthDayOfMonth The day of the month of the shopper's birth. • shopper.dateOfBirthMonth The month of the shopper's birth. • shopper.dateOfBirthYear The year of the shopper's birth. • shopper.telephoneNumber The shopper's telephone number. • shopperType This feld can be used if validation of the shopper felds is desired. If you are including shopperType in the payment session, you will need to include the shopperSig.
-
2.9. Payment Methods For some payment requests, you may decide to flter the payment methods that are displayed on the HPP or bypass the HPP entirely. The allowedMethods feld is used to display specifc payment methods, the blockedMethods feld is used to prevent specifc payment methods from being displayed, and the brandCode and issuerId felds are used take the customer directly to specifc payment method.
-
• additionalAmount (optional) An additional amount when there are extra charges confgured for this custom payment method in your skin. Similiar to the paymentAmount feld, the additionalAmount is specifed in minor units, without a decimal separator. • customPaymentMethod The Custom Payment Method used. • paymentMethod The payment method used, this is the same value as customPaymentMethod. • merchantSig The signature computed over the above values in Base64 encoded format.
-
3. CVC-Only Repeat Payments If a signifcant portion of your business consists of returning shoppers you can use the CVC-Only functionality of the Adyen Payment System to store the card details used by shoppers. Returning shoppers will have the option to pay using a previously stored card by simply flling in the card's security code (CVC/CVV) and confrming the purchase. 3.1. Setting Up the Payment The payment session is set up just like a regular payment.
-
4. Testing Adyen provides a number of card numbers and accounts for testing purposes. These can be found here: https://support.adyen.com/index.php?/Knowledgebase/Article/View/11/0 4.1. Testing AVS Results It is possible to test the 27 diferent AVS result codes. Set the street feld of the billingAddress element to the value “Test AVS result” and specify the avsResult value that you want to test, in the houseNumberOrName feld.
-
• • • • • INVALID_CARD NOT_SUPPORTED NOT_3D_AUTHENTICATED NOT_ENOUGH_BALANCE APPROVED Please note: • There is a limit in characters of the Card Holder Name. The result may be: DECLINED : 05 : ISSUER_UNAVAIL • You may have to lower the risk score for non-alphabetic characters in the card holder name as the ':' character will trigger this check and may cause the payment to be declined with reason code "FRAUD".
-
5. Modifcations In this section we will describe the possible modifcation actions. It is possible to perform modifcations using your account on the Adyen CA. However, we recommend automating this if you are processing more than a handful of payments daily. For this we ofer a SOAP and REST web service which accepts the modifcation requests from your backofce systems. To submit modifcation messages you must supply authentication credentials. The username is ws@Company.
-
• modifcationAmount The amount to capture. This consists of a currency and a value which is the amount in minor units. Please refer to section 2.2 for more information. The currency must match that of the original payment request, and the value must be less than or equal to the authorised amount. • originalReference This is the pspReference that was assigned to the authorisation. You will have received it with the payment status or the authorisation notifcation.
-
• pspReference This is a new unique reference that Adyen has associated with the modifcation request. This is guaranteed to be globally unique. • response The response. If successful, this will be [cancel-received]. If there is an error, we will return a SOAP Fault. The fnal result of the cancellation is sent via a notifcation with the eventCode “CANCELLATION”. The pspReference of this notifcation is the same as the pspReference in the SOAP response.
-
5.4. Cancel or Refund If you do not know if a payment has been captured but you want to reverse the authorisation you can send a modifcation request to the cancelOrRefund action using the following felds: • merchantAccount The merchant account used to process the payment. • originalReference This is the pspReference that was assigned to the authorisation. You will have received it with the payment status or the authorisation notifcation.
-
6. API Fault Codes In the following situations the Adyen platform does not accept or store a submitted request: • If the request does not pass validation. • If the request violates a security constraint. • If the request confguration constraint. Instead you will receive a SOAP Fault which will contain a description of the problem. Generally this will be handled as an Exception in your SOAP toolkit.
-
7. Notifcations Whenever a payment is made, a modifcation is processed or when a report is available for download, we will notify you of the event and whether or not it was performed successfully. Notifcations should be used to keep your backofce systems up to date with the status of each payment and modifcation. Notifcations are sent using either a SOAP call or using HTTP POST parameters to a server, that you host, that will receive and accept the notifcations.
-
◦ REQUEST_FOR_INFORMATION. ◦ NOTIFICATION_OF_CHARGEBACK. ◦ ADVICE_OF_DEBIT. ◦ CHARGEBACK. ◦ CHARGEBACK_REVERSED. For more information about Disputes please refer to the Merchant Manual. Please note that the success feld in a CHARGEBACK_REVERSED notifcation will always be set to true. Other Events ◦ REPORT_AVAILABLE. For more information please refer to the Adyen Reporting Manual.
-
the URL where the report can be downloaded from. • amount The amount, if applicable, associated with the payment or modifcation. This consists of a currencyCode and a value which is the amount in minor units. For HTTP POST notifcations, you will receive the currency and value as parameters. For SOAP notifcations a notifcation message is a container for an array of notifcation items, meaning that you may receive multiple notifcations within a single message.
-
Appendix A: TEST and LIVE URLs TEST URLs Adyen Customer Area (CA) https://ca-test.adyen.com/ Hosted Payment Pages (Multiple): https://test.adyen.com/hpp/select.shtml Hosted Payment Pages (Single): https://test.adyen.com/hpp/pay.shtml Directory Lookup: https://test.adyen.com/hpp/directory.shtml Modifcation SOAP Service https://pal-test.adyen.com/pal/servlet/soap/Payment Modifcation SOAP Service WSDL https://pal-test.adyen.com/pal/Payment.wsdl Notifcation SOAP Service WSDL https://ca-test.adyen.
-
Appendix B: JSON Response To Directory Lookup { "paymentMethods" : [ { "brandCode" : "paypal", "name" : "PayPal" }, { "brandCode" : "ideal", "name" : "iDEAL", "issuers" : [ { "name" : "Test Issuer 7", "issuerId" : "1156" }, { "name" : "Test Issuer 6", "issuerId" : "1155" }, { "name" : "Test Issuer 9", "issuerId" : "1158" }, { "name" : "Test Issuer 8", "issuerId" : "1157" }, { "name" : "Test Issuer 10", "issuerId" : "1159" }, { "name" : "Test Issuer", "issuerId" : "1121" }, { "name" : "Test Issuer 4", "issue
-
{ "name" : "Test Issuer Pending", "issuerId" : "1161" }, { "name" : "Test Issuer Cancelled", "issuerId" : "1162" } ] }, { "brandCode" : "mc", "name" : "MasterCard" }, { "brandCode" : "visa", "name" : "VISA" } ] } 30 / 48 Integration Manual
-
Appendix C: Computing the HMAC The signature is computed using the HMAC algorithm with the SHA-1 hashing function3. The data passed, in the form felds, is concatenated into a string, referred to as the “signing string”. The HMAC signature is then computed over using a key that is specifed in the Skin settings. The signature is passed along with the form data and once Adyen receives it, we use the key to verify that the data has not been tampered with in transit.
-
Payment Result The payment result uses the following signature string: authResult + pspReference + merchantReference + skinCode + merchantReturnData The example from section 2.1.2 would provide us with the following signing string. AUTHORISED1211992213193029Internet Order 123454aD37dJA If the shared secret is Kah942*$7sdp0), the resulting signature is (base64 encoded): ytt3QxWoEhAskUzUne0P5VA9lPw= Please note, shopperLocale is passed as a parameter but is not used in the signing string.
-
Appendix D: SOAP Modifcation Request and Response Capture Modifcation Request YourMerchant PAGE 34
Appendix E: REST Modifcation Request and Response Capture Modifcation Request modificationRequest.merchantAccount=SupportAdyenTest&action=Payment.capture&modificationRequest.or iginalReference=8513939253477759&modificationRequest.reference=test1234&modificationRequest.modifi cationAmount.currency=EUR&modificationRequest.modificationAmount.value=1234 Modifcation Response modificationResult.pspReference=8813939274346857&modificationResult.
-
Appendix F: SOAP Modifcation Request and Response Cancel Modifcation Request YourMerchant PAGE 36
Appendix G: REST Modifcation Request and Response Cancel Modifcation Request modificationRequest.merchantAccount=SupportAdyenTest&modificationRequest.reference=test1234&action =Payment.cancel&modificationRequest.originalReference=7913939284323855 Modifcation Response modificationResult.pspReference=7913939287424924&modificationResult.
-
Appendix H: SOAP Modifcation Request and Response Refund Modifcation Request YourMerchant PAGE 38
Appendix I: REST Modifcation Request and Response Refund Modifcation Request modificationRequest.merchantAccount=SupportAdyenTest&action=Payment.refund&modificationRequest.ori ginalReference=8513939253477759&modificationRequest.reference=test1234&modificationRequest.modific ationAmount.currency=EUR&modificationRequest.modificationAmount.value=1234 Modifcation Response modificationResult.pspReference=7913939278088951&modificationResult.
-
Appendix J: SOAP Modifcation Request and Response CancelOrRefund Modifcation Request YourMerchant PAGE 40
Appendix K: REST Modifcation Request and Response CancelOrRefund Modifcation Request modificationRequest.merchantAccount=SupportAdyenTest&modificationRequest.reference=test1234&action =Payment.cancelOrRefund&modificationRequest.originalReference=8613939281189367 Modifcation Response modificationResult.pspReference=8613939284241702&modificationResult.
-
Appendix L: CVC/CVV and AVS Result Values CVC/CVV Result Values 0 Unknown 1 Matches 2 Doesn't match 3 Not checked 4 No CVC/CVV provided, but was required 5 Issuer not certifed for CVC/CVV 6 No CVC/CVV provided AVS Result 0 Unknown 1 Address matches, postal code doesn't 2 Neither postal code nor address match 3 AVS unavailable 4 AVS not supported for this card type 5 No AVS data provided 6 Postal code matches, address doesn't match 7 Both postal code and address match 8 Address
-
Appendix M: SOAP Notifcation Request and Response SOAP Notifcation Request false PAGE 43
SOAP Notifcation Response PAGE 44
Appendix N: REST Notifcation Request and Response REST Notifcation Request eventDate=2012-0925T13%3A41%3A33.
-
Appendix O: Fault Codes Error Code Fault 000 Unknown 010 Not allowed 100 No amount specifed 101 Invalid card number 102 Unable to determine variant 103 CVC is not the right length 104 Billing address problem 105 Invalid paRes from issuer 106 This session was already used previously 107 Recurring is not enabled 108 Invalid bankaccount number 109 Invalid variant 110 BankDetails missing 111 Invalid BankCountryCode specifed 112 This bank country is not supported 113 No InvoiceLi
-
Error Code Fault 133 Billing address problem (HouseNumberOrName) 134 Billing address problem (Country) 135 Billing address problem (StateOrProvince) 136 Failed to retrieve OpenInvoiceLines 137 Invalid amount specifed 138 Unsupported currency specifed 139 Recurring requires shopperEmail and shopperReference 140 Invalid expiryMonth[1..12] / expiryYear[>2000], or before now 141 Invalid expiryMonth[1..
-
Error Code Fault 180 Invalid shopperReference 181 Invalid shopperEmail 182 Invalid selected brand 183 Invalid recurring contract 184 Invalid recurring detail name 185 Invalid additionalData 186 Missing additionalData feld 187 Invalid additionalData feld 188 Invalid pspEchoData 600 No InvoiceProject provided 601 No InvoiceBatch provided 602 No creditorAccount specifed 603 No projectCode specifed 604 No creditorAccount found 605 No project found 606 Unable to create InvoicePro
-
Error Code Fault 906 Invalid Request: Original pspReference is invalid for this environment! 950 Invalid AcquirerAccount 951 Confguration Error (acquirerIdentifcation) 952 Confguration Error (acquirerPassword) 953 Confguration Error (apiKey) 954 Confguration Error (redirectUrl) 955 Confguration Error (AcquirerAccountData) 956 Confguration Error (currencyCode) 957 Confguration Error (terminalId) 958 Confguration Error (serialNumber) 959 Confguration Error (password) 960 Confguration
