API Manual

Due to strict industry regulations, submitting card payments using the direct API is only available to merchants with full Payment Card Industry Data Security Standard ( PCI DSS) compliance Level 1 or Level 2. Furthermore, certain implementations of the API may require that you process at least a specified minimum amount of transactions per year.

If you do not have full PCI DSS compliance, you may wish to consider integration alternatives like our Hosted Payment Pages (HPP) or Easy Encryption (EE), which considerably reduce your PCI compliance requirements.

While integrating the Adyen platform of products and services with a third-party system, we strongly recommend you follow defensive programming best practices.
This means, for example, that system-automated decisions should have defaulted to non-delivery of products and services:
  • Your system should deliver products and services only after receiving an explicit authorisation response to a corresponding payment request.
  • Your system should not deliver any products or services when it does not receive any explicit response.

When communicating with Adyen, it is important to respect the DNS Time-To-Live (TTL). Some technologies, for example Java, cache DNS lookups by default. Adyen routinely changes its DNS configuration. If your implementation caches DNS lookup, it may affect your ability to submit modifications and/or payments.

When you make requests, you need to provide basic authentication credentials, i.e. user name and password. For automated request and retrieval operations, you can specify this information in the library you use to handle the server-to-server requests and responses with the Adyen platform.
To set a password for your Adyen user account, go to the Adyen Customer Area (CA), then select Settings | Users.

ws@Company.[YourCompanyAccount] User name format for a company level account.
ws@Company. / ws_123456@Company The first part of the user name remains as is.
[YourCompanyAccount] This is a placeholder. For example: ws@company.TestCompany

Some implementations of the API may require that you process at least a specified minimum amount of transactions per year.

Adyen sales representatives are available to help you with your questions about PCI DSS regulations, and they can advise you on API matters and transaction volume requirements. Don't hesitate and get in touch with your Adyen sales representative to learn more.

Audience

This manual targets developers who integrate merchants' systems with the Adyen payment platform.

HPP and CSE alternatives

Besides the direct API integration, Adyen offers alternative integration solutions that are lighter on the PCI compliance side, and therefore easier in terms of requirements:
  • Hosted Payment Pages (HPP): you can use this integration type instead of or in combination with the direct API one. Most non-card payment methods are only available through HPP; moreover, if you opt for an HPP integration to implement card payments, a considerable benefit for you is that it minimizes your PCI compliance requirements.
  • Client-Side Encryption (CSE): with this integration type, shoppers complete their full card payment transactions on your web site or in your application. Again, you can use our direct API integration in combination with client-side encryption (CSE) to encrypt card data in the client, i.e. in a web browser or a mobile app., to reduce your PCI compliance requirements and to make the process easier.

This functionality is not enabled by default, as it requires additional configuration on Adyen's end. Contact the  Adyen Support Team to request enabling it for you.

Feedback

We strive to provide you with clear, concise, and complete documentation. We are committed to improving it continuously to make it accessible and easy to understand.

We appreciate your comments, and we'd love to hear your voice: drop us a line and share your thoughts with us!

  Adyen Support Team

API last update

Version

Date

Changes

4.6.2 2016-10-10 Updated notifications section with directions on how to disable the notification endpoint

Version

Date

Changes

4.6.2 2016-10-10 Updated notifications section with directions on how to disable the notification endpoint
4.6.1 2016-09-29 Added new event code in Notification fields.
4.6 2016-08-22
  • API version moved to 18.
  • Added metadata for payments.
  • Added the ACH Direct Debit  section.
4.5.9 2016-08-05 Added new authorisation refusal reason.
4.5.8 2016-05-11 Updated the reason field in Notifications.
4.5.7 2016-04-07

Added new promotion and basket risk fields.

4.5.6 2016-03-25

Updated fields for payment requests.

4.5.5 2016-03-14

Updated information on Boleto.

4.5.4 2016-02-11

Added new refusal reasons.

4.5.3 2016-01-26

Added information in BIN data and card verification.

4.5.2 2015-12-09

Added information about testing a chargeback in Error codes.

4.5.1 2015-11-12

Included optional fields for risk system.

4.5 2015-10-29

Included information on HMAC calculation.

4.4.1 2015-10-19

Renaming of pages according to our product naming.

4.4 2015-10-15
  • Added airline data.
  • Rearrange of pages to have a better flow.
4.3 2015-09-14

Introduced merchant-specific URL endpoints for API calls to provide improved security.

4.2 2015-08-20

Removed obsolete payment information from the Direct Debit payments section.

4.1 2015-06-19

Adding new refusal reason for payment authorisations.

4.0 2015-05-12
  • Documentation migration from PDF to web-based online deliverable as main distributable asset.
  • Versioning: version reset and adoption of semantic versioning as per v. 4.0.0.
  • Manual redesign to improve readability, navigation, content findability.

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.0

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 on card verification

2.15

2014-10-16

Removed optional functionality

2.14

2014-08-28

  • Added instalments WSDL to Appendix A
  • Added code for inserting line breaks to section 7 and updated examples in Appendices P and Q
  • Corrected typo in REST example in 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

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.0

2013-11-14

  • Combined SOAP and REST manuals
  • Added client-side encryption (CSE)
  • Updated document to conform to Adyen brand guidelines

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 Instalments

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 communication

You can communicate with the Adyen API in one of these ways:

 JSON should be the default way to integrate to Adyen unless there is a strong preference to use another data representation. The data representations are treated exactly the same by Adyen, the only difference is the way they are mapped to/from Adyen's internal object structures.

JSON (JavaScript Object Notation) is an open standard format that uses human-readable text to transmit data objects consisting of key-value pairs. It is used primarily to transmit data between a server and web application, as an alternative to XML.
To submit JSON messages to our API endpoint over HTTPS:

 

SOAP is a messaging protocol to send data in a standardized XML format to web services.

SOAP implementations can automatically handle a number of edge cases around encoding, type safety and validation, resulting in a very robust integration (at the cost of being somewhat more cumbersome and complex).

To submit SOAP messages to our API endpoint over HTTPS:

  • Set the Content-Type HTTP header field of the request to text/XML.

SOAP can be beneficial to high-volume merchants, particularly as far as notifications are concerned: if there are many pending notifications, Adyen can transfer multiple notifications in a single SOAP message. For example, when compared to FORM messages, SOAP notifications use fewer requests and improve throughput.

Contrary to other representations, the SOAP standard does not support HTTP status other than 500 for error/exception handling.

A request can also be submitted as standard HTML Form key-value pairs. Note that for complex data structures, a JSON representation is more readable, easier to code and less error prone. 

To submit HTML Form data to our API endpoint over HTTPS:

  • Set the Content-Type HTTP header field of the request to application/x-www-form-urlencoded.
  • Special care needs to be taken to URL encode the parameter keys and values using UTF-8 character encoding.

API endpoints

When integrating with the Adyen platform, you can use either generic or custom endpoints to communicate with our API.

Our API is versioned using the URL of the endpoint. For example: https://pal-test.adyen.com/pal/servlet/Payment/v25/authorise.

While we endeavor to maintain backwards compatibility, we version the API when a change will create compatibility issues.  We maintain older versions of the API which you can continue to use until you are ready to upgrade. 

By default the Adyen platform will always use our latest API endpoints, which are subject to change. We recommend merchants use specific endpoint versioning in their code to avoid issues with backwards compatibility.


Generic endpoints

This is an overview of the  test and  live URLs to communicate with the API using  JSONSOAP or  FORM.

Test:

This is an overview of the test URL endpoints to communicate with our API using JSON. Use them to test your implementation and run QA checks.

Authorise

https://pal-test.adyen.com/pal/servlet/Payment/v25/authorise

Authorise 3D https://pal-test.adyen.com/pal/servlet/Payment/v25/authorise3d
Capture https://pal-test.adyen.com/pal/servlet/Payment/v25/capture
Refund https://pal-test.adyen.com/pal/servlet/Payment/v25/refund
Cancel https://pal-test.adyen.com/pal/servlet/Payment/v25/cancel
Cancel or Refund https://pal-test.adyen.com/pal/servlet/Payment/v25/cancelOrRefund

Live:

This is an overview of the live URL endpoints to communicate with our API using JSON. Use them in your live/production environment.

Authorise https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/authorise
Authorise 3D https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/authorise3d
Capture https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/capture
Refund https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/refund
Cancel https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/cancel
Cancel or Refund https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/cancelOrRefund

Test:

This is an overview of the test URL endpoints to communicate with our API using the SOAP messaging protocol. Use them to test your implementation and run QA checks.
Payment service https://pal-test.adyen.com/pal/servlet/Payment/v25
Payment service WSDL

https://pal-test.adyen.com/pal/servlet/Payment/v25?wsdl

Live:

This is an overview of the live URL endpoints to communicate with our API using the SOAP messaging protocol.
Use them in your live/production environment.
Payment service https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25
Payment service WSDL https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25?wsdl

Test:

This is an overview of the test URL endpoints to communicate with our API using FORM. Use them to test your implementation and run QA checks.

Authorise https://pal-test.adyen.com/pal/servlet/Payment/v25/authorise
Authorise 3D https://pal-test.adyen.com/pal/servlet/Payment/v25/authorise3d
Capture https://pal-test.adyen.com/pal/servlet/Payment/v25/capture
Refund https://pal-test.adyen.com/pal/servlet/Payment/v25/refund
Cancel https://pal-test.adyen.com/pal/servlet/Payment/v25/cancel
Cancel or Refund https://pal-test.adyen.com/pal/servlet/Payment/v25/cancelOrRefund

Live:

This is an overview of the live URL endpoints to communicate with our API using FORM. Use them in your live/production environment.

Authorise https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/authorise
Authorise 3D https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/authorise3d
Capture https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/capture
Refund https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/refund
Cancel https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/cancel
Cancel or Refund https://[Custom-Endpoint].pal-live.adyenpayments.com/pal/servlet/Payment/v25/cancelOrRefund

Custom endpoints

Although generic URL endpoints for our APIs are still supported (payment API, recurring API), we recommend setting up merchant-specific endpoints. This is the default endpoint configuration option for new merchants.

Merchant-specific endpoints are available only for API integrations, and only in our live environment.

For test purposes, you can use our generic test points.

Merchant-generic API URL endpoint

The standard, generic payment API URL endpoints to communicate with the Adyen payment API are built as shown in this example:

https://pal-live.adyen.com/pal/servlet/Payment/v25/capture

The example shows the standard, generic URL endpoint to make a payment capture request.

Merchant-specific API URL endpoint

Each company account is provided with a unique hostname to communicate with Adyen's APIs.

By connecting to this merchant-specific hostname, Adyen has more control over the routing of transactions. This allows Adyen to improve service robustness and availability for our merchants.

By default all transactions for a merchant-specific endpoint are routed to the same infrastructure as the standard endpoint, however in case of an infrastructure problem on the standard endpoint, especially if the cause is outside of Adyen's scope of control, alternative routing can be enabled to backup infrastructure and new infrastructure can be provisioned on demand.

Example

Convert the generic API endpoint with path “/pal/servlet/Payment/v25/authorise” from:

https://pal-live.adyen.com/pal/servlet/Payment/v25/authorise

to:

https://f96e63be5147-TestCompany.pal-live.adyenpayments.com/pal/servlet/Payment/v25/authorise

Endpoint format

The custom endpoint has the following format:

https://[random]-[company name].pal-live.adyenpayments.com
random

A random string of hex-encoded bytes to make the hostname unpredictable.

company name

The company name is included in the URL endpoint.

  • If the name is too long:
    it is shortened.
  • If the name includes underscores or hyphens:
    any underscores and/or hyphens are stripped.

Endpoint settings

You can access the API endpoint(s) of your company account through the Adyen Customer Area (CA):

  • Log in to the Adyen Customer Area (CA) using your credentials.
  • In the left navigation sidebar, select Settings.
  • On the Settings page, click API URLs.
  • On the API URLs page, you can see the configured endpoint(s) for your company account.

Click API URLs to access the endpoint overview page.

In this example, the TestCompany account has two API URL endpoints: one is configured to communicate with our European servers, whereas the other is set up to exchange data with our US-based servers.
This setup allows you to optimize data traffic depending on the region you operate in.

API idempotency

In an API context, idempotency (or idempotence) means that making the same request many times produces the same effect as making it only once. The operation is free of side effects. This consistent behaviour helps avoid unwanted duplication in case of failures and operation retries. For example, in case of a timeout error it is possible to safely retry sending the same API payment authorisation call many times. When the call successfully delivers its message, only one response action is executed, and the payment is not duplicated.

The accounting rules in the Adyen system take care of most potential double-processing issues that can impact payment modifications.
For example, the following default rules apply to payment authorisations:

  • One authorisation = One capture. Only one capture is accepted for an authorisation.
  • It is not possible to capture a higher amount than the authorised one.

As for refunds:

  • Whereas multiple refunds are allowed, by default the total refunded value cannot exceed the captured amount.

To minimize the risk of unwanted side effects and duplication, you can take the following actions on your end:

  • Implement asynchronous server-to-server notifications to return API request results. For example, this approach helps keep track of missing responses, a common consequence of a data transmission timeout.

  • Implement idempotency and include in your API request the additional Pragma HTTP header key and the corresponding pragma-directive header value.

Enable idempotency

To use the idempotency property of the Adyen API, provide your merchant account and unique merchant reference sent with your request.

For subsequent retries the same unique merchant reference of the first request needs to be used in order to check if the first one was already processed.

Pragma HTTP header

To enable idempotency, set the Pragma  HTTP header  to:

  • Trigger idempotent behaviour.
  • Report status information.

Pragma header key and pragma-directive header value

When a request you send receives no response, you can enable idempotent behaviour by including the Pragma HTTP header key and the appropriate pragma-directive value in your request.

To enable idempotency, you need to set the pragma-directive value to process-retry.

HTTP header key name HTTP header value name Syntax Example
Pragma pragma-directive
Pragma: pragma-directive
Pragma: process-retry

Multiple pragma directive values are comma-separated.

Code example

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/v25" \ 
&& xmllint --format result.xml --output result.xml

Retry idempotent submission

Sometimes, you may want to retry sending a transaction whose status is not finalized yet, and at the same time you want to avoid processing a transaction multiple times. This flow consists of the following steps:

Retry request

When we receive a request that includes the Pragma: process-retry HTTP header, our system performs a lookup to determine whether:

  • The request has already been processed. 
  • The request has not been processed yet.

The request has already been processed

The request has already been processed. In this case:

  • No further processing occurs.
  • We send you a PROCESS_RETRY event code notification, besides the standard scheduled notification for this operation.


The request has not been processed yet

The request has not been processed yet. In this case:

  • The request is processed as if it were the initial request.
  • We send you the standard scheduled notification for this operation, and a PROCESS_RETRY event code notification.

Retry notification

When you submit a request with the Pragma: process-retry HTTP header, you receive a response with a pspReference element.

The request has already been processed

When the request has already been processed, the pspReference in the response is different from the pspReference in the initial request because the initial request missed its synchronous response.

To reconcile the association between the initial request and the corresponding retry, our system sends you a notification with the eventCode value set to PROCESS_RETRY.

This notification contains both pspReference values:

  • pspReference: this field holds the retry request pspReference value.
  • originalReference: this field holds initial request pspReference value.

The request has not been processed yet

When the request has not been processed yet, the pspReference in the response is the same as the the pspReference in the initial request.

Therefore, the notification with the eventCode value set to PROCESS_RETRY you receive from Adyen includes a pspReference value matching the one in the corresponding initial request.

Security - 3D, AVS

Before moving on to describe the different payment methods you can implement using the Adyen API, let's spend a few words on making transactions secure.

This section describes how you can introduce and test additional security layers to payment transactions by implementing the following approaches:

3D Secure

3D Secure (Verified by VISA, MasterCard SecureCode™) is an additional authentication protocol that increases security: the shopper is redirected to their card issuer, where they need to authenticate before the payment operation can send an authorisation request.

Prerequisites

To introduce 3D Secure in your transaction flow, you need to take care of this first:

  • For TEST environment this functionality is enabled by default. 
  • For LIVE, it is enabled by default for VISA/Mastercard/Maestro/BCMC (EU acquiring), and in other cases you need to contact the Adyen Support Team and request configuring 3D Secure for your account.

Your integration should support:

  1. Making an API call to redirect the shopper to the card issuer;

  2. Submitting a second API call after the redirect to complete the payment.

 

Redirect to the card issuer

This API call is very similar for non-3D Secure and 3D Secure payment transactions.

3D Secure payments require one additional element: browserInfo.

The browserInfo object is a child element of the paymentRequest main element in a payment request.

browserInfo acts as a container object for the following child elements:

  • acceptHeader: holds the Accept header information of the shopper's web browser.
  • userAgentuser agent information of the shopper's browser.

"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"
}
<browserInfo xmlns="http://payment.services.adyen.com">
    <acceptHeader xmlns="http://common.services.adyen.com">text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8</acceptHeader>
    <userAgent xmlns="http://common.services.adyen.com">Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0</userAgent>
</browserInfo>
browserInfo.acceptHeader=text%2Fhtml%2Capplication%2Fxhtml%2Bxml%2Capplication%2Fxml%3Bq%3D0.9%2C%2A%2F%2A%3Bq%3D0.8&browserInfo.userAgent=Mozilla%2F5.0+%28X11%3B+Linux+x86_64%29+AppleWebKit%2F537.31+%28KHTML%2C+like+Gecko%29+Chrome%2F26.0.1410.63+Safari%2F537.31

3D Secure directory lookup

After your account is configured for 3D Secure, the Adyen system performs a directory lookup to check if the card is enrolled in the 3D Secure program:

  • If the card is not enrolled, the response is the same as a normal API authorise call.
  • If the card is enrolled, the response contains the following fields:
Name Type Returned by default Description
paRequest String (tick) 3D Secure request data for the issuer.
md String (tick)
Payment session identifier returned by the card issuer.
Identifies the payment session.
issuerUrl String (tick) Redirect URL: this is the HTTP POST action value.
This URL is the endpoint for the HTML form you use to redirect the shopper to the card issuer 3D Secure verification page.
resultCode String (tick)

Returns the code defining the 3D Secure directory lookup result type. Allowed values:

  • RedirectShopper

RedirectShopper correctly redirects the shopper to the card issuer site to carry out 3D Secure verification.

Submit 3D Secure lookup response

When a 3D Secure directory lookup confirms that a card is enrolled, you can redirect the shopper to the card issuer for 3D Secure verification.

You can use an HTML form that you submit with an HTTP POST method call to the URL endpoint specified in issuerUrl.

The form should be self-submitting, with a fallback option in case the shopper disabled JavaScript in their web browser.

In the form, include the following elements:

Name Type Required Description
PaReq String (tick) It corresponds to paRequest.
It holds the 3D Secure request data for the issuer.
MD String (tick)
It corresponds to md.
Payment session identifier returned by the card issuer.
Identifies the payment session.
TermUrl String (tick)

It corresponds to termUrl.
After completing 3D Secure verification on the card issuer site, the shopper is redirected back to the merchant site.
This URL value specifies the merchant site page the shopper goes back to.

Return to the merchant site

After a successful 3D Secure verification, the issuer redirects the shopper to merchant website using an HTTP POST call to the URL endpoint specified in TermUrl.

The POST call includes the following parameters, which should be used while making an authorise payment call to Adyen, to complete the payment transaction:

Name Type Required Description
MD String (tick)
Payment session identifier returned by the card issuer.
Identifies the payment session.
PaRes String (tick) Payment authorisation response returned by the card issuer.

Authorise the payment

To complete a 3D Secure authenticated payment, you call authorise3d and pass the following parameters with the call:

Name Type Required Description
merchantAccount String (tick) The merchant account details specified here should be the same as the corresponding information in the initial payment authorise request.
browserInfo String (tick) You can use the same browserInfo values specified at the beginning of the transaction, as these values are unlikely to change during a transaction.
md String (tick)
Payment session identifier returned by the card issuer.
Identifies the payment session.
paResponse String (tick) Payment authorisation response returned by the card issuer.
paResponse holds the PaRes value received from the card issuer.
shopperIP String (error)

IP address of the shopper.

We strongly recommend providing this data, as it is used in a number of risk checks, like location-based and number of payment attempts checks.

Dynamic 3D secure

RevenueProtect includes a Dynamic 3D secure engine, which enables the establishment of rules that dictate whether a call for local payment methods goes through to 3D Secure or not. All transactions that are sent in with browserInfo go through this engine. If the rule determines that 3DS should be used, the Directory Lookup call is made. If the rules determine that 3DS should not be used, an authorization call occurs without 3D Secure.

if no rules have been defined in the Dynamic 3D Secure engine, all transactions goes through a 3D secure directory lookup call. This allows you to maintain a 3D Secure routing logic on your side by controlling when browserInfo is sent.

3D Secure code examples

Following are the code examples using JSON. SOAP, and FORM:

{
    "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"
}

<?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>

