Test Cards Manual

Adyen provides generic test card numbers but you can also generate your own.

The ability to generate test payment cards on an ad-hoc basis is useful during QA. On the Adyen test platform, you can use the generated test payment cards and request/response messages to simulate real-life traffic scenarios, and to verify the correct integration of your systems with Adyen's platform and services.

Test cards are dummy payment cards; they work only in the Adyen test environment. Transactions carried out with these test cards do not result in actual credits/debits to live (bank) accounts.

The Adyen test environment and the test payment cards allow you to simulate different payment scenarios, according to your needs. For example, you can verify that the system under test correctly performs the necessary payment card checks, identifies valid and invalid transaction requests, handles increasing traffic as expected, and so on.

The Adyen Test Card Management Service generates dummy payment card number ranges. You define a test card range by specifying a starting and an ending dummy payment card number. The service does not generate one dummy card number at a time; it outputs multiple test card numbers within the defined range limits.

To successfully pass QA tests, the generated test card numbers need to behave like actual payment card numbers. While test card numbers in a generated range are not checked for Luhn compliance, the first six digits of the test card numbers in any generated range need to be valid BIN numbers.

The same concept applies to the dummy card holder address details: to pass tests that simulate real-life scenarios, the test card address details need to be AVS compliant.

Benefits

  • Scalable: You can generate large quantities of test cards as needed to test system load and to simulate real-life traffic volumes.
  • Non-disruptive: You can generate test cards and use them without changing configuration or settings in the system under test.
  • Test card generation makes it easier to carry out automated integration and regression testing with large traffic volumes.

Core Features

  • Test payment card number ranges are generated as needed.
  • To make testing easier and faster, the generated test card numbers do not need to be Luhn compliant.

Prerequisites

To create a range of test cards, you need to satisfy the following prerequisites:

  • You need a valid merchant account (account key) to initiate a payment with a test card in the Adyen test environment.
  • You need a valid web service account to generate a test card range to use in the Adyen test environment.
  • The merchant account and the web service account used to generate the test cards need to have the Manage test cards role. Contact the Adyen Support Team (support@adyen.com) to request enabling it.

Requirements

Generated test cards need to meet the following requirements:

  • Test card numbers need to be min. 6 digits and max. 19 digits long.
  • All test card numbers in a generated test card range need to have the same amount of digits, i.e. they need to have the same length.
  • The first six digits of the test card numbers in any generated range need to be valid BIN numbers.
  • Test card numbers need to comply with standard payment card number constraints. For example, to test a system with Visa test cards, you need to create a test card range with a valid Visa BIN.
  • Although the created test card start and end range numbers are not checked for Luhn compliance, if you carry out a (test) payment the test card is handled like a standard payment card, and it undergoes the standard card checks that take place in live environments, including Luhn verification. Therefore, when you perform a (test) payment with a test card, its number is checked for Luhn validity.
  • The billing address details you define for a test card range need to be AVS (Address Verification Service) compliant, i.e. you always need to include at least the street address. Zip code is optional.
  • The billing address check verifies only the numeric characters in the street address and Zip code (if available) fields.

Audience

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

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.

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

Test Cards last update

Version

Date

Changes

4.0.1 2015-11-12

Added information about Test card GUI.

Version

Date

Changes

4.0.1 2015-11-12

Added information about Test card GUI.

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

1.0.3

2015-04-07

Added: Appendix B; additional details about AVS and Luhn compliance

1.0.2

2015-02-18

QA review

1.0.1

2015-02-12

Peer-reviewed, SME-reviewed

1.0

2015-02-05

First draft of the manual


Test Card API Endpoint

Overview of the test URLs to communicate using JSONFORM or SOAP.

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

This is an overview of the test URL endpoints to communicate with our Test card using the SOAP messaging protocol. Use them to test your implementation and run QA checks.

Creating a test card range

To generate a range of test card numbers, you use the Adyen Test Card Management Service, TestCardService, which runs on the Adyen payment API.
TestCardService has one method:

createTestCardRangesThis method sends a request containing the information required to create a test card range. Returns: a list with the generated test card numbers.Error handling: If the operation does not complete successfully, a service exception is thrown. For further details, see Error: Reference source not found.

Request:

 

Fields Type Required Description
accountCode String (tick) The merchant account details used to log in and access the account.
accountTypeCode String (tick)

The type of account used to make the call.

Possible values:

  • Company
  • MerchantAccount

These values are case sensitive.

testCardRanges Array (tick) Contains one or more test card range objects.
TestCardRange Object (tick) Defines the properties of a test card range.
rangeStart String (tick)

 The first test card number in the test card range:

  • Min 6, max 19 digits
  • BIN compliant
  • Ex.: 5432 1234 1234 1234
 rangeEnd  String (tick)

The last test card number in the test card range: 

  • Min 6, max 19 digits
  • BIN compliant
  • Ex.: 5432 1234 1234 4321
 ExpiryDate  String (tick)

