PaymentRequest

The fields described below are the generic payment fields you specify when making an /authorise call to the Adyen payment API.

Field Type Required Description
additionalAmount Amount (error)

A container for the data concerning the additional amount to be authorised. It corresponds to the additional/surcharged part of the amount, and it needs to be in the same currency as amount.

additionalAmount is required only if you want to submit a non-zero value auth BIN or card verification request.

To be accepted by the schemes, the value specified in the additionalAmount field needs to be higher than the currency equivalent of 0.02 USD.

additionalData Object (error)

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 Amount (tick)

A container object for the payable amount information for the transaction.

For BIN or card verification requests, its value needs to be 0 (zero).

bankAccount BankAccount (error)

The details of the bank account, from which the payment should be made from.

Either bankAccount or card field must be provided in a payment request.

billingAddress Address (error) The address where to send the invoice.
browserInfo BrowserInfo (error) A user's browser information.
captureDelayHours Int (error) The delay between the authorisation and scheduled auto capture, specified in hours.
card Card (error)

A container for card data.

Either bankAccount or card field must be provided in a payment request.

dateOfBirth String (error)

The shopper's date of birth.

Format: ISO-8601; example: YYYY-MM-DD

dccQuote ForexQuote (error) The forex quote as returned in the response of the forex service.
deliveryAddress Address (error) The address where the purchased goods should be delivered to.
deliveryDate Date/Time (error)

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 (error) A string containing a shopper's device fingerprint. For more information, refer to Device fingerprinting.
fraudOffset Int (error)

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

installments Installments (error) Contains information on an installment. For more information, refer to Installments.
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.

merchantAccount String (tick)

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

merchantOrderReference String (error)

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.

metadata Object (error)

Metadata consists of entries, each of which includes a key and a value.

Limitations: Maximum 20 key-value pairs per request. When exceeding, the "177" error occurs: "Metadata size exceeds limit".

  key String (error)

Key for the information to be provided.

Example: key = 'storeCountry'

Maximum length: 20 characters. When exceeding, the "178" error occurs: "Metadata key size exceeds limit".

  value String (error)

The value associated with the key.

Example: value = 'US'

Maximum length: 80 characters. When exceeding, the value is truncated to 80 characters with '...' appended to it.

mpiData ThreeDSecureData (error) Authentication data produced by an MPI (Mastercard SecureCode or Verified By Visa).
orderReference String (error) The order reference to link multiple partial payments.
recurring Recurring (error)

The recurring properties of the payment.

Specify this property when you want to enable recurring payments.

recurringProcessingModel String (error)

V30 This element was added in the version 30.

Defines a recurring payment type.

Allowed values:

  • Subscription: A transaction for a fixed or variable amount, which follows a fixed schedule. This is the default value.
  • 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 as a card-on-file transaction.

If all your transactions must have the same recurringProcessingModel value, contact your account manager or Support Team to set the default value for your merchant account.

reference String (tick)

A reference to uniquely identify the 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, you can enter them in this field. Separate each reference value with a hyphen character ("-").

This field has a length restriction: you can enter max. 80 characters.

selectedBrand String (error)

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.

The selectedBrand values are case sensitive. For information on available selectedBrand values, refer to Payment methods.

selectedRecurringDetail
Reference
String (error)

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 (error)

A session identifier used to identify a payment session.

shopperEmail String (error)

The shopper's email address.

We recommend you provide this data, as it is used in velocity fraud checks.

shopperIP String (error)

The shopper's IP address.

We recommend you provide this data, as it is used in a number of risk checks. For example: number of payment attempts, location based checks.

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

shopperInteraction String (error)

Specifies the following information:

  • The sales channel the shopper gives their card details through;
  • Whether the shopper is a returning customer.

By default, for the web service API Adyen assumes Ecommerce shopper interaction.

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. For one-click payments, shopperInteraction must be set to Ecommerce.
  • ContAuth - Card on file and/or subscription transactions, where the card holder is known to the merchant (returning customer).
  • 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.
shopperLocale String (error) The combination of a language code and a country code to specify the language to be used in the payment.
shopperName Name (error) A shopper's full name and gender (if specified).
shopperReference String (error)

A shopper's reference for the payment transaction.

We recommend you provide this data.

This field is required for recurring payments.

shopperStatement String (error)

Set this field in your payment request if you want to include a variable shopper statement.

You can include placeholders for the references. For example:

  • ${reference} for the merchant reference
  • ${pspReference} for the PSP reference.

Note:

  • Not all acquirers support dynamic shopper statements.
  • Maximum allowed character length: 135 characters. For Visa/Mastercard: 25/22 respectively.
  • Allowed characters: a-zA-Z0-9.,-?|
  • Not supported for all payments methods, for further information contact Support Team.

socialSecurityNumber String (error) A shopper's social security number.
telephoneNumber String (error)

A shopper's telephone number.

This field is mandatory in case of Secure+ /authorise requests.

The country code should be preceded with a + sign.