curl --user 'user:pass' https://pal-test.adyen.com/pal/servlet/Payment/authorise3d \
--data-urlencode 'merchantAccount=yourMerchantAccount' \
--data-urlencode 'md=d7T...J+xbw==' \
--data-urlencode 'paResponse=eNqtmF....7pqfKo=' \
--data-urlencode 'browserInfo.acceptHeader=text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
--data-urlencode 'browserInfo.userAgent=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.31 (KHTML, like Gecko) Chrome/26.0.1410.63 Safari/537.31'
Initiate a 3D Secure payment with an HTML form

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>Adyen - Create 3D Secure Payment</title>
    </head>
    <body onload="document.getElementById('3dform').submit();">
        <form method="POST" action="${IssuerUrl}" id="3dform">
            <input type="hidden" name="PaReq" value="${PaReq}" />
            <input type="hidden" name="MD" value="${MD}" />
            <input type="hidden" name="TermUrl" value="${TermUrl}" />
            <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>
</html>

(source: create-3d-secure-payment.jsp)

Create a 3D Secure payment with HTTP POST (Java)

package com.adyen.examples.api;

import java.io.IOException;
import java.io.PrintWriter;
import java.io.UnsupportedEncodingException;
import java.net.URLDecoder;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.client.HttpClient;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

/**
 * Create 3D Secure payment (HTTP Post)
 *
 * 3D 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 (support@adyen.com).
 * 2. Your integration should support redirecting the shopper to the card issuer and submitting
 *    a second API call to complete the payment.
 *
 * This example demonstrates the initial API call to create the 3D secure payment using HTTP Post,
 * and shows the redirection the the card issuer.
 * See the API Manual for a full explanation of the steps required to process 3D Secure payments.
 *
 * @link /2.API/HttpPost/Create3dSecurePayment
 * @author Created by Adyen - Payments Made Easy
 */

@WebServlet(urlPatterns = { "/2.API/HttpPost/Create3dSecurePayment" })
public class Create3dSecurePaymentHttpPost extends HttpServlet {

    protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

        /**
         * HTTP Post settings
         * - apiUrl: URL of the Adyen API you are using (Test/Live)
         * - wsUser: your web service user
         * - wsPassword: your web service user's password
         */
        String apiUrl = "https://pal-test.adyen.com/pal/adapter/httppost";
        String wsUser = "YourWSUser";
        String wsPassword = "YourWSUserPassword";

        /**
         * Create HTTP Client (using Apache HttpComponents library) and set up Basic Authentication
         */
        CredentialsProvider provider = new BasicCredentialsProvider();
        UsernamePasswordCredentials credentials = new UsernamePasswordCredentials(wsUser, wsPassword);
        provider.setCredentials(AuthScope.ANY, credentials);

        HttpClient client = HttpClientBuilder.create().setDefaultCredentialsProvider(provider).build();

        /**
         * A payment can be submitted by sending a PaymentRequest to the authorise action of the web service.
         * 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.
         *
         * <pre>
         * - merchantAccount           : The merchant account for which you want to process the payment
         * - amount
         *     - currency              : The three character ISO currency code.
         *     - value                 : The transaction amount in minor units (e.g. EUR 1,00 = 100).
         * - reference                 : Your reference for this payment.
         * - shopperIP                 : The shopper's IP address. (recommended)
         * - shopperEmail              : The shopper's email address. (recommended)
         * - shopperReference          : An ID that uniquely identifies the shopper, such as a customer id. (recommended)
         * - fraudOffset               : An integer that is added to the normal fraud score. (optional)
         * - card
         *     - expiryMonth           : The expiration date's month written as a 2-digit string,
         *                               padded with 0 if required (e.g. 03 or 12).
         *     - expiryYear            : The expiration date's year written as in full (e.g. 2018).
         *     - holderName            : The card holder's name, as embossed on the card.
         *     - number                : The card number.
         *     - cvc                   : The card validation code, which is the CVC2 (Mastercard),
         *                               CVV2 (Visa) or CID (American Express).
         *     - billingAddress (recommended)
         *         - street            : The street name.
         *         - houseNumberOrName : The house number (or name).
         *         - city              : The city.
         *         - postalCode        : The postal/zip code.
         *         - stateOrProvince   : The state or province.
         *         - country           : The country in ISO 3166-1 alpha-2 format (e.g. NL).
         * - browserInfo
         *     - userAgent             : The user agent string of the shopper's browser (required).
         *     - acceptHeader          : The accept header string of the shopper's browser (required).
         * </pre>
         */
        List<NameValuePair> postParameters = new ArrayList<NameValuePair>();
        Collections.addAll(postParameters,
            new BasicNameValuePair("action", "Payment.authorise"),

            new BasicNameValuePair("paymentRequest.merchantAccount", "YourMerchantAccount"),
            new BasicNameValuePair("paymentRequest.reference",
                "TEST-3D-SECURE-PAYMENT-" + new SimpleDateFormat("yyyy-MM-dd-HH:mm:ss").format(new Date())),
            new BasicNameValuePair("paymentRequest.shopperIP", "123.123.123.123"),
            new BasicNameValuePair("paymentRequest.shopperEmail", "test@example.com"),
            new BasicNameValuePair("paymentRequest.shopperReference", "YourReference"),
            new BasicNameValuePair("paymentRequest.fraudOffset", "0"),

            new BasicNameValuePair("paymentRequest.amount.currency", "EUR"),
            new BasicNameValuePair("paymentRequest.amount.value", "199"),

            new BasicNameValuePair("paymentRequest.card.expiryMonth", "06"),
            new BasicNameValuePair("paymentRequest.card.expiryYear", "2018"),
            new BasicNameValuePair("paymentRequest.card.holderName", "John Doe"),
            new BasicNameValuePair("paymentRequest.card.number", "5212345678901234"),
            new BasicNameValuePair("paymentRequest.card.cvc", "737"),

            new BasicNameValuePair("paymentRequest.card.billingAddress.street", "Simon Carmiggeltstraat"),
            new BasicNameValuePair("paymentRequest.card.billingAddress.houseNumberOrName", "6-50"),
            new BasicNameValuePair("paymentRequest.card.billingAddress.postalCode", "1011 DJ"),
            new BasicNameValuePair("paymentRequest.card.billingAddress.city", "Amsterdam"),
            new BasicNameValuePair("paymentRequest.card.billingAddress.stateOrProvince", ""),
            new BasicNameValuePair("paymentRequest.card.billingAddress.country", "NL"),

            new BasicNameValuePair("paymentRequest.browserInfo.userAgent", request.getHeader("User-Agent")),
            new BasicNameValuePair("paymentRequest.browserInfo.acceptHeader", request.getHeader("Accept"))
            );

        /**
         * Send the HTTP Post request with the specified variables.
         */
        HttpPost httpPost = new HttpPost(apiUrl);
        httpPost.setEntity(new UrlEncodedFormEntity(postParameters));

        HttpResponse httpResponse = client.execute(httpPost);
        String paymentResponse = EntityUtils.toString(httpResponse.getEntity(), "UTF-8");

        /**
         * Keep in mind that you should handle errors correctly.
         * If the Adyen platform does not accept or store a submitted request, you will receive a HTTP response with
         * status code 500 Internal Server Error. The fault string can be found in the paymentResponse.
         */
        if (httpResponse.getStatusLine().getStatusCode() == 500) {
            throw new ServletException(paymentResponse);
        }
        else if (httpResponse.getStatusLine().getStatusCode() != 200) {
            throw new ServletException(httpResponse.getStatusLine().toString());
        }

        /**
         * 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:
         *
         * - paRequest     : The 3-D request data for the issuer.
         * - md            : The payment session.
         * - issuerUrl     : The 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. In this example we are redirecting to another example
         * which completes the 3D Secure payment.
         *
         * @see Authorise3dSecurePaymentHttpPost.java
         *
         * We recommend that the form is "self-submitting" with a fallback in case javascript is disabled.
         * A sample form is implemented in the file below.
         *
         * @see WebContent/2.API/create-3d-secure-payment.jsp
         */
        Map<String, String> paymentResult = parseQueryString(paymentResponse);

        if (paymentResult.get("paymentResult.resultCode").equals("RedirectShopper")) {
            // Set request parameters for use on the JSP page
            request.setAttribute("IssuerUrl", paymentResult.get("paymentResult.issuerUrl"));
            request.setAttribute("PaReq", paymentResult.get("paymentResult.paRequest"));
            request.setAttribute("MD", paymentResult.get("paymentResult.md"));
            request.setAttribute("TermUrl", "YOUR_URL_HERE/Authorise3dSecurePayment");

            // Set correct character encoding
            response.setCharacterEncoding("UTF-8");

            // Forward request data to corresponding JSP page
            request.getRequestDispatcher("/2.API/create-3d-secure-payment.jsp").forward(request, response);
        }
        else {
            PrintWriter out = response.getWriter();

            out.println("Payment Result:");
            out.println("- pspReference: " + paymentResult.get("paymentResult.pspReference"));
            out.println("- resultCode: " + paymentResult.get("paymentResult.resultCode"));
            out.println("- authCode: " + paymentResult.get("paymentResult.authCode"));
            out.println("- refusalReason: " + paymentResult.get("paymentResult.refusalReason"));
        }

    }

    /**
     * Parse the result of the HTTP Post request (will be returned in the form of a query string)
     */
    private Map<String, String> parseQueryString(String queryString) throws UnsupportedEncodingException {
        Map<String, String> parameters = new HashMap<String, String>();
        String[] pairs = queryString.split("&");

        for (String pair : pairs) {
            String[] keyval = pair.split("=");
            parameters.put(URLDecoder.decode(keyval[0], "UTF-8"), URLDecoder.decode(keyval[1], "UTF-8"));
        }

        return parameters;
    }

}

(source: Create3dSecurePaymentHttpPost.java)

Authorise a 3D Secure payment with HTTP POST (Java)

package com.adyen.examples.api;

import java.io.IOException;
import java.io.PrintWriter;
import java.io.UnsupportedEncodingException;
import java.net.URLDecoder;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.client.HttpClient;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

/**
 * Authorise 3D Secure payment (HTTP Post)
 * 
 * 3D 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 (support@adyen.com).
 * 2. Your integration should support redirecting the shopper to the card issuer and submitting
 *    a second API call to complete the payment.
 *
 * This example demonstrates the second API call to complete the payment using HTTP Post.
 * See the API Manual for a full explanation of the steps required to process 3D Secure payments.
 * 
 * Please note: using our API requires a web service user. Set up your WebService user:
 * Adyen CA >> Settings >> Users >> ws@Company. >> Generate Password >> Submit
 * 
 * @link /2.API/HttpPost/Authorise3dSecurePayment
 * @author Created by Adyen - Payments Made Easy
 */

@WebServlet(urlPatterns = { "/2.API/HttpPost/Authorise3dSecurePayment" })
public class Authorise3dSecurePaymentHttpPost extends HttpServlet {

    protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

        /**
         * HTTP Post settings
         * - apiUrl: URL of the Adyen API you are using (Test/Live)
         * - wsUser: your web service user
         * - wsPassword: your web service user's password
         */
        String apiUrl = "https://pal-test.adyen.com/pal/adapter/httppost";
        String wsUser = "YourWSUser";
        String wsPassword = "YourWSUserPassword";

        /**
         * Create HTTP Client (using Apache HttpComponents library) and set up Basic Authentication
         */
        CredentialsProvider provider = new BasicCredentialsProvider();
        UsernamePasswordCredentials credentials = new UsernamePasswordCredentials(wsUser, wsPassword);
        provider.setCredentials(AuthScope.ANY, credentials);

        HttpClient client = HttpClientBuilder.create().setDefaultCredentialsProvider(provider).build();

        /**
         * 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 and a new
         * parameter called PaRes (see API manual). These will be needed to complete the payment.
         *
         * To complete the payment, a PaymentRequest3d should be submitted to the authorise3d action
         * of the web service. The request should contain the following variables:
         * 
         * <pre>
         * - merchantAccount: This should be the same as the Merchant Account used in the original authorise request.
         * - browserInfo:     It is safe to use the values from the original authorise request, as they
                              are unlikely to change during the course of a payment.
         * - md:              The value of the MD parameter received from the issuer.
         * - paReponse:       The value of the PaRes parameter received from the issuer.
         * - shopperIP:       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.
        * </pre>
        */
        List<NameValuePair> postParameters = new ArrayList<NameValuePair>();
        Collections.addAll(postParameters,
            new BasicNameValuePair("action", "Payment.authorise3d"),

            new BasicNameValuePair("paymentRequest3d.merchantAccount", "YourMerchantAccount"),
            new BasicNameValuePair("paymentRequest3d.browserInfo.userAgent", request.getHeader("User-Agent")),
            new BasicNameValuePair("paymentRequest3d.browserInfo.acceptHeader", request.getHeader("Accept")),
            new BasicNameValuePair("paymentRequest3d.md", request.getParameter("MD")),
            new BasicNameValuePair("paymentRequest3d.paResponse", request.getParameter("PaRes")),
            new BasicNameValuePair("paymentRequest3d.shopperIP", "123.123.123.123")
            );

        /**
         * Send the HTTP Post request with the specified variables.
         */
        HttpPost httpPost = new HttpPost(apiUrl);
        httpPost.setEntity(new UrlEncodedFormEntity(postParameters));

        HttpResponse httpResponse = client.execute(httpPost);
        String paymentResponse = EntityUtils.toString(httpResponse.getEntity(), "UTF-8");

        /**
         * Keep in mind that you should handle errors correctly.
         * If the Adyen platform does not accept or store a submitted request, you will receive a HTTP response with
         * status code 500 Internal Server Error. The fault string can be found in the paymentResponse.
         */
        if (httpResponse.getStatusLine().getStatusCode() == 500) {
            throw new ServletException(paymentResponse);
        }
        else if (httpResponse.getStatusLine().getStatusCode() != 200) {
            throw new ServletException(httpResponse.getStatusLine().toString());
        }

        /**
         * If the payment passes validation a risk analysis will be done and, depending on the outcome, an authorisation
         * will be attempted. You receive a payment response with the following fields:
         * 
         * <pre>
         * - pspReference    : Adyen's unique reference that is associated with the payment.
         * - resultCode      : The result of the payment. Possible values: Authorised, Refused, Error or Received.
         * - authCode        : The authorisation code if the payment was successful. Blank otherwise.
         * - refusalReason   : Adyen's mapped refusal reason, populated if the payment was refused.
         * </pre>
         */
        Map<String, String> paymentResult = parseQueryString(paymentResponse);
        PrintWriter out = response.getWriter();

        out.println("Payment Result:");
        out.println("- pspReference: " + paymentResult.get("paymentResult.pspReference"));
        out.println("- resultCode: " + paymentResult.get("paymentResult.resultCode"));
        out.println("- authCode: " + paymentResult.get("paymentResult.authCode"));
        out.println("- refusalReason: " + paymentResult.get("paymentResult.refusalReason"));

    }

    /**
     * Parse the result of the HTTP Post request (will be returned in the form of a query string)
     */
    private Map<String, String> parseQueryString(String queryString) throws UnsupportedEncodingException {
        Map<String, String> parameters = new HashMap<String, String>();
        String[] pairs = queryString.split("&");

        for (String pair : pairs) {
            String[] keyval = pair.split("=");
            parameters.put(URLDecoder.decode(keyval[0], "UTF-8"), URLDecoder.decode(keyval[1], "UTF-8"));
        }

        return parameters;
    }

}

(source: Authorise3dSecurePaymentHttpPost.java)

AVS

Address Verification System (AVS) is a security feature that verifies the billing address of the card holder.

How does it work?

AVS compares the billing address the shopper enters with the one on file at the payment card company.

AVS is only supported on a limited set of acquiring connections, card types, and only for a limited set of countries (United States, Canada, and UK).

Enable AVS check

To use AVS you must supply the full address of the shopper using the billingAddress child element of the payment authorisation request, as shown below:

"billingAddress" : {
  "city" : "Burbank",
  "street" : "Test AVS result",
  "houseNumberOrName" : "4 AVS not supported for this card type",
  "stateOrProvince" : "California",
  "country" : "US",
  "postalCode" : "91521"
}

<billingAddress xmlns="http://payment.services.adyen.com">
	<city xmlns="http://common.services.adyen.com">Burbank</city>
	<street xmlns="http://common.services.adyen.com">Test AVS result</street>
	<houseNumberOrName xmlns="http://common.services.adyen.com">4 AVS not supported for this card type</houseNumberOrName>
	<stateOrProvince xmlns="http://common.services.adyen.com">California</stateOrProvince>
	<country xmlns="http://common.services.adyen.com">US</country>
	<postalCode xmlns="http://common.services.adyen.com">91521</postalCode>
</billingAddress>

card.billingAddress.city=Burbank&card.billingAddress.street=Test+AVS+result&card.billingAddress.houseNumberOrName=4+AVS+not+supported+for+this+card+type&card.billingAddress.postalCode=91521&card.billingAddress.stateOrProvince=CA&card.billingAddress.country=US
 

When you submit the billingAddress object, consider providing the following child elements:

  • city – always required
  • street – always required
  • houseNumberOrName – required in Canada and UK
  • stateOrProvince – required in United States and Canada
  • country – always required
  • postalCode – optional

The country value format needs to adhere to the ISO 3166-1 alpha-2 standard. An invalid country code results in a transaction/request rejection. You can look up country codes on the ISO web site.

Different card brands and networks have specific AVS response codes. They are mapped to Adyen's generic response codes, which are the ones you receive by default. If you prefer to receive the actual response code from the card or network, contact the Adyen Support Team to request enabling the raw AVS reason for you. Once enabled, this information is included in your notifications.

AVS result testing

You can test AVS result values. Assign the appropriate values to the child elements of the billingAddress element, as described below:

Parent Child Value to test AVS
billingAddress    
  street Test AVS result
  houseNumberOrName <specify_here_the_avsResult_value_to_test>

You still need to include and define all the other billingAddress child elements, but their values do not impact the avsResult return value you want to test.

You can use a test card number from this list to test AVS results.

AVS result values

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

CVC-CVV result testing

You can test CCV/CVV result codes. Assign the appropriate values to the child elements of the card element, as described below:

Parent Child Value to test CVC/CVV
card    
  number <specify_here_a_test_card_number>
  cvc <specify_here_the_CVC/CVV_code_to_test>

You still need to include and define all the other card child elements, but their values do not impact the cvc return value you want to test.

You can use a test card number with a CVC from this list to test CVC/CVV results.

Card examples

The following partial examples show how use the card element to test specific CVC/CVV result codes:

"card" : {
    "number" : "4111111111111111", // Use a test card number that has a CVC number
    "cvc" : "004", // Use padding zeroes as necessary before the 1- or 2-digit CVC-CVV code you want to test
    "expiryMonth" : "06",
    "expiryYear" : "2018",
    "holderName" : "Adyen Test"
}

Response:

{
   "additionalData":{
      "cvcResult":"4 No CVC/CVV provided, but was required",
      "cvcResultRaw":"4",
      "refusalReasonRaw":"DECLINED CVC Incorrect",
   },
   "pspReference":"9914613171800003",
   "refusalReason":"Refused",
   "resultCode":"Refused"
}

&card.cvc=737&card.expiryMonth=08&card.expiryYear=2018&card.holderName=Adyen+Tester&card.number=4111111111111111

<!-- cvc: use padding zeroes as necessary before the 1- or 2-digit CVC-CVV code you want to test
     paymentRequest.card.number: use a test card number that has a CVC number -->

<card xmlns="http://payment.services.adyen.com">
    <cvc>004</cvc> // Use padding zeroes as necessary before the 1- or 2-digit CVC-CVV code you want to test
    <expiryMonth>06</expiryMonth>
    <expiryYear>2018</expiryYear>
    <holderName>Adyen Test</holderName>
    <number>4111111111111111</number> // Use a test card number that has a CVC number
</card>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://payment.services.adyen.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Body>
      <ns1:authoriseResponse>
         <ns1:paymentResult>
            <ns1:additionalData>
               <ns1:entry>
                  <ns1:key xsi:type="xsd:string">cvcResult</ns1:key>
                  <ns1:value xsi:type="xsd:string">4 No CVC/CVV provided, but was required</ns1:value>
               </ns1:entry>
               <ns1:entry>
                  <ns1:key xsi:type="xsd:string">cvcResultRaw</ns1:key>
                  <ns1:value xsi:type="xsd:string">4</ns1:value>
               </ns1:entry>
               <ns1:entry>
                  <ns1:key xsi:type="xsd:string">refusalReasonRaw</ns1:key>
                  <ns1:value xsi:type="xsd:string">DECLINED CVC Incorrect</ns1:value>
               </ns1:entry>
            </ns1:additionalData>
            <ns1:pspReference>9914613174950342</ns1:pspReference>
            <ns1:refusalReason>Refused</ns1:refusalReason>
            <ns1:resultCode>Refused</ns1:resultCode>
         </ns1:paymentResult>
      </ns1:authoriseResponse>
   </soap:Body>
</soap:Envelope>

CVC-CVV result codes

0 Unknown
1 Matches
2 Doesn't match
3 Not checked
4 No CVC/CVV provided, but was required
5 Issuer not certifed for CVC/CVV
6 No CVC/CVV provided

Error code testing

