Body

• accountInfo object

  Shopper account information for 3D Secure 2.

  Hide accountInfo attributes Show accountInfo attributes

  • accountAgeIndicator string

    Indicator of how long this shopper account exists in the merchant's environment. Allowed values:

    • notApplicable
    • thisTransaction
    • lessThan30Days
    • from30To60Days
    • moreThan60Days

    Values are notApplicable, thisTransaction, lessThan30Days, from30To60Days, or moreThan60Days.

  • accountChangeDate string(date-time)

    Date when the shopper's account was last changed.

  • accountChangeIndicator string

    Indicator when the shopper's account was last changed. Allowed values:

    • thisTransaction
    • lessThan30Days
    • from30To60Days
    • moreThan60Days

    Values are thisTransaction, lessThan30Days, from30To60Days, or moreThan60Days.

  • accountCreationDate string(date-time)

    Date when the shopper's account was created.

  • addCardAttemptsDay integer(int32)

    Number of attempts the shopper tried to add a card to their account in the last day.

  • deliveryAddressUsageDate string(date-time)

    Date the selected delivery address was last used.

  • deliveryAddressUsageIndicator string

    Indicator for when this delivery address was last used. Allowed values:

    • thisTransaction
    • lessThan30Days
    • from30To60Days
    • moreThan60Days

    Values are thisTransaction, lessThan30Days, from30To60Days, or moreThan60Days.

  • homePhone string

    Shopper's home phone number (including the country code).

  • mobilePhone string

    Shopper's mobile phone number (including the country code).

  • passwordChangeDate string(date-time)

    Date when the shopper has changed their password.

  • passwordChangeIndicator string

    Indicator when the shopper has changed their password. Allowed values:

    • notApplicable
    • thisTransaction
    • lessThan30Days
    • from30To60Days
    • moreThan60Days

    Values are notApplicable, thisTransaction, lessThan30Days, from30To60Days, or moreThan60Days.

  • pastTransactionsDay integer(int32)

    Number of transactions of this shopper in the past 24 hours.

  • pastTransactionsYear integer(int32)

    Number of transactions of this shopper in the past year.

  • paymentAccountAge string(date-time)

    Date this payment method was added to the shopper's account.

  • paymentAccountIndicator string

    Indicator for the amount of time this payment method was enrolled with this account. Allowed values:

    • notApplicable
    • thisTransaction
    • lessThan30Days
    • from30To60Days
    • moreThan60Days

    Values are notApplicable, thisTransaction, lessThan30Days, from30To60Days, or moreThan60Days.

  • purchasesLast6Months integer(int32)

    Number of purchases in the last 6 months.

  • suspiciousActivity boolean

    Whether suspicious activity was recorded on this account.

  • workPhone string

    Shopper's work phone number (including the country code).

• additionalAmount object

  The amount that needs to be captured/refunded. Required for /capture and /refund, not allowed for /cancel. The currency must match the currency used in authorisation, the value must be smaller than or equal to the authorised amount.

  Hide additionalAmount attributes Show additionalAmount attributes

  • currency string Required

    The three-character ISO currency code.

    Minimum length is 3, maximum length is 3.

  • value integer(int64) Required

    The payable amount that can be charged for the transaction.

    The transaction amount needs to be represented in minor units according to the following table.

• additionalData object

  This field contains additional data, which may be required for a particular payment request.

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

• amount object Required

  The amount that needs to be captured/refunded. Required for /capture and /refund, not allowed for /cancel. The currency must match the currency used in authorisation, the value must be smaller than or equal to the authorised amount.

  Hide amount attributes Show amount attributes

  • currency string Required

    The three-character ISO currency code.

    Minimum length is 3, maximum length is 3.

  • value integer(int64) Required

    The payable amount that can be charged for the transaction.

    The transaction amount needs to be represented in minor units according to the following table.

• billingAddress object

  The address where to send the invoice.

  Hide billingAddress attributes Show billingAddress attributes

  • city string

    The name of the city.

    Required if either houseNumberOrName, street, postalCode, or stateOrProvince are provided.

  • country string Required

    The two-character country code of the address

    The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

  • houseNumberOrName string

    The number or name of the house.

  • postalCode string

    The postal code.

    A maximum of five (5) digits for an address in the USA, or a maximum of ten (10) characters for an address in all other countries. Required if either houseNumberOrName, street, city, or stateOrProvince are provided.

  • stateOrProvince string

    The abbreviation of the state or province.

    Two (2) characters for an address in the USA or Canada, or a maximum of three (3) characters for an address in all other countries. Required for an address in the USA or Canada if either houseNumberOrName, street, city, or postalCode are provided.

  • street string

    The name of the street.

    The house number should not be included in this field; it should be separately provided via houseNumberOrName. Required if either houseNumberOrName, city, postalCode, or stateOrProvince are provided.

