Adyen APIManual

API Manual

Contact details Simon Carmiggeltstraat 6-501011 DJ Amsterdam

P.O. Box 100951001 EB AmsterdamThe Netherlands

T +31 20 240 1240

E [email protected]

Version: 3.06

mailto:[email protected]



Table of Contents1. Introduction...............................................................................................................................................................................................................................................................................................................................................7

1.1. PCI Compliance.........................................................................................................................................................................................................................................................................................................................7

1.2. JSON API................................................................................................................................................................................................................................................................ .......................................................................7

2. Submitting API Payments..................................................................................................................................................................................................................................................................................................................8

2.1. Payment Fields3................................................................................................................................................................................................................................................................ ......................................................8

2.1.1. General Payment Fields........................................................................................................................................................................................................................................................................................8

2.1.2. Card Payment Specific Fields................................................................................................................................................................................................................................................................ ............9

2.1.3. Payment Response Fields....................................................................................................................................................................................................................................................................................9

2.2. Client-Side Encryption (CSE) (optional)................................................................................................................................................................................................................................................................ ..10

2.2.1. How Does It Work?................................................................................................................................................................................................................................................................................................10

2.2.2. Additional Payment Fields................................................................................................................................................................................................................................................................ ...............11

2.2.3. Where Can I Find My Public Key?.................................................................................................................................................................................................................................................................11

2.2.4. Is CSE Secure?................................................................................................................................................................................................................................................................ .........................................12

2.2.5. Main Benefits................................................................................................................................................................................................................................................................ ...........................................12

2.3. 3-D Secure................................................................................................................................................................................................................................................................................................................................12

2.4. AVS................................................................................................................................................................................................................................................................ ................................................................................14

2.5. Testing AVS and CVC/CVV Results...............................................................................................................................................................................................................................................................................14

2.5.1. Testing AVS Results................................................................................................................................................................................................................................................................ ..............................14

2.5.2. Testing CVC/CVV Results....................................................................................................................................................................................................................................................................................15

2.5.3. Testing Error Codes...............................................................................................................................................................................................................................................................................................15

2.6. BIN Data and Card Verification.....................................................................................................................................................................................................................................................................................16

2.6.1. Submitting a BIN/Card Verification Request......................................................................................................................................................................................................................................... 16

2.6.2. Receiving a BIN/Card Verification Response......................................................................................................................................................................................................................................... 16

2.7. MasterCard Authorisation Flagging................................................................................................................................................................................................................................................................ ...........17

2.8. Installments.............................................................................................................................................................................................................................................................................................................................17

2.9. Additional Payment Response Data................................................................................................................................................................................................................................................................ ..........17

2.10. Authorisation Responses...............................................................................................................................................................................................................................................................................................18

3. One-Click Payments...........................................................................................................................................................................................................................................................................................................................20

3.1. The Initial Payment.............................................................................................................................................................................................................................................................................................................20

3.2. Submitting A One-Click Payment................................................................................................................................................................................................................................................................................20

4. Card Deposit (CFT)................................................................................................................................................................................................................................................................ .............................................................21

4.1. Card Deposit Using An Existing Transaction........................................................................................................................................................................................................................................................21

4.2. Directly Depositing Funds On A Card................................................................................................................................................................................................................................................................ .......21

4.3. CFT Notifications................................................................................................................................................................................................................................................................ ..................................................22

5. Direct Debit Payments................................................................................................................................................................................................................................................................ .....................................................23

5.1. US ACH Payments.................................................................................................................................................................................................................................................................................................................23

5.1.1. ACH Transaction Types........................................................................................................................................................................................................................................................................................23

5.1.2. ACH Response..........................................................................................................................................................................................................................................................................................................23

5.1.3. ACH Chargebacks...................................................................................................................................................................................................................................................................................................23

5.2. SEPA Direct Debits...............................................................................................................................................................................................................................................................................................................23

5.2.1. One-off SDD Payment Requests................................................................................................................................................................................................................................................................ ...24

5.2.2. Recurring SDD Payment Requests...............................................................................................................................................................................................................................................................24

5.2.3. SDD Notifications................................................................................................................................................................................................................................................................ ..................................25

5.2.4. SDD Settlement Timeline.................................................................................................................................................................................................................................................................................26

5.2.5. SDD Chargebacks................................................................................................................................................................................................................................................................ ..................................26

6. Boleto Bancário....................................................................................................................................................................................................................................................................................................................................27

http://www.w3.org/Protocol2 / 88

API Manual

6.1. Boleto Notifications............................................................................................................................................................................................................................................................................................................27

6.2. Important Information Regarding Storage Of The Boleto PDF.................................................................................................................................................................................................................27

7. Modifications..........................................................................................................................................................................................................................................................................................................................................29

7.1. Capture........................................................................................................................................................................................................................................................................................................................................29

7.2. Cancel................................................................................................................................................................................................................................................................ ..........................................................................30

7.3. Refund................................................................................................................................................................................................................................................................ .........................................................................30

7.4. Cancel or Refund................................................................................................................................................................................................................................................................ ...................................................31

8. Idempotency................................................................................................................................................................................................................................................................ ..........................................................................32

8.1. Idempotency Implementation................................................................................................................................................................................................................................................................ ......................32

8.1.1. What happens when a request is resubmitted idempotently?...................................................................................................................................................................................................32

8.1.2. The RETRY notification................................................................................................................................................................................................................................................................ ......................33

9. Notifications...........................................................................................................................................................................................................................................................................................................................................34

9.1. Notification Message Fields...........................................................................................................................................................................................................................................................................................34

9.2. Accepting Notifications.....................................................................................................................................................................................................................................................................................................36

9.3. Retrying Notifications........................................................................................................................................................................................................................................................................................................37

10. Response Handling................................................................................................................................................................................................................................................................ .........................................................38

10.1. Handling 200 responses................................................................................................................................................................................................................................................................ ...............................38

10.2. Handling 4xx and 5xx responses.............................................................................................................................................................................................................................................................................38

Appendix B: Examples Payment Request and Response..................................................................................................................................................................................................................................................40

Appendix C: CSE Source Libraries Used......................................................................................................................................................................................................................................................................................42

Appendix D: CSE Sample Encrypted Form................................................................................................................................................................................................................................................................ ................43

Appendix E: Integration Example – CSE................................................................................................................................................................................................................................................................ ....................45

Appendix F: Integration Example – Server-Side................................................................................................................................................................................................................................................................ ...46

Appendix G: Authorise3d Request................................................................................................................................................................................................................................................................ .................................47

Appendix H: BIN Data and Card Verification............................................................................................................................................................................................................................................................................48

Appendix I: Payment Request with MasterCard Flagging................................................................................................................................................................................................................................................53

Appendix J: Payment Request with Installments................................................................................................................................................................................................................................................................ ..55

Appendix K: CVC/CVV and AVS Result Values..........................................................................................................................................................................................................................................................................57

Appendix L: ACH Payment Request................................................................................................................................................................................................................................................................ ...............................58

Appendix M: SEPA Direct Debit One-off Payment Request and Response............................................................................................................................................................................................................ 60

Appendix N: SEPA Direct Debit Recurring Payment Request ......................................................................................................................................................................................................................................... 63

Appendix O: Boleto JSON API Payment Request and Response...................................................................................................................................................................................................................................64

Appendix P: Sample Boleto Forms................................................................................................................................................................................................................................................................ ................................68

Appendix Q: Modification Request and Response - Capture.......................................................................................................................................................................................................................................... 70

Appendix R: Modification Request and Response - Cancel............................................................................................................................................................................................................................................. 72

Appendix S: Modification Request and Response - Refund.............................................................................................................................................................................................................................................74

Appendix T: Modification Request and Response - CancelOrRefund.........................................................................................................................................................................................................................76

Appendix U: Notification Request and Response..................................................................................................................................................................................................................................................................78

Appendix V: Fault Codes................................................................................................................................................................................................................................................................ ......................................................81

Appendix W: Minor Units for Currencies................................................................................................................................................................................................................................................................ ....................86


API Manual

ADYEN CONFIDENTIAL INFORMATION

Copyright (c) 2015 Adyen B.V.

ChangelogVersion Date Changes

3.06 2015-04-28 • Edited: Idempotency Implementation to clarify Pragma: pragma-directive HTTP header usage

3.05 2015-04-07 • Added optional field to payment request• Minor content edits, fixes to code examples in Appendices

3.04 2015-03-24 • Edited:• Additional Payment Fields• Sections 7.2, 7.3, and 7.4: returned refund eventCode changed to CANCEL_OR_REFUND.

3.03 2015-03-11 • Modifying reference to correct external manual• Fixing some inconsistencies with notifications and links

3.02 2015-02-16 • BIC field is no longer mandatory for SEPA Direct Debit (SDD). Removed from manual and relevant code examples.

3.01 2015-02-04 • Card Verification/Dynamic Zero Value Auth renamed to: BIN Data and Card Verification• (Appendix) Zero-Auth Request and Response renamed to: BIN Data and Card Verification• Edited the following content:◦ Submitting a BIN/Card Verification Request◦ Receiving a BIN/Card Verification Response◦ (Appendix) BIN Data and Card Verification: added JSON and SOAP code examples including addAdditionalData object.

3.00 2014-12-05 • Manual redesign

2.18 2014-11-20 • Added optional field 'shopperInteraction'• Added appendix with exponent for minor units of currencies

2.17 2014-11-06 • Added section for MasterCard authorisation flagging

2.16 2014-11-04 • Updated optional fields in Payment request• Update section 'Card Verification'

2.15 2014-10-16 • Removed optional functionality

2.14 2014-08-28 • Added code for inserting line breaks to section 7 and updated examples in Appendices P and Q• Corrected typo in REST example of Appendix J

2.13 2014-04-30 • Updated Introduction to include PCI compliance section• Added Transient errors and Idempotency section• Updated authorise REST API examples

2.12 2014-01-15 • Added note about testing CVC/CVV results• Added SEPA DD section• Added note on submitting amount value• Updated installments appendix

2.11 2013-11-27 • Added note about testing AVS results

2.10 2013-11-22 • Added additional information regarding response codes to the AVS section

2.00 2013-11-14 • Combined SOAP and REST manuals• Added Client Side Encryption• Updated document to conform to Adyen brand guidelines


API Manual

1.39 2013-09-13 • Added card verification and idempotency documentation• Moved ELV to direct debit chapter• Removed deprecated iDeal API

1.38 2013-03-18 • Added note about correct XML for SOAP Payment Request with installments

1.37 2012-11-12 • Added Received as possible responseCode

1.36 2012-10-19 • Added additional AVS result codes

1.35 2011-12-15 • Added information about not using LATEST with ONECLICK

1.34 2011-08-31 • Added API Payment Response

1.33 2011-02-16 • Added details about new selectedBrand parameter

1.32 2010-12-30 • Added ACH US direct debits

1.31 2010-12-21 • Added section on Installments

1.30 2010-12-03 • Added general Tips and Warnings

1.21 2010-07-16 • Added changelog and audience sections• Manual reviewed for English and layout consistency


API Manual

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

The latest version of this document is available here:https://support.adyen.com/links/documentation

Cautionary NoteDefensive Programming

Adyen strongly recommends the use of “defensive programming” when integrating with the Adyen platform. This means that automated decisions programmed into your systems should be defaulted to non-delivery of products and services. In other words, program your systems to only deliver products and/or services after receiving an explicit authorisation of the requested payment and NOT to deliver in situations where an explicit response is not received.

FeedbackWe are constantly working to update and improve our documentation, and would be delighted to hear your feedback at: [email protected]

We appreciate your comments.


API Manual


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

1. IntroductionThis manual will show you how to process payments using the Adyen Payment System direct API, including how to submit payments and payment modifications to our platform using Adyen's API with JSON request/response messages1.

Before we begin, a short note: 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 its DNS configuration. If your implementation caches the DNS lookup, your ability to submit modifications and/or payments may be impacted.

For your reference, Adyen has code samples in various programming languages available on Github, which can be found at this link: https://github.com/adyenpayments.

A Brief Look At Adyen Integrations Besides the direct API, Adyen offers two other integrations that may be of interest to readers of this manual.

Hosted Payment Pages (HPP) is an integration which can be used instead of (or alongside) the direct API. Most non-card payment methods are only available using the HPP, and a significant advantage of this solution is that by using the HPP for card payments you can avoid almost all of the burden of PCI DSS compliance.

Client-Side Encryption is an integration in which shoppers complete the full card payment transaction on your website or in your application. The direct API can be used with Client-Side Encryption (CSE) to encrypt card data inside the client (web browser or mobile app), making PCI DSS compliance significantly easier. We cover CSE in more detail in section 2.2.

Please note that the ability to process API payments or Client-Side Encryption payments are not enabled by default. Contact the Adyen Support Team ([email protected]) if you would like to have these functionalities enabled.

1.1. PCI ComplianceDue to strict industry regulations, submitting card payments using the direct API is only available to merchants who have full Payment Card Industry Data Security Standard (PCI DSS)2 compliance and fall into either the Level 1 or Level 2 categories. Furthermore, certain implementations of the API may require that you process minimum annual transaction volumes. Adyen sales representatives are available to help you understand PCI DSS regulations, and advise you further regarding API and transaction volume requirements. Please don't hesitate to get in touch regarding questions around these topics.

1.2. JSON APIJSON or JavaScript Object Notation, is an open standard format that uses human-readable text to transmit data objects consisting of attribute–value pairs. It is used primarily to transmit data between a server and web application, as an alternative to XML. To submit JSON messages over HTTPS to our API endpoint, the content-type of the request must be set to “application/json” and the request data should use UTF-8 character encoding.

To submit authorisation messages you must supply authentication credentials (username/password). This will be configured in the library that you use to communicate the server-to-server request, or response, to the Adyen platform.

The username is ws@Company.[YourCompanyAccount] and you set the password for this user in the Adyen Customer Area (CA) under “Settings” → “Users”.

1It is also possible to submit these messages using SOAP or plain HTTP parameters. Implementation details and examples for these message formats are documented in the appendices. 2Please see http://en.wikipedia.org/wiki/PCI_DSS for more information.


API Manual

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


https://github.com/adyenpayments

2. Submitting API PaymentsAPI payments are submitted using the authorise action. We will explain a simple credit card submission, and in subsequent sections we will show you how to implement “Verified by VISA / MasterCard SecureCode™” (3-D Secure) and Direct Debits.

2.1. Payment Fields3

2.1.1. General Payment Fields• merchantAccount

The merchant account for which you want to process the payment.