You can test refused transactions and the specific refusal reason that are returned when a transaction fails. Assign the appropriate values to the  holderName child element of the  card element, as described below:
Parent Child Value to test refusal reason
card    
  holderName <specify_here_[refusal_code]+[:]+[raw string refusal reason to test]>

This is the format of the refusal reason code you want to test, and whose value you need to assign to the holderName element:

[Response code] : [Refusal reason raw string to test]
DECLINED : 05 : ISSUER_UNAVAILABLE

You can use a test card number with a CVC from this list to test CVC/CVV results.You still need to include and define all the other card child elements, but their values do not impact the refusal reason return value you want to test.

  • The holderName field value cannot be longer than 80 characters max.
  • You may need to lower the risk score value to take into account non-alphabetic characters in the card holder name like a colon  (":"). This and other non-alphabetical characters trigger the risk check, which may cause the payment to be declined with a FRAUD reason code.

  • If you specify an incorrect CVC or an invalid expiry date, the payment fails and the operation returns a generic DECLINED refusal reason.

These are the available response codes for testing:

  • REFERRAL

  • ERROR

  • BLOCK_CARD

  • CARD_EXPIRED

  • DECLINED

  • INVALID_AMOUNT

  • INVALID_CARD

  • NOT_SUPPORTED

  • NOT_3D_AUTHENTICATED

  • NOT_ENOUGH_BALANCE

  • APPROVED

Testing chargebacks

To test a chargeback, create a payment and enter Chargeback in the Cardholder name field.

This simulates a flow for a chargeback, the payment goes through the normal process for authorisation and settlement.

After settlement, the chargeback is initiated.

Payment requests

Go to API playground

To submit API payment request you make a call with the  authorise  action.

The fields described below are the generic payment fields you specify when making an authorise call to the Adyen payment API. 

The Adyen API supports a range of different payment method, the following sections describe the specific field elements you need to include in your payment requests for every payment method.

Check card payment fields for making payment request using a card.

Name Type Required Description
merchantAccount String (tick)
The merchant account identifier you want to process the (transaction) request with.
amount String (tick)
A container object for the payable amount information for the transaction.

It contains the following elements:

  • currency
  • value
currency String (tick)
The three-character ISO currency code.
value int (tick)

The payable amount that can be charged for the transaction, in minor units.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

reference String (tick)
A reference to uniquely identify the payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement.

If you need to provide multiple references for a transaction, you can enter them in this field. Separate each reference value with a hyphen character ("-").

This field has a length restriction: you can enter max. 80 characters.

shopperIP String (error)

The shopper's IP address.

We recommend you provide this data, as it is used in a number of risk checks. For example: number of payment attempts, location based checks.

shopperEmail String (error)

The shopper's email address.

We recommend you provide this data, as it is used in velocity fraud checks.

shopperReference String (error)

The shopper's reference for the payment transaction.

We recommend you provide this data.

This field is required for recurring payments.

fraudOffset Int (error)

An integer value that is added to the normal fraud score. The value can be either positive or negative.

selectedBrand String (error)

Some payment methods require defining a value for this field to specify how to process the transaction.

For the MisterCash payment method, it can be set to:

  • maestro (default), to be processed like a Maestro card, or
  • bcmc, to be processed like a MisterCash card.
deliveryDate Date (error) This specifies the date and time the goods of the order would be delivered, in ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
merchantOrderReference String (error)

This reference allows to link multiple transactions to each other.

shopperInteraction

  (error)

Specifies the following information:

  • The sales channel the shopper gives their card details through;
  • Wheter the shopper is a returning customer.

By default, for the web service API Adyen assumes Ecommerce shopper interaction.

This field has the following possible values:

  • Ecommerce - Online transactions where the card holder is present (online). For better authorisation rates, we recommend sending the card security code (CSC) along with the request.
  • ContAuth - Card on file and/or subscription transactions, where the card holder is known to the merchant (returning customer). If the shopper is present (online), you can supply also the CSC to improve authorisation (one-click payment).
  • POS - Point-of-sale transactions where the shopper is physically present to make a payment using a secure payment terminal.
  • Moto - Mail-order and telephone-order transactions where the shopper is in contact with the merchant via email or telephone.

Additional fields for card payments

Name Type Required Description
card Class (tick)

A container for credit card data.

This field takes the following children:

  • expiryMonth

  • expiryYear

  • holderName

  • number

  • cvc

  • issueNumber

  • startMonth

  • startYear

expiryMonth String (tick)

The card expiry month.

Format: 2 digits, zero-padded for single digits. For example:

  • 03 = March
  • 11 = November
expiryYear String (tick)

The card expiry year.

Format: 4 digits. For example:2018.

holderName String (tick) The name of the card holder, as printed on the card.
number String (tick)

The card number. Do not use any separators.

  • Min. length: 4 characters
  • Max. length: 19 characters
cvc String (tick)

The card verification code. Depending on the card brand, it is known also as:

  • CVV2/CVC2 – length: 3 digits
  • CID – length: 4 digits
  • Min. length: 1 character
  • Max. length: 20 characters
metadata class (error)

Metadata consists of entries, each of which include of key and value.

This field takes the following children:

  • key
  • value

Limitations:

  • Error "177", "Metadata size exceeds limit"
key String (error)

Key for the information to be provided. Example: key = 'storeCountry'

Limitations:

Error "178", "Metadata key size exceeds limit"

value String (error)

Information value. Example: value = 'US'

Limitations:

Maximum length: 80 characters, value is truncated to 80 characters with '...' appended to it.

additionalData fields

Name Type Required Description
riskdata.deliveryMethod String (error) This specifies the method of delivery for the goods.
retry.chainAttemptNumber Integer (error)

The number of times the transaction (not order) has been retried. For instance, the chainAttemptNumber set to 2 means that this transaction has been already retried on another provider before being sent to Adyen.

Make sure that you also provide the merchantOrderReference field value when specifying the chainAttemptNumber.

retry.orderAttemptNumber Integer (error)

The index of the attempt to bill a particular order, which is identified by the merchantOrderReference field.

Make sure that you also provide the merchantOrderReference field value when specifying the orderAttemptNumber.

retry.skipRetry Boolean (error)

The Boolean value indicating whether Adyen should skip or retry this transaction, if possible.

Make sure that you also provide the merchantOrderReference field value when specifying the skipRetry.

BIN data and card verification

You may want to verify card validity and BIN data, for example prior to a sale to apply credit/debit surcharges or promotional offers based on BIN codes.

Submit a BIN or card verification request

Submit an authorisation request with a currency value amounting to 0 (zero value auth). The currency should match 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 AuthorisedRefused or Error.

Not all acquirers and issuers support card verification through zero value auth. When your transactions are routed to an acquirer or issuer that does not support this feature, the Adyen system automatically submits a EUR 1 authorisation, which is immediately followed by an automatic authorisation cancellation. 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 need to include the additionalAmount field to specify the amount to use. The standard amount field value still needs to be 0 (zero) 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, following 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.

Name Type Required Description
amount String (tick)

A container for the data concerning the amount to be authorised.

amount contains the following children:

  • currency
  • value

Its value needs to be 0 (zero) if you want to submit a zero value auth BIN or card verification request.
additionalAmount String (tick)

A container for the data concerning the additional amount to be authorised. It corresponds to the additional/surcharged part of the amount, and it needs to be in the same currency as amount.

additionalAmount contains the following children:

  • currency
  • value

additionalAmount is required only if you want to submit a non-zero value auth BIN or card verification request.

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.

currency String (tick)

The three-character ISO currency code.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

value int (tick) The payment amount of the transaction.

Receive a BIN or card verification response

A zero value auth response includes, among others, the following details:

  • The authorisation request outcome (successful/failed).
  • If the authorisation request failed, an error message is included in the response.
  • An additionalData container object with a cardBin field holding BIN information.

The additionalData object needs to be configured to include this data in the response.

This functionality is not enabled by default, as it requires additional configuration on Adyen's end. Contact the  Adyen Support Team to request enabling it for you.

After enabling it, the cardBin field becomes available as a child element of the additionalData container object, along with the following fields:

Name Type Returned by default Description
cardPaymentMethod String (tick)

The card payment method used for the transaction.

For example: amex

cardIssuingBank String (tick)

The 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 String (tick)

The country where the card was issued.

For example: US

cardIssuingCurrency String (tick)

The currency used in the transaction.

For example: USD

cardBin String (tick)

The Bank Identification Number is a six-digit numeric code that links the buyer and their payment card.

For example: 373731

fundingSource String (tick)
The possible return values are:
  • CHARGE
  • CREDIT
  • DEBIT
  • PREPAID
  • DEFFERED_DEBIT

This functionality is not enabled by default, as it requires additional configuration on Adyen's end. Contact the  Adyen Support Team to request enabling it for you.

For receiving this field in the notification enable Include Funding Source in Notifications -> Additional settings.

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

Code examples: Request

Example of a JSON BIN data/card verification request (zero value authorisation):

{
    "card" : {
        "number" : "4111111111111111",
        "expiryMonth" : "8",
        "expiryYear" : "2018",
        "cvc" : "737",
        "holderName" : "Adyen Test"
    },
    
    "amount" : {
        "value" : 0,
        "currency" : "EUR"
    },
    
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "s.hopper@test.com",
    "shopperIP" : "61.294.12.12",
    "shopperReference" : "Simon Hopper"
}

Example of a SOAP BIN data/card verification request (zero value authorisation):

<?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>08</expiryMonth>
          <expiryYear>2018</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">s.hopper@test.com</shopperEmail>
        <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference>
      </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>

Example of a FORM BIN data/card verification request (zero value authorisation):

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

Code examples: Request with additional amount

Example of a JSON BIN data/card verification request (non-zero value authorisation) with additionalAmount:

{
    "card" : {
        "number" : "4111111111111111",
        "expiryMonth" : "8",
        "expiryYear" : "2018",
        "cvc" : "737",
        "holderName" : "Adyen Test"
    },
    
    "amount" : {
        "value" : 0,
        "currency" : "EUR"
    },

    "additionalAmount" : {
        "value" : 100,
        "currency" : "EUR"
    },
    
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "s.hopper@test.com",
    "shopperIP" : "61.294.12.12",
    "shopperReference" : "Simon Hopper"
}

Example of a SOAP BIN data/card verification request (non-zero value authorisation) 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>08</expiryMonth>
          <expiryYear>2018</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">s.hopper@test.com</shopperEmail>
        <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference>
      </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>
Example of a FORM BIN data/card verification request (non-zero value authorisation) with  additionalAmount :
merchantAccount=TestMerchant&amount.value=0&amount.currency=EUR&additionalAmount.value=100&additionalAmount.currency=EUR&card.expiryYear=2018&card.cvc=737&card.number=4111111111111111&card.holderName=Adyen+Test&card.expiryMonth=08&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com

Code examples: Response

Example of a JSON BIN data/card verification response (non-zero value authorisation) with additionalAmount:

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

Example of a SOAP BIN data/card verification response (non-zero value authorisation) 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: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>
		  <entry>
            <key xsi:type="xsd:string">fundingSource</key>
            <value xsi:type="xsd:string">CREDIT</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>
Example of a FORM BIN data/card verification response (non-zero value authorisation) with  additionalAmount :
additionalData.cardPaymentMethod=amex&additionalData.cardIssuingBank=American+Express+US+Consumer&additionalData.cardIssuingCountry=US&additionalData.cardIssuingCurrency=USD&additionalData.cardBin=373731.fundingSource=CREDIT&pspReference=9914229541655140&refusalReason=Acquirer+Error&resultCode=Error

Mastercard authorization types

Mastercard offers two authorization types:

  • Pre-authorization (PreAuth)
  • Final authorization (FinalAuth)

By default, Adyen handles all Mastercard payment requests as final authorizations.

You can flag each Mastercard payment request to be handled as either a pre- or a final authorization. To do so, add a new entry to the additionalData field of your payment request. The key name of the new entry is mcAuthorisationType. You can then flag a Mastercard payment request by assigning it the appropriate value.

Alternatively, you can define a default authorization flow at merchant level for all Mastercard transactions. 

This functionality is not enabled by default, as it requires additional configuration on Adyen's end. Contact the  Adyen Support Team to request enabling it for you.

Name Type Required Description
mcAuthorisationType String (error)

Flags a Mastercard payment request for either pre-authorization or final authorization.

Allowed values:

  • PreAuth: flags the payment request to be handled as a pre-authorization.
  • FinalAuth: flags the payment request to be handled as a final authorization.

{
    "additionalData" : {
        "mcAuthorisationType" : "PreAuth"
    },
    
    "card" : {
        "number" : "4111111111111111",
        "expiryMonth" : "8",
        "expiryYear" : "2018",
        "cvc" : "737",
        "holderName" : "Adyen Test"
    },
    
    "amount" : {
        "value" : 10000,
        "currency" : "EUR"
    },
    
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "s.hopper@test.com",
    "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>08</expiryMonth>
          <expiryYear>2018</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">s.hopper@test.com</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>

additionalData.mcAuthorisationType=PreAuth&card.number=4111111111111111&card.expiryMonth=8&card.expiryYear=2018&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

Card deposit - Card fund transfer (CFT)

Card deposit or Card Funds Transfer (CFT) allows you to transfer funds directly onto a credit card.

There are two methods to carry out a card deposit:

  • Refund an existing transaction with an amount exceeding the original transaction amount. The difference between the refunded amount and the original amount is deposited onto the card.
    You do not need to know the card details to do this. All you need is a valid reference to the existing transaction.

  • Direct deposit onto a card without using an existing transaction.
    In this case, you need to submit the card details. This process is very similar to submitting a direct payment.

This functionality is not enabled by default, as it requires additional configuration on Adyen's end. Contact the  Adyen Support Team to request enabling it for you.

Card deposit through an existing transaction

To deposit an amount using an existing transaction, use the fundTransfer action to send a FundTransferRequest object.

Fund transfer request

To make a fund transfer request through an existing transaction with the fundTransfer call, include in the FundTransferRequest object the following fields.

Name Type Required Description
merchantAccount String (tick) The merchant account identifier you want to process the (transaction) request with.
modificationAmount String (tick)

A container for the amount data you want to deposit onto the card.
It contains the following elements:

  • currency
  • value

The  currency value must match the corresponding  currency value used in the original payment request.

currency String (tick)

The three-character ISO currency code.

The  currency value must match the corresponding  currency value used in the original payment request.

value int (tick)

The payable amount that can be charged for the transaction, in minor units.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

originalReference String (tick)
The  originalReference value corresponds to the  pspReference value assigned to the original payment.

You receive the pspReference with:

  • The payment status, or
  • The authorisation notification.
reference String (tick)

A reference to uniquely identify the payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement.

If you need to provide multiple references for a transaction, you can enter them in this field. Separate each reference value with a hyphen character ("-").

This field has a length restriction: you can enter max. 80 characters.

A reference to uniquely identify the payment.
This reference is used in all communication with you about the payment status.
We recommend using a unique value per payment; however, it is not a requirement.

If you need to provide multiple references for a transaction, you can enter them in this field.
Separate each reference value with a hyphen character ("-").

This field has a length restriction: you can enter max. 80 characters.

shopperEmail String (error) The shopper's email address.

Fund transfer response

If the message you send with the call, is valid and if the specified merchantAccount is correct, you receive a response with the following fields.

Name Type Returned by defauilt Description
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

response String (tick)
  • If the request is successful, the returned value is [fundtransfer-received].
  • If it fails, an error message is returned.

When you receive a [fundtransfer-received] response, it does not mean that the actual card deposit was successfully performed.
It means that Adyen successfully received your request.

The actual transfer occurs offline, and the final result is communicated with a notification.

Direct deposit onto a card

A direct deposit transfers funds onto a card without referencing an existing transaction. This process is very similar to submitting a direct payment, the only difference being the method name you use to submit a direct deposit request:

  • You send a standard payment request with the authorise method.
  • You send a direct deposit request with the refundWithData method.

Apart from the name, both methods have the same arguments, and they behave in the same way.

Card deposit notifications

Notifications for card deposits requests are the same as payment notifications, except for the eventCode value: the eventCode value of card deposit notifications is REFUND_WITH_DATA.

As with regular payment notifications, always check the success parameter to determine if the deposit was performed succesfully.


SEPA Direct Debit

The Single Euro Payments Area (SEPA) is a EU payment integration initiative to simplify EUR-based bank transfers.

As of February 1, 2014, the European Payments Council (EPC) mandates that merchants who process, or plan to process, ELV or Incasso payments, must implement SEPA Direct Debit (DD).

For further details, refer to the following sources:

SDD one-off payment requests

A one-off payment request using the SEPA Direct Debit option is similar to a standard authorise payment request, except for the following differences:

  • An SDD payment request holds a bankAccount container.
  • An SDD payment request requires a selectedBrand field whose value needs to be sepadirectdebit.

See also the SEPA Direct Debit request and response code examples.

Name Type Required Description
bankAccount class (tick)

A container for bank account data.

It takes the following children:

  • iban
  • ownerName
  • countryCode
iban String (tick) The bank account IBAN code.
ownerName String (tick) The name of the bank account holder.
countryCode String (error)
The country value format needs to adhere to the ISO 3166-1 alpha-2 standard. An invalid country code results in a transaction/request rejection. You can look up country codes on the ISO web site.
selectedBrand String (tick) For SDD payment requests, set the corresponding value to sepadirectdebit.

SDD one-off code examples

Request:

{
    "bankAccount" : {
        "iban" : "NL48RABO0132394782",
        "ownerName" : "Klaas T. Jansen",
        "countryCode" : "NL"
    },
    
    "amount" : {
        "value" : 1500,
        "currency" : "EUR"
    },
    
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "email@shopper.com",
    "shopperIP" : "61.294.12.12",
    "shopperStatement" : "YOUR ORDER 122345677889",
    "selectedBrand" : "sepadirectdebit"
}

Response:

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

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@shopper.com</ns1:shopperEmail>
        <ns1:shopperReference>TheShopperReference</ns1:shopperReference>
        <ns1:shopperIP>10.10.100.200</ns1:shopperIP>
        <ns1:shopperStatement>YOUR ORDER 122345677889</ns1:shopperStatement>
        <ns1:selectedBrand>sepadirectdebit</ns1:selectedBrand>
      </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>

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>

SDD recurring payment requests

A recurring payment request using the SEPA Direct Debit option is similar to a standard authorise payment request, except for the following differences:

  • A recurring SDD payment request holds a selectedRecurringDetailReference field.
  • A recurring SDD payment request requires a selectedBrand field whose value needs to be sepadirectdebit.
Name Type Required Description
selectedRecurringDetailReference String (tick)

This is the recurringDetailReference information you want to use when submitting recurring SDD payment requests.

You can set this field value to LATEST.

selectedBrand String (tick) For SDD payment requests, set the corresponding value to sepadirectdebit.

SDD responses

SEPA Direct Debit responses are similar to payment responses. The SEPA Direct Debit-specific information is included as child elements of the additionalData field.

After a payment is authorised, it is possible to capture it.
SEPA Direct Debit allows capturing payments in one of the following ways:
  • (SALE) The payment is authorised and captured immediately – i.e. the shopper's funds to cover the payment are retrieved during the same transaction session.
  • (AUTH) The payment is first authorized; capture can occur immediately or separately, at a later time.

See also the SEPA Direct Debit request and response code examples.

Name Type Returned by default Description
additionalData class (tick)
The additionalData object is a generic container that can hold extra fields.
sepadirectdebit.dateOfSignature String (tick) Transaction signature date.
Format: yyyy-MM-dd
sepadirectdebit.sequenceType String (tick)
sepadirectdebit.sequenceType can take one of the following values:
  • OneOff: (OOFF) Direct debit instruction to initiate exactly one direct debit transaction.
  • First(FRST) Initial/first collection in a series of direct debit instructions.
  • Recurring: (RCUR) Direct debit instruction to carry out regular direct debit transactions initiated by the creditor.
  • Final: (FNAL) Last/final collection in a series of direct debit instructions.
sepadirectdebit.mandateId String (tick) Its value corresponds to the pspReference value for the transaction.
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

resultCode String (tick)

The outcome of the payment. The possible values are:

  • Authorised
  • Refused
  • Received 
authCode String (tick)

Authorisation code: 

  • When the payment is authorised successfully, this field holds the authorisation code for the payment. 
  • When the payment is not authorised, this field is empty.

For SEPA Direct Debit, the  authCode field value is always nil.
refusalReason String (error) When the payment is not authorised and it is refused, this field holds Adyen's mapped reason for the refusal.

SDD notifications

Pending notifications

By default, pending notifications are disabled. After enabling them, they are sent out at the payment creation moment.

This functionality is not enabled by default, as it requires additional configuration on Adyen's end. Contact the  Adyen Support Team to request enabling it for you.

{
    "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"
        }
    }
}
<com.adyen.services.notification.NotificationRequestItem>
  <amount>
    <value>1500</value>
    <currency>EUR</currency>
  </amount>
  <pspReference>9313547924770610</pspReference>
  <eventCode>PENDING</eventCode>
  <eventDate>2013-11-28 11:55:05.934 CET</eventDate> 
  <merchantAccountCode>TestMerchant</merchantAccountCode>
  <merchantReference>YourMerchantReference1</merchantReference> 
  <paymentMethod>sepadirectdebit</paymentMethod>
  <additionalData>
    <entry>
      <string>sepadirectdebit.dateOfSignature</string>      
      <string>2013-11-28</string>
    </entry>
    <entry>
      <string>sepadirectdebit.sequenceType</string>
      <string>First</string>
    </entry>
    <entry>
      <string>sepadirectdebit.mandateID</string>    
      <string>9913856361050084</string>
    </entry>
  </additionalData>
  <success>true</success>
