Create a payment session

POST/sessions

Use it in a workflow

Add a step and choose the Adyen connector.
Pick the Create a payment session action (under Payments).
Fill in the fields below, then reference the result from later steps as {{createAPaymentSession.response.data}}.

Request

Headers

Idempotency-Keystring

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request body

Enter the body as JSON in the step's Body field.

accountInfoobject

accountAgeIndicatorstring

Indicator for the length of time since this shopper account was created in the merchant's environment. Allowed values: * notApplicable * thisTransaction * lessThan30Days * from30To60Days * moreThan60Days

One ofnotApplicablethisTransactionlessThan30Daysfrom30To60DaysmoreThan60Days

accountChangeDatestring (date-time)

Date when the shopper's account was last changed.

accountChangeIndicatorstring

Indicator for the length of time since the shopper's account was last updated. Allowed values: * thisTransaction * lessThan30Days * from30To60Days * moreThan60Days

One ofthisTransactionlessThan30Daysfrom30To60DaysmoreThan60Days

accountCreationDatestring (date-time)

Date when the shopper's account was created.

accountTypestring

Indicates the type of account. For example, for a multi-account card product. Allowed values: * notApplicable * credit * debit

One ofnotApplicablecreditdebit

addCardAttemptsDayinteger (int32)

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

deliveryAddressUsageDatestring (date-time)

Date the selected delivery address was first used.

deliveryAddressUsageIndicatorstring

Indicator for the length of time since this delivery address was first used. Allowed values: * thisTransaction * lessThan30Days * from30To60Days * moreThan60Days

One ofthisTransactionlessThan30Daysfrom30To60DaysmoreThan60Days

homePhonestring

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

mobilePhonestring

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

passwordChangeDatestring (date-time)

Date when the shopper last changed their password.

passwordChangeIndicatorstring

Indicator when the shopper has changed their password. Allowed values: * notApplicable * thisTransaction * lessThan30Days * from30To60Days * moreThan60Days

One ofnotApplicablethisTransactionlessThan30Daysfrom30To60DaysmoreThan60Days

pastTransactionsDayinteger (int32)

Number of all transactions (successful and abandoned) from this shopper in the past 24 hours.

pastTransactionsYearinteger (int32)

Number of all transactions (successful and abandoned) from this shopper in the past year.

paymentAccountAgestring (date-time)

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

paymentAccountIndicatorstring

Indicator for the length of time since this payment method was added to this shopper's account. Allowed values: * notApplicable * thisTransaction * lessThan30Days * from30To60Days * moreThan60Days

One ofnotApplicablethisTransactionlessThan30Daysfrom30To60DaysmoreThan60Days

purchasesLast6Monthsinteger (int32)

Number of successful purchases in the last six months.

suspiciousActivityboolean

Whether suspicious activity was recorded on this account.

workPhonestring

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

additionalAmountobject

currencystringrequired

The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes) of the amount.

valueinteger (int64)required

The numeric value of the amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes#minor-units).

additionalDataobject

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.

allowedPaymentMethodsarray<string>

List of payment methods to be presented to the shopper. To refer to payment methods, use their [payment method type](https://docs.adyen.com/payment-methods/payment-method-types). Example: `"allowedPaymentMethods":["ideal","applepay"]`

amountobjectrequired

currencystringrequired

The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes) of the amount.

valueinteger (int64)required

The numeric value of the amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes#minor-units).

applicationInfoobject

adyenLibraryobject2 fields

adyenPaymentSourceobject2 fields

externalPlatformobject3 fields

merchantApplicationobject2 fields

merchantDeviceobject3 fields

shopperInteractionDeviceobject3 fields

authenticationDataobject

attemptAuthenticationstring