• amountA container for the data concerning the amount to be authorised. This should contain the following items:

• currencyThe three character ISO currency code.

• valueThe paymentAmount of the transaction.

Please note, the transaction amount should be provided in minor units; some currencies don't have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP would be submitted with a value of “1000” and 10 JPY would be submitted as “10”. Please, refer to Appendix W for a complete list of currencies and their number of decimal points (exponents) used by Adyen.

• referenceThis is your reference for this payment, which will be used in all communication to you regarding the status of the payment. We recommend using a unique value per payment but this is not a requirement. If you need to provide multiple references for a transaction you may use this field to submit them with the transaction, separating each with “-”.

This field has a maximum of 80 characters.

• shopperIP (recommended)The IP address of the shopper. We recommend that you provide this data, as it is used in a number of risk checks, for example, number of payment attempts, location based checks.

• shopperEmail (recommended)The shopper's email address. We recommend that you provide this data, as it is used in a velocity fraud check.

Please note, this field is required for Recurring payments.

• shopperReference (recommended)An ID that uniquely identifies the shopper, such as a customer id in a shopping cart system. We recommend that you provide this data, as it is used in a velocity fraud check and is the key for recurring payments.

Please note, this field is required for Recurring payments.

• fraudOffset (optional)An integer that is added to the normal fraud score. The value can be either positive or negative.

• mcc (optional)The four-digit number merchant category code.

• merchantOrderReference (optional)The reference to link multiple transactions to each other.

• selectedBrand (optional) Used with some payment methods to indicate how it should be processed. For the MisterCash payment method it can be set to maestro (default) to be processed like a Maestro card or bcmc to be processed as a MisterCash

3 Please refer to “Explanation of the Session Fields” section in the Adyen HPP API Manual for more information regarding each of the fields.


API Manual

card.

• shopperInteraction (optional) Used to indicate through which sales channel the shopper gives his card details, and/or whether he is a returning customer. For the web service API, Adyen will, by default, assume e-commerce shopper interaction. The shopperInteraction field includes the following possible fields:

◦ Ecommerce Online transactions, where the cardholder is present (online). For better authorization rates, it's recommended to send along the Card security code (CSC) with the request.

◦ ContAuth Card on file and/or subscription transactions, where the card holder is known to the merchant (returning customer). In case the shopper is present (online), the CSC can also be supplied in order to improve authorization (one-click payment, see 3.2).

◦ POS Point-of-sale transactions, where the shopper is physically present making a payment using a secure payment terminal.

◦ Moto Mail-order and telephone-order transactions, where the shopper is in contact with the merchant via mail or telephone.

JSON fields consist of attribute-value pairs separated by commas. In more complex structures like the amount, the value of an attribute is rendered in a list of other attribute-value pairs delimited in curly brackets:

JSON representation of an amount:

"amount": { "currency": "EUR", "value": 1500}

2.1.2. Card Payment Specific Fields• card

A container for credit card data, this object should not be populated when using Client-Side Encryption. This should contain the following items:

• expiryMonthThe expiration date's month written as a 2-digit string, padded with 0 if required. For example, 03 or 12.

• expiryYearThe expiration date's year written as in full. For example, 2016.

• holderNameThe card holder's name, as embossed on the card.

• numberThe card number.

• cvcThe card validation code. This is the CVC2 code (for MasterCard), CVV2 (for Visa) or CID (for American Express).

• issueNumber (Maestro UK / Solo only)This field is no longer in use.

• startMonth (Maestro UK / Solo only)This field is no longer in use.

• startYear (Maestro UK / Solo only)This field is no longer in use.

2.1.3. Payment Response FieldsIf the message passes validation a risk analysis will be done and, depending on the outcome, an authorisation will be attempted. You will receive a response with the following fields:


API Manual

• pspReferenceThis is Adyen's unique reference that is associated with the payment. This is guaranteed to be globally unique and is used when communicating with us about this payment.

• resultCodeThe result of the payment. The possible values are Authorised, Refused, Error or Received.

• authCodeThe authorisation code if the payment was successful. Blank otherwise.

• refusalReasonAdyen's mapped refusal reason, populated if the payment was refused.

Please refer to Appendix B for a set of examples of API requests and responses.

2.2. Client-Side Encryption (CSE) (optional)Merchants that require more stringent security protocols or do not want the additional overhead of managing their PCI compliance, may decide to implement Client-Side Encryption (CSE). This is particularly useful for Mobile payment flows where only cards are being offered, as it may result in faster load times and an overall improvement of the shopping flow.

If you would like to implement CSE, please provide the completed PCI Self Assessment Questionnaire (SAQ) A to the Adyen Support Team ([email protected]). The form can be found here:https://www.pcisecuritystandards.org/security_standards/documents.php?category=saqs

Transactions that are submitted using Client-Side Encrypted card details follow the same process as a regular authorisation request. However, instead of the card object, the encrypted data is sent in the additional data fields described in section 2.2.2.

The Adyen GitHub repo features a number of code samples.

2.2.1. How Does It Work?To implement CSE, follow this high-level procedure:

1. Build and host the credit card payment form on your servers.

2. Ensure that the card fields have the attribute data-encrypted-name instead of name; the use of name may result in the raw card data to be posted to your servers.

3. Include the adyen.encrypt.min.js Client Encryption library.

4. Set the Adyen public key and tie the Adyen library to your form.

The Client Encryption library does the following:

1. Intercepts the form submission event before it hits your server.

2. Encrypts the card fields in-browser using a per-transaction unique AES key.

3. Encrypts the unique AES key with your RSA public key; Adyen retains its private counterpart.

4. Sends the encrypted data containing the card data and the encrypted AES key with the other fields in the form via the server-to-server API.

Note: the encrypted data must not be stored on your servers or be available in your logs, as this would be a violation of PCI regulations.


API Manual

https://github.com/Adyen/CSE-JS

https://www.pcisecuritystandards.org/security_standards/documents.php?category=saqs


2.2.2. Additional Payment FieldsTo implement CSE, you need to include two additionalData child fields in the payment form you submit with the request:

• generationtimeThis argument determines the validity of the payment request. Transactions submitted more than 24 hours after the generation timestamp are refused.

It takes values in ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ. For example: 2013-11-15T13:42:40.428Z.The generation time value must be generated server-side, as the client (web browser) may not have its system clock synchronised correctly, and this could cause the payment to fail.

• adyen-encrypted-dataThis field holds the encrypted card data: card number, cvc, card holder, and expiry date.The Adyen client encryption library encrypts the card data when the shopper submits the payment form, and it sends the encrypted data to the payment form action handler as an adyen-encrypted-data string.

To use this data in a payment request, assign the adyen-encrypted-data value to the card.encrypted.json element when you send the request.Make sure the card.encrypted.json element is a child of the additionalData element.

Please refer to this HTML payment form example for a sample implementation, and to Appendix E: Integration Example – CSE for a set of examples that walk you through a sample client-side encryption integration.

Please refer to Appendix F: Integration Example – Server-Side for a payment request example.

2.2.3. Where Can I Find My Public Key? The public key is tied to the WebService user you will be using to submit the API payment request. If a key has not previously been generated, you will see an option to “Generate” the key. The generated key is pre-formatted for easy insertion into your page.


API Manual

https://github.com/Adyen/CSE-JS/blob/master/adyen.encrypt.simple.html

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

2.2.4. Is CSE Secure?The CSE solution uses only PCI/NIST approved cryptographic algorithms. The RSA key is 2048 bits and is unique to your user account. Per transaction the client will generate a unique AES (256bit) key which is used in CCM mode for both encryption and authentication.

• The Public Key (RSA) can be downloaded from the Adyen CA.

• The Secret Key (RSA) is only known to Adyen and stored in encrypted form on Adyen's servers.

• All card data is End-To-End encrypted and is never visible to merchant.

• The payment authorisation is done over the server-to-server Adyen API using the encrypted card.

• The encrypted data is only valid for a period of 24 hours and tied to your public key. It is of no use outside of this context.

2.2.5. Main Benefits• The credit card data is never readable to you.

• Stateless, synchronous processing; the solution does not rely on a session token.

• Uses the current API therefore all features are available, including:

◦ 3D Secure.

◦ Recurring.

◦ Installments.

◦ Airline / Level 3 Data.

◦ Risk/Fraud Detection.

2.3. 3-D Secure3D Secure (Verified by VISA / MasterCard SecureCode™) is an additional authentication protocol that involves the shopper being redirected to their card issuer where their identity is authenticated prior to the payment proceeding to an authorisation request.

In order to start processing 3D Secure transactions, the following changes are required:

1. Your Merchant Account needs to be configured by Adyen to support 3D Secure. If you would like to have 3D Secure enabled, please submit a request to the Adyen Support Team ([email protected]).

2. Your integration should support redirecting the shopper to the card issuer and submitting a second API call to complete the payment.

The initial API call for both 3D Secure and non-3D Secure payments is almost identical. However, for 3D Secure payments, you must supply the browserInfo object as a sub-element of the payment request. This is a container for the acceptHeader and userAgent of the shopper's browser.

JSON example:

