Cost estimation 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.

CardBin

This object is returned as a part of the /getCostEstimate response.

This functionality requires additional configuration on Adyen's end. To enable it, contact the  Support Team.

Field

Type

Required

Description

bin

String

(error)

The first 6 digit of the card number. Enable this field via merchant account settings.

commercial

Boolean

(error)

If true, it indicates a commercial card. Enable this field via merchant account settings.

fundingSource String (error)

The card funding source. Valid values are:

  • CREDIT

  • DEBIT

  • PREPAID

  • PREPAID_RELOADABLE
  • DEFERRED_DEBIT

  • CHARGED

Enable this field via merchant account settings.

fundsAvailability String (error)

Indicates availability of funds.

Visa:

  • "I" (fast funds are supported)
  • "N" (otherwise)

Mastercard:

  • "I" (product type is Prepaid or Debit, or issuing country is in CEE/HGEM list)
  • "N" (otherwise)

Returned when you verify a card BIN or estimate costs, and only if payoutEligible is different from "N" or "U".

issuingBank

String

(error)

The issuing bank of the card.

issuingCountry

String

(error)

The issuing country of the card.

issuingCurrency

String

(error)

The issuing currency of the card.

paymentMethod String (error) The payment method associated with the card (e.g. visa, mc, or amex).
payoutEligible String (error)

Indicates whether a payout is eligible or not for this card.

Visa:

  • "Y"
  • "N"

Mastercard:

  • "Y" (domestic and cross-border)
  • "D" (only domestic)
  • "N" (no MoneySend)
  • "U" (unknown)

Returned when you verify a card BIN or estimate costs, and only if payoutEligible is different from "N" or "U".

summary String (error) The last four digits of the card number.

CostEstimateAssumptions

This object can be passed along with the /getCostEstimation request.

Field

Type

Required

Description

assumeLevel3Data

Boolean

(error)

If true, the transaction is expected to have valid Level 3 data.

assume3DSecureAuthenticated

Boolean

(error)

If true, the cardholder is expected to successfully authorise via 3D Secure.

GetCostEstimateRequest

The fields described below are the generic parameters you specify when making a /getCostEstimate call to the Adyen API. For more information, refer to Cost estimation.

Field

Type

Required

Description

amount

Amount

(tick)

The transaction amount used as a base for the cost estimation.

assumptions

CostEstimateAssumptions

(error)

Assumptions made for the expected characteristics of the transaction, for which the charges are being estimated.

cardNumber String (error)

The card number (4-19 characters). Do not use any separators.

Either the cardNumber or encryptedCard field must be provided in a payment request.

encryptedCard String (error)

Encrypted data that stores card information for non PCI-compliant use cases. The encrypted data must be created with the Client-Side Encryption library and must contain at least the number and generationtime fields.

Either the cardNumber or encryptedCard field must be provided in a payment request.

merchantAccount

String
(tick)

The merchant account identifier you want to process the (transaction) request with.

merchantDetails

MerchantDetails
(error)

Additional data for merchants who don't use Adyen as the payment authorisation gateway.

shopperInteraction

String
(error)

 

Specifies the sales channel, through which the shopper gives their card details, and whether the shopper is a returning customer.

For the web service API, Adyen assumes Ecommerce shopper interaction by default.

This field has the following possible values:

  • Ecommerce - Online transactions where the cardholder 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.

GetCostEstimateResponse

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

Field

Type

Required

Description

cardBin CardBin (error) Card BIN details.

costEstimateAmount

Amount 

(error)

The estimated cost (interchange fee + scheme fee) in the settlement currency. If the settlement currency cannot be determined, the fee in EUR is returned.

resultCode String (tick)

The result of the request.

Allowed values:

  • Successful – Cost estimation was successful.
  • Unsupported – Cost estimation is not supported for the given card.

surchargeType

String

(error)

Indicates the way the charges can be passed on to the cardholder. The following values are possible:

  • ZERO - the charges are not allowed to pass on.

  • PASSTHROUGH - the charges can be passed on.

  • UNLIMITED - there is no limit on how much surcharge is passed on.

MerchantDetails

This object can be passed along with the /getCostEstimate request.

Field

Type

Required

Description

countryCode

String

(error)

2-letter ISO 3166 country code of the card acceptor location.

This parameter is required for the merchants who don't use Adyen as the payment authorisation gateway.

enrolledIn3DSecure Boolean (error) If true, indicates that the merchant is enrolled in 3D Secure for the card network.

mcc

String

(error)

The merchant category code (MCC) is a four-digit number which relates to a particular market segment. This code reflects the predominant activity that is conducted by the merchant.

The list of MCCs can be found here.