Indicates when 3D Secure authentication should be attempted. This overrides all other rules, including [Dynamic 3D Secure settings](https://docs.adyen.com/risk-management/dynamic-3d-secure). Possible values: * **always**: Perform 3D Secure authentication. * **never**: Don't perform 3D Secure authentication. If PSD2 SCA or other national regulations require authentication, the transaction gets declined.

One ofalwaysnever

authenticationOnlyboolean

Required to trigger the [authentication-only flow](https://docs.adyen.com/online-payments/3d-secure/authentication-only/). If set to **true**, you will only perform the 3D Secure 2 authentication, and will not proceed to the payment authorization. Default: **false**.

Default false

threeDSRequestDataobject4 fields

billingAddressobject

citystringrequired

The name of the city. Maximum length: 3000 characters.

countrystringrequired

The two-character ISO-3166-1 alpha-2 country code. For example, **US**. > If you don't know the country or are not collecting the country from the shopper, provide `country` as `ZZ`.

houseNumberOrNamestringrequired

The number or name of the house. Maximum length: 3000 characters.

postalCodestringrequired

A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.

stateOrProvincestring

The two-character ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada. > Required for the US and Canada.

streetstringrequired

The name of the street. Maximum length: 3000 characters. > The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.

blockedPaymentMethodsarray<string>

List of payment methods to be hidden from the shopper. To refer to payment methods, use their [payment method type](https://docs.adyen.com/payment-methods/payment-method-types). Example: `"blockedPaymentMethods":["ideal","applepay"]`

captureDelayHoursinteger (int32)

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

channelstring

The platform where a payment transaction takes place. This field is optional for filtering out payment methods that are only available on specific platforms. If this value is not set, then we will try to infer it from the `sdkVersion` or `token`. Possible values: * **iOS** * **Android** * **Web**

One ofiOSAndroidWeb

companyobject

homepagestring

The company website's home page.

namestring

The company name.

registrationNumberstring

Registration number of the company.

registryLocationstring

Registry location of the company.

taxIdstring

Tax ID of the company.

typestring

The company type.

countryCodestring

The shopper's two-letter country code.

dateOfBirthstring (date)

The shopper's date of birth. Format [ISO-8601](https://www.w3.org/TR/NOTE-datetime): YYYY-MM-DD

deliverAtstring (date-time)

The date and time when the purchased goods should be delivered. [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format: YYYY-MM-DDThh:mm:ss+TZD, for example, **2020-12-18T10:15:30+01:00**.

deliveryAddressobject

citystringrequired

The name of the city. Maximum length: 3000 characters.

countrystringrequired

The two-character ISO-3166-1 alpha-2 country code. For example, **US**. > If you don't know the country or are not collecting the country from the shopper, provide `country` as `ZZ`.

firstNamestring

houseNumberOrNamestringrequired

The number or name of the house. Maximum length: 3000 characters.

lastNamestring

postalCodestringrequired

A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.

stateOrProvincestring

The two-character ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada. > Required for the US and Canada.

streetstringrequired

The name of the street. Maximum length: 3000 characters. > The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.

enableOneClickboolean

When true and `shopperReference` is provided, the shopper will be asked if the payment details should be stored for future [one-click payments](https://docs.adyen.com/get-started-with-adyen/payment-glossary/#one-click-payments-definition).

enablePayOutboolean

When true and `shopperReference` is provided, the payment details will be tokenized for payouts.

enableRecurringboolean

When true and `shopperReference` is provided, the payment details will be stored for [recurring payments](https://docs.adyen.com/online-payments/tokenization/#recurring-payment-types) where the shopper is not present, such as subscription or automatic top-up payments.

expiresAtstring (date-time)

The date the session expires in [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. When not specified, the expiry date is set to 1 hour after session creation. You cannot set the session expiry to more than 24 hours after session creation.

fundOriginobject

billingAddressobject6 fields

shopperEmailstring

The email address of the person funding the money.

shopperNameobject2 fields

telephoneNumberstring

The phone number of the person funding the money.

walletIdentifierstring

The unique identifier of the wallet where the funds are coming from.

fundRecipientobject

IBANstring

The IBAN of the bank account where the funds are being transferred to.

billingAddressobject6 fields

shopperEmailstring

The email address of the shopper.

shopperNameobject2 fields

shopperReferencestring

Required for recurring payments. Your reference to uniquely identify this shopper, for example user ID or account ID. The value is case-sensitive and must be at least three characters. > Your reference must not include personally identifiable information (PII) such as name or email address.

storedPaymentMethodIdstring

This is the `recurringDetailReference` returned in the response when you created the token.

subMerchantobject5 fields

telephoneNumberstring

The telephone number of the shopper.

walletIdentifierstring

The unique identifier for the wallet the funds are being transferred to. You can use the shopper reference or any other identifier.

walletOwnerTaxIdstring

The tax identifier of the person receiving the funds.

walletPurposestring

The purpose of a digital wallet transaction.

One ofidentifiedBoletotransferDifferentWallettransferOwnWallettransferSameWalletunidentifiedBoleto

installmentOptionsobject

A set of key-value pairs that specifies the installment options available per payment method. The key must be a payment method name in lowercase. For example, **card** to specify installment options for all cards, or **visa** or **mc**. The value must be an object containing the installment options.

lineItemsarray<object>

Price and product information about the purchased items, to be included on the invoice sent to the shopper. > This field is required for 3x 4x Oney, Affirm, Afterpay, Clearpay, Klarna, Ratepay, and Riverty.

amountExcludingTaxinteger (int64)

Item amount excluding the tax, in [minor units](https://docs.adyen.com/development-resources/currency-codes/#minor-units).

amountIncludingTaxinteger (int64)

Item amount including the tax, in [minor units](https://docs.adyen.com/development-resources/currency-codes/#minor-units).

brandstring

Brand of the item.

colorstring

Color of the item.

descriptionstring

Description of the line item.

idstring

ID of the line item.

imageUrlstring

Link to the picture of the purchased item.

itemCategorystring

Item category, used by the payment methods PayPal and Ratepay.

manufacturerstring

Manufacturer of the item.

marketplaceSellerIdstring

Marketplace seller id.

productUrlstring

Link to the purchased item.

quantityinteger (int64)

Number of items.

receiverEmailstring

Email associated with the given product in the basket (usually in electronic gift cards).

returnShippingCompanystring

Shipping company handling the return of the item.

returnTrackingNumberstring

Tracking number for the return of the item.

returnTrackingUristring

Tracking URI for the return of the item.

riskCategorystring

An optional, free-text category for the item to be used in the risk evaluation. When provided, Protect uses this value to evaluate custom risk rules.

shippingCompanystring

Shipping company handling the delivery of the item.

shippingMethodstring

Shipping method used to deliver the item.

sizestring

Size of the item.

skustring

Stock keeping unit.

taxAmountinteger (int64)

Tax amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes/#minor-units).

taxPercentageinteger (int64)

Tax percentage, represented as a [basis point](https://en.wikipedia.org/wiki/Basis_point) integer. For example: - **530** for 5.3% (five point three percent) - **2100** for 21% (twenty-one percent)

trackingNumberstring

Tracking number for the delivery of the item.

trackingUristring

Tracking URI for the delivery of the item.

upcstring

Universal Product Code.

mandateobject

amountstringrequired

The billing amount (in minor units) of the recurring transactions.

amountRulestring

The limitation rule of the billing amount. Possible values: * **max**: The transaction amount can not exceed the `amount`. * **exact**: The transaction amount should be the same as the `amount`.

One ofmaxexact

billingAttemptsRulestring

The rule to specify the period, within which the recurring debit can happen, relative to the mandate recurring date. Possible values: * **on**: On a specific date. * **before**: Before and on a specific date. * **after**: On and after a specific date.

One ofonbeforeafter

billingDaystring

The number of the day, on which the recurring debit can happen. Should be within the same calendar month as the mandate recurring date. Possible values: 1-31 based on the `frequency`.

countstring

The number of transactions that can be performed within the given frequency.

endsAtstringrequired

End date of the billing plan, in YYYY-MM-DD format.

frequencystringrequired

The frequency with which a shopper should be charged. Possible values: **adhoc**, **daily**, **weekly**, **biWeekly**, **monthly**, **quarterly**, **halfYearly**, **yearly**.

One ofadhocdailyweeklybiWeeklymonthlyquarterlyhalfYearlyyearly

remarksstring

The message shown by UPI to the shopper on the approval screen.

startsAtstring

Start date of the billing plan, in YYYY-MM-DD format. By default, the transaction date.

mccstring

The [merchant category code](https://en.wikipedia.org/wiki/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.

merchantAccountstringrequired

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

merchantOrderReferencestring

This reference allows linking multiple transactions to each other for reporting purposes (i.e. order auth-rate). The reference should be unique per billing cycle. The same merchant order reference should never be reused after the first authorised attempt. If used, this field should be supplied for all incoming authorisations. > 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`.

metadataobject

Metadata consists of entries, each of which includes a key and a value. Limits: * Maximum 20 key-value pairs per request. * Maximum 20 characters per key. * Maximum 80 characters per value.

modestring

Indicates the type of front end integration. Possible values: * **embedded** (default): Drop-in or Components integration * **hosted**: Hosted Checkout integration

One ofembeddedhostedDefault "embedded"

mpiDataobject

authenticationResponsestring

In 3D Secure 2, this is the `transStatus` from the challenge result. If the transaction was frictionless, omit this parameter.

One ofYNUA

cavvstring (byte)

The cardholder authentication value (base64 encoded, 20 bytes in a decoded form).

cavvAlgorithmstring

The CAVV algorithm used. Include this only for 3D Secure 1.

challengeCancelstring

Indicator informing the Access Control Server (ACS) and the Directory Server (DS) that the authentication has been cancelled. For possible values, refer to [3D Secure API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference#mpidata).

One of01020304050607

directoryResponsestring

In 3D Secure 2, this is the `transStatus` from the `ARes`.

One ofACDINRUY

dsTransIDstring

Supported for 3D Secure 2. The unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.

ecistring

The electronic commerce indicator.

riskScorestring

Risk score calculated by Directory Server (DS). Required for Cartes Bancaires integrations.

threeDSVersionstring

The version of the 3D Secure protocol.

tokenAuthenticationVerificationValuestring (byte)

Network token authentication verification value (TAVV). The network token cryptogram.

transStatusReasonstring

Provides information on why the `transStatus` field has the specified value. For possible values, refer to [our docs](https://docs.adyen.com/online-payments/3d-secure/api-reference#possible-transstatusreason-values).

xidstring (byte)

Supported for 3D Secure 1. The transaction identifier (Base64-encoded, 20 bytes in a decoded form).

payableboolean

Indicates if the session is payable. If the payment amount is final, set this to **true** to indicate that the session is payable, so that the shopper can proceed to submit the payment. When you set this to **true**, you can no longer update the session. If you set this to **false**, you must make another request to update the session and set this to **true** before the shopper can submit the payment. If not specified, this defaults to **true**.

platformChargebackLogicobject

behaviorstring

The method of handling the chargeback. Possible values: **deductFromLiableAccount**, **deductFromOneBalanceAccount**, **deductAccordingToSplitRatio**.

One ofdeductFromOneBalanceAccountdeductAccordingToSplitRatiodeductFromLiableAccount

costAllocationAccountstring

The unique identifier of the balance account to which the chargeback fees are booked. By default, the chargeback fees are booked to your liable balance account.

targetAccountstring

The unique identifier of the balance account against which the disputed amount is booked. Required if `behavior` is **deductFromOneBalanceAccount**.

recurringExpirystring

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

recurringFrequencystring

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

recurringProcessingModelstring

Defines a recurring payment type. Required when creating a token to store payment details. Allowed values: * `Subscription` – A transaction for a fixed or variable amount, which follows a fixed schedule. * `CardOnFile` – With a card-on-file (CoF) transaction, 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` – An unscheduled card-on-file (UCoF) transaction is 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.

One ofCardOnFileSubscriptionUnscheduledCardOnFile

redirectFromIssuerMethodstring

Specifies the redirect method (GET or POST) when redirecting back from the issuer.

redirectToIssuerMethodstring

Specifies the redirect method (GET or POST) when redirecting to the issuer.

referencestringrequired

The reference to uniquely identify a payment.

returnUrlstringrequired

The URL to return to in case of a redirection. The format depends on the channel. * For web, include the protocol `http://` or `https://`. You can also include your own additional query parameters, for example, shopper ID or order reference number. Example: `https://your-company.example.com/checkout?shopperOrder=12xy` * For iOS, use the custom URL for your app. To know more about setting custom URL schemes, refer to the [Apple Developer documentation](https://developer.apple.com/documentation/uikit/inter-process_communication/allowing_apps_and_websites_to_link_to_your_content/defining_a_custom_url_scheme_for_your_app). Example: `my-app://` * For Android, use a custom URL handled by an Activity on your app. You can configure it with an [intent filter](https://developer.android.com/guide/components/intents-filters). Example: `my-app://your.package.name` If the URL to return to includes non-ASCII characters, like spaces or special letters, URL encode the value. > The URL must not include personally identifiable information (PII), for example name or email address.

json

{
  "amount": {
    "currency": "string",
    "value": 0
  },
  "merchantAccount": "string",
  "reference": "string",
  "returnUrl": "string",
  "accountInfo": {
    "accountAgeIndicator": "notApplicable",
    "accountChangeDate": "2025-01-01T00:00:00Z",
    "accountChangeIndicator": "thisTransaction",
    "accountCreationDate": "2025-01-01T00:00:00Z",
    "accountType": "notApplicable",
    "addCardAttemptsDay": 0,
    "deliveryAddressUsageDate": "2025-01-01T00:00:00Z",
    "deliveryAddressUsageIndicator": "thisTransaction",
    "homePhone": "string",
    "mobilePhone": "string",
    "passwordChangeDate": "2025-01-01T00:00:00Z",
    "passwordChangeIndicator": "notApplicable"
  },
  "additionalAmount": {
    "currency": "string",
    "value": 0
  },
  "additionalData": {},
  "allowedPaymentMethods": [
    "string"
  ],
  "applicationInfo": {
    "adyenLibrary": {
      "name": "string",
      "version": "string"
    },
    "adyenPaymentSource": {
      "name": "string",
      "version": "string"
    },
    "externalPlatform": {
      "integrator": "string",
      "name": "string",
      "version": "string"
    },
    "merchantApplication": {
      "name": "string",
      "version": "string"
    },
    "merchantDevice": {
      "os": "string",
      "osVersion": "string",
      "reference": "string"
    },
    "shopperInteractionDevice": {
      "locale": "string",
      "os": "string",
      "osVersion": "string"
    }
  },
  "authenticationData": {
    "attemptAuthentication": "always",
    "authenticationOnly": false,
    "threeDSRequestData": {
      "challengeWindowSize": "01",
      "dataOnly": "false",
      "nativeThreeDS": "preferred",
      "threeDSVersion": "2.1.0"
    }
  },
  "billingAddress": {
    "city": "string",
    "country": "string",
    "houseNumberOrName": "string",
    "postalCode": "string",
    "street": "string",
    "stateOrProvince": "string"
  },
  "blockedPaymentMethods": [
    "string"
  ]
}

Response

Returns 201 with an object. Read it in later steps with {{createAPaymentSession.response.data.<field>}}.

accountInfoobject

accountAgeIndicatorstring

One ofnotApplicablethisTransactionlessThan30Daysfrom30To60DaysmoreThan60Days

accountChangeDatestring (date-time)

Date when the shopper's account was last changed.

accountChangeIndicatorstring

Indicator for the length of time since the shopper's account was last updated. Allowed values: * thisTransaction * lessThan30Days * from30To60Days * moreThan60Days

One ofthisTransactionlessThan30Daysfrom30To60DaysmoreThan60Days

accountCreationDatestring (date-time)

Date when the shopper's account was created.

accountTypestring

Indicates the type of account. For example, for a multi-account card product. Allowed values: * notApplicable * credit * debit

One ofnotApplicablecreditdebit

addCardAttemptsDayinteger (int32)

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

deliveryAddressUsageDatestring (date-time)

Date the selected delivery address was first used.

deliveryAddressUsageIndicatorstring

Indicator for the length of time since this delivery address was first used. Allowed values: * thisTransaction * lessThan30Days * from30To60Days * moreThan60Days

One ofthisTransactionlessThan30Daysfrom30To60DaysmoreThan60Days

homePhonestring

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

mobilePhonestring

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

passwordChangeDatestring (date-time)

Date when the shopper last changed their password.

passwordChangeIndicatorstring

Indicator when the shopper has changed their password. Allowed values: * notApplicable * thisTransaction * lessThan30Days * from30To60Days * moreThan60Days

One ofnotApplicablethisTransactionlessThan30Daysfrom30To60DaysmoreThan60Days

pastTransactionsDayinteger (int32)

Number of all transactions (successful and abandoned) from this shopper in the past 24 hours.

pastTransactionsYearinteger (int32)

Number of all transactions (successful and abandoned) from this shopper in the past year.

paymentAccountAgestring (date-time)

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

paymentAccountIndicatorstring

Indicator for the length of time since this payment method was added to this shopper's account. Allowed values: * notApplicable * thisTransaction * lessThan30Days * from30To60Days * moreThan60Days

One ofnotApplicablethisTransactionlessThan30Daysfrom30To60DaysmoreThan60Days

purchasesLast6Monthsinteger (int32)

Number of successful purchases in the last six months.

suspiciousActivityboolean

Whether suspicious activity was recorded on this account.

workPhonestring

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

additionalAmountobject

currencystringrequired

The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes) of the amount.

valueinteger (int64)required

The numeric value of the amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes#minor-units).

additionalDataobject

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.

allowedPaymentMethodsarray<string>

amountobject

currencystringrequired

The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes) of the amount.

valueinteger (int64)required

The numeric value of the amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes#minor-units).

applicationInfoobject

adyenLibraryobject2 fields

adyenPaymentSourceobject2 fields

externalPlatformobject3 fields

merchantApplicationobject2 fields

merchantDeviceobject3 fields

shopperInteractionDeviceobject3 fields

authenticationDataobject

attemptAuthenticationstring

One ofalwaysnever

authenticationOnlyboolean

Default false

threeDSRequestDataobject4 fields

billingAddressobject

citystringrequired

The name of the city. Maximum length: 3000 characters.

countrystringrequired

The two-character ISO-3166-1 alpha-2 country code. For example, **US**. > If you don't know the country or are not collecting the country from the shopper, provide `country` as `ZZ`.

houseNumberOrNamestringrequired

The number or name of the house. Maximum length: 3000 characters.

postalCodestringrequired

A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.

stateOrProvincestring

The two-character ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada. > Required for the US and Canada.

streetstringrequired

The name of the street. Maximum length: 3000 characters. > The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.

blockedPaymentMethodsarray<string>

captureDelayHoursinteger (int32)

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

channelstring

One ofiOSAndroidWeb

companyobject

homepagestring

The company website's home page.

namestring

The company name.

registrationNumberstring

Registration number of the company.

registryLocationstring

Registry location of the company.

taxIdstring

Tax ID of the company.

typestring

The company type.

countryCodestring

The shopper's two-letter country code.

dateOfBirthstring (date-time)

The shopper's date of birth in [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.

deliverAtstring (date-time)

The date and time when the purchased goods should be delivered. [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format: YYYY-MM-DDThh:mm:ss+TZD, for example, **2020-12-18T10:15:30+01:00**.

deliveryAddressobject

citystringrequired

The name of the city. Maximum length: 3000 characters.

countrystringrequired

The two-character ISO-3166-1 alpha-2 country code. For example, **US**. > If you don't know the country or are not collecting the country from the shopper, provide `country` as `ZZ`.

firstNamestring

houseNumberOrNamestringrequired

The number or name of the house. Maximum length: 3000 characters.

lastNamestring

postalCodestringrequired

A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.

stateOrProvincestring

The two-character ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada. > Required for the US and Canada.

streetstringrequired

The name of the street. Maximum length: 3000 characters. > The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.

enableOneClickboolean

enablePayOutboolean

When true and `shopperReference` is provided, the payment details will be tokenized for payouts.

enableRecurringboolean

expiresAtstring (date-time)

fundOriginobject

billingAddressobject6 fields

shopperEmailstring

The email address of the person funding the money.

shopperNameobject2 fields

telephoneNumberstring

The phone number of the person funding the money.

walletIdentifierstring

The unique identifier of the wallet where the funds are coming from.

fundRecipientobject

IBANstring

The IBAN of the bank account where the funds are being transferred to.

billingAddressobject6 fields

shopperEmailstring

The email address of the shopper.

shopperNameobject2 fields

shopperReferencestring

storedPaymentMethodIdstring

This is the `recurringDetailReference` returned in the response when you created the token.

subMerchantobject5 fields

telephoneNumberstring

The telephone number of the shopper.

walletIdentifierstring

The unique identifier for the wallet the funds are being transferred to. You can use the shopper reference or any other identifier.

walletOwnerTaxIdstring

The tax identifier of the person receiving the funds.

walletPurposestring

The purpose of a digital wallet transaction.

One ofidentifiedBoletotransferDifferentWallettransferOwnWallettransferSameWalletunidentifiedBoleto

idstring

A unique identifier of the session.

installmentOptionsobject

lineItemsarray<object>

amountExcludingTaxinteger (int64)

Item amount excluding the tax, in [minor units](https://docs.adyen.com/development-resources/currency-codes/#minor-units).

amountIncludingTaxinteger (int64)

Item amount including the tax, in [minor units](https://docs.adyen.com/development-resources/currency-codes/#minor-units).

brandstring

Brand of the item.

colorstring

Color of the item.

descriptionstring

Description of the line item.

idstring

ID of the line item.

imageUrlstring

Link to the picture of the purchased item.

itemCategorystring

Item category, used by the payment methods PayPal and Ratepay.

manufacturerstring

Manufacturer of the item.

marketplaceSellerIdstring

Marketplace seller id.

productUrlstring

Link to the purchased item.

quantityinteger (int64)

Number of items.

receiverEmailstring

Email associated with the given product in the basket (usually in electronic gift cards).

returnShippingCompanystring

Shipping company handling the return of the item.

returnTrackingNumberstring

Tracking number for the return of the item.

returnTrackingUristring

Tracking URI for the return of the item.

riskCategorystring

An optional, free-text category for the item to be used in the risk evaluation. When provided, Protect uses this value to evaluate custom risk rules.

shippingCompanystring

Shipping company handling the delivery of the item.

shippingMethodstring

Shipping method used to deliver the item.

sizestring

Size of the item.

skustring

Stock keeping unit.

taxAmountinteger (int64)

Tax amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes/#minor-units).

taxPercentageinteger (int64)

Tax percentage, represented as a [basis point](https://en.wikipedia.org/wiki/Basis_point) integer. For example: - **530** for 5.3% (five point three percent) - **2100** for 21% (twenty-one percent)

trackingNumberstring

Tracking number for the delivery of the item.

trackingUristring

Tracking URI for the delivery of the item.

upcstring

Universal Product Code.

mandateobject

amountstringrequired

The billing amount (in minor units) of the recurring transactions.

amountRulestring

The limitation rule of the billing amount. Possible values: * **max**: The transaction amount can not exceed the `amount`. * **exact**: The transaction amount should be the same as the `amount`.

One ofmaxexact

billingAttemptsRulestring

One ofonbeforeafter

billingDaystring

The number of the day, on which the recurring debit can happen. Should be within the same calendar month as the mandate recurring date. Possible values: 1-31 based on the `frequency`.

countstring

The number of transactions that can be performed within the given frequency.

endsAtstringrequired

End date of the billing plan, in YYYY-MM-DD format.

frequencystringrequired

The frequency with which a shopper should be charged. Possible values: **adhoc**, **daily**, **weekly**, **biWeekly**, **monthly**, **quarterly**, **halfYearly**, **yearly**.

One ofadhocdailyweeklybiWeeklymonthlyquarterlyhalfYearlyyearly

remarksstring

The message shown by UPI to the shopper on the approval screen.

startsAtstring

Start date of the billing plan, in YYYY-MM-DD format. By default, the transaction date.

mccstring

merchantAccountstring

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

merchantOrderReferencestring

metadataobject

Metadata consists of entries, each of which includes a key and a value. Limits: * Maximum 20 key-value pairs per request. * Maximum 20 characters per key. * Maximum 80 characters per value.

modestring

Indicates the type of front end integration. Possible values: * **embedded** (default): Drop-in or Components integration * **hosted**: Hosted Checkout integration

One ofembeddedhostedDefault "embedded"

mpiDataobject

authenticationResponsestring

In 3D Secure 2, this is the `transStatus` from the challenge result. If the transaction was frictionless, omit this parameter.

One ofYNUA

cavvstring (byte)

The cardholder authentication value (base64 encoded, 20 bytes in a decoded form).

cavvAlgorithmstring

The CAVV algorithm used. Include this only for 3D Secure 1.

challengeCancelstring

One of01020304050607

directoryResponsestring

In 3D Secure 2, this is the `transStatus` from the `ARes`.

One ofACDINRUY

dsTransIDstring

Supported for 3D Secure 2. The unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.

ecistring

The electronic commerce indicator.

riskScorestring

Risk score calculated by Directory Server (DS). Required for Cartes Bancaires integrations.

threeDSVersionstring

The version of the 3D Secure protocol.

tokenAuthenticationVerificationValuestring (byte)

Network token authentication verification value (TAVV). The network token cryptogram.

transStatusReasonstring

xidstring (byte)

Supported for 3D Secure 1. The transaction identifier (Base64-encoded, 20 bytes in a decoded form).

payableboolean

platformChargebackLogicobject

behaviorstring

The method of handling the chargeback. Possible values: **deductFromLiableAccount**, **deductFromOneBalanceAccount**, **deductAccordingToSplitRatio**.

One ofdeductFromOneBalanceAccountdeductAccordingToSplitRatiodeductFromLiableAccount

costAllocationAccountstring

The unique identifier of the balance account to which the chargeback fees are booked. By default, the chargeback fees are booked to your liable balance account.

targetAccountstring

The unique identifier of the balance account against which the disputed amount is booked. Required if `behavior` is **deductFromOneBalanceAccount**.

recurringExpirystring

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

recurringFrequencystring

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

recurringProcessingModelstring

One ofCardOnFileSubscriptionUnscheduledCardOnFile

redirectFromIssuerMethodstring

Specifies the redirect method (GET or POST) when redirecting back from the issuer.

redirectToIssuerMethodstring

Specifies the redirect method (GET or POST) when redirecting to the issuer.

referencestring

The reference to uniquely identify a payment.

json

{
  "amount": {
    "currency": "string",
    "value": 0
  },
  "expiresAt": "2025-01-01T00:00:00Z",
  "id": "string",
  "merchantAccount": "string",
  "reference": "string",
  "returnUrl": "string",
  "accountInfo": {
    "accountAgeIndicator": "notApplicable",
    "accountChangeDate": "2025-01-01T00:00:00Z",
    "accountChangeIndicator": "thisTransaction",
    "accountCreationDate": "2025-01-01T00:00:00Z",
    "accountType": "notApplicable",
    "addCardAttemptsDay": 0,
    "deliveryAddressUsageDate": "2025-01-01T00:00:00Z",
    "deliveryAddressUsageIndicator": "thisTransaction",
    "homePhone": "string",
    "mobilePhone": "string",
    "passwordChangeDate": "2025-01-01T00:00:00Z",
    "passwordChangeIndicator": "notApplicable"
  },
  "additionalAmount": {
    "currency": "string",
    "value": 0
  },
  "additionalData": {},
  "allowedPaymentMethods": [
    "string"
  ],
  "applicationInfo": {
    "adyenLibrary": {
      "name": "string",
      "version": "string"
    },
    "adyenPaymentSource": {
      "name": "string",
      "version": "string"
    },
    "externalPlatform": {
      "integrator": "string",
      "name": "string",
      "version": "string"
    },
    "merchantApplication": {
      "name": "string",
      "version": "string"
    },
    "merchantDevice": {
      "os": "string",
      "osVersion": "string",
      "reference": "string"
    },
    "shopperInteractionDevice": {
      "locale": "string",
      "os": "string",
      "osVersion": "string"
    }
  },
  "authenticationData": {
    "attemptAuthentication": "always",
    "authenticationOnly": false,
    "threeDSRequestData": {
      "challengeWindowSize": "01",
      "dataOnly": "false",
      "nativeThreeDS": "preferred",
      "threeDSVersion": "2.1.0"
    }
  }
}

Need more? See the Adyen guide for connection setup and behaviour shared by every action.

Was this page helpful?