"browserInfo" : { "userAgent" : "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0", "acceptHeader" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"}

Once your account is configured for 3-D Secure, the Adyen system performs a directory inquiry to verify that the card is enrolled in the 3-D Secure programme. If it is not enrolled, the response is the same as a normal API authorisation. If, however, it is enrolled, the response contains these fields:

• paRequestThe 3-D request data for the issuer.


API Manual


• mdThe payment session.

• issuerUrlThe URL to direct the shopper to.

• resultCode

The resultCode will be RedirectShopper.

The paRequest and md fields should be included in an HTML form, which needs to be submitted using the HTTP POST method to the issuerUrl. You must also include a termUrl parameter in this form, which contains the URL on your site that the shopper will be returned to by the issuer after authentication. We recommend that the form is “self-submitting” with a fallback in case javascript is disabled. A sample form is shown below.

<body onload="document.getElementById('3dform').submit();"><form method="POST" action="${issuerUrl}" id="3dform"><input type="hidden" name="PaReq" value="${paRequest}" /><input type="hidden" name="TermUrl" value="${termUrl}" /><input type="hidden" name="MD" value="${md}" /><noscript> <br/> <br/> <div style="text-align: center"> <h1>Processing your 3-D Secure Transaction </h1> <p>Please click continue to continue the processing of your 3-D Secure transaction.</p> <input type="submit" class="button" value="continue"/> </div> </noscript> </form></body>

After the shopper's identity is authenticated by the issuer, they will be returned to your site by sending an HTTP POST request to the TermUrl containing the MD parameter as explained previously and a new parameter called PaRes. These will be needed to complete the payment.

To complete the payment, the following parameters should be submitted to the authorise3d action:

• merchantAccountThis should be the same as the Merchant Account used in the original authorise request.

• browserInfoIt is safe to use the values from the original “authorise” request, as they are unlikely to change during the course of a payment.

• mdThe value of the MD parameter received from the issuer.

• paResponseThe value of the PaRes parameter received from the issuer.

• shopperIP (recommended)The IP address of the shopper. We recommend that you provide this data, as it is used in a number of risk checks, for example, the number of payment attempts and location based checks.

Please refer to Appendix G for an example of an authorise3d request.


API Manual

2.4. AVSAddress Verification Service (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, card types, and only for a limited set of countries (United States, Great Britain and Canada).

To use AVS you must supply the full address of the shopper using the billingAddress4 sub-element of the payment request.

"billingAddress": { "street": "South Buena Vista Street", "houseNumberOrName": "500", "postalCode": "91521", "city": "Burbank", "stateOrProvince": "California", "country": "US"}

Please note:

• If you are submitting the billingAddress object all the sub-elements are mandatory. If some fields are not provided you will receive an error response.

• The country value must be provided as the 2-character ISO country code, for example, “GB” for the Great Britain. An invalid country code may result in the payment request being rejected. The full list is available here:http://www.iso.org/iso/english_country_names_and_code_elements

• The various card brands and networks have their own specific AVS response codes. These are mapped to Adyen's generic response codes that are sent to you by default. If you would like to receive the actual response from the card or network, please contact the Adyen Support Team ([email protected]) to have the Raw AVS Reason enabled for you. This will be included in the Notification that you receive.

2.5. Testing AVS and CVC/CVV Results2.5.1. Testing AVS ResultsIt is possible to test the 27 different AVS result codes. If the street field of the billingAddress element has the value “Test AVS result” you can specify the avsResult value in the houseNumberOrName field. Note that all other billingAddress fields are still required but their values do not impact the avsResult that is returned.

Please refer to Appendix K for the complete list of AVS result codes.

JSON billingAddress element:

"billingAddress": { "street": "South Buena Vista Street", "houseNumberOrName": "500", "postalCode": "91521", "city": "Burbank", "stateOrProvince": "California", "country": "US"}

Please note, when testing the AVS results it is important to ensure that you are using one of the AVS test card numbers found here:https://support.adyen.com/index.php?/Knowledgebase/Article/View/11/0

4 billingAddress is no longer a sub-element of the card object, but a sub-element of the payment request


API Manual

https://support.adyen.com/index.php?/Knowledgebase/Article/View/11/0

http://www.iso.org/iso/english_country_names_and_code_elements

2.5.2. Testing CVC/CVV ResultsIt is possible to test the 7 different CVC/CVV result codes. You will need to use one of the Adyen test cards that includes a CVC and instead of inputting the CVC, enter the code you want to simulate.

Please refer to Appendix K for the complete list of CVC/CVV result codes.

JSON card element:

"card": { "number": "4111111111111111", "cvc": "737", "expiryMonth": "8", "expiryYear": "2018", "holderName": "John Smith",}

Please note, when testing the CVC/CVV results it is important to ensure that you are using one of the test card numbers that requires a CVC found here:https://support.adyen.com/index.php?/Knowledgebase/Article/View/11/0

2.5.3. Testing Error CodesIt is possible to test Refused transactions and their specific Refusal reasons by placing the following text in the Card Holder Name:

[Response code] : [The refusal reason raw String that is tested]

For example:

DECLINED : 05 : ISSUER_UNAVAILABLE

Other response codes that are available for testing are:

• REFERRAL• ERROR• BLOCK_CARD• CARD_EXPIRED• DECLINED• INVALID_AMOUNT• INVALID_CARD• NOT_SUPPORTED• NOT_3D_AUTHENTICATED• NOT_ENOUGH_BALANCE• APPROVED

Please note:

• There is a limit in characters of the Card Holder Name. The result may be:

DECLINED : 05 : ISSUER_UNAVAIL

• You may have to lower the risk score for non-alphabetic characters in the card holder name as the ':' character will trigger this check and may cause the payment to be declined with reason code "FRAUD".

• An incorrect CVC or invalid expiry date will override the response code and always lead to a generic "DECLINE".


API Manual

https://support.adyen.com/index.php?/Knowledgebase/Article/View/11/0

2.6. BIN Data and Card VerificationMerchants may need to verify card validity and BIN data. It may be necessary to verify BIN information, for example prior to a sale to apply credit/debit surcharges or promotional offers based on BIN codes.

2.6.1. Submitting a BIN/Card Verification RequestSubmit an authorisation request with a currency value amounting to 0 (zero value auth). Make sure that the currency matches the eventual transaction currency.

A zero value auth requests the Adyen system to submit a card verification call to the Acquirer. The call returns a resultCode whose value can be Authorised, Refused or Error.

Not all Acquirers and Issuers support card verification through zero value auth. When your transactions are routed to an Acquirer that does not support this feature, the Adyen system automatically submits a EUR 1 authorisation, immediately followed by an automatic cancellation of the authorisation. For other currencies, an approximate value equivalent to EUR 1 is used; for example, 1000 Korean Won (KRW), as 1 KRW is too low an amount to be authorised. In this case, the notification message you receive after the authorisation request includes the additionalAmount field to notify the amount used for the card verification (for example, 1000 Korean Won).

If you want to force a card verification request to use a non-zero value, you must include the additionalAmount field to specify the amount to use. The standard amount field value still needs to be 0 to allow the Adyen system to recognize the transaction as a non-zero amount validation, instead of an actual low-value transaction authorisation. This triggers an automated cancellation by the Adyen system after the authorisation. To be accepted by the schemes, the value specified in the additionalAmount field needs to be higher than the currency equivalent of 0.02 USD.

The amount and the additionalAmount fields both take two elements:

JSON format

"amount": { "currency": "EUR", "value": 0},

SOAP format

<amount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">0</value></amount>

2.6.2. Receiving a BIN/Card Verification ResponseA zero value auth response includes details like whether the authorisation request was successful or not, and an error message in case of failure.

It also includes an additionalData object with a cardBin field holding BIN information. The additionalData object needs to be configured to include this data in the response. Please contact the Adyen Support Team ([email protected]) if you wish to enable these fields for your Merchant Account:

• cardPaymentMethodThe card payment method used for the transaction. For example: amex.

• cardIssuingBankThe bank or the financial institution granting lines of credit through card association branded payment cards. This information can be included when available. For example: American Express US Consumer.

• cardIssuingCountry


API Manual


The country where the card was issued. For example: US.

• cardIssuingCurrencyThe currency used in the transaction. For example: USD.

• cardBinThe Bank Identification Number is a six-digit numeric code that links the buyer and their payment card. For example: 373731.

This information is sent also as a notification message following a zero value auth request.

Please refer to Appendix H to review examples of dynamic zero value auth request, and zero value auth requests with additionalAmount and additionalData.

2.7. MasterCard Authorisation FlaggingMasterCard provides two types of authorisation, pre-authorisation (PreAuth) and final-authorisation (FinalAuth). Adyen, by default, handles all MasterCard payment requests as FinalAuth.

If required, you can individually flag any MasterCard payment request to be handled as one of the two authorisation types . Simply, you need to add a new entry with key 'mcAuthorisationType' to the additionalData field of your payment request (please see Appendix I for a for a set of examples). As for the value of the new entry, there are the two possible options (case sensitive) for flagging a MasterCard payment request

• PreAuthFlags the payment request to be handled as pre-authorisation

• FinalAuthFlags the payment request to be handled as final-authorisation

You can also request to have a default authorisation type for all your MasterCard transactions at a Merchant level. To do this please contact the Adyen Support Team ([email protected]).

2.8. InstallmentsSome Acquirers, most notably in South America, support payments by installments. This means the shopper is not charged the full payment amount in one charge, but is charged partial amounts at specified intervals over a fixed period. Please contact the Adyen Support Team ([email protected]) for more details about the Acquirers that support this functionality.

To support installments an additional object must be submitted in the authorise payment request:

• installmentsA container for the installment data.

◦ Value = <the number of installments>The number of installments must be greater than zero.Note: There is normally a limit on the maximum number of installments, for example 24, but this limit is set by the individual Acquirer.

Please refer to Appendix J to review a payment request in which the number of installments is set to 4.

2.9. Additional Payment Response DataIf required, the response can include extra fields in the additionalData object. By default, they are disabled. Please contact the Adyen Support Team ([email protected]) if you wish to enable these fields for your Merchant Account:


API Manual




• authCodeThe authorisation code if the payment was successful. Blank otherwise.

• cvcResultThe CVC result of the payment; please refer to Appendix K for the list of possible values that my be returned.

• avsResultThe AVS result of the payment; please refer to Appendix K for the list of possible values that my be returned.

• referredWhen the payment is referred the value of this field will be true; otherwise the field will not be available. Please note that this is not typically returned for e-commerce transactions.

Where available, you may choose to receive the raw results that we receive from the Acquirer. This is an extra setting that must be enabled for your Merchant Account by the Adyen Support Team ([email protected]). The setting will add the following fields to the additionalData object of the response.

• cvcResultRawThe raw CVC result received from the Acquirer where available.

• avsResultRawThe raw AVS result received from the Acquirer where if available.

• refusalReasonRawThe raw refusal reason received from the Acquirer where available.

2.10. Authorisation ResponsesAfter an authorise request is received a payment response is going to be generated with an HTTP status. A 200 HTTP status response means that the request was submitted correctly and it was processed successfully by Adyen. However, it does not necessarily mean that the payment was authorised. As explained in Section 2.1.3, the field resultCode is part of the response message, which can have one of the following values:

resultCode Description

Authorised The payment was authorised

Refused The payment was refused

Error There was an error in the payment

Cancelled The payment was cancelled

Received The payment was received

RedirectShopper The shopper needs to be redirected

When the payment response includes a resultCode whose value is Refused or Cancelled, a refusalReason field is added; it can take one of the following values:

RefusalReason

Unknown

Approved

Refused

Referral

Blocked Card

Expired Card

Invalid Amount

Invalid Card Number


API Manual


RefusalReason

Issuer Unavailable

Not supported

3D Not Authenticated

Not enough balance

Pending

Acquirer Fraud

Cancelled

Shopper Cancelled

Invalid Pin

Pin tries exceeded

Pin validation not possible

FRAUD

Not Submitted

FRAUD-CANCELLED

Below is a JSON example of a payment requested that was correctly processed (I.e status code 200), but it was refused by the Acquirer.

{"pspReference": "9914177032697735","resultCode": “Refused“,"refusalReason": "Refused",

}

Please see chapter 10 for information about payment responses with 4xx or 5xx HTTP status.


API Manual

3. One-Click PaymentsOne-Click Payments can be used to allow repeat/known shoppers to pay without re-entering their payment details. With One-Click Payments, the shopper is given the opportunity to store their payment details the first time they make a transaction, and these details are then used to reduce the shopper's payment process to “one-click” for subsequent transactions. For One-Click Payments the shopper must enter their credit card's CVC. Currently One-Click payments only work for Card payments.

Please refer to the Adyen Recurring Manual for more details regarding managing and submitting Recurring payments.

3.1. The Initial PaymentThe initial payment, or subsequent payments with different details, are processed as normal payment requests as described in section 2. The only difference is the addition of the Recurring object to the payment request, and that the shopperReference and shopperEmail fields are required.

The Recurring object contains the following fields:

• contract This should be set to ONECLICK.

• recurringDetailName (optional)A short description entered by the shopper to identify their payment details. For example, “My wife's MasterCard”.

If the payment is successful the details are stored.

3.2. Submitting A One-Click PaymentWhen submitting a payment using a payment detail returned from listRecurringDetails, you generate a normal payment request, which follows the same rules as the initial payment. This means that the shopperReference and shopperEmail are required and that a Recurring object should be present and contain the value ONECLICK for the contract field. However, the recurringDetailName should not be supplied.

One additional field is added to the payment request:

• selectedRecurringDetailReferenceThis is the recurringDetailReference you want to use for this payment, the customer will need to provide the CVC for the selected card and so the value LATEST cannot be used.

In the case of a card payment you should supply a card object in the payment request with only the cvc field and value populated.


API Manual

4. Card Deposit (CFT)Card Deposit, also referred to as Card Funds Transfer (CFT), allows you to transfer funds directly onto a credit card. There are two methods to do this:

1. Refund an existing transaction for an amount exceeding the original transaction amount. This does not require you to know the card details, only a reference to the existing transaction.

2. Directly deposit funds on a card without an existing transaction. This requires you to submit the card details and is much like the process for submitting a direct payment.

Both methods are disabled by default. Please contact the Adyen Support Team ([email protected]) if you would like to submit card deposits.

4.1. Card Deposit Using An Existing TransactionTo deposit an amount using an existing transaction send a FundTransferRequest using the fundTransfer action containing the following fields:

• merchantAccountThe merchant account the original payment was processed with.

• modificationAmountThe amount to deposit. This consists of a currencyCode and a paymentAmount5. The currencyCode must match the currency used in the original payment.

• originalReferenceThis is the pspReference that was assigned to the original payment. It is received with the payment status or with the authorisation notification.

• referenceYour reference for this payment. This reference will be used in all communication to you regarding the status of the payment. We recommend using a unique value per payment but this is not a requirement.

• shopperEmail (optional)The shopper's email address.

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

• pspReferenceA new unique reference Adyen has assigned to identify this deposit. This is guaranteed to be globally unique and should be used when communicating with us about this payment.

• responseIf successful, this value returned will be [fundtransfer-received], if unsuccessful an informational message will be returned.

Please note, that [fundtransfer-received] does not mean that the card deposit was successful, it means that Adyen has successfully received the message. The actual transfer is executed offline and the final result communicated using a notification, please see Section 4.3 for details.

4.2. Directly Depositing Funds On A CardThe process to directly deposit funds on to a card, without reference to an existing transaction, is similar to submitting a payment to the API (refer to section 2). The request is exactly the same as for a payment request but the request is submitted to the refundWithData method rather than the authorise method.

5 Please refer to “Explanation of the Session Fields” section in the Adyen HPP API Manual.


API Manual


4.3. CFT NotificationsNotifications for card deposits, using both methods, are the same as for payments but the eventCode is REFUND_WITH_DATA, please refer to the Notifications Section 9. As with regular payments you should check the success parameter to determine if the deposit succeeded.


API Manual

5. Direct Debit Payments5.1. US ACH PaymentsACH (Automated Clearing House) payments are a form of Electronic Direct Debit used in the United States.

The payment request is similar to a credit card request, but rather than supplying a card you supply a bankAccount container with the following fields:

• bankAccountNumberThe US shopper's bank account number, this is a numeric field.

• bankLocationIdThe shopper's bank transit routing number, a nine digit number – leading zeroes should not be stripped out.

• bankAccountTypeThe value 'C' for a checking account or 'S' for a savings account.

• ownerNameThe bank account holder name.

• countryCodeThe value 'US'.

For ACH payments shopperReference and shopperIP are required fields.

5.1.1. ACH Transaction TypesThe ACH transaction types WEB and TEL are supported:

• WEB – Internet-Initiated TransactionsWEB is used when a merchant is authorised by the consumer, via the Internet, to create an ACHP debit. The WEB code applies to both single-entry and recurring payments. WEB transactions must be drawn on a consumer account and are payable in U.S. currency.

• TEL – Telephone-Initiated Transactions TEL may only be used when a consumer initiates contact with the merchant or there is a previously existing relationship between the merchant and the consumer, this is defined as the consumer having made a purchase from the merchant within the past two years.

A transaction's Shopper Interaction will determine how the transaction will be processed; this is configured at the Merchant Account level or using an override per transaction. eCommerce transactions will be processed as WEB, ContAuth will cause the transaction to be processed as WEB recurring and MOTO transactions will be processed as TEL.

Please refer to Appendix L for a sample for a set of examples of ACH Payment request.

5.1.2. ACH ResponseThe response for ACH payments is similar to card payments, however an authorisation code is not generated or returned.

5.1.3. ACH ChargebacksACH payments may be reversed by the account holder after settlement, which will result in a payment status of Chargeback. The process is comparable with a Credit Card chargeback but without the ability to defend against the dispute.

5.2. SEPA Direct DebitsThe Single Euro Payments Area (SEPA) is an EU payment-integration initiative for the simplification of bank transfers


API Manual

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

5.2.1. One-off SDD Payment Requests

The payment request will include the bankAccount container that contains the following elements:

• ibanThe IBAN.

• ownerName (optional)The name of the account holder.

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

• selectedBrandThe value should be “sepadirectdebit”.

Please refer to Appendix M for an example of a sepadirectdebit one-off API payment request.

5.2.2. Recurring SDD Payment RequestsThe only change to the normal payment request is that you must include the selectedBrand element.

Please refer to Appendix N for an example of a sepadirectdebit recurring API payment request.


API Manual

5.2.3. SDD NotificationsPending Notification

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

{"notificationItems": {

"NotificationRequestItem": {"amount": { "value": 1500, "currency": "EUR"},"pspReference": "9313547924770610","eventCode": "PENDING","eventDate": "2013-11-28 11:55:05.934 CET","merchantAccountCode": "TestMerchant","operations": { "CANCEL", "CAPTURE", "REFUND"},"merchantReference": "YourMerchantReference1","paymentMethod": "sepadirectdebit","additionalData": { "sepadirectdebit.dateOfSignature": "2013-11-28", "sepadirectdebit.sequenceType": "First", "sepadirectdebit.mandateId": "9913856361050084"},"success": "true"

} }}

Authorisation Notification

"NotificationRequestItem": {"amount": { "value": 1500, "currency": "EUR"

},"pspReference": "9313547924770610","eventCode": "AUTHORISATION","eventDate": "2013-11-28 11:55:05.934 CET","merchantAccountCode": "TestMerchant","merchantReference": "YourMerchantReference1","paymentMethod": "sepadirectdebit","success": "true""additionalData": { "sepadirectdebit.dateOfSignature": "2013-11-28", "sepadirectdebit.sequenceType": "First", "sepadirectdebit.mandateId": "9913856361050084"}

}


API Manual


5.2.4. SDD Settlement TimelinePrior to initiating the DD, you will need to inform the customer that the payment is due.

Core

Event: SDD First SDD Recurring

Pre-notification (T-14) T-5 (T-14) T-2

Submit SDD instructions (Moment of payment request)

T-5 T-2

Latest moment to revoke (cancel) SDD T-1 T-1

SDD instruction processed by bank T T

Reconciliation by Adyen PSP T+1 T+1

Core 1

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

Event: SDD SDD Recurring

Pre-notification (T-14) T-1 (T-14) T-2

Submit SDD instructions T-1 T-2

Latest moment to revoke (cancel) SDD N/A T-1

SDD instruction processed by bank T T

Reconciliation by Adyen PSP T+1 T+1

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

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

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

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


API Manual

6. Boleto BancárioBoleto Bancário, often simply referred to as Boleto, is an offline payment method used in Brazil. The consumer will take the Boleto form to an ATM, bank, an approved facility, or access their online banking system to complete the payment. Once the Boleto is paid, the bank will send Adyen a file confirming that the payment was made. This usually takes one day, but it may occur up to 6 days after the payment. If a Boleto is not paid, the transaction will expire once the expirationDate is reached.

The payment request will contain the data that is displayed on the Boleto. The billingAddress, deliveryDate and shopperStatement fields are optional but may be used to customise the Boleto form:

• deliveryDate (optional)This is the date by which the consumer must submit their payment. There aren't any time restrictions on the date inserted, however, if you do not populate this field the Adyen system will insert a date 5 days from the creation date.

• shopperStatement (optional)In this context the field can be used to provide the consumer with customised instructions for submitting their payment. If you do not provide this field, the default text will be displayed:

Não receber após o vencimento.

Não aceitar o pagamento com cheque.

This translates to:

Do not accept payment after the due date.

Do not accept payment by cheque.

• socialSecurityNumber (mandatory)The consumer will need to provide their Cadastro de Pessoas Físicas (CPF) number.

• firstName and lastName (mandatory)Shopper's full name.

Please refer to Appendix O for a set of examples of Boleto requests and responses.

When submitting a Boleto payment, the Adyen system will return a URL to you in the field boletobancario.url. You may use this to download the PDF of the Boleto or redirect the consumer to it. This will render the Boleto form that the shopper must use to complete their payment at an ATM, bank or approved facility. The PDF may be accessed until the expirationDate, this is the deliveryDate + 15 days, at this time the transaction will expire in the Adyen system.

Please refer to Appendix P for sample Boleto forms.

6.1. Boleto NotificationsAdyen will send a PENDING notification once the Boleto transaction is created in the Adyen system. We will return the additionalData.acquirerReference, in the notification, you may want to store this data as it is the Boleto's "Nosso Numero" or ID at the bank.

Adyen will send an AUTHORISATION notification once we have received confirmation from the bank that the Boleto has been paid.

6.2. Important Information Regarding Storage Of The Boleto PDF

The Boleto contains sensitive information, namely the consumer's address and CPF. The Adyen URL is not available via a


API Manual

direct link but if you do decide to download the PDF and make it available on your systems, the recommended approach is to ensure that it is only available from a secure location. If, however, you do intend to store the files in a publicly available area, we suggest ensuring that the content is not indexed. You may use the following command in the HTTP header where the file is being served: X-Robots-Tag:noindex. This will prevent the PDF file from being indexed by search engines and will ensure it does not appear in search results pages.


API Manual

7. ModificationsIn this section, we describe the possible modification actions. It is possible to perform modifications using your account on the Adyen Customer Area (CA). However, we recommend automating this if you are processing more than a handful of payments daily. For this we offer a web service which accepts the modification requests from your backoffice systems. To submit modification messages you must supply authentication credentials. The username is ws@Company.[YourCompanyAccount] and you set the password for this user in the CA under “Settings” → “Users”.

Please note, for all modification requests Adyen will respond with a message appropriate to the modification type such as captureReceived, cancelReceived or refundReceived. This message is an acknowledgment of your modification request, it does not signify that the payment was actually modified. Once your request has been processed you will receive a notification informing you whether or not the modification was successful.

7.1. CaptureIn order to capture an authorised payment, you send a modification request to the capture action using the following fields.

Please note, this is only applicable to payment methods that support separate authorisations and captures. You can specify your capture delay via the CA “Settings” → “Merchant Setting” → “Capture Delay”.

• merchantAccountThe merchant account used to process the payment.

• modificationAmount

The amount to capture. This consists of a currency and a value which is the amount in minor units. The currency must match that of the original payment request, and the value must be less than or equal to the authorised amount.

• originalReferenceThis is the pspReference that was assigned to the authorisation. You receive it with the payment status or the authorisation notification.

• reference (optional)If you wish, you can to assign your own reference or description to the modification. The reference is visible in the Merchant Backoffice and in the reporting.


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

• pspReferenceThis is a new unique reference that Adyen has associated with the modification request. This is guaranteed to be globally unique.

• responseThe response. If successful, this will be [capture-received]. If there is an error, we will return a fault.

In most cases the final result of the capture is sent via a notification with the “CAPTURE” eventCode. The pspReference of this notification is the same as the pspReference in the response. The success field indicates if the capture was successful, “true”, or not, “false”. If false, the reason field of the notification provides a short description. For some payment methods, where the capture process is handled offline, we may subsequently receive a failure. In this situation we send a notification with the “CAPTURE_FAILED” eventCode. The pspReference of this notification is the same as the pspReference in the response. The success field value is set to “true”.

The Adyen 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.

Please refer to Appendix Q for a set of examples of capture modification request and response.


API Manual

7.2. CancelSimilar to the capture modification, in order to cancel an authorised payment you send a modification request to the cancel action using the following fields.

Please note, this is only applicable to payment methods that support separate authorisations and captures.


• originalReferenceThis is the pspReference that was assigned to the authorisation. You receive it with the payment status or the authorisation notification.



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

• pspReference

This is a new unique reference that Adyen associates with the modification request. This is guaranteed to be globally unique.

• responseThe response. If successful, this will be [cancel-received]. If there is an error, we will return a Fault.

The final result of the cancellation is sent via a notification with the “CANCELLATION” eventCode. The pspReference of this notification is the same as the pspReference in the response. The success field indicates if the cancellation was successful, “true” or not, “false”. If false, the reason field of the notification provides a short description.

Please refer to Appendix R for a set of examples of cancel modification request and response.

7.3. RefundA refund is initiated by sending a modification request using the refund action using the following fields:


• modificationAmountThe amount to refund. This consists of a currency and a value which is the amount in minor units. The currency must match that of the original payment request, and the value must be less than or equal to the authorised amount.

• originalReferenceThis 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 the merchantAccount is correct you will receive a refundReceived response with the following fields:

• pspReferenceThis is a new unique reference that Adyen has associated with the modification request. This is guaranteed to be


API Manual

globally unique.

• responseThe response. If successful, this will be [refund-received]. If there is an error, we will return a Fault.

In most cases the final result of the refund is sent via a notification with the “REFUND” eventCode. The pspReference of this notification is the same as the pspReference in the response. The success field indicates if the refund was successful, “true” or not, “false”. If false, the reason field of the notification provides a short description. For some payment methods, where the refund process is handled offline, we may subsequently receive a failure. In this situation we send a notification with the “REFUND_FAILED” eventCode. The pspReference of this notification is the same as the pspReference in the response. The success field value is set to “true”.

Please refer to Appendix S for a set of examples of refund modification request and response.

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


• originalReferenceThis 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 the merchantAccount is correct you will receive a cancelOrRefundReceived response with the following fields:

• pspReferenceThis is a new unique reference that Adyen has associated with the modification request. This is guaranteed to be globally unique.

• responseThe response. If successful, this will be [cancelOrRefund-received]. If there is an error, we will return a Fault.

If the payment is authorised, but not yet captured, it will be cancelled. For those payment methods that do not support cancellations, the transaction will be refunded in full.

If the request resulted in a cancellation, the final result is sent via a notification with the “CANCEL_OR_REFUND” eventCode. The pspReference of this notification is the same as the pspReference in the response. The success field indicates if the cancellation was successful, “true” or not, “false”. If false, the reason field provides a short description.

If the request resulted in a refund, the final result is sent via a notification with the “CANCEL_OR_REFUND ” eventCode. The pspReference of this notification is the same as the pspReference in the response. The success field indicates if the refund was successful, “true” or not, “false”. If false, the reason field provides a short description.

If the request fails a notification is sent with the “CANCEL_OR_REFUND” eventCode. With SUCCESS=FALSE the pspReference of this notification is the same as the pspReference in the response. The success field value is set to “false” to indicate that the request failed and the reason field provides a short description.

Please refer to Appendix T for a set of examples of cancelOrRefund modification request and response.


API Manual

8. IdempotencyWhen interfacing with an API, dealing with failures and retries can be challenging. Adyen's API attempts to limit the impact of such a problem:

• Asynchronous server-to-server notifications inform you of the result of a request to the API. This is particularly useful in the eventuality that an authorisation response is missed. Note: An authorisation response may be missed due to a timeout. If this is the case, please refer to section 9 for information regarding notifications.

• Capture and refunds requests are validated against balances in the accounting system.

◦ It is not possible to capture more than the initial authorisation amount.

◦ By default the system does not allow you to refund more than the original captured amount

While this is usually sufficient to deal with most exceptions, you may also choose to use the Adyen API in idempotent mode. Idempotency is an API feature where there is no additional effect if a method is called more than once with the same input parameters. This allows your system to safely retry an API call in the case of failure without worrying about the payment/modification being duplicated.

8.1. Idempotency ImplementationMessages will be uniquely identified using a message key, which is a combination of the Merchant Account and Merchant Reference. In order to use idempotency, make sure that you always use a unique Merchant Reference for each request.

In case you receive no response to your request, you may resubmit the request for idempotent processing. This is achieved by setting a Pragma: pragma-directive HTTP header, as defined below.

The pragma directive value you need to specify to enable idempotency is process-retry.

HTTP header key HTTP header value Syntax Example

Pragma pragma-directive Pragma: pragma-directive Pragma: process-retry

The following cURL call to the Adyen test payment endpoint authenticates the user and adds the pragma: process-retry HTTP header to the request.

curl -w "\n\nRequest size: %{size_request} \nResponse size: %{size_download} \nResponse code: %{http_code} \nTime total: %{time_total} [namelookup tcpconnect appconnect starttransfer]=[%{time_namelookup} %{time_connect} %{time_appconnect} %{time_starttransfer}]\n\n" \

--basic --verbose --output result.xml \--header "content-type: text/xml" \--header "pragma: process-retry" \--data-binary @payment.xml \--user "ws@Company.{YourCompanyAccount}:{yourPassword}" \--url "https://pal-test.adyen.com/pal/servlet/Payment/v12" \&& xmllint --format result.xml --output result.xml

8.1.1. What happens when a request is resubmitted idempotently?

When the system receives a request which is marked as process-retry, a lookup is performed in order to determine if the request has already been received and processed. In this situation, there are two possible scenarios:

• Scenario A—If it was already processed:

No processing is performed, but a RETRY notification is sent (see next section). The regular notification for this operation will have already been scheduled for sending to your system.


API Manual

https://pal-test.adyen.com/pal/servlet/Payment/v12

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.32




• Scenario B—If it was not already processed:

The request is processed as if it was the initial request. You will receive the regular notification for this operation, and additionally a RETRY notification will be sent (see section 8.1.2).

For modifications, which are always process asynchronously, the response will be exactly the same for a retry. Authorisations are processed synchronously, therefore a retry will always have resultCode Received as the retry will be processed asynchronously. The result of the retried authorisations will always be communicated through the regular AUTHORISATION notification.

8.1.2. The RETRY notification

When you submit a request as “process-retry”, you will receive a pspReference in the response.

In scenario A, this pspReference is not the same as the pspReference of the initial request (for which you have missed the synchronous response). In order to reconcile the link between the retried request and the initial request, the system will send you a notification with eventCode PROCESS_RETRY containing both pspReference values. The pspReference field will contain the pspReference of the retry whereas the originalReference field will contain the pspReference value of the initial request.

In scenario B, you will also receive a PROCESS_RETRY notification, but both pspReference values will be the same.


API Manual

9. NotificationsWhenever a payment is made, a modification 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. Notifications should be used to keep your backoffice systems up to date with the status of each payment and modification.

Notifications are sent to a server, that you host, that will receive and accept the notifications. We provide code examples in common programming languages for this, please refer to the link in the Introduction. Your system should be able to handle requests/responses which contain additional fields and duplicate notifications for the same transaction.

Due to the nature of the Adyen platform, an AUTHORISATION notification may be sent twice. The front end systems (HPP) will attempt to send the notification as soon as the payment is made. However our front-end systems do not register if this notification is received successfully by your servers. This is done on a central application and hardware instance which updates the accounting journal entries for each transaction. This system not only sends at least one notification, it also records whether or not it was successfully received, this is determined by your server responding to the notification with a message indicating that the notification has been [accepted]. Please refer to section 9.2 for more details regarding accepting notifications.

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. 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 Adyen CA. You can set the method (JSON), URL to submit to, and user name/password for HTTP Basic authentication. Default HTTP (TCP port 80) and HTTPS (TCP port 443) are allowed, as well as extra TCP ports 8080, 8888 (for HTTP) and 8443, 8843 (for HTTPS) if needed.

Please note, you will only receive a CAPTURE notification for CAPTURE requests submitted via your web service or the CA. This does not include automatic captures initiated by the Adyen platform.

9.1. Notification Message FieldsA notification contains the following fields for each transaction that it references:

• 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

◦ CANCEL_OR_REFUND

◦ CAPTURE

◦ CAPTURE_FAILED

◦ REFUND

◦ REFUND_FAILED

◦ REFUNDED_REVERSEDPlease note that the success field in a REFUNDED_REVERSED notification will always be set to false.

Dispute Events◦ ADVICE_OF_DEBIT


API Manual

◦ CHARGEBACK

◦ CHARGEBACK_REVERSEDFor more information about Disputes please refer to the Merchant Manual.

Please note that the success field in a CHARGEBACK_REVERSED notification will always be set to true.

◦ NOTIFICATION_OF_CHARGEBACK

◦ NOTIFICATION_OF_FRAUD

◦ REQUEST_FOR_INFORMATION

Manual Review Events◦ MANUAL_REVIEW_ACCEPT

◦ MANUAL_REVIEW_REJECT

Recurring Events◦ DEACTIVATE_RECURRING

◦ RECURRING_CONTRACT

◦ SUBMIT_RECURRING

Payout◦ PAYOUT_EXPIRE

◦ PAYOUT_DECLINE

◦ PAYOUT_THIRDPARTY

◦ REFUND_WITH_DATA

• Other Events◦ AUTHORISE_REFERRAL

◦ EXPIRE

◦ FRAUD_ONLY

◦ FUND_TRANSFER

◦ HANDLED_EXTERNALLY

◦ OFFER_CLOSED

◦ ORDER_OPENED

◦ ORDER_CLOSED

◦ PENDING

◦ PROCESS_RETRY

◦ REPORT_AVAILABLE

For more information please refer to the Adyen Reporting Manual.

For specialised applications, such as recurring payments, other values are possible. Please note, Adyen may add new codes at any time and, as such, your listening service should not be coded to expect a fixed set of values.

• pspReferenceThe unique reference that Adyen 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.

• merchantReferenceThis is the reference you assigned to the original payment.


API Manual

• merchantAccountCode

The 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, this is only populated for an AUTHORISATION. e.g. visa, mc, ideal, elv, wallie, etc.

• operationsThis field displays the modification operations supported by this payment as a list of strings. It is only populated for AUTHORISATION notifications. The operations will inform you whether you need to capture the payment (if you don't have auto-capture set up), whether you can cancel the payment (before capture) or if you can refund the payment (after it has been captured). Values include:

◦ CAPTURE

◦ REFUND

◦ CANCEL

For HTTP POST notifications, the operations are sent as a single comma-separated string.

• reasonText field with information depending on whether the result is successful or not. For AUTHORISATION events with the success field set to true and a payment method of visa, mc or amex, this field contains the authorisation code, the last 4 digits of the card, and the expiry date in the following format:

6 digit Authorisation Code:Last 4 digits:Expiry Date. For example, 874574:1935:11/2012.

When the success field is set to false it gives a reason as to why it was refused. For REPORT_AVAILABLE it contains the URL where the report can be downloaded from.

• amountThe amount, if applicable, associated with the payment or modification. This consists of a currencyCode and a value which is the amount in minor units. For HTTP POST notifications, you will receive the currency and value as parameters.

A notification message is a container for an array of notification items, meaning that you may receive multiple notifications within a single message. Please refer to Appendix U for samples of notifications and responses.

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.

9.2. Accepting NotificationsThe Adyen notification system requires a response within 30 seconds of receipt of the notification. After sending a notification, the server expects the following response, square brackets included: [accepted].

When our systems receive [accepted] as a response, all notifications contained in the message are marked as successfully sent. It is important that Adyen receives the [accepted] message within 30 seconds, and that this process is not interrupted by any errors in processing the notification. As such, we recommend that the acceptance of notifications is handled separately from the processing of the notifications, and that an [accepted] response is generated when a notification has been stored. Please refer to Appendix U for samples of notifications and responses.

The URL to send the notification messages to and the authentication are configurable in the Adyen CA. There is also a testing facility that you can use to verify that your server is able to correctly receive the notifications coming from the Adyen systems.


API Manual

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 stop sending notifications.

9.3. Retrying NotificationsNotifications will be resent if their delivery has failed or if the delivery is uncertain. They are resent at the following durations:

5 minutes 10 minutes 15 minutes 30 minutes 1 hour 2 hours 4 hours 8 hours

A system message is placed on the CA after the 3rd unsuccessful attempt, i.e. after 5 + 10 + 15 minutes.

The system will continue to retry every 8 hours until 7 days have passed.

If you wish to trigger a resend attempt, you may send yourself a test notification via the CA at “Settings” → “Server Communications”. If it is successful all the queued notifications will be resent. Otherwise you will be advised of the current errors our system is recording.


API Manual

10. Response HandlingAfter submitting a call, you will receive a confirmation that the message was received, and if it was correctly processed. The API returns HTTP status codes together with the response message.

HTTP Status Code Description

200 Request processed normally

400 Problem reading or understanding request

401 Authentication required

403 Insufficient permission to process request

422 Request validation error

500 Server could not process request

Depending on the HTTP status code of the response message, you may find it helpful to build some logic to handle any error that the request or system generated.

10.1. Handling 200 responsesA 200 http status response means that the request was submitted correctly and it was processed successfully by Adyen. However, it does not necessarily mean that the payment or modification request was successful. For instance, if a capture payment request

10.2. Handling 4xx and 5xx responsesIn 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 violates a configuration constraint.

• If there was an internal error in Adyen's system

When this happens, you will receive a Fault which will contain a description of the problem. Generally this will be handled as an Exception in your toolkit. Payment requests that are rejected with an error message will not be charged.

If the request was rejected, the response will contain the following fields:

• errorTypeType of the error with the following values {internal, validation, security, configuration}

• errorCodeAdyen's code for the error message.

• messageError message

• statusHTTP status code

Adyen's mapped refusal reason, populated if the payment was refused:


API Manual

<faultstring> ::= <type> ' ' <message> <type> ::= 'validation' | 'security' | 'configuration' | 'internal' <message> ::= unicode

JSON Example:

{"errorType": "security","errorCode": “901“,"message": "Invalid Merchant Account","status": "403”

}

The way to check the description is to read the fault-string. If the payment was rejected by our platform the fault string will start with one of validation, security, or configuration followed by a code and it's descriptive message.

Please refer to Appendix V for a list of the error codes and messages.


API Manual

Appendix B: Examples Payment Request and ResponseJSON Payment Request

{"card": { "number": "4111111111111111", "expiryMonth": "6", "expiryYear": "2016", "cvc": "737", "holderName": "Adyen Test"},"amount": { "value": 2000, "currency": "EUR"},"reference": “Your Reference Here“,"merchantAccount": "TestMerchant",“shopperEmail”: “[email protected]”,“shopperIP”: “61.294.12.12”,“shopperReference”: “Simon Hopper”

}

JSON Payment Response

{"authCode": “64158“,"pspReference": "9914176829759187”,“resultCode”: “Authorised”,

}

SOAP Payment Request

<?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:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest> <amount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">2000</value> </amount> <card xmlns="http://payment.services.adyen.com"> <cvc>737</cvc> <expiryMonth>06</expiryMonth> <expiryYear>2016</expiryYear> <holderName>Adyen Test</holderName> <number>4111111111111111</number> </card> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant </merchantAccount> <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference> <shopperEmail xmlns="http://payment.services.adyen.com">[email protected]</shopperEmail> <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP> <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference> </ns1:paymentRequest> </ns1:authorise> </soap:Body></soap:Envelope>


API Manual

SOAP Payment Response

<?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:authoriseResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentResult> <authCode xmlns="http://payment.services.adyen.com">64158</authCode> <dccAmount xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <dccSignature xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <fraudResult xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <issuerUrl xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <md xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <paRequest xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <pspReference xmlns="http://payment.services.adyen.com">9914176829759187</pspReference> <refusalReason xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <resultCode xmlns="http://payment.services.adyen.com">Authorised</resultCode> </ns1:paymentResult> </ns1:authoriseResponse> </soap:Body> </soap:Envelope>

REST Payment Request

merchantAccount=TestMerchant&amount.value=2000&card.expiryYear=2016&amount.currency=EUR&card.cvc=737&card.number=4111111111111111&card.holderName=Adyen+Test&card.expiryMonth=06&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com&shopperIP=61.294.12.12

REST Payment Response

pspReference=9914176829759187&authCode=64158&resultCode=Authorised


API Manual

Appendix C: CSE Source Libraries UsedRSA and ECC in JavaScript

The jsbn library is a fast, portable implementation of large number math in pure JavaScript, enabling public-key crypto and other applications on desktop and mobile browsers.

http://www-cs-students.stanford.edu/~tjw/jsbn/

Stanford Javascript Crypto Library (AES) The Stanford Javascript Crypto Library is a project by the Stanford Computer Security Lab to build a secure, powerful, fast, small, easy-to-use, cross-browser library for cryptography in JavaScript.

http://crypto.stanford.edu/sjcl/


API Manual

http://crypto.stanford.edu/sjcl/

http://www-cs-students.stanford.edu/~tjw/jsbn/

Appendix D: CSE Sample Encrypted Form<!DOCTYPE html> <html lang="en"> <head> <title>Example Payment Form</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> </head><body> <form method="POST" action="#handler" id="adyen-encrypted-form"> <fieldset> <legend>Card Details</legend> <div class="field"> <label for="adyen-encrypted-form-number">Card Number <input type="text" id="adyen-encrypted-form-number" value="5555444433331111" size="20" autocomplete="off" data-encrypted-name="number" /> </label> </div> <div class="field"> <label for="adyen-encrypted-form-holder-name">Card Holder Name <input type="text" id="adyen-encrypted-form-holder-name" value="John Doe" size="20" autocomplete="off" data-encrypted-name="holderName" /> </label> </div> <div class="field"> <label for="adyen-encrypted-form-cvc">CVC <input type="text" id="adyen-encrypted-form-cvc" value="737" size="4" autocomplete="off" data-encrypted-name="cvc" /> </label> </div> <div class="field"> <label for="adyen-encrypted-form-expiry-month">Expiration Month (MM) <input type="text" value="06" id="adyen-encrypted-form-expiry-month" size="2" autocomplete="off" data-encrypted-name="expiryMonth" /> / </label> <label for="adyen-encrypted-form-expiry-year">Expiration Year (YYYY) <input type="text" value="2016" id="adyen-encrypted-form-expiry-year" size="4" autocomplete="off" data-encrypted-name="expiryYear" /> </label> </div> <div class="field"> <input type="hidden" id="adyen-encrypted-form-expiry-generationtime" value="generate-this-server-side" data-encrypted-name="generationtime" /> <input type="submit" value="Submit" /> </div> </fieldset> </form>

<!-- How to use the Adyen encryption client-side JS library → <script src="../js/adyen.encrypt.min.js"></script> <script> // generate time client side for testing... Don't deploy on a real integration!!! document.getElementById('adyen-encrypted-form-expiry-generationtime').value = new Date().toISOString(); // the form element to encrypt var form = document.getElementById('adyen-encrypted-form'); // the public key – Replace as explained in section 2.2.3 var key = "10001|80C7821C961865FB4AD23F172E220F819A5CC7B9956BC3458E2788"+ "F9D725B07536E297B89243081916AAF29E26B7624453FC84CB10FC7DF386"+ "31B3FA0C2C01765D884B0DA90145FCE217335BCDCE4771E30E6E5630E797"+ "EE289D3A712F93C676994D2746CBCD0BEDD6D29618AF45FA6230C1D41FE1"+ "DB0193B8FA6613F1BD145EA339DAC449603096A40DC4BF8FACD84A5D2CA5"+ "ECFC59B90B928F31715A7034E7B674E221F1EB1D696CC8B734DF7DE2E309"+ "E6E8CF94156686558522629E8AF59620CBDE58327E9D84F29965E4CD0FAF"+ "A38C632B244287EA1F7F70DAA445D81C216D3286B09205F6650262CAB415"


API Manual

+ "5F024B3294A933F4DC514DE0B5686F6C2A6A2D";

var options = {}; // the form will be encrypted before it is submitted adyen.encrypt.createEncryptedForm( form, key, options); </script> </body></html>


API Manual

Appendix E: Integration Example – CSEThe Adyen GitHub repository features a full integration example, along with the JavaScript library.

Identify your form with an id attribute

<form method="POST" action="posthandler.action" id="adyen-encrypted-form">

Input fields for the card data should not have a “name” attribute

<input type="text" value="" size="20" autocomplete="off" data-encrypted-name="number">

Add a hidden generationtime field with the current time on server

The format of this should be in the ISO 8601 standard format for XML as YYYY-MM-DDTHH:mm:ss.sssZ. For example, 2013-04-26T14:02:30.668Z.

It is important to not rely on the client's time, especially in the LIVE environment, which may be incorrect as the encrypted data is only usable within a 24 hour period of this time.

<input type="hidden" value="GENERATE_ON_SERVER" id="generationtime" data-encrypted-name="generationtime">

JavaScript

Include the JavaScript:

<script src="js/adyen.encrypt.min.js"></script>

var form = document.getElementById('adyen-encrypted-form'); // the form element to encryptvar key = "10001|80C7821C961865FB4AD23F172E220F819A5CC7B9956BC3458E2788" …

+ "5F024B3294A933F4DC514DE0B5686F6C2A6A2D"; // the public key

adyen.encrypt.createEncryptedForm( form, key ); // the form will be encrypted before it is submitted

Adjusting the default form post behaviour (e.g. A JAX)

You can change the behaviour of the library by adding options to the “createEncryptedForm()”:

For example, change the name of the encrypted data, the default is “adyen-encrypted-data” and submit the form using A JAX rather than the default:

var name = 'fieldnameofyourchoosing';

adyen.encrypt.createEncryptedForm( form, key { name : name, onsubmit : function(e) {

… Your AJAX Code Here … e.preventDefault();

}});


API Manual

https://github.com/Adyen/CSE-JS

Appendix F: Integration Example – Server-SideJSON Payment Request

{"additionalData": { "card.encrypted.json": "adyenjs_0_1_4p1....HVCwFw5GQu1EyqNCQ"},"amount": { "value": 2000, "currency": "EUR"},"reference": “Your Reference Here“,"merchantAccount": "TestMerchant",“shopperEmail”: “[email protected]”,“shopperIP”: “61.294.12.12”,“shopperReference”: “Simon Hopper”

}


<?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:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest> <additionalData xmlns="http://payment.services.adyen.com"> <entry xmlns="http://payment.services.adyen.com"> <key xmlns="http://payment.services.adyen.com" xsi:type="xsd:string">card.encrypted.json</key> <value xmlns="http://payment.services.adyen.com" xsi:type="xsd:string">Your generated key string from the JavaScript encryption... adyenjs_0_1_1$eGcJxidHkg5LYQ...6LUio9RipqyTBu11MJIC+rlMYxituYCT7A9yDeF2Rlv2I56KOAap66tTm2uZkto4PKRW4YCA8dZYQ==</value> </entry> </additionalData> <amount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">2000</value> </amount> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount> <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference> <shopperEmail xmlns="http://payment.services.adyen.com">[email protected]</shopperEmail> <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP> <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference> </ns1:paymentRequest> </ns1:authorise> </soap:Body></soap:Envelope>


API Manual

Appendix G: Authorise3d RequestThe response to this request is the same as a non-3-D Secure payment request and the resultCode will be one of Authorised, Refused or Error.

JSON Request

{"browserInfo": { "acceptHeader": "text/html,appli.../*;q=0.8", "userAgent": "Mozilla/5.0 ... Firefox/3.0"},"md": “31h..........vOXek7w“,"merchantAccount": "TestMerchant",“paResponse”: “eNqtmF........wGVA4Ch”,“shopperIP”: “61.294.12.12”

}

SOAP Request

<?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:authorise3d xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest3d> <browserInfo xmlns="http://payment.services.adyen.com"> <acceptHeader xmlns="http://common.services.adyen.com">text/html,appli.../*;q=0.8</acceptHeader> <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 ... Firefox/3.0</userAgent> </browserInfo> <md xmlns="http://payment.services.adyen.com">31h..........vOXek7w=</md> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount> <paResponse xmlns="http://payment.services.adyen.com">eNqtmF........wGVA4Ch</paResponse> <shopperIP xmlns="http://payment.services.adyen.com">62.194.82.12</shopperIP> </ns1:paymentRequest3d> </ns1:authorise3d> </soap:Body></soap:Envelope>


API Manual

Appendix H: BIN Data and Card VerificationJSON BIN Data/Card Verification Request (Zero Value Auth)

{"card": { "number": "4111111111111111", "expiryMonth": "6", "expiryYear": "2016", "cvc": "737", "holderName": "Adyen Test"},"amount": { "value": 0, "currency": "EUR"},"reference": “Your Reference Here“,"merchantAccount": "TestMerchant",“shopperEmail”: “[email protected]”,“shopperIP”: “61.294.12.12”,“shopperReference”: “Simon Hopper”

}

JSON BIN Data/Card Verification Request (Zero Value Auth) with additionalAmount

{"card": { "number": "4111111111111111", "expiryMonth": "6", "expiryYear": "2016", "cvc": "737", "holderName": "Adyen Test"},"amount": { "value": 0, "currency": "EUR"},"additionalAmount": { "value": 100, "currency": "EUR"},"reference": “Your Reference Here“,"merchantAccount": "TestMerchant",“shopperEmail”: “[email protected]”,“shopperIP”: “61.294.12.12”,“shopperReference”: “Simon Hopper”

}


API Manual

SOAP BIN Data/Card Verification Request (Zero Value Auth)

<?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:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest> <amount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">0</value> </amount> <card xmlns="http://payment.services.adyen.com"> <cvc>737</cvc> <expiryMonth>06</expiryMonth> <expiryYear>2016</expiryYear> <holderName>Adyen Test</holderName> <number>4111111111111111</number> </card> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount> <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference> <shopperEmail xmlns="http://payment.services.adyen.com">[email protected]</shopperEmail> <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference> </ns1:paymentRequest> </ns1:authorise> </soap:Body></soap:Envelope>


API Manual

SOAP BIN Data/Card Verification Request (Zero Value Auth) with additionalAmount

<?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:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest> <amount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">0</value> </amount> <additionalAmount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">100</value> </additionalAmount> <card xmlns="http://payment.services.adyen.com"> <cvc>737</cvc> <expiryMonth>06</expiryMonth> <expiryYear>2016</expiryYear> <holderName>Adyen Test</holderName> <number>4111111111111111</number> </card> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount> <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference> <shopperEmail xmlns="http://payment.services.adyen.com">[email protected]</shopperEmail> <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference> </ns1:paymentRequest> </ns1:authorise> </soap:Body></soap:Envelope>

REST BIN Data/Card Verification Request (Zero Value Auth)

merchantAccount=TestMerchant&amount.value=0&card.expiryYear=2016&amount.currency=EUR&card.cvc=737&card.number=4111111111111111&card.holderName=Adyen+Test&card.expiryMonth=06&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com

REST BIN Data/Card Verification Request (Zero Value Auth) with additionalAmount

merchantAccount=TestMerchant&amount.value=0&amount.currency=EUR&additionalAmount.value=100&additionalAmount.currency=EUR&card.expiryYear=2016&card.cvc=737&card.number=4111111111111111&card.holderName=Adyen+Test&card.expiryMonth=06&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com


API Manual

JSON BIN Data/Card Verification Response (Zero Value Auth) with additionalData

{ "additionalData": { "cardPaymentMethod": "amex", "cardIssuingBank": "American Express US Consumer", "cardIssuingCountry": "US", "cardIssuingCurrency": "USD", "cardBin": "373731" }, "pspReference": "9914229541655140", "refusalReason": "Acquirer Error", "resultCode": "Error"}

SOAP BIN Data/Card Verification Response (Zero Value Auth) with additionalData

<?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:authoriseResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentResult> <additionalData xmlns="http://payment.services.adyen.com"> <entry> <key xsi:type="xsd:string">cardPaymentMethod</key> <value xsi:type="xsd:string">amex</value> </entry> <entry> <key xsi:type="xsd:string">cardIssuingBank</key> <value xsi:type="xsd:string">American Express US Consumer</value> </entry> <entry> <key xsi:type="xsd:string">cardIssuingCountry</key> <value xsi:type="xsd:string">US</value> </entry> <entry> <key xsi:type="xsd:string">cardIssuingCurrency</key> <value xsi:type="xsd:string">USD</value> </entry> <entry> <key xsi:type="xsd:string">cardBin</key> <value xsi:type="xsd:string">373731</value> </entry> </additionalData> <authCode xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <dccAmount xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <dccSignature xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <fraudResult xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <issuerUrl xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <md xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <paRequest xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <pspReference xmlns="http://payment.services.adyen.com">9914229541655140</pspReference> <refusalReason xmlns="http://payment.services.adyen.com">Acquirer Error</refusalReason> <resultCode xmlns="http://payment.services.adyen.com">Error</resultCode> </ns1:paymentResult> </ns1:authoriseResponse> </soap:Body></soap:Envelope>


API Manual

REST BIN Data/Card Verification Response (Zero Value Auth) with additionalData

additionalData.cardPaymentMethod=amex&additionalData.cardIssuingBank=American+Express+US+Consumer&additionalData.cardIssuingCountry=US&additionalData.cardIssuingCurrency=USD&additionalData.cardBin=373731&pspReference=9914229541655140&refusalReason=Acquirer+Error&resultCode=Error


API Manual

Appendix I: Payment Request with MasterCard Flagging JSON Payment Request

{"additionalData": { "mcAuthorisationType": "PreAuth"}"card": { "number": "4111111111111111", "expiryMonth": "6", "expiryYear": "2016", "cvc": "737", "holderName": "Adyen Test"},"amount": { "value": 10000, "currency": "EUR"},"reference": “Your Reference Here“,"merchantAccount": "TestMerchant",“shopperEmail”: “[email protected]”,“shopperIP”: “61.294.12.12”,“shopperReference”: “Simon Hopper”

}


<?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:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest> <additionalData xmlns="http://payment.services.adyen.com"> <entry xmlns="http://payment.services.adyen.com"> <key xsi:type="xsd:string">mcAuthorisationType</key> <value xsi:type="xsd:string">PreAuth</value> </entry> </additionalData> <amount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">10000</value> </amount> <card xmlns="http://payment.services.adyen.com"> <cvc>737</cvc> <expiryMonth>06</expiryMonth> <expiryYear>2016</expiryYear> <holderName>Adyen Test</holderName> <number>5100290029002909</number> </card> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount> <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference> <shopperEmail xmlns="http://payment.services.adyen.com">[email protected]</shopperEmail> <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP> <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference> </ns1:paymentRequest> </ns1:authorise> </soap:Body></soap:Envelope>


API Manual


additionalData.mcAuthorisationType=PreAuth&card.number=4111111111111111&card.expiryMonth=6&card.expiryYear=2016&card.cvc=737&card.holderName=Adyen+Test&amount.value=10000&amount.currency=EUR&reference=Your Reference Here&merchantAccount=TestMerchant&shopperEmail=s.hopper%40test.com&shopperIP=61.294.12.12&shopperReference=Simon+Hopper


API Manual

Appendix J: Payment Request with InstallmentsJSON Payment Request

{"card": { "number": "4111111111111111", "expiryMonth": "6", "expiryYear": "2016", "cvc": "737", "holderName": "Adyen Test"},"amount": { "value": 2000, "currency": "BRL"},

"installments": { "value": 4 },

"reference": “Your Reference Here“,"merchantAccount": "TestMerchant”,“shopperEmail”: “[email protected]”,“shopperIP”: “61.294.12.12”,“shopperReference”: “Simon Hopper”

}


<?xml version="1.0" encoding="UTF-8"?><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:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest> <amount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">BRL</currency> <value xmlns="http://common.services.adyen.com">2000</value> </amount> <card xmlns="http://payment.services.adyen.com"> <cvc>737</cvc> <expiryMonth>06</expiryMonth> <expiryYear>2016</expiryYear> <holderName>Adyen Test</holderName> <number>4111111111111111</number> </card> <installments xmlns="http://payment.services.adyen.com"> <value xmlns=4</value> </installments> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount> <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference> <shopperEmail xmlns="http://payment.services.adyen.com">[email protected]</shopperEmail> <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP> <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference> </ns1:paymentRequest> </ns1:authorise> </soap:Body></soap: Envelope>


API Manual


amount.currency=BRL&amount.value=2000&card.cvc=737&card.expiryMonth=06&card.expiryYear=2016 &card.holderName=Adyen+Test&card.number=4111111111111111&merchantAccount=TestMerchant &reference=test1234&installments.value=4&shopperEmail=s.hopper%40test.com&shopperIP=“61.294.12.12”&shopperReference=Simon+Hopper


API Manual

Appendix K: CVC/CVV and AVS Result ValuesCVC/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 certified 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 not checked, postal code unknown

9 Address matches, postal code unknown

10 Address doesn't match, postal code unknown

11 Postal code not checked, address unknown

12 Address matches, postal code not checked

13 Address doesn't match, postal code not checked

14 Postal code matches, address unknown

15 Postal code matches, address not checked

16 Postal code doesn't match, address unknown

17 Postal code doesn't match, address not checked

18 Neither postal code nor address were checked

19 Name and postal code matches

20 Name, address and postal code matches

21 Name and address matches

22 Name matches

23 Postal code matches, name doesn't match

24 Both postal code and address matches, name doesn't match

25 Address matches, name doesn't match

26 Neither postal code, address nor name matches


API Manual

Appendix L: ACH Payment RequestJSON Payment Request

{"bankAccount": { "bankAccountNumber": "11111111111111111", "bankLocationId": "011000028", "countryCode": "US", "ownerName": "Andrews", "bankAccountType": "C"},"amount": { "value": 200, "currency": "USD"},"reference": “Your Reference Here“,"merchantAccount": "TestMerchant",“shopperEmail”: “[email protected]”,“shopperIP”: “61.294.12.12”,“shopperReference”: “Simon Hopper”“shopperInteraction”: “Ecommerce”

}


<?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:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest> <amount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">USD</currency> <value xmlns="http://common.services.adyen.com">200</value> </amount> <bankAccount xmlns="http://payment.services.adyen.com"> <bankAccountNumber>11111111111111111</bankAccountNumber> <bankLocationId>011000028</bankLocationId> <countryCode>US</countryCode> <ownerName>Andrews</ownerName> <bankAccountType>C</bankAccountType> </bankAccount> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount> <reference xmlns="http://payment.services.adyen.com">Your Reference Here</reference> <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP> <shopperReference xmlns="http://payment.services.adyen.com">111541</shopperReference> <shopperInteraction xmlns="http://payment.services.adyen.com">Ecommerce</shopperInteraction> </ns1:paymentRequest> </ns1:authorise> </soap:Body></soap:Envelope>


API Manual


amount.currency=USD&amount.value=200&merchantAccount=TestMerchant&reference=testReference1234&bankAccount.bankAccountNumber=11111111111111111&bankAccount.bankLocationId=011000028&bankAccount.countryCode=US&bankAccount.ownerName=Andrews&bankAccount.bankAccountType=C&shopperIP=212.14.111.12&shopperReference=111541&shopperInteraction=Ecommerce


API Manual

Appendix M: SEPA Direct Debit One-off Payment Request and ResponseJSON One-Off Payment Request

{"bankAccount": { "iban": "NL48RABO0132394782", "ownerName": "Klaas T. Jansen", "countryCode": "NL",},"amount": { "value": 1500, "currency": "EUR"},"reference": “Your Reference Here“,"merchantAccount": "TestMerchant",“shopperEmail”: “[email protected]”,“shopperIP”: “61.294.12.12”,“shopperStatement”: “UW ORDER 122345677889”,“selectedBrand”: “sepadirectdebit”

}

JSON One-Off Payment Response

{"additionalData": { "sepadirectdebit.dateOfSignature": "2013-11-28", "sepadirectdebit.sequenceType": "OneOff", "sepadirectdebit.mandateId": "9913856361050084",},“resultCode”: “Received”“pspReference”: “9913856361050084”

}

For the field sepadirectdebit.sequenceType:

• If this is the first payment in a recurring flow, the value will be “First".

• If this is a subsequent payment, the value will be “Recurring”.

• If this is a one-off payment, the value will be "OneOff".


API Manual

SOAP One-Off Payment Request

<?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:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest> <ns1:amount> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">1500</value> </ns1:amount> <ns1:bankAccount> <ns1:iban>NL48RABO0132394782</ns1:iban> <ns1:ownerName>Klaas T. Jansen</ns1:ownerName> <ns1:countryCode>NL</ns1:countryCode> </ns1:bankAccount> <ns1:merchantAccount>TestMerchant</ns1:merchantAccount> <ns1:reference>Your Reference Here</ns1:reference> <ns1:shopperEmail>[email protected]</ns1:shopperEmail> <ns1:shopperReference>TheShopperReference</ns1:shopperReference> <ns1:shopperIP>10.10.100.200</ns1:shopperIP> <ns1:shopperStatement>UW ORDER 122345677889</ns1:shopperStatement> <ns1:selectedBrand>sepadirectdebit</ns1:selectedBrand> </ns1:paymentRequest> </ns1:authorise> </soap:Body></soap:Envelope>


API Manual

SOAP One-Off Payment Response

<?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:authoriseResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentResult> <additionalData xmlns="http://payment.services.adyen.com"> <entry> <key xsi:type="xsd:string">sepadirectdebit.dateOfSignature</key> <value xsi:type="xsd:string">2013-11-28</value> </entry> <entry> <key xsi:type="xsd:string">sepadirectdebit.sequenceType</key> <value xsi:type="xsd:string">OneOff</value> </entry> <entry> <key xsi:type="xsd:string">sepadirectdebit.mandateId</key> <value xsi:type="xsd:string">9913856361050084</value> </entry> </additionalData> <authCode xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <dccAmount xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <dccSignature xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <fraudResult xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <issuerUrl xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <md xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <paRequest xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <pspReference xmlns="http://payment.services.adyen.com">9913856361050084</pspReference> <refusalReason xmlns="http://payment.services.adyen.com" xsi:nil="true"/> <ns1:resultCode>Received</ns1:resultCode> </ns1:paymentResult> </ns1:authoriseResponse> </soap:Body></soap:Envelope>

For the field sepadirectdebit.sequenceType:

• If this is the first payment in a recurring flow, the value will be “First".

• If this is a subsequent payment, the value will be “Recurring”.

• If this is a one-off payment, the value will be "OneOff".


API Manual

Appendix N: SEPA Direct Debit Recurring Payment RequestJSON Request

{"amount": { "value": 2150, "currency": "EUR"},"reference": "Your Reference Here","merchantAccount": "TestMerchant","shopperEmail": "[email protected]","shopperReference": "TheShopperReference","shopperInteraction": "ContAuth","recurring": { "contract": "RECURRING",},"selectedRecurringDetailRetail": "LATEST","selectedBrand": "sepadirectdebit"

}

SOAP Request

<?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:authorise xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentRequest> <ns1:amount> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">2150</value> </ns1:amount> <ns1:merchantAccount>TestMerchant</ns1:merchantAccount> <ns1:reference>Your Reference Here</ns1:reference> <ns1:shopperEmail>[email protected]</ns1:shopperEmail> <ns1:shopperReference>TheShopperReference</ns1:shopperReference> <ns1:shopperInteraction>ContAuth</ns1:shopperInteraction> <ns1:recurring> <ns1:contract>RECURRING</ns1:contract> </ns1:recurring> <ns1:selectedRecurringDetailRetail>LATEST</ns1:selectedRecurringDetailRetail> <ns1:selectedBrand>sepadirectdebit</ns1:selectedBrand> </ns1:paymentRequest> </ns1:authorise> </soap:Body></soap:Envelope>

JSON Request

amount.value=2150&amount.currency=EUR&reference=Your+Reference+Here&merchantAccount=TestMerchant&shopperEmail=email%40shopper.com&shopperReference=TheShopperReference&shopperInteraction=ContAuth &recurring.contract=RECURRING&selectedRecurringDetailRetail=LATEST&selectedBrand=sepadirectdebit


API Manual

Appendix O: Boleto JSON API Payment Request and ResponseJSON Payment Request

{"amount": { "value": 1000, "currency": "BRL"},"billingAddress": { "city": "São Paulo", "country": "BR", "houseNumberOrName": "999", "postalCode": "04787910", "stateOrPrivince": "SP", "street": "Roque Petroni Jr"},"deliveryDate": "2013-10-29T23:00:00.000Z","reference": "Teste Boleto","merchantAccount": "TestMerchant”,"selectedBrand": "boletobancario_santander","shopperName": { "firstName": "José", "lastName": "Silva"},"shopperStatement": "Aceitar o pagamento até 15 dias após o vencimento.
Não cobrar

juros. Não aceitar o pagamento com cheque","socialSecurityNumber": "56861752509"

}

JSON Payment Response

{"additionaldata": { "boletobancario.url": https://test.adyen.com/hpp/generationBoleto.shtml?

data=AgABAQAk5QYbuNl9TiV63c5KeLTvXpB03Ml3krv%2FtwYj....2FFq3920vVWRd5HKHT96mCdVXyo4Gzq%2BTkzNbmT2XcgFf%2FwhYkU4%3D,

"boletobancario.data":"AgABAQAk5QYbuNl9TiV63c5KeLTvXpB03Ml3krv/twYj....2FFq3920vVWRd5HKHT96mCdVXyo4Gzq+TkzNbmT2XcgFf/whYkU4=",

"boletobancario.expirationDate": "2013-08-19", "boletobancario.dueDate": "2013-08-12"},"pspReference": "8813760397300101","resultCode": "Received"

}


API Manual


<?xml version="1.0" encoding="UTF-8"?><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> <authorise xmlns="http://payment.services.adyen.com"> <paymentRequest> <amount> <ns1:currency xmlns:ns1="http://common.services.adyen.com">BRL</ns1:currency> <ns2:value xmlns:ns2="http://common.services.adyen.com">1000</ns2:value> </amount> <billingAddress> <ns3:city xmlns:ns3="http://common.services.adyen.com">São Paulo</ns3:city> <ns4:country xmlns:ns4="http://common.services.adyen.com">BR</ns4:country> <ns5:houseNumberOrName xmlns:ns5="http://common.services.adyen.com">999</ns5:houseNumberOrName> <ns6:postalCode xmlns:ns6="http://common.services.adyen.com">04787910</ns6:postalCode> <ns7:stateOrPrivince xmlns:ns7="http://common.services.adyen.com">SP</ns7:stateOrPrivince> <ns8:street xmlns:ns8="http://common.services.adyen.com">Roque Petroni Jr</ns8:street> </card> <deliveryDate xmlns="http://payment.services.adyen.com">2013-10-29T23:00:00.000Z</deliveryDate> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount> <reference xmlns="http://payment.services.adyen.com">Teste Boleto</reference> <selectedBrand xmlns="http://payment.services.adyen.com">boletobancario_santander</selectedBrand> <shopperName xmlns="http://payment.services.adyen.com"> <ns9:firstName xmlns:ns9="http://common.services.adyen.com">José</ns9:firstName> <ns10:lastName xmlns:ns10="http://common.services.adyen.com">Silva</ns10:lastName> </shopperName> <shopperStatement>Aceitar o pagamento até 15 dias após o vencimento.
Não cobrar juros. Não aceitar o pagamento com cheque.</shopperStatement> <socialSecurityNumber>56861752509</socialSecurityNumber> </paymentRequest> </ns1:authorise> </soap:Body></soap:Envelope>


API Manual

SOAP Payment Response

<?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:authoriseResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:paymentResult> <additionaldata xmlns="http://payment.services.adyen.com"> <entry> <key xsi:type="xsd:string">boletobancario.url</key> <value xsi:type="xsd:string">https://test.adyen.com/hpp/generationBoleto.shtml?data=AgABAQAk5QYbuNl9TiV63c5KeLTvXpB03Ml3krv%2FtwYj....2FFq3920vVWRd5HKHT96mCdVXyo4Gzq%2BTkzNbmT2XcgFf%2FwhYkU4%3D</value> </entry> <entry> <key xsi:type="xsd:string">boletobancario.data</key> <value xsi:type="xsd:string">AgABAQAk5QYbuNl9TiV63c5KeLTvXpB03Ml3krv/twYj....2FFq3920vVWRd5HKHT96mCdVXyo4Gzq+TkzNbmT2XcgFf/whYkU4=</value> </entry> <entry> <key xsi:type="xsd:string">boletobancario.expirationDate</key> <value xsi:type="xsd:string">2013-08-19</value> </entry> <entry> <key xsi:type="xsd:string">boletobancario.dueDate</key> <value xsi:type="xsd:string">2013-08-12</value> </entry> </additionaldata> <pspReference xmlns="http://payment.services.adyen.com">8813760397300101</authCode> <resultCode xmlns="http://payment.services.adyen.com">Received</authCode> </ns1:paymentResult> </ns1:authoriseResponse> </soap:Body> </soap:Envelope>


amount.currency=BRL&amount.value=1000&billingAddress.city=Sao+Paulo&billingAddress.country=BR&billingAddress.houseNumberOrName=999&billingAddress.postalCode=04787910&billingAddress.stateOrProvince=SP&billingAddress.street=Rua+Roque+Petroni+Jr&deliveryDate=2013-08-15T02:00:00+02:00&merchantAccount=TestMerchant&reference=Teste+Boleto&selectedBrand=boletobancario_santander&shopperName.firstName=José&shopperName.lastName=Silva&shopperStatement=Aceitar+o+pagamento+até+15+dias+após+o+vencimento.%0A+Não+cobrar+juros.+Não+aceitar+o+pagamento+com+cheque.&socialSecurityNumber=65468766205

REST Payment Response


API Manual

additionalData.boletobancario.url=https://test.adyen.com/hpp/generationBoleto.shtml?data=AgABAQClZUyg1NqsD7nN5X1uqN4mabJ7A3FH5LgAUbqDnJ6EAQlnSAVL%2Bu7eWIXY%2Fo%2B7F0v04ZEnh6VR%2F%2BIAUfJoMQba2uHb2%2BqezXU%2FhgULKuFov7s2ZnwmszAuuHgE6JvahvWtAygC5lnpLEgw34pp7z8Vf2hAQYO9mvELei6ZR8S6DMxVTObYGE6r%2FanhX1ucteKztIR79zv1wWWzV%2FbccQIqgOEp5b8AYU6mwOlbm0oP2lPZofq4CFAQfs%2FROyBk0JBQlQDaZHQRmY8YP3236nD6eEr4cBEy6MpULl8w0iin39NxXGsi7OCmuQDe2w1Fy%2F40Iv6AA2sar3JTo4Ap3eraC6PEN8s5%2BSoOB5MO%2BfpFbRSfFeSHGh9L3%2FwzuxaXCHopNfwjjgx6aJEVv1FmaPzyVYm9kB7%2B%2F1IpaxzBIp6nTh5VSMp8iJOyOccCoV4e7Qv6SKNDkvT5lc2KPXg6jUC4tQJWyFFbvgV55rlQojjRecQfLwCiQ51tONSyaw2QLewemJJys9Q2AyIXYemGUXdzYAORNlSLJkTQdkoQZKdMwuOx4LDPFkNQuzHLlg4Xg%2BpWYhgSz0TEZJrS83voNSRTbrIwOPN3&pspReference=8513763283942198&additionalData.boletobancario.dueDate=2013-08-15& additionalData.boletobancario.data=AgABAQClZUyg1NqsD7nN5X1uqN4mabJ7A3FH5LgAUbqDnJ6EAQlnSAVL+u7eWIXY/o+7F0v04ZEnh6VR/+IAUfJoMQba2uHb2+qezXU/hgULKuFov7s2ZnwmszAuuHgE6JvahvWtAygC5lnpLEgw34pp7z8Vf2hAQYO9mvELei6ZR8S6DMxVTObYGE6r/anhX1ucteKztIR79zv1wWWzV/bccQIqgOEp5b8AYU6mwOlbm0oP2lPZofq4CFAQfs/ROyBk0JBQlQDaZHQRmY8YP3236nD6eEr4cBEy6MpULl8w0iin39NxXGsi7OCmuQDe2w1Fy/40Iv6AA2sar3JTo4Ap3eraC6PEN8s5+SoOB5MO+fpFbRSfFeSHGh9L3/wzuxaXCHopNfwjjgx6aJEVv1FmaPzyVYm9kB7+/1IpaxzBIp6nTh5VSMp8iJOyOccCoV4e7Qv6SKNDkvT5lc2KPXg6jUC4tQJWyFFbvgV55rlQojjRecQfLwCiQ51tONSyaw2QLewemJJys9Q2AyIXYemGUXdzYAORNlSLJkTQdkoQZKdMwuOx4LDPFkNQuzHLlg4Xg+pWYhgSz0TEZJrS83voNSRTbrIwOPN3& additionalData.boletobancario.expirationDate=2013-08-22&resultCode=Received


API Manual

Appendix P: Sample Boleto FormsDefault Form


API Manual

Custom Form


API Manual

Appendix Q: Modification Request and Response - CaptureJSON Modification Request

{"merchantAccount": "TestMerchant","modificationAmount": { "value": 500, "currency": "EUR"},"originalReference": "8313547924770610","reference": "YourModificationReference"

}

JSON Modification Response

{"pspReference": “8413547924770610“,"response": “[capture-received]“

}

SOAP Modification Request

<?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">TestMerchant</merchantAccount> <modificationAmount xmlns="http://payment.services.adyen.com"> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">500</value> </modificationAmount> <originalReference xmlns="http://payment.services.adyen.com">8313547924770610</originalReference> <reference xmlns="http://payment.services.adyen.com">YourModificationReference</reference> </ns1:modificationRequest> </ns1:capture> </soap:Body></soap:Envelope>

SOAP Modification Response


API Manual

<?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">8413547924770610</pspReference> <response xmlns="http://payment.services.adyen.com">[capture-received]</authCode> </ns1:captureResult> </ns1:captureResponse> </soap:Body> </soap:Envelope>

REST Modification Request

merchantAccount=TestMerchant&originalReference=8313547924770610&reference=YourModificationReference&modificationAmount.currency=EUR&modificationAmount.value=500

REST Modification Response

pspReference=8413547924770610&response=%5Bcapture-received%5D


API Manual

Appendix R: Modification Request and Response - CancelJSON Cancel Request

{"merchantAccount": "TestMerchant”,"originalReference": "8313547924770610","reference": "YourModificationReference"

}

JSON Cancel Response

{"pspReference": "8412534564722331","response": "[cancel-received]"

}


<?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:cancel xmlns:ns1="http://payment.services.adyen.com"> <ns1:modificationRequest> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount> <originalReference xmlns="http://payment.services.adyen.com">8313547924770610</originalReference> <reference xmlns="http://payment.services.adyen.com">YourModificationReference</reference> </ns1:modificationRequest> </ns1:cancel> </soap:Body></soap:Envelope>


<?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:cancelResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:cancelResult> <pspReference xmlns="http://payment.services.adyen.com">8412534564722331</pspReference> <response xmlns="http://payment.services.adyen.com">[cancel-received]</authCode> </ns1:cancelResult> </ns1:cancelResponse> </soap:Body> </soap:Envelope>


API Manual


merchantAccount=TestMerchant&reference=YourModificationReference&originalReference=8313547924770610


pspReference=8412534564722331&response=%5Bcancel-received%5D


API Manual

Appendix S: Modification Request and Response - RefundJSON Refund Request

{"merchantAccount": "TestMerchant”,"modificationAmount": { "value": 500, "currency": "EUR"},"originalReference": "9313547924770610","reference": "YourModificationReference"

}

JSON Refund Response

{"pspReference": "8312534564722331","response": "[refund-received]"

}


<?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:refund xmlns:ns1="http://payment.services.adyen.com"> <ns1:modificationRequest> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</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">9313547924770610</originalReference> <reference xmlns="http://payment.services.adyen.com">YourModificationReference</reference> </ns1:modificationRequest> </ns1:refund> </soap:Body></soap:Envelope>


<?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:refundResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:refundResult> <pspReference xmlns="http://payment.services.adyen.com">8312534564722331</pspReference> <response xmlns="http://payment.services.adyen.com">[refund-received]</authCode> </ns1:refundResult> </ns1:refundResponse> </soap:Body> </soap:Envelope>


API Manual


merchantAccount=TestMerchant&originalReference=9313547924770610&reference=YourModificationReference&modificationAmount.currency=EUR&modificationAmount.value=500


pspReference=8312534564722331&response=%5Brefund-received%5D


API Manual

Appendix T: Modification Request and Response - CancelOrRefundJSON CancelOrRefund Request

{"merchantAccount": "TestMerchant”,"originalReference": "9313547924770610","reference": "YourModificationReference"

}

JSON CancelOrRefund Response

{"pspReference": "8863534564726784","response": "[cancelOrRefund-received]"

}


<?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:cancelOrRefund xmlns:ns1="http://payment.services.adyen.com"> <ns1:modificationRequest> <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount> <originalReference xmlns="http://payment.services.adyen.com">9313547924770610</originalReference> <reference xmlns="http://payment.services.adyen.com">YourModificationReference</reference> </ns1:modificationRequest> </ns1:cancelOrRefund> </soap:Body></soap:Envelope>


<?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:cancelOrRefundResponse xmlns:ns1="http://payment.services.adyen.com"> <ns1:cancelOrRefundResult> <pspReference xmlns="http://payment.services.adyen.com">8863534564726784</pspReference> <response xmlns="http://payment.services.adyen.com">[cancelOrRefund-received]</authCode> </ns1:cancelOrRefundResult> </ns1:cancelOrRefundResponse> </soap:Body> </soap:Envelope>


API Manual


merchantAccount=TestMerchant&reference=YourModificationReference&originalReference=9313547924770610


pspReference=8863534564726784&response=%5BcancelOrRefund-received%5D


API Manual

Appendix U: Notification Request and ResponseJSON Notification Request

{"live": "false","notificationItems": [ {

"NotificationRequestItem": {"additionalData": { "authCode": "58747", "cardSummary": "1111", "expiryDate": "6/2016"},

"amount": { "value": 500, "currency": "EUR"},

"pspReference": "9313547924770610","eventCode": "AUTHORISATION","eventDate": "2009-01-01T01:02:01.111+02:00","merchantAccountCode": "TestMerchant","operations": [ "CANCEL", "CAPTURE", "REFUND"],"merchantReference": "YourMerchantReference1","paymentMethod": "visa","reason": "58747:1111:12/2012","success": "true"

} }]}

JSON Notification Response

{"notificationResponse": "[accepted]"

}


API Manual

SOAP Notification Request

<?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> <entry> <key xsi:type="xsd:string">authCode</key> <value xsi:type="xsd:string">58747</value> </entry> <entry> <key xsi:type="xsd:string">cardSummary</key> <value xsi:type="xsd:string">1111</value> </entry> <entry> <key xsi:type="xsd:string">expiryDate</key> <value xsi:type="xsd:string">6/2016</value> </entry> </additionalData> <amount> <currency xmlns="http://common.services.adyen.com">EUR</currency> <value xmlns="http://common.services.adyen.com">500</value> </amount> <eventCode>AUTHORISATION</eventCode> <eventDate>2009-01-01T01:02:01.111+02:00</eventDate> <merchantAccountCode>TestMerchant</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>58747:1111:6/2016</reason> <success>true</success> </NotificationRequestItem> </ns1:Notification> </ns1:sendNotification> </soap:Body></soap:Envelope>


API Manual

SOAP Notification Response

<?xml version="1.0" encoding="UTF-8"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns1:sendNotificationResponse xmlns:ns1="http://notification.services.adyen.com" xmlns:ns2="http://common.services.adyen.com"> <notificationResponse>[accepted]</notificationResponse> </ns1:sendNotificationResponse> </soap:Body> </soap:Envelope>

REST Notification Request

eventDate=2009-01-01T01%3A02%3A01.111Z&reason=58747%3A1111%3A6%2F2016&additionalData.cardSummary= 1111&originalReference=&merchantReference=YourMerchantReference1&additionalData.expiryDate=6%2F2016&currency=EUR&pspReference=8888777766665555&additionalData.authCode=58747&merchantAccountCode=TestMerchant&eventCode=AUTHORISATION&value=500&operations=CANCEL%2CCAPTURE%2CREFUND&success=true& paymentMethod=visa&live=false

REST Notification Response

notificationResponse=&5Baccepted%5D


API Manual

Appendix V: Fault CodesError Code Error Message

000 Unknown

010 Not allowed

100 No amount specified

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 specified

112 This bank country is not supported

113 No InvoiceLines provided

114 Received an incorrect InvoiceLine

115 Total amount is not the same as the sum of the lines

116 Invalid date of birth

117 Invalid billing address

118 Invalid delivery address

119 Invalid shopper name

120 ShopperEmail is missing

121 ShopperReference is missing

122 PhoneNumber is missing

123 The PhoneNumber should be mobile

124 Invalid PhoneNumber

125 Invalid recurring contract specified

126 Bank Account or Bank Location Id not valid or missing

127 Account holder missing

128 Card Holder Missing

129 Expiry Date Invalid

130 Reference Missing

131 Billing address problem (City)

132 Billing address problem (Street)


API Manual

Error Code Error Message

133 Billing address problem (HouseNumberOrName)

134 Billing address problem (Country)

135 Billing address problem (StateOrProvince)

136 Failed to retrieve OpenInvoiceLines

137 Invalid amount specified

138 Unsupported currency specified

139 Recurring requires shopperEmail and shopperReference

140 Invalid expiryMonth[1..12] / expiryYear[>2000], or before now

141 Invalid expiryMonth[1..12] / expiryYear[>2000]

142 Bank Name or Bank Location not valid or missing

143 Submitted total iDeal merchantReturnUrl length is {0}, but max size is {1} for this request

144 Invalid startMonth[1..12] / startYear[>2000], or in the future

145 Invalid issuer countrycode

146 Invalid social security number

147 Delivery address problem (City)

148 Delivery address problem (Street)

149 Delivery address problem (HouseNumberOrName)

150 Delivery address problem (Country)

151 Delivery address problem (StateOrProvince)

152 Invalid number of installments

153 Invalid CVC

154 No additional data specified

155 No acquirer specified

156 No authorisation mid specified

157 No fields specified

158 Required field {0} not specified

159 Invalid number of requests

160 Not allowed to store Payout Details

161 Invalid iban

162 Inconsistent iban

163 Invalid bic

164 Auto-capture delay invalid or out of range

165 MandateId does not match pattern

166 Amount not allowed for this operation

167 Original pspReference required for this operation

168 AuthorisationCode required for this operation

170 Generation Date required but missing


API Manual


171 Unable to parse Generation Date

172 Encrypted data used outside of valid time period

173 Unable to load Private Key for decryption

174 Unable to decrypt data

175 Unable to parse JSON data

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 field

187 Invalid additionalData field

188 Invalid pspEchoData

189 Invalid shopperStatement

190 Invalid shopper IP

191 No params specified

192 Invalid field {0}

193 Bin Details not found for the given card number

194 Billing address missing

600 No InvoiceProject provided

601 No InvoiceBatch provided

602 No creditorAccount specified

603 No projectCode specified

604 No creditorAccount found

605 No project found

606 Unable to create InvoiceProject

607 InvoiceBatch already exists

608 Unable to create InvoiceBatch

609 InvoiceBatch validity period exceeded

610 No dunning configuration found

611 Invalid dunning configuration

690 Error while storing debtor

691 Error while storing invoice

692 Error while checking if invoice already exists for creditorAccount

693 Error while searching invoices

694 No Invoice Configuration configured for creditAccount


API Manual


695 Invalid Invoice Configuration configured for creditAccount

700 No method specified

701 Server could not process request

702 Problem parsing request

800 Contract not found

801 Too many PaymentDetails defined

802 Invalid contract

803 PaymentDetail not found

804 Failed to disable

805 RecurringDetailReference not available for provided recurring-contract

806 No applicable contractTypes left for this payment-method

901 Invalid Merchant Account

902 Shouldn't have gotten here without a request!

903 Internal error

904 Unable To Process

905 Payment details are not supported

906 Invalid Request: Original pspReference is invalid for this environment!

907 US Payment details are not supported

908 Invalid request

950 Invalid AcquirerAccount

951 Configuration Error (acquirerIdentification)

952 Configuration Error (acquirerPassword)

953 Configuration Error (apiKey)

954 Configuration Error (redirectUrl)

955 Configuration Error (AcquirerAccountData)

956 Configuration Error (currencyCode)

957 Configuration Error (terminalId)

958 Configuration Error (serialNumber)

959 Configuration Error (password)

960 Configuration Error (projectId)

961 Configuration Error (merchantCategoryCode)

962 Configuration Error (merchantName)

963 Invalid company registration number

964 Invalid company name

965 Missing company details

966 Configuration Error (privateKeyAlias)

967 Configuration Error (publicKeyAlias)


API Manual


1000 Card number cannot be specified for Incontrol virtual card requests

1001 Recurring not allowed for Incontrol virtual card requests

1002 Invalid Authorisation Type supplied


API Manual

Appendix W: Minor Units for CurrenciesCode Currency Exponent Code Currency Exponent

AED UAE Dirham 2 EEK Estonian Krone 2

ALL Albanian Lek 2 EGP Egyptian Pound 2

AMD Armenian Dram 2 ETB Ethiopian Birr 2

ANG Antillian Guilder 2 EUR Euro 2

ARS Nuevo Argentine Peso 2 FJD Fiji Dollar 2

AUD Australian Dollar 2 FKP Falkland Islands Pound 2

AWG Aruban Guilder 2 GBP Pound Sterling 2

AZN Azerbaijani manat 2 GEL Georgian Lari 2

BAM Bosnia and Herzegovina Convertible Marks

2 GHC Ghanaian Cedi (2nd) 0

BBD Barbados Dollar 2 GHS Ghanaian Cedi (3rd) 2

BDT Bangladesh Taka 2 GIP Gibraltar Pound 2

BGL Bulgaria Lev 2 GMD Gambia Delasi 2

BGN New Bulgarian Lev 2 GNF Guinea Franc 0

BHD Bahraini Dinar 3 GTQ Guatemala Quetzal 2

BMD Bermudian Dollar 2 GYD Guyanese Dollar 2

BND Brunei Dollar 2 HKD Hong Kong Dollar 2

BOB Bolivia Boliviano 2 HNL Honduras Lempira 2

BRL Brazilian Real 2 HRK Croatia Kuna 2

BSD Bahamian Dollar 2 HTG Haitian Gourde 2

BWP Botswana Pula 2 HUF Hungarian Forint 2

BYR Belarusian Ruble 0 IDR Indonesian Rupiah 0

BZD Belize Dollar 2 ILS New Israeli Scheqel 2

CAD Canadian Dollar 2 INR Indian Rupee 2

CHF Swiss Franc 2 ISK Iceland Krona 2

CLP Chilean Peso 2 JMD Jamaican Dollar 2

CNY Yuan Renminbi 2 JOD Jordanian Dinar 3

COP Colombian Peso 2 JPY Japanese Yen 0

CRC Costa Rican Colon 2 KES Kenyan Shilling 2

CSD Serbian Dinar 2 KGS Kyrgyzstan Som 2

CVE Cape Verdi Escudo 0 KHR Cambodia Riel 2

CZK Czech Koruna 2 KMF Comoro Franc 0

DJF Djibouti Franc 0 KRW South-Korean Won 0

DKK Danish Krone 2 KWD Kuwaiti Dinar 3

DOP Dominican Republic Peso 2 KYD Cayman Islands Dollar 2


API Manual

Code Currency Exponent Code Currency Exponent

DZD Algerian Dinar 2 KZT Kazakhstani Tenge 2

LAK Laos Kip 2 RWF Rwanda Franc 0

LBP Lebanese Pound 2 SAR Saudi Riyal 2

LKR Sri Lanka Rupee 2 SBD Solomon Island Dollar 2

LTL Lithuanian Litas 2 SCR Seychelles Rupee 2

LVL Latvian Lats 2 SEK Swedish Krone 2

LYD Libyan Dinar 3 SGD Singapore Dollar 2

MAD Moroccan Dirham 2 SHP St. Helena Pound 2

MDL Moldovia Leu 2 SKK Slovak Koruna 2

MNT Mongolia Tugrik 2 SLL Sierra Leone 2

MOP Macau Pataca 2 SOS Somalia Shilling 2

MRO Mauritania Ouguiya 1 STD Sao Tome & Principe Dobra 2

MUR Mauritius Rupee 2 SVC El Salvador Colón 2

MVR Maldives Rufiyaa 2 SZL Swaziland Lilangeni 2

MWK Malawi Kwacha 2 THB Thai Baht 2

MXN Mexican Peso 2 TND Tunisian Dinar 3

MXP Mexican Peso 2 TOP Tonga Pa’anga 2

MYR Malaysian Ringgit 2 TRY New Turkish Lira 2

NAD Namibian Dollar 2 TTD Trinidad & Tobago Dollar 2

NGN Nigerian Naira 2 TWD New Taiwan Dollar 2

NIO Nicaragua Cordoba Oro 2 TZS Tanzanian Shilling 2

NOK Norwegian Krone 2 UAH Ukraine Hryvnia 2

NPR Nepalese Rupee 2 UGX Uganda Shilling 0

NZD New Zealand Dollar 2 USD US Dollars 2

OMR Rial Omani 3 UYU Peso Uruguayo 2

PAB Panamanian Balboa 2 UZS Uzbekistani Som 2

PEN Peruvian Nuevo Sol 2 VEF Venezuelan Bolívar 2

PGK New Guinea Kina 2 VND Vietnamese New Dong 0

PHP Philippine Peso 2 VUV Vanuatu Vatu 0

PKR Pakistan Rupee 2 WST Samoan Tala 2

PLN New Polish Zloty 2 XAF CFA Franc BEAC 0

PYG Paraguay Guarani 0 XCD East Carribean Dollar 2

QAR Qatari Rial 2 XOF CFA Franc BCEAO 0

ROL Romanian Lei 2 XPF CFP Franc 0

RON New Romanian Lei 2 YER Yemeni Rial 2

RSD Serbian Dinar 2 ZAR South African Rand 2

RUB Russian Ruble 2 ZMW Zambia Kwacha 2


API Manual


API Manual

Adyen APIManual

Documents

general payment fields

payment response fields

payment fields3

card payment specific

json api

api payments

dj amsterdamp

eb amsterdamthe netherlands