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 and then retry the request.

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 Adyen processed it successfully.

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

If the HTTP 200/OK payment response includes a resultCode with the value Refused or Cancelled, a refusalReason field is added. This short message informs you why the payment or modification was refused.

The refusalReason field will provide one of the values below. You can test a number of these refusal reasons in our test environment.

We have specified which payments with refused reasons can be retried. Contact Support Team to know more.

refusalReason Description Retry

3d-secure: Authentication failed

3D Secure authentication was not executed, or it did not execute successfully. Yes
Acquirer Fraud Possible fraud. No
Blocked Card The card used for the transaction is blocked, therefore unusable. No
Cancelled The transaction was cancelled. Yes
CVC Declined The specified card security code is invalid.
For example, this refusal reason maps, among others, Visa "N7: Decline for CVV2 failure" response.
Yes
Refused The transaction was refused. Yes
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.
Yes
Acquirer Error The transaction did not go through due to an error that occurred on the acquirer's end. Yes
Expired Card The card used for the transaction has expired. Therefore it is unusable. Yes
FRAUD Possible fraud. No
FRAUD-CANCELLED The risk check flagged the transaction as fraudulent (risk score >= 100); therefore, the operation is cancelled. No
Invalid Amount An amount mismatch occurred during the transaction process. No
Invalid Card Number The specified card number is incorrect or invalid. No
Invalid Pin The specified PIN number is incorrect or invalid. No
Issuer Suspected Fraud

Issuer reported the transaction as suspected fraud.

Yes
Issuer Unavailable It is not possible to contact the shopper’s bank to authorise the transaction. Yes
Not enough balance The card does not have enough money to cover the payable amount. Yes
Not Submitted The transaction was not submitted correctly for processing. Yes
Not supported The shopper's bank does not support or does not allow this type of transaction. Yes
Pending The transaction is in between states, and it is waiting for its current state to be replaced with the new, pending one. No
Pin tries exceeded The shopper specified an incorrect PIN number more that three times in a row. Yes
Pin validation not possible It is not possible to validate the specified PIN number. No
Referral Referrals. No
Restricted Card

Decline codes such as

are mapped to this refusal reason response value.

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

No
Shopper Cancelled The shopper cancelled the transaction before completing it. Yes
Withdrawal count exceeded The number of withdrawals permitted for the shopper's card has exceeded. Yes
Withdrawal amount exceeded The withdrawal amount permitted for the shopper's card has exceeded. Yes
Transaction Not Permitted

Declined codes such as:

are mapped to this refusal reason response value.

Yes
Unknown

It is not possible to clearly assess the cause of the issue. Contact Support Team to request assistance.

No

Handle 4xx and 5xx responses

In the following scenarios, the Adyen payments 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 payments platform.

In these cases, you receive an error message with an error code containing a description of the problem.
In general, you should handle it as an exception.

There is no charge for rejected payment requests accompanied by an error message.

Error response parameters

In the case of rejected API requests, the response message contains the following fields: ServiceException.

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

Response mapping

Adyen refusal reason mapping structure.
In the case of refused payments, these fields are populated.

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

Error codes types

Depending on your integration type, there are a number of error codes you can receive. All integrations can receive Generic error codes.

Additional error codes apply for:

If you are unsure how to interpret a specific error, contact the Support Team.

Generic error codes

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
205 Missing or invalid networkTxReference

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

704 Request already processed

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

Invalid or empty request data

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

912 The TX Variant does not support the redemption type.

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

Checkout error codes

Error code Error message
14_002 Missing payment data
14_003 Invalid payment data
14_004 Missing payment method details
14_005 Invalid payment method details
14_006 Missing payment method data
14_007 Invalid payment method data
14_008 Session has expired
14_010 The request contains no sdkVersion although the channel is set to Web
14_011 The provided channel is conflicting the provided parameters. Please provide correct token for iOS or Android, or sdkVersion for Web. Do not provide both of them.
14_012 The provided SDK token could not be parsed
14_013 For HTML Response; origin has to be provided
14_014 This end point requires the version to be specified
14_015 Token is missing
14_016 Invalid sdkVersion provided
14_017 The provided SDK Token has an invalid timestamp
14_018 Invalid payload provided
14_019 The request does not contain sdkVersion or token
14_020 No issuer selected
14_021 Unknown terminal
14_022 Missing uniqueTerminalId
14_023 Installments were not configured in setup request
14_024 Invalid open invoice request
14_025 Card holder name is required by configuration, but missing in payment details
14_026 The selected flow is invalid
14_027 The provided returnUrlQueryString is invalid
14_028 3D Auth Data is incomplete. Please provide both PaRes and MD.