<com.adyen.services.notification.NotificationRequestItem>

Authorisation notifications

{
    "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"
        }
    }
}
<com.adyen.services.notification.NotificationRequestItem>
  <amount>
    <value>1500</value>
    <currency>EUR</currency>
  </amount>
  <pspReference>9313547924770610</pspReference>
  <eventCode>AUTHORISATION</eventCode>
  <eventDate>2013-11-28 11:55:05.934 CET</eventDate> 
  <merchantAccountCode>TestMerchant</merchantAccountCode>
  <merchantReference>YourMerchantReference1</merchantReference> 
  <paymentMethod>sepadirectdebit</paymentMethod>
  <success>true</success>
  <additionalData>
    <entry>
      <string>sepadirectdebit.dateOfSignature</string>      
      <string>2013-11-28</string>
    </entry>
    <entry>
      <string>sepadirectdebit.sequenceType</string>
      <string>First</string>
    </entry>
    <entry>
      <string>sepadirectdebit.mandateID</string>    
      <string>9913856361050084</string>
    </entry>
  </additionalData>
<com.adyen.services.notification.NotificationRequestItem>

 

SDD settlement timeline

Before initiating DD, you need to inform the customer that a payment is due.

Event

SDD

SDD Recurring

Pre-notification

(T-14) T-1

(T-14) T-2

Submit SDD instructions (payment request moment)

T-1

T-2

Latest moment to revoke (cancel) SDD

N/A

T-1

SDD instruction processed by the bank

T

T

Reconciliation by Adyen PSP

T+1

T+1

SDD chargebacks

The chargeback process is standardised for all SEPA Direct Debit variants. The SEPA Direct Debit schemes ensure more protection and refund rights for consumers:

  • Shoppers have 8 weeks to claim for an authorised SEPA Direct Debit payment to be refunded.
  • Shopper have 13 months to report to their bank an incorrect and/or unauthorised SEPA Direct Debit transaction. Since they did not authorise the debit or since the Direct Debit instruction/Direct Debit mandate has expired or it was cancelled, they can request a full refund.  

The process is very similar to a credit card chargeback; however, in case of a SEPA Direct Debit chargeback it is not possible to defend against a dispute.

ACH Direct Debit

ACH (Automated Clearing House)  direct debit is an increasingly popular form of payment and a cost-effective alternative to credit and debit cards in the United States.

Currency: USD.

Settlement time: Depending on a shopper's bank account, settlement time varies between 2-3 days.

ACH payments over Adyen HPP follows the payment flow outlined in this document. You can customize appearance of these pages and specify available payment methods using skins.

  1. On the payment selection page, a shopper should choose the ACH Direct Debit method.

  2. A shopper enters payment details, such as bank account information and the billing address.

  3. Clicks pay.

After the payment is successfully completed, a shopper is redirected to the result page.

Custom payment flow

If you have a shopper's billing information, you may skip initial payment pages and redirect a shopper directly to the confirmation page.  If you already have a shopper's bank account and billing address information, we recommend that you skip the payment details page and immediately proceed to Step 3 (ACH default payment flow). In this case a shopper will only need to review the payment details and click Pay, which provides better user experience and reduces the number of incomplete payment transactions.

To implement this custom payment flow:

Post a payment request directly to the  https://test.adyen.com/hpp/skipDetails.shtml endpoint with the following parameters.

http://test.adyen.com/hpp/skipDetails.shtml?ach.ownerName=Andrews&ach.bankCountryCode=US&ach.bankAccountNumber=4640348490&ach.bankLocationId=011000138&ach.billingAddress.street=Bakkerstraat&ach.billingAddress.houseNumberOrName=137&ach.billingAddress.postalCode=12010&ach.billingAddress.city=Amsterdam&ach.billingAddress.stateOrProvince=NY&ach.billingAddress.country=US&ach.acceptDirectDebit=true&sig={YOUR SIGNATURE}&merchantReference=TMRef1234&brandCode=ach&paymentAmount=8650&currencyCode=USD&shipBeforeDate=2016-08-30&skinCode=aF563qQs&merchantAccount=TestMerchant&sessionValidity=2016-08-24T14%3A22%3A22Z

For the complete list of parameters required for this call, refer to the API manual.

ACH payments API

To make an ACH payment, post an API payment request with data similar to card payment requests, but with a bankAccount object instead of card.

The table below lists parameters passed in a payment request.

Name Type Required Description
bankAccount Object (tick)

A container for bank account data.

It contains the following elements:

  • countryCode
  • ownerName
  • bankLocationId
  • bankAccountNumber
  • bankName
  • bic
  countryCode String (tick)

The country code for the transaction.

For ACH transactions, set its value to "US ".

  ownerName String (tick) The bank account holder name.
  bankLocationId String (tick)

The ABA routing transit number for ACH payments from the bank account.

Format: 9-digit number.

Do not remove any leading zeroes in it.

  bankAccountNumber String (tick)

The US bank account number from which the payment will be debited.

Format: numeric.

For ACH transactions, the bank account number needs to comply with length restrictions: min. 4, max. 17 digits.

  bankName String (error)

The name of the bank where the account is held.

  bic String (error)

The business identifier code (BIC) is the SWIFT address assigned to a bank.

billingAddress Object (tick)

A container for the billing address information.

It contains the following elements:

  • country
  • street
  • houseNumberOrName
  • city
  • postalCode
  • stateOrProvince
  country String (tick)

The country identifier.

For ACH payments, set its value to " US".

  street String (tick)

Name of the street.

You can append a house number to the street parameter. In this case, houseNumberOrName should be set to an empty string.

  houseNumberOrName String (tick)

House number, or house name, or another house identifier.

  city String (tick)

Name of the city.

  postalCode String (tick)

Zip/Post code.

  stateOrProvince String (tick)

Name of the state, region or province, where applicable.

An ACH payment response is similar to card payment responses, the only difference being that an ACH response does not include an authorisation code (authCode), because it is not generated in this case.

The table below lists parameters returned in a ACH payment response.

Name Type Returned by default Description
additionalData Object (tick)
The additionalData object is a generic container that can hold extra fields.
  achdirectdebit.dateOfSignature String (tick) Transaction signature date.
Format: yyyy-MM-dd
  achdirectdebit.mandateId String (tick) Its value corresponds to the pspReference value for the transaction.
  achdirectdebit.sequenceType String (tick)
achdirectdebit.sequenceType can take one of the following values:
  • OneOff: (OOFF) Direct debit instruction to initiate exactly one direct debit transaction.
  • First(FRST) Initial/first collection in a series of direct debit instructions.
  • Recurring: (RCUR) Direct debit instruction to carry out regular direct debit transactions initiated by the creditor.
  • Final: (FNAL) Last/final collection in a series of direct debit instructions.
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

resultCode String (tick)

The outcome of the payment. The possible values are:

  • Authorised
  • Refused
  • Received 
refusalReason String (error) When the payment is not authorised and it is refused, this field holds Adyen's mapped reason for the refusal.

ACH payments code example

Use one of the following formats to make an authorisation request for a one-off ACH payment. 

You must post payment requests either to a Test or a Live endpoint, depending on your current integration status. For more information, refer to API endpoints.

For JSON, make this call to the https://pal-test.adyen.com/pal/servlet/Payment/v25/authorise test endpoint.

{
   "amount": {
      "currency": "USD",
      "value": "1000"
   },
   "merchantAccount": "TestMerchant",
   "reference": "MRef001-117",
   "shopperReference": "test1111",
   "bankAccount": {
      "countryCode": "US",
      "ownerName": "Andrews",
      "bankLocationId": "011000138",
      "bankAccountNumber": "4640348490",
      "bankName": "Bank of America",
      "bic": "BOFAUS3N"
   },
   "billingAddress": {
      "country": "US",
      "street": "Test",
      "houseNumberOrName": "137",
      "city": "Amsterdam",
      "postalCode": "12010",
      "stateOrProvince": "NY"
   }
}

In case of successful authorisation, you will get the following payment response:

{
    "additionalData": {
        "achdirectdebit.dateOfSignature": "2016-08-16",
        "achdirectdebit.mandateId": "9914713364543277",
        "achdirectdebit.sequenceType": "OneOff"
    },
    "pspReference": "9914713364543277",
    "resultCode": "Authorised"
}

For SOAP, make this call to the https://pal-test.adyen.com/pal/servlet/Payment/v25 test endpoint.

<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" xmlns:ns2="http://common.services.adyen.com">
            <ns1:paymentRequest>
                <ns1:amount>
                    <currency>USD</currency>
                    <ns2:value>1000</ns2:value>
                </ns1:amount>
                <ns1:merchantAccount>TestMerchant</ns1:merchantAccount>
                <ns1:reference>MRef001-117</ns1:reference>
                <ns1:shopperReference>test1111</ns1:shopperReference>
                <ns1:bankAccount>
                    <countryCode>US</countryCode>
                    <ownerName>Andrews</ownerName>
                    <bankLocationId>011000138</bankLocationId>
                    <bankAccountNumber>4640348490</bankAccountNumber>
                    <bankName>Bank of America</bankName>
                    <bic>BOFAUS3N</bic>
                </ns1:bankAccount>
                <ns1:billingAddress>
                    <country>US</country>
                    <ns2:street>Test</ns2:street>
                    <ns2:houseNumberOrName>137</ns2:houseNumberOrName>
                    <ns2:city>Amsterdam</ns2:city>
                    <ns2:postalCode>12010</ns2:postalCode>
                    <ns2:stateOrProvince>NY</ns2:stateOrProvince>
                </ns1:billingAddress>
            </ns1:paymentRequest>
        </ns1:authorise>
    </soap:Body>
</soap:Envelope>

In case of successful authorisation, you will get the following payment response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:ns1="http://payment.services.adyen.com" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Body>
      <ns1:authoriseResponse>
         <ns1:paymentResult>
            <ns1:additionalData>
               <ns1:entry>
                  <ns1:key xsi:type="xsd:string">achdirectdebit.dateOfSignature</ns1:key>
                  <ns1:value xsi:type="xsd:string">2016-08-16</ns1:value>
               </ns1:entry>
               <ns1:entry>
                  <ns1:key xsi:type="xsd:string">achdirectdebit.mandateId</ns1:key>
                  <ns1:value xsi:type="xsd:string">9914713344211235</ns1:value>
               </ns1:entry>
               <ns1:entry>
                  <ns1:key xsi:type="xsd:string">achdirectdebit.sequenceType</ns1:key>
                  <ns1:value xsi:type="xsd:string">OneOff</ns1:value>
               </ns1:entry>
            </ns1:additionalData>
            <ns1:pspReference>9914713344211235</ns1:pspReference>
            <ns1:resultCode>Authorised</ns1:resultCode>
         </ns1:paymentResult>
      </ns1:authoriseResponse>
   </soap:Body>
</soap:Envelope>

For FORM requests, make this call to the  https://pal-test.adyen.com/pal/servlet/Payment/v25/authorise test endpoint.

amount.currency=USD&amount.value=1500&merchantAccount=TestMerchant&reference=MRef001-117&shopperReference=test1111&bankAccount.countryCode=US&bankAccount.ownerName=Andrews&bankAccount.bankLocationId=011000138&bankAccount.bankAccountNumber=4640348490&bankAccount.bankName="Bank of America"&bankAccount.bic=BOFAUS3N&billingAddress.country=US&billingAddress.street=Test&billingAddress.houseNumberOrName=137&billingAddress.city=Amsterdam&billingAddress.postalCode=12010&billingAddress.stateOrProvince=NY

In case of successful authorisation, you will get the following payment response:

additionalData.achdirectdebit.dateOfSignature=2016-08-16&additionalData.achdirectdebit.mandateId=9914713520469052&additionalData.achdirectdebit.sequenceType=OneOff&pspReference=9914713520469052&resultCode=Authorised

ACH chargebacks

The ACH chargeback process is similar to a credit card chargeback; however, in case of an ACH chargeback it is not possible for a merchant to defend against a dispute.

Shoppers can reverse a ACH payment after settlement for one of the following reasons:

  • If a charge was never authorized by the account holder or the authorization was revoked. In this case, a shopper has up to 60 days from the specified date of payment to report the transaction to their bank and request a reversal.
  • If a charge was processed on a date earlier than authorized.
  • If a charge was settled for an amount different than authorized.

To initiate an ACH chargeback, an account holder provides notice to the bank in writing (or the electronic equivalent) that one of the above three conditions exists. This is different from credit card transactions where a customer can initiate a chargeback by claiming that the product or service received was not what they expected.

Boleto Bancário

This section describes how to implement payments supporting Boleto Bancário, a popular cash-based payment option in Brazil.

What is a boleto?

Boleto Bancário, often referred to as Boleto, is a card based payment method used in Brazil.

A boleto is a bank payment slip that entitles the receiver to be credited with the exact amount specified on the slip.

Boletos always include:

  • Issuer bank information
  • 44-digit ID field: it holds the same information as the bar code
  • Bar code: it holds the same information as the ID field
  • Payable amount value
  • Due date/Expiry date.
  • Shopper statement: Customisable payment instructions to shoppers.

How does a boleto work?

Shoppers can pay a boleto at an ATM, a bank, an approved facility, or through their bank's online banking system. After the boleto is paid, the bank sends Adyen a file confirming the payment. Usually, this takes a business day; however, it may require up to 6 business days after the payment date. Boletos have a due date; if a boleto has not been paid before the due date, the corresponding transaction remains open at Adyen Customer Area (CA) for 15 days.

When a Boleto payment is submitted, the Adyen system returns a response with a URL in the boletobancario.url field. The URL points to a downloadable PDF copy of the boleto that the shopper needs to use to proceed with their payment. You can redirect the consumer to it, so that they can complete the payment at an ATM, a bank or an approved facility.

The PDF is available until it expires. When a boleto expires, Adyen automatically updates its status to Offer cancelled in the customer area. The expiry date is included in the response, in the expirationDate field. The expiry date is calculated by adding 15 days to the deliveryDate value that is passed with the boleto payment request:

expirationDate = deliveryDate + 15 days

Boletos contain sensitive information like the consumer's address and their CPF (Cadastro de Pessoas Físicas, a unique identifier that is very similar to the Social Security Number in the USA).

The URL to the downloadable PDF boleto that Adyen provides is not available via a direct link. If you decide to download the PDF and make it available on your system, make sure that it is only available from a secure location.

If you store the file in a publicly available area, make sure that the content is not indexed to prevent search engines from accessing the PDF and including it in their search result pages.

To exclude content from being indexed by search engines, add the following HTTP header where the file is served:

X-Robots-Tag: noindex

Boleto payment request

A boleto payment request is a standard payment requests with extra elements to accommodate the boleto form details:

  • billingAddress
  • deliveryDate
  • shopperName
  • shopperStatement*
  • socialSecurityNumber

*Populating the field shopperStatement is crucial to ensure your shoppers have all the necessary information to complete a transaction. Besides general information, it is highly recommended to have customer service contact details (email and phone) in this field. 

Name Type Required Description
amount class (tick)
A container object for the payable amount information for the transaction.

It contains the following elements:

  • currency
  • value
value int (long) (tick)

The payable amount that can be charged for the transaction, in minor units.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

currency String (tick)
The three-character ISO currency code.
billingAddress class (error) A container for the billing address information.

It contains the following elements:

  • city
  • country
  • houseNumberOrName
  • postalCode
  • stateOrProvince
  • street
city String (error) Name of the city.
country String (error)

The country identifier. For boleto payments it is BR.

The country value format needs to adhere to the ISO 3166-1 alpha-2 standard. An invalid country code results in a transaction/request rejection. You can look up country codes on the ISO web site.

houseNumberOrName String (error) House number, or house name, or other house identifier.
postalCode String (error) Zip/Post code.
stateOrProvince String (error) Name of the state, region or province, where applicable.
street String (error) Name of the street.
deliveryDate String (error)

This is the date by which the consumer must submit their payment.

There are no time restrictions on the date.

However, if you do not populate this field, the Adyen system automatically sets the date 5 days in the future from the creation date.

reference String (tick)

A reference to uniquely identify the payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement.

If you need to provide multiple references for a transaction, you can enter them in this field. Separate each reference value with a hyphen character ("-").

This field has a length restriction: you can enter max. 80 characters.

A reference to uniquely identify the payment.
This reference is used in all communication with you about the payment status.
We recommend using a unique value per payment; however, it is not a requirement.

If you need to provide multiple references for a transaction, you can enter them in this field.
Separate each reference value with a hyphen character ("-").

This field has a length restriction: you can enter max. 80 characters.

merchantAccount String (tick)
The merchant account identifier you want to process the (transaction) request with.
selectedBrand String (tick)

Some payment methods require defining a value for this field to specify how to process the transaction.

For boleto payments, the corresponding value usually follows this format:

boletobancario_<issuer_bank_name>

shopperName class (tick) A container for the shopper's full name details.

It contains the following elements:

  • firstName
  • lastName
firstName String (tick) Shopper's first/given name.
lastName String (tick) Shopper's last/family name.
shopperStatement String (error)

This is a free-text field where you may give the shopper ad-hoc instructions concerning the payment they are submitting.

If you leave it empty, it is populated with the following default Portuguese text:

Não aceitar pagamento via cheque e/ou após a data do vencimento. 

Do not accept payment by cheque and/or after the due date.

Seu pedido será enviado somente após a confirmação do pagamento deste boleto, desde que não tenha divergência de valores entre o valor cobrado e o valor pago.  

Your order will only be processed once the payment of this Boleto has been confirmed and as long as there is no difference between the payable and paid amounts.

A falta de pagamento deste boleto não implica em qualquer multa ou juros e o pedido será automaticamente cancelado.

Failure to pay this boleto will not incur any penalty or interest and your order will be automatically cancelled.

Não deposite nem faça transferência.

Do not pay by deposit or bank transfer.

socialSecurityNumber String (error)

The shopper can provide their Cadastro de Pessoas Físicas (CPF) or Cadastro Nacional da Pessoa Jurídica (CNPJ) number, where necessary.

The socialSecurityNumber value is added to the Beneficiary field on boleto, along with firstName and lastName values.

Code examples

 

Request:

{
    "amount" : {
        "value" : 1000,
        "currency" : "BRL"
    },

    "billingAddress" : {
        "city" : "São Paulo",
        "country" : "BR",
        "houseNumberOrName" : "999",
        "postalCode" : "04787910",
        "stateOrProvince" : "SP",
        "street" : "Roque Petroni Jr"
    },
    
    "deliveryDate" : "2018-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.&#xA;Não cobrar juros. Não aceitar o pagamento com cheque",
    "socialSecurityNumber" : "56861752509"
}

Aceitar o pagamento até 15 dias após o vencimento.

Não cobrar juros.

Não aceitar o pagamento com cheque.

Accept payment up to 15 days past due.

Do not charge interest.

Do not accept payment by check.

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" : "2018-11-14",
        "boletobancario.dueDate" : "2018-10-30"
    },
    
    "pspReference" : "8813760397300101",
    "resultCode" : "Received"
}

Request:

<?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" xmlns:ns2="http://common.services.adyen.com">
      <paymentRequest>
        <amount>
          <ns2:currency>BRL</ns2:currency>
          <ns2:value>1000</ns2:value>
        </amount>
        <billingAddress>
          <ns2:city>São Paulo</ns2:city>
          <ns2:country>BR</ns2:country>
          <ns2:houseNumberOrName>999</ns2:houseNumberOrName>
          <ns2:postalCode>04787910</ns2:postalCode>
          <ns2:stateOrProvince>SP</ns2:stateOrProvince>
          <ns2:street>Roque Petroni Jr</ns2:street>
        </billingAddress>
        <ns1:deliveryDate>2018-10-29T23:00:00.000Z</ns1:deliveryDate>
        <ns1:merchantAccount>TestMerchant</ns1:merchantAccount>
        <ns1:reference>Teste Boleto</ns1:reference>
        <ns1:selectedBrand>boletobancario_santander</ns1:selectedBrand>
        <ns1:shopperName>
          <ns2:firstName>José</ns2:firstName>
          <ns2:lastName>Silva</ns2:lastName>
        </ns1:shopperName>
        <shopperStatement>Aceitar o pagamento até 15 dias após o vencimento.&#xA;Não cobrar juros. Não aceitar o pagamento com cheque.</shopperStatement>
        <socialSecurityNumber>56861752509</socialSecurityNumber>
      </paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>

Aceitar o pagamento até 15 dias após o vencimento.

Não cobrar juros.