Expiry date on the card. Contains the below values:

  • expiryMonth
  • expiryYear
 expiryMonth  String (tick) Expiry month for the test card range. Allowed values: JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER
 expiryYear  String  (tick) Expiry year for the test card range. Ex.: 2020
 cvc  String (tick) The test card range security code. Ex.: 123
 cardHolderName  String (tick) The name of the card holder, as it appears on the card, for the test card range. Ex.: S Hopper
 address Object  (tick) Contains the billing address of the card holder. The address details need to be AVS (Address Verification Service) compliant, i.e. you need to define at least streetAddress.
 streetAddress  String (tick) Billing address of the card holder.Ex.: 1 Infinite Loop, Cupertino
 zip  String (error) Optional. Zip code associated to the billing address of the card holder. Ex.: CA 95014
threeDUserName String (error) Optional. 3D Secure user name details of the card holder. Ex.: simonhopper
threeDPassword String (error) Optional. 3D Secure password details of the card holder. Ex.: myPa$$w0rd
threeDDirectoryServerResponse String (error) Optional. 3D Secure server response. It notifies whether the specified card holder is enrolled in a 3D Secure service. Possible values:- Y (Authentication available)- N (Card holder not enrolled/not participating) - U (Unable to authenticate)

Response:

 

Fields Type Returned by default Description
rangeCreationResults Object (tick) Returned by defaultContains one or more test card range result outputs.
TestCardRangeCreationResult Object (tick)

Returned by default Contains:

  • Start and end values for the generated test card range;
  • A notification message (optional: only when an error occurs).
 cardNumberRangeStart  String (tick) Returned by default. The first test card number in the generated test card range. Ex.: 5432 1234 1234 1234
 cardNumberRangeEnd  String (tick) Returned by default. The last test card number in the generated test card range. Ex.: 5432 1234 1234 4321
 creationResultCode  String (tick) Returned by default. Notification message. It informs about the outcome of the operation. Possible values:- CREATED- ALREADY_EXISTS - ERROR

Code examples

Call createTestCardRanges to generate one or more ranges of test cards.

Request:
{
   "accountCode":"TestMerchant",
   "accountTypeCode":"MerchantAccount",
   "testCardRanges":[
      {
         "TestCardRange":{
            "rangeStart":"5232492669190772",
            "rangeEnd":"5232492670020681",
            "expiryMonth":"JANUARY",
            "expiryYear":2020,
            "cvc":"123",
            "cardHolderName":"S Hopper",
            "address":{
               "streetAddress":"1 Infinite Loop, Cupertino",
               "zip":"CA 95014"
            },
            "threeDUsername":"simonhopper",
            "threeDPassword":"mypa$$word",
            "threeDDirectoryServerResponse":"Y"
         }
      },
      {
         "TestCardRange":{
            "rangeStart":"4596123423450871",
            "rangeEnd":"4596123434560780",
            "expiryMonth":"MARCH",
            "expiryYear":2021,
            "cvc":"321",
            "cardHolderName":"T Anderson",
            "address":{
               "streetAddress":"42, End of the Universe Rd., Los Alamos",
               "zip":"NM 87544"
            },
            "threeDUsername":"thomasanderson",
            "threeDPassword":"IamN3o",
            "threeDDirectoryServerResponse":"Y"
         }
      }
   ]
}

Response:

{  
   "rangeCreationResults":[  
      {  
         "TestCardRangeCreationResult":{  
            "cardNumberRangeStart":"5232492669190772",
            "cardNumberRangeEnd":"5232492670020681",
            "creationResultCode":"ALREADY_EXISTS"
         }
      },
      {  
         "TestCardRangeCreationResult":{  
            "cardNumberRangeStart":"4596123423450871",
            "cardNumberRangeEnd":"4596123434560780",
            "creationResultCode":"ALREADY_EXISTS"
         }
      }
   ]
}
 

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>
      <createTestCardRanges xmlns="http://testcard.services.adyen.com">
         <request>
            <accountCode>TestMerchant</accountCode>
            <accountTypeCode>MerchantAccount</accountTypeCode>
            <testCardRanges>
               <TestCardRange>
                  <rangeStart>5232492670020681</rangeStart>
                  <rangeEnd>5232492669190772</rangeEnd>
                  <expiryMonth>JANUARY</expiryMonth>
                  <expiryYear>2020</expiryYear>
                  <cvc>123</cvc>
                  <cardHolderName>S Hopper</cardHolderName>
                  <address>
                     <streetAddress>1 Infinite Loop, Cupertino</streetAddress>
                     <zip>CA 95014</zip>
                  </address>
                  <threeDUsername>simonhopper</threeDUsername>
                  <threeDPassword>mypa$$word</threeDPassword>
                  <threeDDirectoryServerResponse>Y</threeDDirectoryServerResponse>
               </TestCardRange>
               <TestCardRange>
                  <rangeStart>4596123434560780</rangeStart>
                  <rangeEnd>4596123423450871</rangeEnd>
                  <expiryMonth>MARCH</expiryMonth>
                  <expiryYear>2021</expiryYear>
                  <cvc>321</cvc>
                  <address>
                     <streetAddress>42, End of the Universe Rd., Los Alamos</streetAddress>
                     <zip>NM 87544</zip>
                  </address>
                  <cardHolderName>T Anderson</cardHolderName>
                  <threeDUsername>thomasanderson</threeDUsername>
                  <threeDPassword>IamN3o</threeDPassword>
                  <threeDDirectoryServerResponse>Y</threeDDirectoryServerResponse>
               </TestCardRange>
            </testCardRanges>
         </request>
      </createTestCardRanges>
   </soap:Body>
