Recurring API

To communicate with the Adyen API you should submit HTTP POST requests to corresponding endpoints. These endpoints differ for test and live accounts, and also depend on the data format (SOAP, JSON, or FORM) you use to submit data to the Adyen payments platform.

This document lists all endpoints available for you to integrate with the test platform and run QA checks.

Endpoints

SOAP

For the SOAP messaging protocol, all test payment requests must be posted to the following endpoint:

The data schema for corresponding SOAP objects is available at:

JSON and FORM

This is an overview of the test URL endpoints to communicate with our API using JSON or FORM (key-value parameters passed in an Http POST URL).

After you are ready to go live, you should switch to either generic or custom live endpoints. For more information, refer to Live endpoints.

DisableRequest

This class contains data that should be passed in a /disable request.

Field Type Required Description
contract String (error)

Specify the contract if you only want to disable a specific use.

This field can be set to one of the following values, or to their combination (comma-separated):

  • ONECLICK
  • RECURRING
  • PAYOUT
merchantAccount String (tick)

Your merchant account.

recurringDetailReference String (error)

The ID that uniquely identifies the recurring detail reference.

If it is not provided, the whole recurring contract of the shopperReference will be disabled, which includes all recurring details.

shopperReference String (tick)

The ID that uniquely identifies the shopper.

This shopperReference must be the same as the shopperReference used in the initial payment.

DisableResult

This class contains data that is returned as a response to a /disable request.

Field Type Required Description
response String (tick) Depending on whether a specific recurring detail was in the request, result is either "[detail-successfully-disabled]" or "[all-details-successfully-disabled]".

RecurringDetail

The RecurringDetailsResult is a result with a list with zero or more details containing:

Field Type Required Description
additionalData Object (error)

This field contains additional data, which may be returned in a particular response.

The additionalData object consists of entries, each of which includes the key and value. For more information on possible key-value pairs, refer to RecurringDetail.additionalData.

alias String (tick)

The alias of the credit card number.

Applies only to recurring contracts storing credit card details.

aliasType String (tick)

The alias type of the credit card number.

Applies only to recurring contracts storing credit card details.

bank BankAccount (error) A container for bank account data.
billingAddress Address (error) The billing address.
card Card (error) A container for card data.
contractTypes Array of strings (error) Types of recurring contracts.
creationDate Date/Time (tick) The date when the recurring details were created.
firstPspReference String (tick) The pspReference of the first recurring payment that created the recurring detail.
name String (error) An optional descriptive name for this recurring detail.
paymentMethodVariant String (error) The  type or sub-brand of a payment method used, e.g. Visa Debit, Visa Corporate, etc. For more information, refer to PaymentMethodVariant.
recurringDetailReference String (tick) The reference that uniquely identifies the recurring detail.
shopperName Name (error) The name of the shopper.
socialSecurityNumber String (error) A shopper's social security number (only in countries where it is legal to collect).
variant String (tick)

The payment method, such as “mc", "visa", "ideal".

RecurringDetail.additionalData

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

Field Type Required Description
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.

cvcResult String (tick)

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

For possible cvcResult values, see CVC-CVV result testing.

avsResult String (tick)

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

For possible avsResult values, see AVS.

referred Boolean (tick)

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)

Returns last 4 digits of a credit card number.

Returned only in the case of a card payment.

expiryDate String (tick)

Returns expiry date of the credit card returned.

Returned only in the case of a card payment.

refusalReasonRaw String (error)

Returns raw authorisation or refusal reason from the acquirers.

Example: AUTHORISED

avsResultRaw String (error)

Returns raw AVS result from the acquirers.

Example: 7

cvcResultRaw String (error)

Returns raw CVC check result from the acquirers.

Example: 1

acquirerCode String (error)

Returns the name of the acquirer processing the payment request.

Example: TestPmmAcquirer

hmacSignature String (error)

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)

Returns reference number that can be used for reconciliation in case a non-Adyen acquirer is used for settlement.

Example: 7C9N3FNBKT9

ownerName String (error)

Only relevant for SEPA Direct Debit transactions

Returns owner name of bank account.

countryCode String (error)

Only relevant for SEPA Direct Debit transactions

Returns country code of bank account.

bic String (error)

Only relevant for SEPA Direct Debit transactions

Returns BIC of bank account.

Example: TESTNL01

iban String (error)

Only relevant for SEPA Direct Debit transactions

Returns IBAN of bank account.

Example: NL13TEST0123456789

deliveryAddress.stateOrProvince String (error) Returns delivery address state or province passed in the payment request.
deliveryAddress.city String (error) Returns delivery address city passed in the payment request.
deliveryAddress.postalCode String (error) Returns delivery address postal code passed in the payment request.
deliveryAddress.street String (error) Returns delivery address street passed in the payment request.
deliveryAddress.houseNumberOrName String (error) Returns delivery address house number or name passed in the payment request.
deliveryAddress.country String (error) Returns delivery address country passed in the payment request.
extraCostsCurrency String (error) Returns currency of extra amount charged due to additional amounts set in the skin used in the HPP payment request.
extraCostsValue String (error) 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)