Não aceitar o pagamento com cheque.

Accept payment up to 15 days past due.

Do not charge interest.

Do not accept payment by check.

Response:

<?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" xmlns:ns1="http://payment.services.adyen.com">
    <soap:Body>
        <ns1:authoriseResponse>
            <ns1:paymentResult>
                <ns1:additionalData>
                    <ns1:entry>
                        <ns1:key xsi:type="xsd:string">boletobancario.barCodeReference</ns1:key>
                        <ns1:value xsi:type="xsd:string">03399.32225 33897.803304 82223.201027 9 76930000001000</ns1:value>
                    </ns1:entry>
                    <ns1:entry>
                        <ns1:key xsi:type="xsd:string">boletobancario.data</ns1:key>
                        <ns1:value xsi:type="xsd:string">BQABAQBn2luGsOzfTke2whlBTlZS.....TOUZJ7AA356PisDmnQhyxrtAIhyex/SxshWeUvUSgLeQ=</ns1:value>
                    </ns1:entry>
                    <ns1:entry>
                        <ns1:key xsi:type="xsd:string">boletobancario.dueDate</ns1:key>
                        <ns1:value xsi:type="xsd:string">2018-10-30</ns1:value>
                    </ns1:entry>
                    <ns1:entry>
                        <ns1:key xsi:type="xsd:string">boletobancario.url</ns1:key>
                        <ns1:value xsi:type="xsd:string">https://test.adyen.com/hpp/generationBoleto.shtml?data=BQABAQBn2luGsOzfTEA7TmjSS52Re.....nQhyxKrtAeUvUSgLeQ%3D</ns1:value>
                    </ns1:entry>
                    <ns1:entry>
                        <ns1:key xsi:type="xsd:string">boletobancario.expirationDate</ns1:key>
                        <ns1:value xsi:type="xsd:string">2018-11-14</ns1:value>
                    </ns1:entry>
                </ns1:additionalData>
                <ns1:pspReference>7914734540825637</ns1:pspReference>
                <ns1:resultCode>Received</ns1:resultCode>
            </ns1:paymentResult>
        </ns1:authoriseResponse>
    </soap:Body>
</soap:Envelope>

Request:

amount.value=1000&amount.currency=BRL&billingAddress.city=São+Paulo&billingAddress.country=BR&billingAddress.houseNumberOrName=999&billingAddress.postalCode=04787910&billingAddress.stateOrProvince=SP&billingAddress.street=Roque+Petroni+Jr&deliveryDate=2018-10-29T23:00:00.000Z&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=56861752509

Aceitar o pagamento até 15 dias após o vencimento.

Não cobrar juros.

Não aceitar o pagamento com cheque.

Accept payment up to 15 days past due.

Do not charge interest.

Do not accept payment by check.

Response:

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&additionalData.boletobancario.data=AgABAQClZUyg1NqsD7nN5X1uqN4mabJ7A3FH5LgAUbqDnJ6EAQlnSAVL+u7eWIXY/o+7F0v04ZEnh6VR/+IAUfJoMQba2uHb2+qezXU/hgULKuFov7s2ZnwmszAuuHgE6JvahvWtAygC5lnpLEgw34pp7z8Vf2hAQYO9mvELei6ZR8S6DMxVTObYGE6r/anhX1ucteKztIR79zv1wWWzV/bccQIqgOEp5b8AYU6mwOlbm0oP2lPZofq4CFAQfs/ROyBk0JBQlQDaZHQRmY8YP3236nD6eEr4cBEy6MpULl8w0iin39NxXGsi7OCmuQDe2w1Fy/40Iv6AA2sar3JTo4Ap3eraC6PEN8s5+SoOB5MO+fpFbRSfFeSHGh9L3/wzuxaXCHopNfwjjgx6aJEVv1FmaPzyVYm9kB7+/1IpaxzBIp6nTh5VSMp8iJOyOccCoV4e7Qv6SKNDkvT5lc2KPXg6jUC4tQJWyFFbvgV55rlQojjRecQfLwCiQ51tONSyaw2QLewemJJys9Q2AyIXYemGUXdzYAORNlSLJkTQdkoQZKdMwuOx4LDPFkNQuzHLlg4Xg+pWYhgSz0TEZJrS83voNSRTbrIwOPN3&additionalData.boletobancario.expirationDate=2013-08-19&additionalData.boletobancario.dueDate=2013-08-12&pspReference=8813760397300101&resultCode=Received

Boleto notifications

When a boleto transaction is created in the Adyen system, we send you the following information:

  • PENDING status notification, as soon as the boleto transaction is created in the Adyen system.
  • The notification includes also an additionalData.acquirerReference field. You may want to store this data, as it corresponds to the Nosso Numero, i.e. the reference ID at the bank on the boleto slip.
  • When we receive a confirmation from the bank that the boleto has been paid, we send you an AUTHORISATION status notification.

Installments

Installment payments are a way to spread out a payable amount: instead of receiving one charge with the full amount, shoppers can split it up into smaller chunks, which they pay off at regular intervals over a set period of time. Installments are popular in Latin America. Contact the Adyen Support Team if you'd like to learn more about the acquirers supporting this payment option.

Installment payment request

A payment request supporting installments is a standard authorise payment request, with an additional installments object.

Name Type Required Description
installments class (tick)

A container for the installment information.

It contains the following element:

  • value
value int (short) (tick)

Defines the number of installments.
Its value needs to be greater than zero.

Usually, the maximum allowed number of installments is capped.
For example, it may not be possible to split a payment in more than 24 installments.
The acquirer sets this upper limit, so its value may vary.

Code examples

 

{
    "card" : {
        "number" : "4111111111111111",
        "expiryMonth" : "8",
        "expiryYear" : "2018",
        "cvc" : "737",
        "holderName" : "Adyen Test"
    },
    
    "amount" : {
        "value" : 2000,
        "currency" : "BRL"
    },
    
    "installments" : {
        "value" : 4
    },
        
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "s.hopper@test.com",
    "shopperIP" : "61.294.12.12",
    "shopperReference" : "John Smith"
}

amount.currency=BRL&amount.value=2000&card.cvc=737&card.expiryMonth=08&card.expiryYear=2018&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

<?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>08</expiryMonth>
          <expiryYear>2018</expiryYear>
          <holderName>Adyen Test</holderName>
          <number>4111111111111111</number>
        </card>
        <installments xmlns="http://common.services.adyen.com">
          <value xmlns="http://common.services.adyen.com">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">s.hopper@test.com</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>

Payment fields for risk system

Adyen's API for payment requests contains several optional fields that can be provided by the merchants. Some of these fields are quite important when the merchant uses several risk checks in the Risk System. We recommend the use of the following fields in order to use to its fullest the capabilities of Adyen's Risk System.

Field Required Description
reference (tick)

A unique identifier associated to a specific transaction. It is 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.

shopperReference (error)

A shopper's reference, which is the unique identifier for a shopper.

Used in the following risk checks:

dateOfBirth (error)

A shopper's date of birth. Format: yyyy-MM-dd HH:mm:ss.SSS z

Used in the following risk checks:

shopperName (error)

A shopper's personal information including the firstName, infix, lastName, and gender.

Used in the following risk checks:

shopperEmail (error)

shopperIP

(error)
deliveryAddress (error)

The address where a shopper is going to receive goods/services. Providing the following detailed information street, houseNumberOrName, city, postalCode, stateOrProvince, country.

Used in the following risk checks:

billingAddress (error)

The address where a shopper is going to receive the bill. Providing the following detailed information street, houseNumberOrName, city, postalCode, stateOrProvince, country.

Used in the following risk checks:

deviceFingerprint (error)

Information from a shopper's device and uses the combined value to identify the device of the shopper.

Used in the following risk checks:

telephoneNumber

(error) A shopper's phone number (only in countries where it is legal to collect).

socialSecurityNumber

(error) A shopper's social security number (only in countries where it is legal to collect).
deliveryDate (error)

The expected date of delivery or fulfillment of the goods/services to the shopper.

Used in the following risk checks:

fraudOffset (error) An integer that is added to the final fraud score of all risk checks. The value can be either positive or negative.
merchantOrderReference (error) A reference that merchants can use to link multiple transactions to each other.
browserInfo (error) With the browser info data, we can determine if the device is mobile or not, which is used for device fingerprinting and other device logic.

Additional data fields

These fields should be used within the additionalData field.

Fields Required Description
riskdata.deliveryMethod (error)

The method to deliver the goods to the shopper.

Used in the following risk checks:

riskdata.externalRiskScore (error)

Used only before authorisation and when external risk provider is used by merchant.

Used in the following risk checks:

riskdata.shopperAccountCreationDate

(error)

This specifies the date when the shopper's account was created.

Format: yyyy-MM-dd HH:mm:ss.SSS z

Used in Shopper Account Age Check.

{  
   "amount":{  
      "value":1700,
      "currency":"EUR"
   },
   "card":{  
      "number":"4111111111111111",
      "expiryMonth":"8",
      "expiryYear":"2018",
      "cvc":"737",
      "holderName":"Simon Hopper"
   },
   "reference":"LASPDAVIDDK2",
   "merchantAccount":"TestMerchant",
   "shopperReference":"Simon Hopper",
   "dateOfBirth":"1982-07-17T00:00:00Z",
   "shopperName":{
      "firstName":"Simon",
      "infix":"R.",
      "lastName":"Hopper",
      "gender": "MALE"
   },
   "shopperEmail":"s.hopper@test.com",
   "shopperIP":"61.294.12.12",
   "additionalData":{  
      "riskdata.deliveryMethod":"express"
   }
}
<?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/XMLSchemainstance">
   <soap:Body>
      <ns1:authorise xmlns:ns1="http://payment.services.adyen.com">
         <ns1:paymentRequest>
            <amount xmlns="http://payment.services.adyen.com">
               <value xmlns="http://common.services.adyen.com">1700</value>
               <currency xmlns="http://common.services.adyen.com">EUR</currency>
            </amount>
            <card xmlns="http://payment.services.adyen.com">
               <number>4111111111111111</number>
               <expiryMonth>08</expiryMonth>
               <expiryYear>2018</expiryYear>
               <cvc>737</cvc>
               <holderName>Simon Hopper</holderName>
            </card>
            <reference xmlns="http://payment.services.adyen.com">LASPDAVIDDK2</reference>
            <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
            <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference>
            <dateOfBirth xmlns="http://payment.services.adyen.com">1982-07-17T00:00:00Z</dateOfBirth>
            <shopperName xmlns="http://payment.services.adyen.com">
               <firstName xmlns="http://common.services.adyen.com">Simon</firstName>
               <infix xmlns="http://common.services.adyen.com">R.</infix>
               <lastName xmlns="http://common.services.adyen.com">Hopper</lastName>
               <gender xmlns="http://common.services.adyen.com">MALE</gender>
            </shopperName>
            <shopperEmail xmlns="http://payment.services.adyen.com">s.hopper@test.com</shopperEmail>
            <shopperIP xmlns="http://payment.services.adyen.com">61.294.12.12</shopperIP>
            <additionalData xmlns="http://payment.services.adyen.com">
               <riskdata.deliveryMethod>express</riskdata.deliveryMethod>
            </additionalData>
         </ns1:paymentRequest>
      </ns1:authorise>
   </soap:Body>
</soap:Envelope>
merchantAccount=TestMerchant&amount.value=10000&amount.currency=EUR&card.expiryYear=2018&card.cvc=737&card.number=4111111111111111&card.holderName=Adyen+Test&card.expiryMonth=08&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com&additionalData.riskdata.deliveryMethod=EXPRESS

Basket and promotion content fields

Adyen provides merchants the possibility to include basket and promotion information of a payment transaction in their API request to Adyen. This extra information is particular important when performing case management of transactions before they are captured.

These fields should be used within the additionalData field.

Basket content fields

Name Type Required Description

riskdata.basket.item<itemNr.>


class (error) A container for a specific item.
The <itemNr.> placeholder is replaced with an integer that increments by one unit.

It contains the following elements:

  • itemID
  • productTitle
  • amountPerItem
  • currency
  • upc
  • sku
  • brand
  • manufacturer
  • category
  • color
  • size
  • quantity

itemID

String (error)

ID of the item.

productTitle String (error)

A text description of the product the invoice line refers to.

amountPerItem String (error)

The price of item<itemNr> in the basket, represented in minor units.

currency

String (error)

The three-character ISO currency code.

upc String (error)

Universal Product Code.

sku String (error)

Stock keeping unit.

brand String (error)

Brand of the item.

manufacturer String (error)

Manufacturer of the item.

category String (error)

Category of the item.

color String (error)

Color of the item.

size String (error)

Size of the item.

quantity String (error)

Quantity of the item purchased.

Promotion content fields

Name Type Required Description


riskdata.promotions.promotion<promotionNr.>


class (error) A container for a specific promotion.
The <promotionNr.> placeholder is replaced with an integer that increments by one unit.

It contains the following elements:

  • promotionCode
  • promotionName
  • promotionDiscountAmount
  • promotionDiscountCurrency
  • promotionDiscountPercentage

promotionCode

String (error)

Code of the promotion.

promotionName String (error)

Name of the promotion.

promotionDiscountAmount String (error)

The discount amount of the promotion, represented in minor units.

promotionDiscountCurrency

String (error)

The three-character ISO currency code.

promotionDiscountPercentage String (error)

Promotion's percentage discount. It is represented in percentage value and there is no need to include the '%' sign.

e.g. for a promotion discount of 30%, the value of the field should be 30.

Payment responses

Go to API playground

If the message passes validation, a risk analysis is performed. Depending on the outcome, an authorisation is attempted. You receive a response with the following fields:

 

Name Type Returned by default Description
pspReference
String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

resultCode
String (tick)

The outcome of the payment. The possible values are:

  • Authorised
  • Refused
  • Error
  • Cancelled
  • Received
  • RedirectShopper
authCode String

(tick)

Authorisation code: 

  • When the payment is authorised successfully, this field holds the authorisation code for the payment. 
  • When the payment is not authorised, this field is empty.
refusalReason
String (error)
When the payment is not authorised, it is refused, or if an error occurs, this field holds Adyen's mapped reason for the refusal or a description of the error.
  • The additionalData object can include standard, as well as acquirer raw data.
    You can implement the additionalData object to include extra fields and receive additional information in your response.
  • When a payment authorisation response includes resultCode and refusalReason, the transaction failed or was declined.
    Check their values for further details about any issues that affected the operation.

additionalData payment responses

This functionality is not enabled by default, as it requires additional configuration on Adyen's end. Contact the  Adyen Support Team to request enabling it for you.

The additionalData object is a generic container that can hold extra fields.

Standard additionalData

When the additionalData object is enabled for your merchant account, it can be configured to return the following fields:

Name Type Returned by default Example value Description
authCode String (tick) 58747

Authorisation code: 

  • When the payment is authorised successfully, this field holds the authorisation code for the payment. 
  • When the payment is not authorised, this field is empty.

cvcResult String (tick)

For possible cvcResult values,

see the CVC/CCV table below.

The CVC result code of the payment. It provides information about the outcome of the CVC check.

avsResult String (tick)

For possible avsResult values,

see the AVS result values table below.

The AVS result code of the payment. It provides information about the outcome of the AVS check.

referred String (tick) true/false

Returned if the payment is referred, this field is set to true.

This fields is unavailable if the payment is referred and is usually not returned with Ecommerce transactions.

cardSummary String (tick) 1111

Returns last 4 digits of a credit card number.

Returned only in the case of a card payment.

expiryDate String (tick) 6/2016

Returns expiry date of the credit card returned.

Returned only in the case of a card payment.

refusalReasonRaw String (error) AUTHORISED Returns raw authorisation or refusal reason from the acquirers.

inferredRefusalReason

String (error) “3D Secure Mandated”
Provides a best indication of why a transaction was refused. When a transaction fails with either “Refused”, “Restricted Card”, “Transaction Not Permitted”, “Not supported” or "Declined Non Generic" refusalReason from the issuer, Adyen cross references it's PSP wide data for extra insight into the refusal reason. If an inferred refusal reason is available the inferredRefusalReason field will be populated and the refusalReason will be set to "Not Supported".

Possible values:

  • 3D Secure Mandated
  • ContAuth Not Supported
  • CVC Mandated
  • Ecommerce Not Allowed
  • Crossborder Not Supported
avsResultRaw String (error) 7 Returns raw AVS result from the acquirers.
cvcResultRaw String (error) 1 Returns raw CVC check result from the acquirers.
acquirerCode String (error) TestPmmAcquirer Returns the name of the acquirer processing the payment request.
hmacSignature String (error)

9u5B7JSCTLKN3W5LQWIBIod

XXPx4MHWgkO%2Fl9qOmFRE%3D

Returns optional HMAC signature generated based on the HMAC key generated for each notification endpoint in the Adyen Customer Area (CA) → Settings → Server Communication → Additional Settings.

acquirerReference String (error) 7C9N3FNBKT9 Returns reference number that can be used for reconciliation in case a non-Adyen acquirer is used for settlement.
ownerName String (error) A. Klaassen Only relevant for SEPA Direct Debit transactions Returns owner name of bank account.
countryCode String (error) NL Only relevant for SEPA Direct Debit transactions Returns country code of bank account.
bic String (error) TESTNL01 Only relevant for SEPA Direct Debit transactions Returns BIC of bank account.
iban String (error) NL13TEST0123456789 Only relevant for SEPA Direct Debit transactions Returns IBAN of bank account.
deliveryAddress.stateOrProvince String (error) NH Returns delivery address state or province passed in the payment request.
deliveryAddress.city String (error) Amsterdam Returns delivery address city passed in the payment request.
deliveryAddress.postalCode String (error) 1011 DJ Returns delivery address postal code passed in the payment request.
deliveryAddress.street String (error) Simon Carmiggeltstraat Returns delivery address street passed in the payment request.
deliveryAddress.houseNumberOrName String (error) 6-50 Returns delivery address house number or name passed in the payment request.
deliveryAddress.country String (error) NL Returns delivery address country passed in the payment request.
extraCostsCurrency String (error) EUR Returns currency of extra amount charged due to additional amounts set in the skin used in the HPP payment request.
extraCostsValue String (error) 150 Returns amount of extra amount charged due to additional amounts set in the skin used in the HPP payment request. Amount is in minor units.
installments.value String (error) 5 Returns the number of installments that the payment amount will be charged with. Only relevant for card payments in countries that support installments. 
paypalPayerStatus String (error) unverified Only relevant for Paypal transactions. Returns the status of the Paypal Buyer Paypal Account.
paypalPayerResidenceCountry String (error) US Only relevant for Paypal transactions. Returns the status of the Paypal Buyer country of residence.
acquirerAccountCode String (error) PayPalSandbox_TestAcquirer Only relevant for Paypal transactions. Returns the status of the Adyen acquirer account.
paypalPayerId String (error) LF5HCWWBRV2KL Only relevant for Paypal transactions. Returns the Paypal PayerID.
paypalEmail String (error) paypaltest@adyen.com Only relevant for Paypal transactions. Returns the Paypal Buyer account's email address.
paypalProtectionEligibility String (error) Ineligible Only relevant for Paypal transactions. Returns the eligibility for Paypal Seller Protection for this payment.
terminalId String (error) 06022622 Returns the terminal ID used in a Point-of-Sale payment.
shopperReference String (error) AdyenTestShopperXX Returns the shopperReference passed in the payment request.
shopperInteraction String (error) Ecommerce Returns the shopper interaction type of the payment request.
paymentMethodVariant String (error) mcpro Returns the Adyen sub-variant of the payment method used for the payment request.
fraudCheck-[nn]-[Fraud Check name] String (error) 20 Returns the fraud score due to a particular fraud check. Name of the fraud check is found in the key of the key-value pair.
alias String (error) H167852639363479 Returns the Adyen alias of the card.
aliasType String (error) Default Returns the type of the card alias.
cardBin String (error) 521234 Returns the Bank Identification Number of a credit card, which is the first six digits of a card number.
cardHolderName String (error) Test Cardholder Returns the Cardholder name passed in the payment request.
issuerCountry String (error) JP Returns the issuing country of the card based on the BIN list that Adyen maintains.
threeDOffered Boolean (error) true Returns a boolean value indicating whether 3DS was offered for this payment.
threeDAuthenticated Boolean (error) true Returns a boolean value indicating whether 3DS authentication was completed on this payment.
threeDOfferedResponse String (error) Y Returns the raw enrolment result from the 3DS directory services of the card schemes.
threeDAuthenticatedResponse String (error) N Returns the raw 3DS authentication result from the card issuer.
fundingSource String (error) DEBIT Returns information regarding the funding type of the card.
cardIssuingCurrency String (error) USD Returns the currency in which the card is issued, if information is available.
cardIssuingBank String (error)

American_Express

_US_Consumer

Returns the name of the bank that issued the card.
cavv String (error)

AQIDBAUGBw

gJCgsMDQ4PEBESExQ=

Returns the Cardholder Authentication Verification Value for the 3DS authentication session. Value returned is a Base64 encoded 20-byte byteArray.
xid String (error)

ODgxNDc2MDg2