• browserInfo object

  The shopper's browser information.

  Hide browserInfo attributes Show browserInfo attributes

  • acceptHeader string Required

    The accept header value of the shopper's browser.

    Minimum length is 10, maximum length is 50.

  • colorDepth integer(int32) Required

    The color depth of the shopper's device in bits per pixel. Should be obtained by using the browser's screen.colorDepth property.

  • javaEnabled boolean Required

    Boolean value indicating if the shopper's browser is able to execute Java.

  • language string Required

    The navigator.language value of the shopper's browser (as defined in IETF BCP 47).

  • screenHeight integer(int32) Required

    The total height of the shopper's device screen in pixels.

  • screenWidth integer(int32) Required

    The total width of the shopper's device screen in pixels.

  • timeZoneOffset integer(int32) Required

    Time difference between UTC time and the shopper's browser local time, in minutes.

  • userAgent string Required

    The user agent value of the shopper's browser.

    Minimum length is 10, maximum length is 50.

• captureDelayHours integer(int32)

  The delay between the authorisation and scheduled auto-capture, specified in hours.

• dateOfBirth string(date-time)

  The shopper's date of birth.

  Format ISO-8601: YYYY-MM-DD

• dccQuote object

  The forex quote as returned in the response of the forex service.

  Hide dccQuote attributes Show dccQuote attributes

  • account string

    The account name.

  • accountType string

    The account type.

  • baseAmount object

    The amount that needs to be captured/refunded. Required for /capture and /refund, not allowed for /cancel. The currency must match the currency used in authorisation, the value must be smaller than or equal to the authorised amount.

    Hide baseAmount attributes Show baseAmount attributes

    • currency string Required

      The three-character ISO currency code.

      Minimum length is 3, maximum length is 3.

    • value integer(int64) Required

      The payable amount that can be charged for the transaction.

      The transaction amount needs to be represented in minor units according to the following table.

  • basePoints integer(int32) Required

    The base points.

  • buy object

    The amount that needs to be captured/refunded. Required for /capture and /refund, not allowed for /cancel. The currency must match the currency used in authorisation, the value must be smaller than or equal to the authorised amount.

    Hide buy attributes Show buy attributes

    • currency string Required

      The three-character ISO currency code.

      Minimum length is 3, maximum length is 3.

    • value integer(int64) Required

      The payable amount that can be charged for the transaction.

      The transaction amount needs to be represented in minor units according to the following table.

  • interbank object

    The amount that needs to be captured/refunded. Required for /capture and /refund, not allowed for /cancel. The currency must match the currency used in authorisation, the value must be smaller than or equal to the authorised amount.

    Hide interbank attributes Show interbank attributes

    • currency string Required

      The three-character ISO currency code.

      Minimum length is 3, maximum length is 3.

    • value integer(int64) Required

      The payable amount that can be charged for the transaction.

      The transaction amount needs to be represented in minor units according to the following table.

  • reference string

    The reference assigned to the forex quote request.

  • sell object

    The amount that needs to be captured/refunded. Required for /capture and /refund, not allowed for /cancel. The currency must match the currency used in authorisation, the value must be smaller than or equal to the authorised amount.

    Hide sell attributes Show sell attributes

    • currency string Required

      The three-character ISO currency code.

      Minimum length is 3, maximum length is 3.

    • value integer(int64) Required

      The payable amount that can be charged for the transaction.

      The transaction amount needs to be represented in minor units according to the following table.

  • signature string

    The signature to validate the integrity.

  • source string

    The source of the forex quote.

  • type string

    The type of forex.

  • validTill string(date-time) Required

    The date until which the forex quote is valid.