Returns the number of installments that the payment amount will be charged with. Only relevant for card payments in countries that support installments.

Example: 5

paypalPayerStatus String (error)

Only relevant for PayPal transactions.

Returns the status of the PayPal Buyer PayPal Account.

Example: unverified

paypalPayerResidenceCountry String (error)

Only relevant for PayPal transactions.

Returns the status of the PayPal Buyer country of residence.

Example: NL

acquirerAccountCode String (error)

Only relevant for PayPal transactions.

Returns the status of the Adyen acquirer account.

Example: PayPalSandbox_TestAcquirer

paypalPayerId String (error)

Only relevant for PayPal transactions.

Returns the PayPal PayerID.

paypalEmail String (error)

Only relevant for PayPal transactions.

Returns the PayPal Buyer account's email address.

paypalProtectionEligibility String (error)

Only relevant for PayPal transactions.

Returns the eligibility for PayPal Seller Protection for this payment.

Example: Ineligible

terminalId String (error)

Returns the terminal ID used in a Point-of-Sale payment.

Example: 06022622

shopperReference String (error) Returns the shopperReference passed in the payment request.
shopperInteraction String (error)

Returns the shopper interaction type of the payment request.

Example: Ecommerce

paymentMethodVariant String (error)

Returns the Adyen sub-variant of the payment method used for the payment request.

Example: mcpro

billingAddress.stateOrProvince String (error) Returns billing address state or province passed in the payment request.
billingAddress.city String (error) Returns billing address city passed in the payment request.
billingAddress.postalCode String (error) Returns billing address postal code passed in the payment request.
billingAddress.street String (error) Returns billing address street passed in the payment request.
billingAddress.houseNumberOrName String (error) Returns billing address house number or name passed in the payment request.
billingAddress.country String (error) Returns billing address country passed in the payment request.
fraudCheck-[nn]-[Fraud Check name] String (error)

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.

Example: 20

alias String (error)

Returns the Adyen alias of the card.

Example: H167852639363479

aliasType String (error)

Returns the type of the card alias.

Example: Default

cardBin String (error)

Returns the Bank Identification Number of a credit card, which is the first six digits of a card number.

Example: 521234

cardHolderName String (error)

Returns the Cardholder name passed in the payment request.

Example: Test Cardholder

issuerCountry String (error) Returns the issuing country of the card based on the BIN list that Adyen maintains.
threeDOffered Boolean (error) Returns a boolean value indicating whether 3DS was offered for this payment.
threeDAuthenticated Boolean (error) Returns a boolean value indicating whether 3DS authentication was completed on this payment.
threeDOfferedResponse String (error)

Returns the raw enrollment result from the 3DS directory services of the card schemes.

Example: Y

threeDAuthenticatedResponse String (error)

Returns the raw 3DS authentication result from the card issuer.

Example: N

fundingSource String (error)

Returns information regarding the funding type of the card.

Example: DEBIT

cardIssuingCurrency String (error) Returns the currency in which the card is issued if information is available.
cardIssuingBank String (error) Returns the name of the bank that issued the card.
cavv String (error) Returns the Cardholder Authentication Verification Value for the 3DS authentication session. The returned value is a Base64 encoded 20-byte byteArray.
xid String (error) 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) Returns the algorithm used to generate the 3DS Cardholder Authentication Verification Value. 
eci String (error) Returns the Electronic Commerce Indicator returned from the schemes for the 3DS payment session.

RecurringDetailsRequest

This class contains data that should be passed in a /listRecurringDetails request.

Field Type Required Description
merchantAccount String (tick)
The merchant account identifier you want to process the (transaction) request with.
recurring Recurring (error)

A container for the type of a recurring contract to be retrieved.

The contract value needs to match the contract value submitted in the payment transaction used to create a recurring contract.

However, if ONECLICK,RECURRING is the original contract definition in the initial payment, then contract should take either ONECLICK or RECURRING, depending on whether or not you want the shopper to enter their card's security code when they finalize their purchase.

shopperReference String (tick) The reference you use to uniquely identify the shopper (e.g. user ID or account ID).

RecurringDetailsResult

This class contains data returned as a response to a /listRecurringDetails request.

Field Type Required Description
creationDate DateTime (tick) The date when the recurring details were created.
details Array of RecurringDetail (tick) A list of one or more recurring payment details.
lastKnownShopperEmail String (error) The most recent email for this shopper (if available).
shopperReference String (tick) The reference you use to uniquely identify the shopper (e.g. user ID or account ID).

The response is different in the following scenarios:

  • If the shopperReference does not exist, the endpoint returns an empty object.
  • If the shopperReference exists but the request contains a specific contract type and a recurring detail for that contract does not exist, the details array is not included in the response.