Skip to main content

Adyen Classic

Overview​

Gateway Website: https://www.adyen.com/
Developer Documentation: https://docs.adyen.com/api-explorer/#/Payment/v51/overview
Default Currency: USD

Request Objects: BillingAddress, ShippingAddress, CreditCard, Check, OrderInfo , SoftDescriptors, StoredCredentials, ThreeDSecure

Gateway Endpoints
This implementation of Adyen forwards requests to the below endpoints.

warning

Production requests must include the livePrefix field (detailed in parameters). TokenEx uses this field to forward requests to the appropriate endpoints. This field is not necessary for the Test environment.

ActionProd EndpointTest Endpoint
Card Authorize, Card Purchase, Check Purchasehttps://random-companyName-pal-live.adyen.com/pal/servlet/Payment/v51/authorisehttps://pal-test.adyen.com/pal/servlet/Payment/v51/authorise
Card Capturehttps://random-companyName-pal-live.adyen.com/pal/servlet/Payment/v51/capturehttps://pal-test.adyen.com/pal/servlet/Payment/v51/capture
Card Refund, Check Refundhttps://random-companyName-pal-live.adyen.com/pal/servlet/Payment/v51/refundhttps://pal-test.adyen.com/pal/servlet/Payment/v51/refund
Card Void, Check Voidhttps://random-companyName-pal-live.adyen.com/pal/servlet/Payment/v51/cancelhttps://pal-test.adyen.com/pal/servlet/Payment/v51/cancel

Supported Request Parameters:​

* denotes a required field
Field NameTypeAdyen MappingNotes
gatewaystringN/AAdyen
userName*stringUserNameYour Adyen User Name
Not required if "PrivateKey" is provided
password*stringPasswordYour Adyen Password
Not required if "PrivateKey" is provided
privateKey*stringApiKeyx-ApiKey from Adyen Portal
Not required if "UserName" & "Password" is provided
merchantAccount*stringPaymentRequest.​MerchantAccountThe merchant account identifier, with which you want to process the transaction.
livePrefixstringN/AThis integration is built on the Adyen Classic Payments v51 API. Use this field to pass the merchant-specific live endpoint prefix. https://docs.adyen.com/development-resources/live-endpoints#classic-payments-endpoints Required for Production
reference*stringPaymentRequest.​ReferenceThe reference to uniquely identify a payment. If you need to provide multiple references for a transaction, separate them with hyphens ("-"). Maximum length: 80 characters.
captureDelayHoursstringPaymentRequest.​CaptureDelayHoursThe delay between the authorisation and scheduled auto-capture, specified in hours. *Numbers only
idempotencyKeystringPaymentRequest.​IdempotencyKeyThe Adyen API supports idempotency, allowing you to retry a request multiple times while only performing the action once. https://docs.adyen.com/development-resources/api-idempotency
amountnumericPaymentRequest.​Amount.​ValueThe amount in minor units.
currencyCodestringPaymentRequest.​Amount.​CurrencyThe three-character ISO currency code. Alpha-3 ISO currency code

Use the ISO 4217 three-letter alphabetic code for the currency.
creditCard.​FirstName
CreditCard.​LastName		stringPaymentRequest.​Card.​HolderNameThe name of the cardholder, as printed on the card.
CreditCard.​FullNamestringPaymentRequest.​Card.​HolderNameThe name of the cardholder, as printed on the card.
creditCard.​NumberstringPaymentRequest.​Card.​NumberCard number or TokenEx Token - TokenEx will replace the Token with the Detokenized number
creditCard.​StartMonthnumericPaymentRequest.​Card.​StartMonthThe month component of the start date (for some UK debit cards only). Format: 2 digits, zero-padded for single digits. Example: 03 = March, 11 = November
creditCard.​ExpMonthnumericPaymentRequest.​Card.​ExpiryMonthThe customer’s credit card expiration month. Format: 2 digits, zero-padded for single digits. Example: 03 = March, 11 = November
creditCard.​StartYearnumericPaymentRequest.​Card.​StartYearThe year component of the start date (for some UK debit cards only). Format: 4 digits. For example: 2020
creditCard.​ExpYearnumericPaymentRequest.​Card.​ExpiryYearThe customer’s credit card expiration year. Format: 4 digits. For example: 2020
creditCard.​CvvstringPaymentRequest.​Card.​CvcThe card verification code (1-20 characters)