MDExODk5MAAAAAA=

Returns the 3DS transaction ID of the 3DS session. Value is Base64 encoded and will be returned for transactions with directoryResponse 'N' or 'Y'.
cavvAlgorithm String (error) 3 Returns the algorithm used to generate the 3DS Cardholder Authentication Verification Value. 
eci String (error) 02 Returns the Electronic Commerce Indicator returned from the schemes for the 3DS payment session.

CVC/CVV result values

0 Unknown
1 Matches
2 Doesn't match
3 Not checked
4 No CVC/CVV provided, but was required
5 Issuer not certifed for CVC/CVV
6 No CVC/CVV provided

AVS result values

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

Acquirer additionalData

Payment response: acquirer additionalData fields

This functionality is not enabled by default, as it requires additional configuration on Adyen's end. Contact the  Adyen Support Team to request enabling it for you.

Where available, you can choose to receive the raw results we receive from the acquirer. Once this feature is set up for you, the the additionalData object in the API response includes the additional fields described below.

Whether any values are returned depends on the data we receive from the acquirer.

Name Type Returned by default Description
cvcResultRaw String (tick) Raw CVC result received from the acquirer, where available.
avsResultRaw String (tick) Raw AVS result received from the acquirer, where available.
refusalReasonRaw String (tick) Raw refusal reason received from the acquirer, where available.

Modification requests

This section describes the possible modification actions. You can submit modifications through your merchant account through the Adyen Customer Area (CA). If you are processing more than a handful of payments on a daily basis, we recommend automating this process; to do this, we make available a web service that accepts the modification requests from your backoffice system.

To submit modification messages, you need to provide valid authentication credentials:

  • The user name format is ws@Company.[YourCompanyAccount].
  • To set the corresponding password, go to the the Adyen Customer Area (CA), then select Settings | Users.

Adyen replies to modification requests with an appropriate response message, for example capture-receivedcancel-received or refund-received. This message means that the request is being processed. The modification requests are verified by Adyen backend systems before sending to the payment methods. If the data provided in the request differs from auth request, you are notified to correct the data and submit the request again.

Capture

You can capture payments only for payment methods that support distinct authorisations and captures.

After authorising a payment, you can capture it to complete the transaction and collect the payment.

Request

To capture an authorised payment, you send a modification request to the capture action, where you pass the fields described below.

To define a capture delay, go to the Adyen Customer Area (CA), then select Settings | Merchant Setting | Capture Delay.

The Adyen Customer Area (CA) offers an option to configure an automated capture process to automatically capture payments after a specified number of days, ranging from no delay, i.e. immediate capture, up to 14 days.

Name Type Required Description
merchantAccount String (tick)

The merchant account where the transaction, for which the request needs to be initiated, was processed.

modificationAmount Class (tick)

The amount to capture. It consists of:

  • value
  • currency
The  currency must match the currency used in the original payment request.

The value must be smaller than or equal to the authorised amount.

value int (tick)

The payable amount that can be charged for the transaction, in minor units.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.
currency String (tick)

The three-character ISO currency code.

The  currency value must match the corresponding  currency value used in the original payment request.
originalReference String (tick)
The  originalReference value corresponds to the  pspReference value assigned to the original payment.

You receive the pspReference with:

  • The payment status, or
  • The authorisation notification.
reference String (error)
If you want, you can specify your reference for the modification request.
The reference is visible in the Merchant Backoffice and in the reporting section.
This field has a length restriction: you can enter max. 80 characters.

Response

If the message you send with the call is syntactically valid you receive a captureReceived response with the following fields:

Name Type Returned by default Description
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

response String (tick)
  • If the request is successful, the returned value is [capture-received].
  • If it fails, an error message is returned.

Capture final result

In most cases, the final result of a capture is sent with a notification message whose eventCode value is CAPTURE.

The  pspReference in this notification is the same as the  pspReference in the capture modification response.

The success field in the response indicates if the capture was successful or not:

  • true: the capture was successful
  • false: the capture failed. In this case, the notification message includes a reason field with a short description of the problem.

Offline capture

Some payment methods handle the capture process offline. Sometimes, we may receive a failure. In such a scenario, we send a notification message whose eventCode value is CAPTURE_FAILED.

The pspReference of this notification is the same as the pspReference in the capture modification response.

The success field in the response is set to true.

Examples

The following code examples show payment capture modification requests and responses in JSON, FORM, and SOAP.

Request:

{
    "merchantAccount" : "TestMerchant",

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

Response:

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

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>

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

Request:

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

Response:

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

Cancel

You can cancel payments only for payment methods that support distinct authorisations and captures.

After authorising a payment, you may wish to cancel it.

Request

To cancel an authorised payment, you send a modification request to the cancel action, where you pass the fields described below.

Name Type Required Description
merchantAccount String (tick) The merchant account where the transaction, for which the request needs to be initiated, was processed.
originalReference String (tick)
The  originalReference value corresponds to the  pspReference value assigned to the original payment.

You receive the pspReference with:

  • The payment status, or
  • The authorisation notification.
reference String (error)
If you want, you can specify your reference for the modification request.
The reference is visible in the Merchant Backoffice and in the reporting section.
This field has a length restriction: you can enter max. 80 characters.

Response

Name Type Returned by default Description
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

response String (tick)
  • If the request is successful, the returned value is [cancel-received].
  • If it fails, an error message is returned.

Cancel final result

The final result of a cancellation is sent with a notification message whose eventCode value is CANCELLATION.

The pspReference of this notification is the same as the pspReference in the cancel modification response.

The success field in the response indicates if the cancellation was successful or not:

  • true: the cancellation was successful
  • false: the cancellation failed. In this case, the notification message includes a reason field with a short description of the problem.

Examples

The following code examples show payment cancellation modification requests and responses in JSON, FORM, and SOAP.

Request:

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

Response:

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

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

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

Request:

merchantAccount=TestMerchant&reference=YourModificationReference&originalReference=8313547924770610

Response:

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

Refund

You may need to issue a refund when you cancel a payment and return the partially or fully charged amount to the shopper.

After capturing a payment and charging the shopper, it may  be necessary to return the paid amount to the shopper if they request a refund.

When sending the refund request through API you will receive the [refund-received] response. We send out the notification with the result of the refund as soon as it is processed.

Request

To initiate a refund of an authorised and charged payment, you send a modification request to the refund action, where you pass the fields described below:

Name Type Required Description
merchantAccount String (tick) The merchant account where the transaction, for which the request needs to be initiated, was processed.
modificationAmount Class (tick)

A container for the amount that needs to be refunded.

It contains the following elements:

  • value
  • currency

The  currency must match the currency used in the original payment request.

The value must be smaller than or equal to the authorised amount.

value int (tick)

The refundable amount that can be returned to the shopper.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

currency String (tick)

The three-character ISO currency code.

The  currency value must match the corresponding  currency value used in the original payment request.

originalReference String (tick)
The  originalReference value corresponds to the  pspReference value assigned to the original payment.

You receive the pspReference with:

  • The payment status, or
  • The authorisation notification.
reference String (error)
If you want, you can specify your reference for the modification request.
The reference is visible in the Merchant Backoffice and in the reporting section.
This field has a length restriction: you can enter max. 80 characters.

Response

If the message you send with the call is valid and if the specified merchantAccount is correct, you receive a refundReceived response with the following fields:

Name Type Returned by default Description
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

response String (tick)
  • If the request is successful, the returned value is [refund-received].
  • If it fails, an error message is returned.

Refund final result

The final result of a refund is sent with a notification message whose eventCode value is REFUND.

The pspReference of this notification is the same as the pspReference in the refund modification response.

The success field in the response indicates if the refund was successful or not:

  • true: the refund was successful
  • false: the refund failed. In this case, the notification message includes a reason field with a short description of the problem.

Offline refund

Some payment methods handle the refund process offline. Sometimes, we may receive a failure. In such a scenario, we send a notification message whose eventCode value is REFUND_FAILED.

The pspReference of this notification is the same as the pspReference in the refund modification response.

The success field in the response is set to true.

Examples

The following code examples show payment refund modification requests and responses in JSON, FORM, and SOAP.

Request:

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

Response:

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

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

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

Request:

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

Response:

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

Cancel or refund

If you are not sure whether a payment has been correctly captured, and at the same time you want to reverse the payment authorisation, you can issue a cancel or refund.

Request

To initiate a cancellation or refund of an authorised payment that may or may not have been captured, you send a modification request to the cancelOrRefund action, where you pass the fields below.

Name Type Required Description
merchantAccount String (tick) The merchant account where the transaction, for which the request needs to be initiated, was processed.
originalReference String (tick)
The  originalReference value corresponds to the  pspReference value assigned to the original payment.

You receive the pspReference with:

  • The payment status, or
  • The authorisation notification.
reference String (error)
If you want, you can specify your reference for the modification request.
The reference is visible in the Merchant Backoffice and in the reporting section.
This field has a length restriction: you can enter max. 80 characters.

Response

If the message you send with the call is valid and if the specified merchantAccount is correct, you receive a cancelOrRefundReceived response with the following fields:

Name Type Returned by default Description
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

response String (tick)
  • If the request is successful, the returned value is [cancelOrRefund-received].
  • If it fails, an error message is returned.

Cancel or refund scenarios

The final result of a refund is sent with a notification message whose eventCode value is REFUND.

The pspReference of this notification is the same as the pspReference in the refund modification response.

The success field in the response indicates if the refund was successful or not:

  • true: the refund was successful
  • false: the refund failed. In this case, the notification message includes a reason field with a short description of the problem.

Payment authorised but not captured

If the payment is authorised, but not yet captured, it is cancelled.

 If the selected payment method for the transaction does not support cancellation, the transaction amount us fully refunded.

Cancellation

If the cancel or refund modification request produces a cancellation, the final result is sent with a notification message whose eventCode value is CANCEL_OR_REFUND.

The pspReference of this notification is the same as the pspReference in the cancel or refund modification response.

The success field in the response indicates if the cancellation was successful or not:

  • true: the cancellation was successful
  • false: the cancellation failed. In this case, the notification message includes a reason field with a short description of the problem.

Refund

If the cancel or refund modification request produces a refund, the final result is sent with a notification message whose eventCode value is CANCEL_OR_REFUND.

The pspReference of this notification is the same as the pspReference in the cancel or refund modification response.

The success field in the response indicates if the refund was successful or not:

  • true: the refund was successful
  • false: the refund failed. In this case, the notification message includes a reason field with a short description of the problem.

Failure

If the cancel or refund modification request fails, the final result is sent with a notification message whose eventCode value is SUCCESS=FALSE.

The pspReference of this notification is the same as the pspReference in the cancel or refund modification response.

The success field in the response is set to false: the refund failed.

The notification message includes a reason field with a short description of the problem.

Examples

The following code examples show payment cancel or refund modification requests and responses in JSON, FORM, and SOAP.

Request:

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

Response:

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

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

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

Request:

merchantAccount=TestMerchant&reference=YourModificationReference&originalReference=9313547924770610

Response:

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

Airline specific information

In the airline industry, it is often a requirement to send airline data over to the acquirers when processing credit card transactions. 

Overview of airline data fields

Airline data fields can be sent in the payment authorisation, capture and refund requests under the additionalData container. 

The main container objects for airline data are:

  • airline: Top-level container object for all airline data.
  • airline.leg<legNr>: Second-level container object for leg data. The leg number counter starts at 1 and sequentially increments by 1 unit. Maximum number of supported legs is 4.
  • airline.passenger<passengerNr.>: Second-level container object for passenger data. The passenger number counter starts at 1 and sequentially increments by 1 unit, maximum number of supported passengers is 10.

Parent Child
airline  












agency_invoice_number

agency_plan_name

airline_code

customer_reference_number

boarding_fee

passenger_name

ticket_issue_address

ticket_number

travel_agency_code

travel_agency_name
flight_date
airline_designator_code

passenger

leg

airline.passenger  
 

first_name

last_name

traveller_type

date_of_birth
phone_number
airline.leg  
 

carrier_code

class_of_travel

date_of_travel

depart_airport

depart_tax

destination_code

fare_base_code

flight_number

stop_over_code

Airline fields

Parent container object for airline data fields: airline

Name Type Required Description Notes
passenger_name
String (error)

Passenger name, initials and title name.

 

  • Format: last name + first name or initials + title
    Example: EARHART/AMELIA MARY MS.
  • minLength: 1
  • maxLength: 49
customer_reference_number String (error)

Reference number; alphanumeric.

 

  • minLength: 0
  • maxLength: 20
ticket_issue_address String (error) Addres of the place/agency that issued the ticket.
  • minLength: 0
  • maxLength: 16
airline_code String (error)

IATA 3-digit accounting code (PAX); numeric.

It identifies the carrier.

  • Format: IATA 3-digit accounting code (PAX)
    Example.: KLM = 074
  • minLength: 3
  • maxLength: 3
airline_designator_code String (error)

IATA 2-letter accounting code (PAX); alphabetical.

It identifies the carrier.
  • Format: IATA 2-letter airline code
    Example.: KLM = KL
  • minLength: 2
  • maxLength: 2
ticket_number String (error) The ticket's unique identifier.
  • minLength: 1
  • maxLength: 150
travel_agency_code String (error)

IATA number, also ARC number or ARC/IATA number.

Unique identifier number for travel agencies.

  • minLength: 1
  • maxLength: 8
travel_agency_name String (error) The name of the travel agency.
  • minLength: 1
  • maxLength: 25
agency_plan_name String (error) 2-letter agency plan identifier; alphabetical.
  • minLength: 2
  • maxLength: 2
agency_invoice_number String (error) Reference number for the invoice, issued by the agency.
  • minLength: 1
  • maxLength: 6
flight_date String (error)

Flight departure date.

Local time (HH:mm) is optonal.

  • Date format: yyyy-MM-dd
  • Date and time format: yyyy-MM-dd HH:mm
  • minLength: 10
  • maxLength: 16
boarding_fee String (error)

Chargeable amount for boarding the plane.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

  • minLength: 1
  • maxLength: 18

Airline leg fields

Parent container object for airline leg data fields: airline.leg<legNr.>

Name Type Required Description Notes
depart_airport String (error)

Alphabetical identifier of the departure airport.
This field is required/mandatory if the airline data includes leg details.

 

  • Format: IATA 3-letter airport code.
    Example: Amsterdam = AMS
  • minLength: 3
  • maxLength: 3
flight_number String (error) The flight identifier.
  • minLength: 1
  • maxLength: 5
carrier_code String (error)

IATA 2-letter accounting code (PAX); alphabetical.
It identifies the carrier.
This field is required/mandatory if the airline data includes leg details.

 

  • Format: IATA 2-letter airline code
    Example.: KLM = KL
  • minLength: 2
  • maxLength: 2
fare_base_code String (error) Fare basis code; alphanumeric.
  • minLength: 1
  • maxLength: 7
class_of_travel String (error)

1-letter travel class identifier; alphabetical.

There is no standard; however, the following codes are used rather consistently:

  • F: first class
  • J: business class
  • Y: economy class
  • W: premium economy
  • minLength: 1
  • maxLength: 1
stop_over_code String (error)

1-letter code that indicates whether the passenger is entitled to make a stopover.

Only two types of characters are allowed:

  • O: Stopover allowed
  • X: Stopover not allowed
  • minLength: 1
  • maxLength: 1
destination_code String (error)

Alphabetical identifier of the destination/arrival airport.
This field is required/mandatory if the airline data includes leg details.

 

  • Format: IATA 3-letter airport code.
    Example: Amsterdam = AMS
  • minLength: 3
  • maxLength: 3
date_of_travel

String

(error) Date and time of travel.
ISO 8601-compliant.
  • Format: yyyy-MM-dd HH:mm
  • minLength: 16
  • maxLength: 16
depart_tax

String

(error)

Departure tax. Amount charged by a country to an individual upon their leaving.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

  • minLength: 1
  • maxLength: 12

Airline passenger fields

Parent container object for airline passenger data fields: airline.passenger<passengerNr.>

Name Type Required Description Notes
first_name String (error)

Passenger first name/given name.
This field is required/mandatory if the airline data includes passenger details.

 

This field does not have a max. character length constraint. However:
  • passenger_name cannot be longer than 49 character.
  • Most acquirers truncate this field at ~40 characters, sometimes even at ~30 characters.

Therefore, it's advisable to keep this field length within the recommended maxLength value.

  • minLength: 1
  • maxLength: ~20
last_name String (error)

Passenger last name/family name.
This field is required/mandatory if the airline data includes passenger details.

 

This field does not have a max. character length constraint. However:
  • passenger_name cannot be longer than 49 character.
  • Most acquirers truncate this field at ~40 characters, sometimes even at ~30 characters.

Therefore, it's advisable to keep this field length within the recommended maxLength value.

  • minLength: 1
  • maxLength: ~20
traveller_type String (error)

Passenger type code (PTC).

IATA PTC values are 3-letter alphabetical. Example: ADT, SRC, CNN, INS.

However, several carriers use non-standard codes that can be up to 5 alphanumeric characters.

  • minLength: 3
  • maxLength: 6
telephone_number String (error) Telephone number of the passenger, including country code. This is an alphanumeric field that can include the '+' and '-' signs.
  • minLength: 3
  • maxLength: 30
date_of_birth String (error) Date of birth of the passenger.
  • Date format: yyyy-MM-dd
  • minLength: 10
  • maxLength: 10

Authorisation request

Listed are some code examples in FORM, SOAP and JSON on how to send airline data as part of the additional data container in your authorisation request.

You can look up the respective API endpoints for FORM and JSON.

{    "card" : {
        "number" : "4111111111111111",
        "expiryMonth" : "8",
        "expiryYear" : "2018",
        "cvc" : "737",
        "holderName" : "Adyen Test"
    },
     
    "amount" : {
        "value" : 199,
        "currency" : "EUR"
    },
     
    "reference" : "Your Reference Here",
    "merchantAccount" : "TestMerchant",
    "shopperEmail" : "s.hopper@test.com",
    "shopperIP" : "61.294.12.12",
    "shopperReference" : "Simon Hopper",
	"additionalData" : {
		"airline.ticket_number" : "ABC123000000001",
		"airline.passenger1.first_name" : "Peter",
		"airline.passenger1.last_name" : "Parker",
		"airline.leg1.depart_airport" : "AMS",
		"airline.leg1.destination_code" : "LON"
	}
}
merchantAccount=TestMerchant&amount.value=199&card.expiryYear=2018&amount.currency=EUR&card.cvc=737&card.number=4111111111111111&card.holderName=Adyen+Test&card.expiryMonth=08&reference=Your+Reference+Here&shopperReference=Simon+Hopper&shopperEmail=s.hopper%40test.com&additionalData.airline.ticket_number=ABC123000000001&additionalData.airline.passenger1.first_name=Peter&additionalData.airline.passenger1.last_name=Parker&additionalData.airline.leg1.depart_airport=AMS&additionalData.airline.leg1.destination_code=LON
<?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">199</value>
        </amount>
        <card xmlns="http://payment.services.adyen.com">
          <cvc>737</cvc>
          <expiryMonth>08</expiryMonth>
          <expiryYear>2018</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">s.hopper@test.com</shopperEmail>
        <shopperReference xmlns="http://payment.services.adyen.com">Simon Hopper</shopperReference>
		<additionalData xmlns="http://payment.services.adyen.com">
         		<entry>
          		   <key xsi:type="xsd:string">airline.ticket_number</key>
         		   <value xsi:type="xsd:string">ABC123000000001</value>
         		</entry>
        		<entry>
         		   <key xsi:type="xsd:string">airline.passenger1.first_name</key>
         		   <value xsi:type="xsd:string">Peter</value>
         		</entry>
       		    <entry>
       		     	<key xsi:type="xsd:string">airline.passenger1.last_name</key>
    		        <value xsi:type="xsd:string">Parker</value>
    		    </entry>
    		    <entry>
        			<key xsi:type="xsd:string">airline.leg1.departure_airport</key>
       		    	<value xsi:type="xsd:string">AMS</value>
       		    </entry>
        		<entry>
           		<key xsi:type="xsd:string">airline.leg1.destination_code</key>
            	<value xsi:type="xsd:string">LON</value>
          </entry>
		</additionalData>
      </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>

Capture and Refund request

Listed are some code examples in FORM, SOAP and JSON on how to send airline data as part of the additional data container in your modification requests.

You can look up the respective API endpoints for FORM, and JSON.

Capture/Refund:

merchantAccount=TestMerchant&modificationAmount.value=199&modificationAmount.currency=EUR&reference=Your+Modification+Reference+Here&originalReference=4411239248317592&additionalData.airline.ticket_number=ABC123000000001&additionalData.airline.passenger1.first_name=Peter&additionalData.airline.passenger1.last_name=Parker&additionalData.airline.leg1.depart_airport=AMS&additionalData.airline.leg1.destination_code=LON

Capture/Refund:

{
   "modificationAmount" : {
        "value" : 199,
        "currency" : "EUR"
    },
      
    "reference" : "Your Modification Reference Here",
	"originalReference" : "4411239248317592",
    "merchantAccount" : "TestMerchant",

    "additionalData" : {
        "airline.ticket_number" : "ABC123000000001",
        "airline.passenger1.first_name" : "Peter",
        "airline.passenger1.last_name" : "Parker",
        "airline.leg1.depart_airport" : "AMS",
        "airline.leg1.destination_code" : "LON"
    }
}

Capture:

<?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>
        <amount xmlns="http://payment.services.adyen.com">
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
          <value xmlns="http://common.services.adyen.com">199</value>
        </amount>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <reference xmlns="http://payment.services.adyen.com">Your Modification Reference Here</reference>
        <originalReference xmlns="http://payment.services.adyen.com">4411239248317592</originalReference>
        <additionalData xmlns="http://payment.services.adyen.com">
                <entry>
                   <key xsi:type="xsd:string">airline.ticket_number</key>
                   <value xsi:type="xsd:string">ABC123000000001</value>
                </entry>
                <entry>
                   <key xsi:type="xsd:string">airline.passenger1.first_name</key>
                   <value xsi:type="xsd:string">Peter</value>
                </entry>
                <entry>
                    <key xsi:type="xsd:string">airline.passenger1.last_name</key>
                    <value xsi:type="xsd:string">Parker</value>
                </entry>
                <entry>
                    key xsi:type="xsd:string">airline.leg1.departure_airport</key>
                    <value xsi:type="xsd:string">AMS</value>
                </entry>
                <entry>
                <key xsi:type="xsd:string">airline.leg1.destination_code</key>
                <value xsi:type="xsd:string">LON</value>
          </entry>
        </additionalData>
      </ns1:modificationRequest>
    </ns1:capture>
  </soap:Body>
</soap:Envelope>

Refund:

<?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>
        <amount xmlns="http://payment.services.adyen.com">
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
          <value xmlns="http://common.services.adyen.com">199</value>
        </amount>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <reference xmlns="http://payment.services.adyen.com">Your Modification Reference Here</reference>
        <originalReference xmlns="http://payment.services.adyen.com">4411239248317592</originalReference>
        <additionalData xmlns="http://payment.services.adyen.com">
                <entry>
                   <key xsi:type="xsd:string">airline.ticket_number</key>
                   <value xsi:type="xsd:string">ABC123000000001</value>
                </entry>
                <entry>
                   <key xsi:type="xsd:string">airline.passenger1.first_name</key>
                   <value xsi:type="xsd:string">Peter</value>
                </entry>
                <entry>
                    <key xsi:type="xsd:string">airline.passenger1.last_name</key>
                    <value xsi:type="xsd:string">Parker</value>
                </entry>
                <entry>
                    key xsi:type="xsd:string">airline.leg1.departure_airport</key>
                    <value xsi:type="xsd:string">AMS</value>
                </entry>
                <entry>
                <key xsi:type="xsd:string">airline.leg1.destination_code</key>
                <value xsi:type="xsd:string">LON</value>
          </entry>
        </additionalData>
      </ns1:modificationRequest>
    </ns1:refund>
  </soap:Body>
</soap:Envelope>

Sending airline data to acquirers

Airline data can be provided at all stages of the payment (e.g. authorisation, capture and refund). However, airline data is only sent over to the acquirers in the capture and refund stages in a batch file.

On this page, we recommend using one of the 3 following workflows when planning how to send airline data to the acquirers.

Data flow 1: Airline data is sent in only during authorisation. No airline data is sent for a capture, and refund.

  • Capture: Capture uses the complete airline data set sent with authorisation.
  • Refund: Refund uses the complete airline data set sent with authorisation.

Data flow 2:  No Airline data is sent in during authorisation. Airline data is sent in both the capture, and refund calls.

  • Capture: Capture uses the complete airline data set sent with capture.
  • Refund: Refund uses the complete airline data set sent with refund. 

Data flow 3:  Airline data is sent in all three stages: authorisation, capture and refund.

  • Capture: Capture uses the complete airline data set sent with capture.
  • Refund: Refund uses the complete airline data set sent with refund.

The preset default and override values in your company/merchant account is taken into account in the data flows.

Defaults and Overrides

It can be challenging to meet the different airline data requirements of different acquirers if your company is using more than one.

Adyen helps you with this by offering the ability to set default and/or override values at the company or merchant level for any number of airline data fields. 

Here is an example case to illustrate how the logic works: 

Airline data field name Adyen Defaults

Data sent in

by merchant

Overrides

Final dataset sent

to acquirer

airline.travel_agency_name Test Airline     Test Airline
airline.travel_agency_code 000123     000123
airline.flight_date   2018-12-31   2018-12-31
airline.agency_invoice_number        
airline.customer_reference_number        
airline.ticket_number   123ABC000000001   123ABC000000001
airline.ticket_issue_address        
airline.passenger_name        
airline.agency_plan_name        
airline.airline_designator_code     AA AA
airline.boarding_fee        
airline.airline_code 123     123
airline.passenger1.first_name   Peter   Peter
airline.passenger1.last_name   Parker   Parker
airline.passenger1.date_of_birth   1987-10-12   1987-10-12
airline.passenger1.traveller_type        
airline.passenger1.phone_number        
airline.leg1.date_of_travel        
airline.leg1.flight_number        
airline.leg1.carrier_code   AA BB BB
airline.leg1.depart_airport XXX AMS   AMS
airline.leg1.destination_code XXX LON   LON
airline.leg1.fare_base_code        
airline.leg1.stop_over_code   X   X
airline.leg1.class_of_travel   J   J
airline.leg1.depart_tax        

Notifications

We send you notifications to inform you about the outcome of an action: when a payment is made, a modification is processed or a report is available for download, we notify the event and whether it was successful or not.

The purpose of notifications is to sync your backoffice system, so that payment and modification statuses are always up to date.

(tick) You receive capture notifications for capture requests submitted via your web service or the Adyen CA.
(error) You do not receive capture notifications for automatic captures initiated by the Adyen platform.

Set up notifications

Notification configuration

To configure notifications, go to Adyen Customer Area (CA)  → Settings → Server communication. On this page select one of existing notifications (if there are any) or add a new notification (by default, choose Standard Notification).

Then, on the notification settings page, do the following:

  • Specify the URL to submit notifications to.
  • Set the communication method (SOAP, JSON, HTTP POST).
  • Enter a user name and a password for HTTP basic authentication.

Ports to use:

Port Transport layer Application layer
80 TCP HTTP
Default port for HTTP traffic
443 TCP

HTTPS
Default port for HTTPS traffic

8080 TCP HTTP
Alternative port
8888 TCP HTTP
Alternative port
8443 TCP HTTPS
Alternative port
8843 TCP HTTPS
Alternative port

Notification server

You need to set up a server to receive and accept the notifications we send you with a JSON/SOAP call or through HTTP POST. Your system needs to be able to handle requests and responses containing additional fields, as well as duplicate notifications for the same transaction.

Notification fields

Depending on the message payload, notification messages can include a number of different fields.
The fields included in a notification message can vary, depending on the event types that trigger it.

Adyen reserves the right to introduce new fields in the future.
Therefore, make sure your listening service does not expect a fixed, predefined set of values.

A notification message can refer to one or more transactions.
These are the fields that can be included in a notification message.

Name Type Returned by default Description
live Boolean (tick)

Informs about the origin of the notification:

  • true: the notification originated from the live environment.
  • false: the notification originated from the test environment.
notificationItems List (tick) A container object for the details included in the notification.
notificationItems list includes one or more NotificationRequestItem objects.
NotificationRequestItem class (tick)

A container object for the details referring to a single transaction.
It can contain the following elements:

  • additionalData
  • amount
  • pspReference
  • eventCode
  • eventDate
  • merchantAccountCode
  • operations
  • merchantReference
  • originalReference
  • paymentMethod
  • reason
  • success
additionalData Object (error)

The additionalData object is a generic container that can hold extra fields.

It contains the following elements:

  • shopperReference
  • shopperEmail
  • authCode
  • cardSummary
  • expiryDate
  • authorisedAmountValue
  • authorisedAmountCurrency

shopperReference

String (tick) The ID that uniquely identifies the shopper. This shopperReference is the same as the shopperReference used in the initial payment.
shopperEmail String (tick) The shopper's email address.
authCode String (error)

Authorisation code: 

  • When the payment is authorised successfully, this field holds the authorisation code for the payment. 
  • When the payment is not authorised, this field is empty.
cardSummary String (error)

Returns the last 4 digits of the credit card.

Only digits allowed. No alphabetic characters.
expiryDate String (error)

Returns the card expiry date.

  • Format: MM/YYYY

authorisedAmountValue

String (error)

Value of the amount authorised.

Scenario 1 - Zero value auth transaction

Some issuers don't allow a zero value transaction. In this case Adyen authorises a minimum amount, for example Euro 1.00, to verify the shoppe's card. After successful authorisation, Adyen's system automatically cancel the authorisation. The actual authorised amount is returned in this field which may differ from the amount sent in in the payment request.

Scenario 2 - Available amount

A shopper makes a transaction of Euro 10 using a gift card but the card contains only Euro 06. In this case Adyen deducts the available amount and keeps the pending amount open to be completed with other payment options. The authorised amount is returned in this field.

You can enable this feature using Adyen Customer Area (CA)Merchant accountSettingsServer CommunicationAdditional Settings.

authorisedAmountCurrency String (error)

Currency of the authorised amount.

amount String (tick)

A container object for the payable amount information for the transaction.

It contains the following elements:

  • currency
  • value

In case of HTTP POST notifications, currency and value are returned as URL parameters.

currency String (tick)
The three-character ISO currency code.
value int (tick)

The payable amount that can be charged for the transaction, in minor units.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

This field displays the amount sent in the payment request.

pspReference

String

(tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

In REPORT_AVAILABLE response you receive a file name in this field.

In PAIDOUT_REVERSED event code pspsreference is for Capture's pspsreference.

eventCode String (tick)

The type of event the notification item refers to.

When eventCode returns AUTHORISATION , it does not necessarily mean that the payment authorisation request has been successfully processed.

The authorisation is successful if successtrue.

If success = false, check the  the reason value for further information on the authorisation failure cause.

This can occur, for example, if an error occurs or if the transaction is refused.

eventDate Date (tick)

The time when the event was generated.

merchantAccountCode

String

(tick) The merchant account identifier used in the transaction the notification item refers to.
operations List (tick)

This field holds a list with the modification operations supported by the transaction the notification item refers to.

The available operations in the list give information on the follow-up actions concerning the payment.
You may be requested to:

  • Capture the payment (for example, if auto-capture is not set up),
  • Cancel the payment (if the payment has not been capture yet), or
  • Refund the payment (if the payment has already been captured).

Possible values:

  • CANCEL
  • CAPTURE
  • REFUND

This field is populated only in authorisation notifications.

In case of HTTP POST notifications, the operation list is a sequence of comma-separated string values.

merchantReference

String

(tick)

A reference to uniquely identify the payment.
This reference is used in all communication with you about the payment status.
We recommend using a unique value per payment; however, it is not a requirement.

If you need to provide multiple references for a transaction, you can enter them in this field.
Separate each reference value with a hyphen character ("-").

This field has a length restriction: you can enter max. 80 characters.

By default, merchantReference is always returned with payment notifications,
as merchantReference returns the reference field value of the corresponding payment request.
In this case, returned by default = (tick)

Modification requests do not require sending a merchant reference value along with the call.
Therefore, the corresponding notifications do not include it by default.
In this case, returned by default = (error)

An empty merchantReference field in a notification message takes null as a value.

originalReference String (error)
If the notification item is about a... ...then:

Modification request

The  originalReference value corresponds to the  pspReference value assigned to the original payment.

You receive the pspReference with:

  • The payment status, or
  • The authorisation notification.

Payment /
Payment authorisation

This field is not populated, it is blank.

paymentMethod String (tick)

The payment method used in the transaction the notification item refers to.

Example payment methods that can be set to this field:

visa, mc, ideal, elv, wallie, and so on.

This field is populated only in authorisation notifications.
reason

String

(error)

This field is included only in some notifications.

This field holds plain text. The value varies depending on whether the outcome of the event is successful or not (successtrue or false):

If... ...then:
  • eventCodeAUTHORISATION
  • successtrue
  • paymentMethod = visamc or amex

reason includes the following details:

  • Authorisation code
  • Last 4 digits of the card
  • Card expiry date

Format:

6-digit auth code:last 4 digits:expiry date

Example:

874574:1935:11/2012

  • success = false
reason includes a short message with an explanation for the refusal.
  • eventCode = REPORT_AVAILABLE
reason includes the download URL where you can obtain a copy of the report.
  • eventCode = PAIDOUT_REVERSED

reason field in the notification contains the bank statement description if present, else it contains PaidOutReversed.

success Boolean (tick)

Informs about the outcome of the event (eventCode) the notification refers to:

  • true: the event (eventCode) the notification refers to was executed successfully.
  • false: the event was not executed successfully.

 

When eventCode returns AUTHORISATION , it does not necessarily mean that the payment authorisation request has been successfully processed.

The authorisation is successful if successtrue.

If success = false, check the  the reason value for further information on the authorisation failure cause.

This can occur, for example, if an error occurs or if the transaction is refused.

Event codes

eventCode holds information about the type of event the notification is informing you about. The following table gives an overview of some of the values this field can take.

Events Description
AUTHORISATION(***) The result of an authorised transaction is returned in this notification.
Modification events
CANCELLATION The result of a cancel modification is returned in this notification.
REFUND The result of a refund modification is returned in this notification.
CANCEL_OR_REFUND The result of a refund or cancel modification is returned in this notification.
CAPTURE The result of a capture modification is returned in this notification.
CAPTURE_FAILED( ** )

Whenever a capture or refund actually failed after it was processed by the third party we return this notification. It basically means that there was a technical issue which needs to be further investigated. Most of the times it is need to be retried to make it work.

This notification comes always after the CAPTURE notification with Success = True.

REFUND_FAILED( ** )

Whenever a capture or refund actually failed after it was processed by the third party we return this notification. It basically means that there was a technical issue which needs to be further investigated. Most of the times it is need to be retried to make it work.

This notification comes always after the REFUND notification with Success = True.

REFUNDED_REVERSED ( * ) When we receive back the funds from the bank we book the transaction to Refunded Reversed. This can happen if the card is closed.

PAIDOUT_REVERSED ( * )

When we receive back the funds because it couldn't be paid to the shopper, we book the transaction to PaidOutReversed.

Dispute events
REQUEST_FOR_INFORMATION(**) Whenever a shopper opens an RFI (Request for Information) case with the bank we will send this notification. You should upload defense material which gives the information to the shopper to understand the charge.
CHARGEBACK( ** ) Whenever the funds are really deducted we send out the chargeback notification. 
CHARGEBACK_REVERSED ( ** )

This is triggered when the funds are returned to your account we send out the chargeback_reversed notification.

NOTIFICATION_OF_CHARGEBACK ( ** ) Whenever a real dispute case is opened this is the first notification in the process which you receive. This is the start point to look into the dispute and upload defense material.
NOTIFICATION_OF_FRAUD( ** ) This notification list the transaction that have been reported as Fraudulent by the schemes. The presence of a transaction in this notification does not have direct financial consequences, nor is action required by the merchant. This is only the case if a chargeback is received (which is eventually sent out separately). Use this notification, for example, to identify fraudulent transactions with a 3D secure liability shift, which are not a (and may not be) chargeback.
Manual review events
MANUAL_REVIEW_ACCEPT( ** ) Notification for acceptance of manual review.
MANUAL_REVIEW_REJECT( ** ) Notification for rejection of manual review.
Recurring events
RECURRING_CONTRACT Notification for creation of a recurring contract.
Payout events
PAYOUT_EXPIRE( ** ) Notification when a payout expires.
PAYOUT_DECLINE( ** ) Notification when a payout is declined.
PAYOUT_THIRDPARTY Notification when a third party payout is processed.
REFUND_WITH_DATA Notification when a refund with data or payout is processed.
Other
AUTHORISE_REFERRAL Notification when a referral is authorised.
EXPIRE( ** ) Notification when a transaction time expires.
FRAUD_ONLY( ** ) Notification for a fraud transaction.
FUND_TRANSFER Notification for a fund transfer from your account to the shopper's account.
HANDLED_EXTERNALLY( ** ) Notification if a payment is handled outside the Adyen system.
OFFER_CLOSED( ** ) Notification when an offer is closed.
ORDER_OPENED(**) Notification when an order is created.
ORDER_CLOSED(**)

This notification is sent in case of partial payments, when all the transactions for the order is complete.

This does not symbolise that the order is successful.

PENDING( ** ) Notification when the transaction is pending.
PROCESS_RETRY(**) Notification when an idempotent request is processed.  
REPORT_AVAILABLE(**) Every time Adyen's system generates a report, we send out the notification which includes the url which can be used to automatically retrieve the notification

( * ) When eventCode = REFUNDED_REVERSED/PAIDOUT_REVERSEDsuccess = false (always).

( ** ) When eventCode = CHARGEBACK_REVERSEDsuccess = true (always).

( *** ) AUTHORISATION does not necessarily reflect a successful authorisation, see success in the Notification fields table to know more.

Accept notifications

Response

Our server expects the following response value, square brackets included:

[accepted]

When our server receives this response to a sent notification message, all notification items in that message are marked as successfully sent.

Our server needs to receive an [accepted] response within 10 seconds, and there should be no interruptions or breaks in the process.
Therefore, we recommend that you handle accepting and replying to notifications separately from processing them, and that you generate an [accepted] response when a notification is stored.

Reply-to URL

In the Adyen Customer Area (CA) you can configure the reply-to URL to send notification responses to, and the necessary authentication details.

You can test your configuration to verify that your server can correctly receive our notifications.

If you receive a notification message that you cannot handle, either because the original transaction is not recognised or because of an unknown  eventCode, you should accept the message and store the item, or at least log it.
If you do not accept the message, the notification process is suspended. To resume it, you need to accept the message.

At-least-once delivery

If the notification delivery fails, or in case it is not possible to determine whether the message was delivered successfully or not, notifications are sent multiple times. This at-least-once delivery rule means  that you may receive the same notification multiple times.

Retries

Whenever a successful response is not explicitly received, notifications are sent multiple times at regular, increasing time intervals:

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

A system message is displayed in the Adyen Customer Area (CA) after the third unsuccessful attempt, i.e. after 2 + 5 + 10 = 17 minutes.
Then, the system continues retrying every 8 hours during the following 7 days.

If you want to trigger a resend attempt, you can send a test notification to yourself:

  • In the Adyen Customer Area (CA), go to Settings | Server Communications.

If the operation is successful, all queued notifications are resent.
Otherwise, you get an overview of the current errors our system has recorded until then.

Disabling notifications

If you disable the notification endpoint, Adyen will store notifications for you until you re-enable the endpoint again. If you re-enable the endpoint, all pending notifications will be sent, including any duplicates that may arise from configuring more than one endpoint.

Duplicate notifications

Due to the structure of the Adyen platform, an authorisation notification may be sent twice.
Duplicate notifications have the same corresponding values for the eventCode and pspReference fields.
If you receive a duplicate notification whose success field is set to true, it overrides and supersedes the previous identical notification.
In all other cases, you do not need to take any action on duplicate notifications.

Notification examples

The following code examples show notification message requests you can receive from Adyen, and the responses you need to send back to us to confirm that you accepted the corresponding notifications. Examples are in JSON, FORM, and SOAP.

Request:

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

                "additionalData" : {
                    "authCode" : "58747",
                    "cardSummary" : "1111",
                    "expiryDate" : "8/2018"
                },
    
                "amount" : {
                    "value" : 500,
                    "currency" : "EUR"
                 },
                 
                "pspReference" : "9313547924770610",
                "eventCode" : "AUTHORISATION",
                "eventDate" : "2018-01-01T01:02:01.111+02:00",
                "merchantAccountCode" : "TestMerchant",
                
                "operations" : [
                    "CANCEL",
                    "CAPTURE",
                    "REFUND"
                ],
                
                "merchantReference" : "YourMerchantReference1",
                "paymentMethod" : "visa",
                "reason" : "58747:1111:12/2012",
                "success" : "true"
            }
        }
    ]
}

Response:

{
	"notificationResponse" : "[accepted]"
}

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">8/2018</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:8/2018</reason> 
            <success>true</success> 
          </NotificationRequestItem> 
      </ns1:Notification>
    </ns1:sendNotification>
  </soap:Body>
</soap:Envelope>

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>

Request:

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

Response:

&5Baccepted%5D

HMAC on Notifications

Hash-based Message Authentication Codes (HMAC) can be used as an extra layer of security for data verification and message authentication for notifications. Using the HMAC, the notification recipient can be certain that the transaction variables have not been altered by a malicious third party.

Furthermore, the identity of the sender can be confirmed through a shared key that only the host (Adyen) and the client (you) have stored.

Buckets for Notification Messages

The notification system is an integral part of the Adyen payment platform. When new features are added, the notifications may change due to additional variables being added to the system. In order to maintain backwards compatibility, the fields in notifications are divided into three buckets.