</soap:Envelope>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns0="http://testcard.services.adyen.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Body>
      <ns0:createTestCardsResponse>
         <ns0:result>
            <ns0:rangeCreationResults>
               <ns0:TestCardRangeCreationResult>
                  <ns0:cardNumberRangeEnd>5232492669190772</ns0:cardNumberRangeEnd>
                  <ns0:cardNumberRangeStart>5232492670020681</ns0:cardNumberRangeStart>
                  <ns0:creationResultCode>ALREADY_EXISTS</ns0:creationResultCode>
               </ns0:TestCardRangeCreationResult>
               <ns0:TestCardRangeCreationResult>
                  <ns0:cardNumberRangeEnd>4596123423450871</ns0:cardNumberRangeEnd>
                  <ns0:cardNumberRangeStart>4596123434560780</ns0:cardNumberRangeStart>
                  <ns0:creationResultCode>ALREADY_EXISTS</ns0:creationResultCode>
               </ns0:TestCardRangeCreationResult>
            </ns0:rangeCreationResults>
         </ns0:result>
      </ns0:createTestCardsResponse>
   </soap:Body>
</soap:Envelope>

Error Handling

After submitting a call, you receive a confirmation that the message was received, and if it was correctly processed. The API returns HTTP status codes and the response message.

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

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

Handling 200 responses

A 200 HTTP status code response means that the request was submitted correctly and it was processed successfully by Adyen. However, it does not necessarily mean that the test card range generation completed correctly. The creationResultCode field is part of the response message, which can have one of the following values:

creationResultCode

Description

CREATED

The test card range was created successfully

ALREADY_EXISTS

The test card range you are trying to create already exists. You need to define different start and end test card numbers for the new range.

ERROR

The test card range creation failed.

Handling 4xx and 5xx responses

In the following situations the Adyen platform does not accept or store a submitted request in the following cases:

  • The request does not pass validation.
  • The request violates a security constraint.
  • The request violates a configuration constraint.
  • An internal error occurs in the Adyen system.

More specifically, test card generation fails in the following cases:

  • The range start test card number is larger than the end one.
  • The range start and the end test card numbers have different lengths, i.e. they do not have the same amount of digits.
  • The test card numbers are shorter than 6 digits or longer than 19 digits.
  • The test card numbers do not observe BIN code and AVS constraints (see Requirements).
  • If you use a generated test card number to carry out an actual payment, the test card number needs to be Luhn compliant because this check is part of standard behaviour in a live environment.

A Luhn compliance error is returned as a 101 Invalid card number fault code.
When this happens, you receive a fault response with a description of the problem. In general, your toolkit handles this situation as an exception. Payment requests that are rejected with an error message are not charged.
If the request is rejected, the response contains the following fields:

 Error codes and responses

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

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.

Adyen refusal reason mapping structure.
When a payment is refused, the fields are populated.

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

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

For explanations of the possible causes of the errors and suggestions to fix them, see Prerequisites and Requirements.

AVS Response Messages

Response Code

Response Message

7 (MATCHED)

Both postal code and address match.

1 (ADDRESS_MATCH_ZIP_NOT)

Address matches, but the postal code does not match.

6 (ZIP_MATCH_ADDRESS_NOT)

Postal code matches, but the address does not match.

2 (NOT_MATCHED)

Both Postal code and address do not match.

Service Exceptions

Exception

Error Message

Invalid test card range

The length of the start of the card range needs to be between 6 and 19 digits long but was {specified_start_range_length_value}.

Invalid test card range

The length of the end of the card range needs to be between 6 and 19 digits long but was {specified_end_range_length_value}.

Invalid test card range

The length of the start of the card range ({specified_start_range_length_value}) needs to match the length of the end of the card range ({specified_end_range_length_value}).

Invalid test card range

The specified range start value {specified_start_value} does not represent a valid number.

Invalid test card range

The specified range end value {specified_end_value} does not represent a valid number.

Invalid test card number

The specified card {specified_test_card_number} number is invalid.

Fault Codes

Error Code

Error Message

000

Unknown

010

Not allowed

101

Invalid card number

901

Invalid Merchant Account

903

Internal error

Test cards GUI

Adyen offers an easy and simple way to add test cards:

  • Log into the Adyen Customer Area (CA) and go to Settings -> Test Cards.
  • Click Add New Range.
  • Enter the necessary details in the Test Card Range form.
  • Click Save.

See creating a test card range for the description of the fields.

This feature is not available for every merchant. Contact Adyen Support Team to request the rights to use it.