CostEstimateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/adyen/main/json-schema/adyen-cost-estimate-request-schema.json",
  "title": "CostEstimateRequest",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/adyen-cost-api-openapi.yml#/components/schemas/CostEstimateRequest",
  "properties": {
    "amount": {
      "description": "The transaction amount used as a base for the cost estimation.",
      "$ref": "#/$defs/Amount"
    },
    "assumptions": {
      "description": "Assumptions made for the expected characteristics of the transaction, for which the charges are being estimated.",
      "$ref": "#/$defs/CostEstimateAssumptions"
    },
    "cardNumber": {
      "description": "The card number (4-19 characters) for PCI compliant use cases. Do not use any separators.\n\n> Either the `cardNumber` or `encryptedCardNumber` field must be provided in a payment request.",
      "maxLength": 19,
      "minLength": 4,
      "type": "string"
    },
    "encryptedCardNumber": {
      "description": "Encrypted data that stores card information for non PCI-compliant use cases. The encrypted data must be created with the Checkout Card Component or Secured Fields Component, and must contain the `encryptedCardNumber` field.\n\n> Either the `cardNumber` or `encryptedCardNumber` field must be provided in a payment request.",
      "type": "string"
    },
    "merchantAccount": {
      "description": "The merchant account identifier you want to process the (transaction) request with.",
      "type": "string"
    },
    "merchantDetails": {
      "description": "Additional data for merchants who don't use Adyen as the payment authorisation gateway.",
      "$ref": "#/$defs/MerchantDetails"
    },
    "recurring": {
      "description": "The recurring settings for the payment. Use this property when you want to enable [recurring payments](https://docs.adyen.com/online-payments/tokenization).",
      "$ref": "#/$defs/Recurring"
    },
    "selectedRecurringDetailReference": {
      "description": "The `recurringDetailReference` you want to use for this cost estimate. The value `LATEST` can be used to select the most recently stored recurring detail.",
      "type": "string"
    },
    "shopperInteraction": {
      "description": "Specifies the sales channel, through which the shopper gives their card details, and whether the shopper is a returning customer.\nFor the web service API, Adyen assumes Ecommerce shopper interaction by default.\n\nThis field has the following possible values:\n* `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.\n* `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).\n* `Moto` - Mail-order and telephone-order transactions where the shopper is in contact with the merchant via email or telephone.\n* `POS` - Point-of-sale transactions where the shopper is physically present to make a payment using a secure payment terminal.",
      "enum": [
        "Ecommerce",
        "ContAuth",
        "Moto",
        "POS"
      ],
      "type": "string"
    },
    "shopperReference": {
      "description": "Required for recurring payments. \nYour reference to uniquely identify this shopper, for example user ID or account ID. Minimum length: 3 characters.\n> Your reference must not include personally identifiable information (PII), for example name or email address.",
      "type": "string"
    }
  },
  "required": [
    "amount",
    "merchantAccount"
  ],
  "type": "object",
  "$defs": {
    "Amount": {
      "properties": {
        "currency": {
          "description": "The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).",
          "maxLength": 3,
          "minLength": 3,
          "type": "string"
        },
        "value": {
          "description": "The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).",
          "format": "int64",
          "type": "integer"
        }
      },
      "required": [
        "value",
        "currency"
      ],
      "type": "object"
    },
    "CostEstimateAssumptions": {
      "properties": {
        "assume3DSecureAuthenticated": {
          "description": "If true, the cardholder is expected to successfully authorise via 3D Secure.",
          "type": "boolean"
        },
        "assumeLevel3Data": {
          "description": "If true, the transaction is expected to have valid Level 3 data.",
          "type": "boolean"
        },
        "installments": {
          "description": "If not zero, the number of installments.",
          "format": "int32",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "MerchantDetails": {
      "properties": {
        "countryCode": {
          "description": "2-letter ISO 3166 country code of the card acceptor location.\n> This parameter is required for the merchants who don't use Adyen as the payment authorisation gateway.",
          "maxLength": 2,
          "minLength": 2,
          "type": "string"
        },
        "enrolledIn3DSecure": {
          "description": "If true, indicates that the merchant is enrolled in 3D Secure for the card network.",
          "type": "boolean"
        },
        "mcc": {
          "description": "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.\n\nThe list of MCCs can be found [here](https://en.wikipedia.org/wiki/Merchant_category_code).",
          "type": "string"
        }
      },
      "type": "object"
    },
    "Recurring": {
      "properties": {
        "contract": {
          "description": "The type of recurring contract to be used.\nPossible values:\n* `ONECLICK`  Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid).\n* `RECURRING`  Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-not-present-cnp).\n* `ONECLICK,RECURRING`  Payment details can be used regardless of whether the shopper is on your site or not.\n* `PAYOUT`  Payment details can be used to [make a payout](https://docs.adyen.com/online-payments/online-payouts).",
          "enum": [
            "ONECLICK",
            "RECURRING",
            "PAYOUT"
          ],
          "type": "string"
        },
        "recurringDetailName": {
          "description": "A descriptive name for this detail.",
          "type": "string"
        },
        "recurringExpiry": {
          "x-addedInVersion": "40",
          "description": "Date after which no further authorisations shall be performed. Only for 3D Secure 2.",
          "format": "date-time",
          "type": "string"
        },
        "recurringFrequency": {
          "x-addedInVersion": "40",
          "description": "Minimum number of days between authorisations. Only for 3D Secure 2.",
          "type": "string"
        },
        "tokenService": {
          "x-addedInVersion": "25",
          "description": "The name of the token service.",
          "enum": [
            "VISATOKENSERVICE",
            "MCTOKENSERVICE",
            "AMEXTOKENSERVICE",
            "TOKEN_SHARING"
          ],
          "type": "string"
        }
      },
      "type": "object"
    }
  }
}