Please refer to Tokenization, Detokenization and CVV Retrieval.

Depending on the card brand, it is known also as: CVV2/CVC2 – length: 3 digits, CID – length: 4 digits
creditCard.​BrandstringPaymentRequest.​Card.​BrandOptional Parameter. If not passed, will match pattern with the following cards and assign value.
creditCard.​IssueNumberstringPaymentRequest.​Card.​IssueNumberThe issue number of the card (for some UK debit cards only).
check.​FirstName

Check.​LastName		stringPaymentRequest.​BankAccount.​OwnerNameThe name of the bank account holder.
Check.​FullNamestringPaymentRequest.​BankAccount.​OwnerNameThe name of the bank account holder.
check.​BankCountryCodestringPaymentRequest.​BankAccount.​CountryCodeCountry code where the bank is located. A valid value is an ISO two-character country code (e.g. 'NL').
check.​AccountNumberstringPaymentRequest.​BankAccount.​BankAccountNumberThe bank account number (without separators) or TokenEx Token - Tokenex will replace the Token with the Detokenized number
check.​RoutingNumberstringPaymentRequest.​BankAccount.​BankLocationIdThe location id of the bank.
check.​BankNamestringPaymentRequest.​BankAccount.​BankNameThe name of the bank.
check.​BankAccountHolderTaxIdstringPaymentRequest.​BankAccount.​TaxIdThe bank account holder's tax ID.
check.​BankCitystringPaymentRequest.​BankAccount.​BankCityThe bank city.
orderInfo.​CustomerIdstringPaymentRequest.​AdditionalData.​enhancedSchemeData.​customerReferenceCustomer code, if supplied by a customer. Required for Level 2 data.
tax.​AmountnumericPaymentRequest.​AdditionalData.​enhancedSchemeData.​totalTaxAmountTotal tax amount, in minor units. For example, 2000 means USD 20.00. Max length: 12 characters. Required for Level 2 data.
tax.​DestinationPostalCodestringPaymentRequest.​AdditionalData.​enhancedSchemeData.​destinationPostalCodeThe postal code of a destination address. Max length: 10 characters. Required for American Express.
billingAddress.​Address1stringPaymentRequest.​BillingAddress.​HouseNumberOrNameThe number or name of the house. Maximum length: 3000 characters.
billingAddress.​Address2stringPaymentRequest.​BillingAddress.​StreetThe name of the street. Maximum length: 3000 characters. The house number should not be included in this field.
billingAddress.​CitystringPaymentRequest.​BillingAddress.​CityThe name of the city. Maximum length: 3000 characters.
billingAddress.​StatestringPaymentRequest.​BillingAddress.​StateOrProvinceState or province codes as defined in ISO 3166-2. For example, CA in the US or ON in Canada.
billingAddress.​ZipstringPaymentRequest.​BillingAddress.​PostalCodeA maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
billingAddress.​CountrystringPaymentRequest.​BillingAddress.​CountryThree-Character Country Code ISO country code.
if provided, We convert this value to two-character country code.
In case if it's unavailable, please pass it as blank value and we forward it as "ZZ" as Adyen docs suggested.
billingAddress.​EmailstringPaymentRequest.​ShopperEmailThe shopper's email address.
shippingAddress.​Address1stringPaymentRequest.​DeliveryAddress.​HouseNumberOrNameThe number or name of the house. Maximum length: 3000 characters.
shippingAddress.​Address2stringPaymentRequest.​DeliveryAddress.​StreetThe name of the street. Maximum length: 3000 characters. The house number should not be included in this field.
shippingAddress.​CitystringPaymentRequest.​DeliveryAddress.​CityThe name of the city. Maximum length: 3000 characters.
shippingAddress.​StatestringPaymentRequest.​DeliveryAddress.​StateOrProvinceState or province codes as defined in ISO 3166-2. For example, CA in the US or ON in Canada.
shippingAddress.​ZipstringPaymentRequest.​DeliveryAddress.​PostalCodeA maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
shippingAddress.​CountrystringPaymentRequest.​DeliveryAddress.​CountryThree-Character Country Code ISO country code.
if provided, We convert this value to two-character country code.
In case if it's unavailable, please pass it as blank value and we forward it as "ZZ" as Adyen docs suggested.
threeDSecure.​CAVVstringmpiData.​cavvThe cardholder authentication value
threeDSecure.​AuthenticationResponsestring(1)mpidata.​authenticationResponseThis is the transStatus from the challenge result. If the transaction was frictionless, omit this parameter.
threeDSecure.​DirectoryResponsestring(1)mpiData.​directoryResponseThis is the transStatus from the ARes.
threeDSecure.​ECIstringmpiData.​eciThe electronic commerce indicator.
threeDSecure.​DSTransIdstringmpiData.​dsTransIDThe unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.
threeDSecure.​ThreeDSecureVersionstringmpiData.​threeDSVersionThe version of the EMV 3D Secure protocol.