This bucket holds the variables that define the state of a transaction. The uniqueness of the payment and the state of the transaction as reflected on the shopper statement is determined by the variables in this bucket, the entire bucket is signed as the notification HMAC.

The following variables are signed:

  • pspReference
  • originalReference
  • merchantAccountCode
  • merchantReference
  • amount -> value
  • amount -> currencyCode
  • eventCode
  • success

This bucket holds the variables that characterize the payment in terms of risk, fraud, and conversion. Every notification has different characteristics. These variables are not critical to the payment state and typically used for analysis and categorisation.

The fields in this bucket are not signed as part of the notification HMAC.

  • bin
  • last4digits
  • paymentMethod
  • rawAcquirerResult
  • reason
  • risk result
  • shopperInteraction
  • subvariant
  • live

This bucket holds the remaining notification variables, mostly meta-data variables, and variables provided by the merchant. These variables are not critical to the payment state and/or already known to the merchant.

For this reason, this bucket is excluded from the notification HMAC.

  • additional information (/ custom information)
  • eventDate
  • issuerCountryCode
  • operations
    ** any new, non-critical fields **

Enabling HMAC On Notifications

Adyen provides mutual authentication over SSL in combination with basic authentication by default. This setup is sufficient for most merchants processing on the Adyen payment platform.

Enable HMAC signing of the Adyen notifications for additional security:

  1. Log into the Adyen Customer Area (CA) and navigate to Settings -> Server Communication.
  2. For standard notification, click Edit & Test.
  3. Expand Additional Settings.
  4. Click Generate New HMAC Key, and copy the key to use it for your server configuration.
  5. Click Save Configuration, the newly generated HMAC key is now in effect, and is used to sign all newly generated notifications.

HMAC Calculation

Below JSON, FORM and SOAP messages including the HMAC signature of the notifications. Also a Java example on how to calculate the HMAC signature.

{  
   "live":"false",
   "notificationItems":[  
      {  
         "notificationRequestItem":{  
            "additionalData":{  
               "hmacSignature":"+JWKfq4ynALK+FFzGgHnp1jSMQJMBJeb87dlph24sXw="
            },
            "amount":{  
               "value":1130,
               "currency":"EUR"
            },
            "pspReference":"7914073381342284",
            "eventCode":"AUTHORISATION",
            "eventDate":"2014-08-06T17:15:34.121+02:00",
            "merchantAccountCode":"TestMerchant",
            "operations":[  
               "CANCEL",
               "CAPTURE",
               "REFUND"
            ],
            "merchantReference":"testing 125161ï",
            "paymentMethod":"visa",
            "success":"true"
         }
      }
   ]
}
eventDate=2014-08-06T15%3A14%3A47.71Z&originalReference=0234567891123456&merchantReference=testing 125161ï&additionalData.hmacSignature=kfQO6cj64G9FGICJVozUx8xhp38ktwZJfAuYT%2BSA2Vc%3D&currency=EUR 
&pspReference=1234567890123456&merchantAccountCode=TestMerchant&eventCode=AUTHORISATION&value=1130 
&operations=CANCEL%2CCAPTURE%2CREFUND&success=true&paymentMethod=visa&live=false
<?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: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">hmacSignature</key>
                        <value xsi:type="xsd:string">+JWKfq4ynALK+FFzGgHnp1jSMQJMBJeb87dlph24sXw=</value>
                     </entry>
                  </additionalData>
                  <amount>
                     <currency xmlns="http://common.services.adyen.com">EUR</currency>
                     <value xmlns="http://common.services.adyen.com">1130</value>
                  </amount>
                  <eventCode>AUTHORISATION</eventCode>
                  <eventDate>2014-08-06T17:15:34.121+02:00</eventDate>
                  <merchantAccountCode>TestMerchant</merchantAccountCode>
                  <merchantReference>testing 125161ï</merchantReference>
                  <operations>
                     <string>CANCEL</string>
                     <string>CAPTURE</string>
                     <string>REFUND</string>
                  </operations>
                  <originalReference xsi:nil="true" />
                  <paymentMethod>visa</paymentMethod>
                  <pspReference>7914073381342284</pspReference>
                  <success>true</success>
               </notificationRequestItem>
            </notificationItems>
         </ns1:notification>
      </ns1:sendNotification>
   </soap:Body>
</soap:Envelope>
import static org.junit.Assert.assertTrue;
import java.io.UnsupportedEncodingException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Arrays;
import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.DecoderException;
import org.apache.commons.codec.binary.Base64;
import org.apache.commons.codec.binary.Hex;
import org.junit.Test;

public class NotificationHmacExample {
    private static final char SEPARATOR_CHAR = ':';
    @
    Test
    public void testNotificationHmac() {
        // Example HEX Key (set in customer portal under: 
        // Settings -> Server Communication -> Standard Notification 
        String keyHex = "009E9E92268087AAD241638D3325201AFC8AAE6F3DCD369B6D32E87129FFAB10";
        // hmacSignature can be found in additionalData.get("hmacSignature") 
        final String hmacSignature = "S+5bAYKLd+L2A07Pal0pG/qBarnInaIe709YNzNcHOA=";
        // Example data 
        String pspReference = "7914073251449896";
        String originalReference = "";
        String merchantAccountCode = "TestMerchant";
        String merchantReference = "TestPayment-1407325143704";
        Amount amt = new Amount(8650 L, "EUR");
        String eventCode = "AUTHORISATION";
        boolean success = true;
        StringBuilder payloadToSign = new StringBuilder();
        if (pspReference != null) {
            payloadToSign.append(pspReference);
        }
        payloadToSign.append(SEPARATOR_CHAR);
        if (originalReference != null) {
            payloadToSign.append(originalReference);
        }
        payloadToSign.append(SEPARATOR_CHAR);
        if (merchantAccountCode != null) {
            payloadToSign.append(merchantAccountCode);
        }
        payloadToSign.append(SEPARATOR_CHAR);
        if (merchantReference != null) {
            payloadToSign.append(merchantReference);
        }
        payloadToSign.append(SEPARATOR_CHAR);
        if (amt == null) {
            payloadToSign.append(SEPARATOR_CHAR);
            payloadToSign.append(SEPARATOR_CHAR);
        } else {
            payloadToSign.append(Long.toString(amt.getValue()));
            payloadToSign.append(SEPARATOR_CHAR);
            payloadToSign.append(amt.getCurrency());
            payloadToSign.append(SEPARATOR_CHAR);
        }
        if (eventCode != null) {
            payloadToSign.append(eventCode);
        }
        payloadToSign.append(SEPARATOR_CHAR);
        payloadToSign.append(success ? "true" : "false");
        Base64 base64 = new Base64();
        try {
            // decode HEX Key into bytes 
            byte[] keyBytes = Hex.decodeHex(keyHex.toCharArray());
            // compile the payload to sign 
            String payloadString = payloadToSign.toString();
            // get payload in bytes 
            byte[] payload = payloadString.getBytes("UTF-8");
            // instantiate the MAC object using HMAC / SHA256 
            Mac hmacSha256 = javax.crypto.Mac.getInstance("HmacSHA256");
            // create a key object using the secret key and MAC object 
            SecretKey secretKey = new SecretKeySpec(keyBytes, hmacSha256.getAlgorithm());
            // initialise the MAC object 
            hmacSha256.init(secretKey);
            // finalise the MAC operation 
            byte[] signedPayload = hmacSha256.doFinal(payload);
            // encode the signed payload in Base64 
            byte[] encodedSignedPayload = base64.encode(signedPayload);
            System.out.println("original HMAC signature: " + hmacSignature);
            System.out.println("computed HMAC signature: " + new String(encodedSignedPayload, "ASCII"));
            // assert the calculated Base64 encoded HMAC is equal to the received Base64 encoded HMAC 
            assertTrue(Arrays.equals(encodedSignedPayload, hmacSignature.getBytes("UTF-8")));
        } catch (NoSuchAlgorithmException e) {
            // HmacSHA256 should be supported 
        } catch (DecoderException e) {
            // Check key for odd number or characters outside of HEX (base16) 
        } catch (InvalidKeyException e) {
            // The key is invalid 
        } catch (UnsupportedEncodingException e) {
            // UTF-8 should be supported 
        }
    }
}

HMAC calculation example notification with the following parameters:

Fields Required Value
pspReference (tick) 7914073381342284
originalReference (tick)  
merchantAccountCode (tick) TestMerchant
merchantReference (tick) testing 125161ï
amount.value (tick) 1130
amount.currency (tick) EUR
eventCode (tick) AUTHORISATION
success (tick) true

The HMAC signature payload can be found in the hmacSignature node, which is part of the additionalData element of the notification message. 

When verifying the notification, the signing string is constructed as follows:

pspReference:originalReference:merchantAccountCode:merchantReference:value:currency:eventCode:success

The order of the fields is exactly as described above. If any of the fields is empty, for example the originalReference, the value for this field in the signing string is an empty string. Adyen returns the HMAC signature over the following signing string: 

7914073381342284::TestMerchant:testing 125161ï:1130:EUR:AUTHORISATION:true

Response handling

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP responses

HTTP status code HTTP status message Adyen status message Notes
200 OK Request processed normally

The request message has been successfully processed, and it has produced a response.
The response message varies, depending on the request method and the requested data.

400 Bad Request Problem reading or understanding request

The receiving server cannot understand the request because of malformed syntax.
Do not repeat the request without first modifying it; check the request for errors, fix them, then retry it.

401 Unauthorized Authentication required

You need to input valid authentication credentials (user name/password) to access the resource.

403 Forbidden Insufficient permission to process request You do not have the appropriate user rights to access the request.
Do not repeat the request.
404 Not Found File Not Found It was not possible to retrieve the resource you requested at the specified location.
It may or may not become available again in the future.
Usually, this happens when the URL you pass with the request is incorrect.
You may make subsequent calls.
422 Unprocessable Entity Request validation error The request is formally valid, but semantically incorrect: the receiving server can read it, but it cannot understand it.
500 Internal Server Error Server could not process request The receiving server encountered an unexpected condition that prevents it from fulfilling the request.
Our servers may return a 500 status code also when the request is incorrect, for example because of a missing or not filled in mandatory field.

See also

Handle 200 responses

After receiving an  authorisation request, a payment response with an HTTP status is generated.
An HTTP 200/OK response status code means that the request was submitted correctly, and it was successfully processed by Adyen.

An HTTP 200 response does not automatically mean that the payment or the modification request was successfully executed.

When the payment response includes a resultCode whose value is Refused or Cancelled, a refusalReason field is added.

Check the refusal reason messages to learn more about the possible issues of the payment or the modification request refusal.

For example:

  • You send a capture payment request.
  • The response to your capture request returns HTTP 200/OK. This means:
    • We received your request.
    • We will execute a payment capture.
    • We still do not know if the capture operation will be successful or not.
    • We'll let you know in the corresponding notification message.
  • If the capture operation fails, for example because the acquirer declines to accept the shopper's card, the payable amount for the transaction is not collected.
  • Based on your settings, you'll receive a notification message that includes the notification information about this capture example:
    • The  pspReference in this notification is the same as the  pspReference in the capture modification response.
    • The success field value is false, and the reason field includes a short message to explain the cause of the failure.

 

 

Authorisation refusal reasons

When a HTTP 200/OK  payment response includes a resultCode whose value is Refused or Cancelled, a refusalReason field is added.
The value this field takes is a short text message to inform you about the possible causes of the payment or modification request refusal.

refusalReason values

A payment authorisation refusalReason field can take one of the values below.

You can test a number of these refusal reasons in our test environment.

refusalReason Description

3d-secure: Authentication failed

3D Secure authentication was not executed or it did not execute successfully.
Acquirer Fraud Possible fraud.
Blocked Card The card used for the transaction is blocked, therefore unusable.
Cancelled The transaction was cancelled.
CVC Declined The specified card security code is invalid.
For example, this refusal reason maps, among others, Visa "N7: Decline for CVV2 failure" response.
Refused The transaction was refused.
Declined Non Generic This response maps all those response codes that cannot be reliably mapped.
This makes it easier to tell generic declines (for example, MasterCard "05: Do not honor" response) from more specific ones.
Acquirer Error The transaction did not go through due to an error that occurred on the acquirer's end.
Expired Card The card used for the transaction has expired, therefore it is unusable.
FRAUD Possible fraud.
FRAUD-CANCELLED The risk check flagged the transaction as fraudulent (risk score >= 100); therefore, the operation is cancelled.
Invalid Amount An amount mismatch occurred during the transaction process.
Invalid Card Number The specified card number is incorrect or invalid.
Invalid Pin The specified PIN number is incorrect or invalid.
Issuer Suspected Fraud

Issuer reported transaction as suspected fraud.

Issuer Unavailable It is not possible to contact the shopper’s bank to authorise the transaction.
Not enough balance The card does not have enough money to cover the payable amount.
Not Submitted The transaction was not submitted correctly for processing.
Not supported The shopper's bank does not support or does not allow this type of transaction.
Pending The transaction is in between states, and it is waiting for its current state to be replaced with the new, pending one.
Pin tries exceeded The shopper specified an incorrect PIN number more that three times in a row.
Pin validation not possible It is not possible to validate the specified PIN number.
Referral Referrals.
Restricted Card

Decline codes such as

are mapped to this refusal reason response value.

Revocation Of Auth Decline codes such as
  • "R1: Revocation of Authorization Order”,
  • "R3: Revocation of All Authorizations Order", and
  • "R0: Stop Payment Order"

are mapped to this refusal reason response value.
It indicates that the shopper requested to stop a subscription.

Shopper Cancelled The shopper cancelled the transaction before completing it.
Withdrawal count exceeded The number of withdrawals permitted for the shopper's card have exceeded.
Withdrawal amount exceeded The withdrawal amount permitted for the shopper's card has exceeded.
Transaction Not Permitted

Declined codes such as:

are mapped to this refusal reason response value.

Unknown
It is not possible to clearly assess the root cause of the issue.
Contact the Adyen Support Team to request assistance.

Handle 4xx and 5xx responses

In the following scenarios, the Adyen platform does not accept or store submitted requests:

  • The request does not pass validation.
  • The request violates a security constraint.
  • The request violates a configuration constraint.
  • An internal error occurs on the Adyen system.

In these cases, you receive an error message with a fault code containing a description of the problem.
In general, you should handle it as an exception.

Rejected payment requests accompanied by an error message are not charged.

Error codes (API)

Error codes returned with HTTP 4xx/5xx

This is an overview of the error codes and the corresponding error messages that can be returned when a request to our payment API is not successfully received (HTTP 4xx/5xx), and the call request is not executed as expected. 

Error 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)

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

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

195 Could not find an account with this key: {0}
196 Invalid Mcc
198 Reference may not exceed 79 characters
199 The cryptographic operation could not proceed, no key configured
200 Invalid country code

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

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)

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

Error response fields

When the API request is rejected, the response message contains the following fields.

Name Type Returned by default Description
errorType String (tick)

Returns the type of error that was encountered.

Allowed error types:

  • internal
  • validation
  • security
  • configuration
errorCode String

(tick)

Returns the Adyen code thatt is mapped to the error message.
message String (tick) Returns the message, a short explanation of the issue.
status String (tick) Returns the HTTP response status code.

Error reason mapping

Adyen refusal reason mapping structure.
When a payment is refused, the fields are populated.

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

Error response examples

The following code examples show error/refusal response messages in JSON, FORM, and SOAP.

{
    "errorType" : "security",
    "errorCode" : "901",
    "message" : "Invalid Merchant Account",
    "status" : "403"
}
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Server</faultcode>
      <faultstring>security 901 Invalid Merchant Account</faultstring>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>
HTTP/1.1 403 Forbidden security
901 Invalid Merchant Account

API currency codes

The transaction amount needs to be represented in minor units according to the table below.

Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

Code

Currency

Exponent

AED

UAE Dirham

2

ALL

Albanian Lek

2

AMD

Armenian Dram

2

ANG

Antillian Guilder

2

ARS

Argentine Peso

2

AUD

Australian Dollar

2

AWG

Aruban Guilder

2

AZN

Azerbaijani manat

2

BAM

Bosnia and Herzegovina Convertible Marks

2

BBD

Barbados Dollar

2

BDT

Bangladesh Taka

2

BGL

Bulgaria Lev

2

BGN

New Bulgarian Lev

2

BHD

Bahraini Dinar

3

BMD

Bermudian Dollar

2

BND

Brunei Dollar

2

BOB

Bolivia Boliviano

2

BRL

Brazilian Real

2

BSD

Bahamian Dollar

2

BWP

Botswana Pula

2

BYN

New Belarusian Ruble 2

BZD

Belize Dollar

2

CAD

Canadian Dollar

2

CHF

Swiss Franc

2

CLP

Chilean Peso

2

CNY

Yuan Renminbi

2

COP

Colombian Peso

2

CRC

Costa Rican Colon

2

CSD

Serbian Dinar

2

CVE

Cape Verdi Escudo

0

CZK

Czech Koruna

2

DJF

Djibouti Franc

0

DKK

Danish Krone

2

DOP

Dominican Republic Peso

2

DZD

Algerian Dinar

2

LAK

Laos Kip

2

LBP

Lebanese Pound

2

LKR

Sri Lanka Rupee

2

LTL

Lithuanian Litas

2

LVL

Latvian Lats

2

LYD

Libyan Dinar

3

MAD

Moroccan Dirham

2

MDL

Moldovia Leu

2

MNT

Mongolia Tugrik

2

MOP

Macau Pataca

2

MRO

Mauritania Ouguiya

1

MUR

Mauritius Rupee

2

MVR

Maldives Rufiyaa

2

MWK

Malawi Kwacha

2

MXN

Mexican Peso

2

MXP

Mexican Peso

2

MYR

Malaysian Ringgit

2

NAD

Namibian Dollar

2

NGN

Nigerian Naira

2

NIO

Nicaragua Cordoba Oro

2

NOK

Norwegian Krone

2

NPR

Nepalese Rupee

2

NZD

New Zealand Dollar

2

OMR

Rial Omani

3

PAB

Panamanian Balboa

2

PEN

Peruvian Nuevo Sol

2

PGK

New Guinea Kina

2

PHP

Philippine Peso

2

PKR

Pakistan Rupee

2

PLN

New Polish Zloty

2

PYG

Paraguay Guarani

0

QAR

Qatari Rial

2

ROL

Romanian Lei

2

RON

New Romanian Lei

2

RSD

Serbian Dinar

2

RUB

Russian Ruble

2

EEK

Estonian Krone

2

EGP

Egyptian Pound

2

ETB

Ethiopian Birr

2

EUR

Euro

2

FJD

Fiji Dollar

2

FKP

Falkland Islands Pound

2

GBP

Pound Sterling

2

GEL

Georgian Lari

2

GHC

Ghanaian Cedi (2nd)

0

GHS

Ghanaian Cedi (3rd)

2

GIP

Gibraltar Pound

2

GMD

Gambia Delasi

2

GNF

Guinea Franc

0

GTQ

Guatemala Quetzal

2

GYD

Guyanese Dollar

2

HKD

Hong Kong Dollar

2

HNL

Honduras Lempira

2

HRK

Croatia Kuna

2

HTG

Haitian Gourde

2

HUF

Hungarian Forint

2

IDR

Indonesian Rupiah

0

ILS

New Israeli Scheqel

2

INR

Indian Rupee

2

ISK

Iceland Krona

2

JMD

Jamaican Dollar

2

JOD

Jordanian Dinar

3

JPY

Japanese Yen

0

KES

Kenyan Shilling

2

KGS

Kyrgyzstan Som

2

KHR

Cambodia Riel

2

KMF

Comoro Franc

0

KRW

South-Korean Won

0

KWD

Kuwaiti Dinar

3

KYD

Cayman Islands Dollar

2

KZT

Kazakhstani Tenge

2

RWF

Rwanda Franc

0

SAR

Saudi Riyal

2

SBD

Solomon Island Dollar

2

SCR

Seychelles Rupee

2

SEK

Swedish Krone

2

SGD

Singapore Dollar

2

SHP

St. Helena Pound

2

SKK

Slovak Koruna

2

SLL

Sierra Leone

2

SOS

Somalia Shilling

2

STD

Sao Tome & Principe Dobra

2

SVC

El Salvador Colón

2

SZL

Swaziland Lilangeni

2

THB

Thai Baht

2

TND

Tunisian Dinar

3

TOP

Tonga Pa'anga

2

TRY

New Turkish Lira

2

TTD

Trinidad & Tobago Dollar

2

TWD

New Taiwan Dollar

2

TZS

Tanzanian Shilling

2

UAH

Ukraine Hryvnia

2

UGX

Uganda Shilling

0

USD

US Dollars

2

UYU

Peso Uruguayo

2

UZS

Uzbekistani Som

2

VEF

Venezuelan Bolívar

2

VND

Vietnamese New Dong

0

VUV

Vanuatu Vatu

0

WST

Samoan Tala

2

XAF

CFA Franc BEAC

0

XCD

East Carribean Dollar

2

XOF

CFA Franc BCEAO

0

XPF

CFP Franc

0

YER

Yemeni Rial

2

ZAR

South African Rand

2

ZMW

Zambia Kwacha

2