• deliveryAddress object

  The address where to send the invoice.

  Hide deliveryAddress attributes Show deliveryAddress attributes

  • city string

    The name of the city.

    Required if either houseNumberOrName, street, postalCode, or stateOrProvince are provided.

  • country string Required

    The two-character country code of the address

    The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

  • houseNumberOrName string

    The number or name of the house.

  • postalCode string

    The postal code.

    A maximum of five (5) digits for an address in the USA, or a maximum of ten (10) characters for an address in all other countries. Required if either houseNumberOrName, street, city, or stateOrProvince are provided.

  • stateOrProvince string

    The abbreviation of the state or province.

    Two (2) characters for an address in the USA or Canada, or a maximum of three (3) characters for an address in all other countries. Required for an address in the USA or Canada if either houseNumberOrName, street, city, or postalCode are provided.

  • street string

    The name of the street.

    The house number should not be included in this field; it should be separately provided via houseNumberOrName. Required if either houseNumberOrName, city, postalCode, or stateOrProvince are provided.

• deliveryDate string(date-time)

  The date and time the purchased goods should be delivered.

  Format ISO 8601: YYYY-MM-DDThh:mm:ss.sssTZD

  Example: 2017-07-17T13:42:40.428+01:00

• deviceFingerprint string

  A string containing the shopper's device fingerprint. For more information, refer to Device fingerprinting.

• fraudOffset integer(int32)

  An integer value that is added to the normal fraud score. The value can be either positive or negative.

• installments object

  Contains installment settings. For more information, refer to Installments.

  Hide installments attribute Show installments attribute

  • value integer(int32) Required

    Defines the number of installments. Its value needs to be greater than zero.

    Usually, the maximum allowed number of installments is capped. For example, it may not be possible to split a payment in more than 24 installments. The acquirer sets this upper limit, so its value may vary.

• mcc string

  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.

• merchantAccount string Required

  The merchant account identifier, with which you want to process the transaction.

• merchantOrderReference string

  This reference allows linking multiple transactions to each other.

  We strongly recommend you send the merchantOrderReference value to benefit from linking payment requests when authorisation retries take place. In addition, we recommend you provide retry.orderAttemptNumber, retry.chainAttemptNumber, and retry.skipRetry values in PaymentRequest.additionalData.

• merchantRiskIndicator object

  Additional risk fields for 3D Secure 2.

  Hide merchantRiskIndicator attributes Show merchantRiskIndicator attributes

  • addressMatch boolean

    Whether the chosen delivery address is identical to the billing address.

  • deliveryAddressIndicator string

    Indicator regarding the delivery address. Allowed values:

    • shipToBillingAddress
    • shipToVerifiedAddress
    • shipToNewAddress
    • shipToStore
    • digitalGoods
    • goodsNotShipped
    • other

    Values are shipToBillingAddress, shipToVerifiedAddress, shipToNewAddress, shipToStore, digitalGoods, goodsNotShipped, or other.

  • deliveryEmail string

    The delivery email address (for digital goods).

  • deliveryTimeframe string

    The estimated delivery time for the shopper to receive the goods. Allowed values:

    • electronicDelivery
    • sameDayShipping
    • overnightShipping
    • twoOrMoreDaysShipping

    Values are electronicDelivery, sameDayShipping, overnightShipping, or twoOrMoreDaysShipping.

  • giftCardAmount object

    The amount that needs to be captured/refunded. Required for /capture and /refund, not allowed for /cancel. The currency must match the currency used in authorisation, the value must be smaller than or equal to the authorised amount.

    Hide giftCardAmount attributes Show giftCardAmount attributes

    • currency string Required

      The three-character ISO currency code.

      Minimum length is 3, maximum length is 3.

    • value integer(int64) Required

      The payable amount that can be charged for the transaction.

      The transaction amount needs to be represented in minor units according to the following table.

  • giftCardCount integer(int32)

    Number of individual prepaid or gift cards used for this purchase.

  • preOrderDate string(date-time)

    For pre-order purchases, the expected date this product will be available to the shopper.

  • preOrderPurchase boolean

    Whether this transaction is for pre-ordering a product.

  • reorderItems boolean

    Whether the shopper has already purchased the same items in the past.

• metadata object

  Metadata consists of entries, each of which includes a key and a value. Limitations: Error "177", "Metadata size exceeds limit"

• orderReference string

  When you are doing multiple partial (gift card) payments, this is the pspReference of the first payment. We use this to link the multiple payments to each other. As your own reference for linking multiple payments, use the merchantOrderReferenceinstead.