For backwards compatibility, these values will be mapped to the following 3DS versions:
1 = 3DS 2.1.0
2 = 3DS 2.2.0
storedCredentials.​Initiatorstringunmapped
storedCredentials.​CredentialStoredbooleanshopperInteractionSee usage in The Basics - Stored Credentials. True = "ContAuth", False = "Ecommerce".
storedCredentials.​PreviousNetworkTransactionIdstringnetworkTxReference See usage in The Basics - Stored Credentials. Value obtained from Adyen response field additionalData.networkTxReference. This response field must be turned on from the Adyen portal -> Developers -> Additional Data -> Acquirer Section -> select Network Transaction Reference. Save configuration.
storedCredentials.​TransactionTypestringrecurringProcessingModelValid values:
"recurring" = "Subscription",
"installment" = "Subscription",
"unscheduled" = "UnscheduledCardOnFile".
any other string value that can be parsed into "Subscription", "CardOnFile", or "UnscheduledCardOnFile" will be forwarded. If the value cannot be parsed and does not match the valid values above, an error will be thrown.
softDescriptors.​pspReferencestringshopperStatementThe reference number that is tied to a request/transaction that will show on the shopper's bank statement. See ShopperStatement callout below.
softDescriptors.​merchantPhonestringshopperStatementThe merchant phone number that will show on the shopper's bank statement. See ShopperStatement callout below.
softDescriptors.​merchantUrlstringshopperStatementThe merchant URL that will show up on the shopper's bank statement. See ShopperStatement callout below.
softDescriptors.​supportPhoneNumberstringshopperStatementThe merchant phone number for support that will show up on the shopper's bank statement. See ShopperStatement callout below.
softDescriptors.​shopperStatementstringshopperStatementIf present, this value will override the shopper statement generated by the other soft descriptor fields and will be sent to Adyen. See ShopperStatement callout below.
Soft Descriptors - ShopperStatement Construction

The following fields are utilized when generating a value for ShopperStatement: Reference, SoftDescriptors.PspReference, SoftDescriptors.MerchantPhone, SoftDescriptors.MerchantUrl, and SoftDescriptors.SupportPhoneNumber. When a one or more of the fields are assigned, their key-value-pairs are concatenated and assigned to ShopperStatement. Example output: pspReference: b56dq6ejkhkyq0to phoneNumber: 555-555-5555 merchantUrl: https://www.merchant.com supportPhoneNumber: 555-555-5555