• recurring object

  The recurring settings for the payment. Use this property when you want to enable recurring payments.

  Hide recurring attributes Show recurring attributes

  • contract string

    The type of recurring contract to be used. Possible values:

    • ONECLICK – Payment details can be used to initiate a one-click payment, where the shopper enters the card security code (CVC/CVV).
    • RECURRING – Payment details can be used without the card security code to initiate card-not-present transactions.
    • ONECLICK,RECURRING – Payment details can be used regardless of whether the shopper is on your site or not.
    • PAYOUT – Payment details can be used to make a payout.

    Values are ONECLICK, RECURRING, or PAYOUT.

  • recurringDetailName string

    A descriptive name for this detail.

  • recurringExpiry string(date-time)

    Date after which no further authorisations shall be performed. Only for 3D Secure 2.

  • recurringFrequency string

    Minimum number of days between authorisations. Only for 3D Secure 2.

  • tokenService string

    The name of the token service.

    Values are VISATOKENSERVICE or MCTOKENSERVICE.

• recurringProcessingModel string

  Defines a recurring payment type. Allowed values:

  • Subscription – A transaction for a fixed or variable amount, which follows a fixed schedule.
  • CardOnFile – Card details are stored to enable one-click or omnichannel journeys, or simply to streamline the checkout process. Any subscription not following a fixed schedule is also considered a card-on-file transaction.
  • UnscheduledCardOnFile – A transaction that occurs on a non-fixed schedule and/or have variable amounts. For example, automatic top-ups when a cardholder's balance drops below a certain amount.

  Values are CardOnFile, Subscription, or UnscheduledCardOnFile.

• reference string Required

  The reference to uniquely identify a payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement. If you need to provide multiple references for a transaction, separate them with hyphens ("-"). Maximum length: 80 characters.

• selectedBrand string

  Some payment methods require defining a value for this field to specify how to process the transaction.

  For the Bancontact payment method, it can be set to:

  • maestro (default), to be processed like a Maestro card, or
  • bcmc, to be processed like a Bancontact card.
• selectedRecurringDetailReference string

  The recurringDetailReference you want to use for this payment. The value LATEST can be used to select the most recently stored recurring detail.

• sessionId string

  A session ID used to identify a payment session.

• shopperEmail string

  The shopper's email address. We recommend that you provide this data, as it is used in velocity fraud checks.

• shopperIP string

  The shopper's IP address. We recommend that you provide this data, as it is used in a number of risk checks (for instance, number of payment attempts or location-based checks).

  This field is mandatory for some merchants depending on your business model. For more information, contact Support.

• shopperInteraction string

  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 cardholder 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).
  • Moto - Mail-order and telephone-order transactions where the shopper is in contact with the merchant via email or telephone.
  • POS - Point-of-sale transactions where the shopper is physically present to make a payment using a secure payment terminal.

  Values are Ecommerce, ContAuth, Moto, or POS.

• shopperLocale string

  The combination of a language code and a country code to specify the language to be used in the payment.

• shopperName object

  The shopper's full name and gender (if specified).

  Hide shopperName attributes Show shopperName attributes

  • firstName string Required

    The first name.

  • gender string Required

    The gender.

    The following values are permitted: MALE, FEMALE, UNKNOWN.

    Minimum length is 1, maximum length is 1. Values are MALE, FEMALE, or UNKNOWN.

  • infix string

    The name's infix, if applicable.

    A maximum length of twenty (20) characters is imposed.

  • lastName string Required

    The last name.

• shopperReference string

  The shopper's reference to uniquely identify this shopper (e.g. user ID or account ID).

  This field is required for recurring payments.

• shopperStatement string

  The text to appear on the shopper's bank statement.

• socialSecurityNumber string

  The shopper's social security number.

• splits array[object]

  The details of how the payment should be split when distributing a payment to a MarketPay Marketplace and its Accounts.

  Hide splits attributes Show splits attributes

  • account string

    The account to which this split applies.

    Required if the type is MarketPlace.

  • amount object Required

    The amount of this split.

    Hide amount attributes Show amount attributes

    • currency string

      The three-character ISO currency code.

      If this value is not provided, the currency in which the payment is made will be used.

      Minimum length is 3, maximum length is 3.

    • value integer(int64) Required

      The payable amount that can be charged for the transaction.

      The transaction amount needs to be represented in minor units according to the following table.

  • description string

    A description of this split.

  • reference string

    The reference of this split. Used to link other operations (e.g. captures and refunds) to this split.

    Required if the type is MarketPlace.

  • type string Required

    The type of this split.

    Permitted values: Default, PaymentFee, VAT, Commission, MarketPlace, Verification.

    Values are Commission, Default, MarketPlace, PaymentFee, VAT, or Verification.

• store string

  The physical store, for which this payment is processed.

  Minimum length is 1, maximum length is 16.

• telephoneNumber string

  The shopper's telephone number.

• threeDS2RequestData object

  Request fields for 3D Secure 2.

  Hide threeDS2RequestData attributes Show threeDS2RequestData attributes

  • authenticationOnly boolean

    If set to true, you will only do the 3D Secure 2 authentication, not the payment authorization.

  • challengeIndicator string

    Possibility to specify a preference for receiving a challenge from the issuer. Allowed values:

    • noPreference
    • requestNoChallenge
    • requestChallenge

    Values are noPreference, requestNoChallenge, or requestChallenge.

  • deviceChannel string Required

    The environment of the shopper. Allowed values:

    • app
    • browser
  • deviceRenderOptions object

    Display options for the 3D Secure 2 SDK. Only for deviceChannel set to app.

    Hide deviceRenderOptions attributes Show deviceRenderOptions attributes

    • sdkInterface string

      Supported SDK interface types.

      Values are Html, Native, or both.

    • sdkUiType array[string]

      UI types supported for displaying specific challenges.

      Values are multiSelect, otherHtml, outOfBand, singleSelect, or text.

  • messageVersion string

    The messageVersion value indicating the 3D Secure 2 protocol version.

  • notificationURL string

    URL the CRes value will be sent. Only for deviceChannel set to browser.

  • sdkAppID string

    The sdkAppID value as received from the 3D Secure 2 SDK. Only for deviceChannel set to app.

  • sdkEncData string

    The sdkEncData value as received from the 3D Secure 2 SDK. Only for deviceChannel set to app.

  • sdkEphemPubKey object

    The sdkEphemPubKey value as received from the 3D Secure 2 SDK. Only for deviceChannel set to app.

    Hide sdkEphemPubKey attributes Show sdkEphemPubKey attributes

    • crv string

      The crv value as received from the 3D Secure 2 SDK.

    • kty string

      The kty value as received from the 3D Secure 2 SDK.

    • x string

      The x value as received from the 3D Secure 2 SDK.

    • y string

      The y value as received from the 3D Secure 2 SDK.

  • sdkMaxTimeout integer(int32)

    The maximum amount of time in minutes for the 3D Secure 2 authentication process. Only for deviceChannel set to app.

  • sdkReferenceNumber string

    The sdkReferenceNumber value as received from the 3D Secure 2 SDK. Only for deviceChannel set to app.

  • sdkTransID string

    The sdkTransID value as received from the 3D Secure 2 SDK. Only for deviceChannel set to app.

  • threeDSRequestorID string

    Unique 3D Secure requestor identifier assigned by the Directory Server.

  • threeDSRequestorName string

    Unique 3D Secure requestor name assigned by the Directory Server.

  • threeDSRequestorURL string

    URL of the (customer service) website that will be shown to the shopper in case of technical errors during the 3D Secure 2 process.

• threeDS2Result object

  Thre ThreeDS2Result that was returned in the final CRes.

  Hide threeDS2Result attributes Show threeDS2Result attributes

  • authenticationValue string

    The authenticationValue value as defined in the 3D Secure 2 specification.

  • dsTransID string

    The dsTransID value as defined in the 3D Secure 2 specification.

  • eci string

    The eci value as defined in the 3D Secure 2 specification.

  • threeDSServerTransID string

    The threeDSServerTransID value as defined in the 3D Secure 2 specification.

  • timestamp string

    The timestamp value of the 3D Secure 2 authentication.

  • transStatus string

    The transStatus value as defined in the 3D Secure 2 specification.

  • transStatusReason string

    The transStatusReason value as defined in the 3D Secure 2 specification.

• threeDS2Token string

  The ThreeDS2Token that was returned in the /authorise call.

• totalsGroup string

  The reference value to aggregate sales totals in reporting. When not specified, the store field is used (if available).

  Minimum length is 1, maximum length is 16.

• trustedShopper boolean

  Set to true if the payment should be routed to a trusted MID.