To bypass the formatting above, send a value in SoftDescriptors.ShopperStatement.
The value Adyen receives from ShopperStatement is visible within the Adyen merchant portal's description of that transaction's Shopper Details.

Example Requests​

{
  "merchantId": "<Your merchant account identifier>",
  "username": "<Your Adyen User Name>",
  "password": "<Your Adyen Password>",
  "testMode": true,
  "currencyCode": "USD",
  "gateway": "Adyen",
  "idempotencyKey": "<Your Idempotency Key>",
  "amount": 120,
  "captureDelayHours": 0,
  "shippingAddress": {
    "address1": "123",
    "address2": " Someplace Lane",
    "city": "Tulsa",
    "state": "OK",
    "zip": "74111",
    "country": "USA"
  },
  "creditCard": {
    "brand": "Visa",
    "number": "4000000000000002",
    "startMonth": 1,
    "expMonth": 6,
    "startYear": 2020,
    "expYear": 2024,
    "firstName": "John",
    "lastName": "Doe",
    "cvv": "123",
    "issueNumber": "<Card Issuer Number>"
  },
  "billingAddress": {
    "address1": "123",
    "address2": " Someplace Lane",
    "city": "Tulsa",
    "state": "OK",
    "zip": "74111",
    "country": "USA"
  },
  "tax": {
    "destinationPostalCode": "74111",
    "amount": 639
  },
  "orderInfo": {
    "customerId": "CustomerCode"
  },
  "storedCredentials": {
    "credentialStored": true,
    "transactionType": "installment",
    "previousNetworkTransactionId": "HKF5ISPDV0922"
  }
}

Gateway Response Parameters​

Field NameTypeAdyen MappingNotes
ApprovalCodestringPaymentResult.AuthCodeApproval code
ApprovedbooleanPaymentResult.RefusalReasonTransaction Outcome
If PaymentResult.RefusalReason is empty.
ProviderTransactionCodestringPaymentResult.PspReferenceAdyen's 16-character reference associated with the transaction/request.

Example Responses​

{
  "gatewayResponse": {
    "rawResponse": "{\r\n  \"resultCode\": \"Authorised\",\r\n  \"authCode\": \"095734\",\r\n  \"additionalData\": {\r\n    \"liabilityShift\": \"false\",\r\n    \"authCode\": \"095734\",\r\n    \"avsResult\": \"2 Neither postal code nor address match\",\r\n    \"PaymentAccountReference\": \"NuWFE8PbN190JnT5cikH8aDmR9Fir\",\r\n    \"threeDOffered\": \"false\",\r\n    \"networkTxReference\": \"UIG3DLGB51130\",\r\n    \"refusalReasonRaw\": \"AUTHORISED\",\r\n    \"checkout.cardAddedBrand\": \"mc\",\r\n    \"expiryDate\": \"3/2030\",\r\n    \"cvcResult\": \"5 Issuer not certified for CVC/CVV\",\r\n    \"recurringProcessingModel\": \"Subscription\",\r\n    \"avsResultRaw\": \"2\",\r\n    \"threeDAuthenticated\": \"false\",\r\n    \"paymentMethod\": \"mc\",\r\n    \"retry.attempt1.shopperInteraction\": \"Ecommerce\",\r\n    \"cvcResultRaw\": \"U\",\r\n    \"acquirerCode\": \"TestPmmAcquirer\",\r\n    \"acquirerReference\": \"dR-e9929a_e\"\r\n  },\r\n  \"pspReference\": \"TTQGFQFDDV8DCG65\"\r\n}",
    "gatewayErrors": [],
    "tokenExTransactionCode": "VFRRR0ZRRkREVjhEQ0c2NQ==",
    "approvalCode": "095734",
    "providerTransactionCode": "TTQGFQFDDV8DCG65",
    "approved": true
  },
  "referenceNumber": "23113010061326918600",
  "success": true,
  "error": "",
  "message": "",
  "thirdPartyStatusCode": "200"
}
Last updated on