Pricing Templates
Log in Sign up
Integrations / Adyen Checkout / ...

POST /sessions

Creates a payment session for Web Drop-in and Web Components integrations.

The response contains encrypted payment session data. The front end then uses the session data to make any required server-side calls for the payment flow.

You get the payment outcome asynchronously, in an AUTHORISATION webhook.

Servers

Request headers

Name Type Required Description
Content-Type String Yes The media type of the request body.

Default value: "application/json"
Idempotency-Key String No

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

Request body fields

Name Type Required Description
shopperReference String No

Your reference to uniquely identify this shopper, for example user ID or account ID. Minimum length: 3 characters.

Your reference must not include personally identifiable information (PII), for example name or email address.
mcc String No

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.
storePaymentMethodMode String No

Indicates if the details of the payment method will be stored for the shopper. Possible values:

  • disabled – No details will be stored (default).
  • askForConsent – If the shopperReference is provided, the UI lets the shopper choose if they want their payment details to be stored.
  • enabled – If the shopperReference is provided, the details will be stored without asking the shopper for consent.

Possible values:

  • "askForConsent"
  • "disabled"
  • "enabled"
metadata Object No

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.
trustedShopper Boolean No

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

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

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.
shopperLocale String No

The combination of a language code and a country code to specify the language to be used in the payment.
blockedPaymentMethods[] Array No

List of payment methods to be hidden from the shopper. To refer to payment methods, use their payment method type.

Example: "blockedPaymentMethods":["ideal","giropay"]
recurringProcessingModel String No

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.

Possible values:

  • "CardOnFile"
  • "Subscription"
  • "UnscheduledCardOnFile"
redirectToIssuerMethod String No

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

When true and shopperReference is provided, the shopper will be asked if the payment details should be stored for future one-click payments.
redirectFromIssuerMethod String No

Specifies the redirect method (GET or POST) when redirecting back from the issuer.
splits[] Array No

An array of objects specifying how to split a payment when using Adyen for Platforms, Classic Platforms integration, or Issuing.
splits[].account String No

The unique identifier of the account to which the split amount is booked. Required if type is MarketPlace or BalanceAccount.

  • Classic Platforms integration: The accountCode of the account to which the split amount is booked.
  • Balance Platform: The balanceAccountId of the account to which the split amount is booked.
splits[].description String No

Your description for the split item.
splits[].amount Object No

The amount of the split item.

  • Required for all split types in the Classic Platforms integration.
  • Required if type is BalanceAccount, Commission, Default, or VAT in your Balance Platform integration.
splits[].amount.value Integer Yes

The value of the split amount, in minor units.
splits[].amount.currency String No

The three-character ISO currency code. By default, this is the original payment currency.
splits[].type String Yes

The part of the payment you want to book to the specified account.

Possible values for the Balance Platform:

  • BalanceAccount: books part of the payment (specified in amount) to the specified account.
  • Transaction fees types that you can book to the specified account:
    • AcquiringFees: the aggregated amount of the interchange and scheme fees.
    • PaymentFee: the aggregated amount of all transaction fees.
    • AdyenFees: the aggregated amount of Adyen's commission and markup fees.
    • AdyenCommission: the transaction fees due to Adyen under blended rates.
    • AdyenMarkup: the transaction fees due to Adyen under Interchange ++ pricing.
    • Interchange: the fees paid to the issuer for each payment made with the card network.
    • SchemeFee: the fees paid to the card scheme for using their network.
  • Commission: your platform's commission on the payment (specified in amount), booked to your liable balance account.
  • Remainder: the amount left over after a currency conversion, booked to the specified account.
  • TopUp: allows you and your users to top up balance accounts using direct debit, card payments, or other payment methods.
  • VAT: the value-added tax charged on the payment, booked to your platforms liable balance account.
  • Commission: your platform's commission (specified in amount) on the payment, booked to your liable balance account.
  • Default: in very specific use cases, allows you to book the specified amount to the specified account. For more information, contact Adyen support.

Possible values for the Classic Platforms integration: Commission, Default, MarketPlace, PaymentFee, VAT.

Possible values:

  • "MarketPlace"
  • "SchemeFee"
  • "Surcharge"
  • "Commission"
  • "PaymentFee"
  • "AdyenCommission"
  • "Tip"
  • "AdyenMarkup"
  • "Remainder"
  • "Interchange"
  • "AcquiringFees"
  • "AdyenFees"
  • "BalanceAccount"
  • "Default"
  • "VAT"
splits[].reference String No

Your unique reference for the part of the payment booked to the specified account.

This is required if type is MarketPlace (Classic Platforms integration) or BalanceAccount (Balance Platform).

For the other types, we also recommend providing a unique reference so you can reconcile the split and the associated payment in the transaction overview and in the reports.
authenticationData Object No

Configuration data for 3DS payments.
authenticationData.attemptAuthentication String No

Indicates when 3D Secure authentication should be attempted. This overrides all other rules, including Dynamic 3D Secure settings.

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.

Possible values:

  • "never"
  • "always"
authenticationData.threeDSRequestData Object No

Object with additional parameters for the 3D Secure authentication flow.
authenticationData.threeDSRequestData.nativeThreeDS String No

Indicates if native 3D Secure authentication should be used when available.

Possible values:

  • preferred: Use native 3D Secure authentication when available.
  • disabled: Only use the redirect 3D Secure authentication flow.

Possible values:

  • "preferred"
  • "disabled"
authenticationData.threeDSRequestData.threeDSVersion String No

The version of 3D Secure to use.

Possible values:

  • 2.1.0
  • 2.2.0

Possible values:

  • "2.1.0"
  • "2.2.0"
authenticationData.threeDSRequestData.dataOnly String No

Flag for data only flow.

Possible values:

  • "false"
  • "true"
authenticationData.threeDSRequestData.challengeWindowSize String No

Dimensions of the 3DS2 challenge window to be displayed to the cardholder.

Possible values:

  • 01 - size of 250x400
  • 02 - size of 390x400
  • 03 - size of 500x600
  • 04 - size of 600x400
  • 05 - Fullscreen

Possible values:

  • "05"
  • "04"
  • "03"
  • "02"
  • "01"
authenticationData.authenticationOnly Boolean No

If set to true, you will only perform the 3D Secure 2 authentication, and not the payment authorisation. Default: false.

Default value: false
expiresAt String No

The date the session expires in ISO8601 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.
enablePayOut Boolean No

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

If set to true, you will only perform the 3D Secure 2 authentication, and not the payment authorisation.

Default value: false
reference String Yes

The reference to uniquely identify a payment.
lineItems[] Array No

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, Riverty, and Zip.
lineItems[].size String No

Size of the item.
lineItems[].description String No

Description of the line item.
lineItems[].brand String No

Brand of the item.
lineItems[].taxAmount Integer No

Tax amount, in minor units.
lineItems[].quantity Integer No

Number of items.
lineItems[].productUrl String No

Link to the purchased item.
lineItems[].amountExcludingTax Integer No

Item amount excluding the tax, in minor units.
lineItems[].imageUrl String No

Link to the picture of the purchased item.
lineItems[].marketplaceSellerId String No

Marketplace seller id.
lineItems[].id String No

ID of the line item.
lineItems[].amountIncludingTax Integer No

Item amount including the tax, in minor units.
lineItems[].itemCategory String No

Item category, used by the payment methods PayPal and Ratepay.
lineItems[].receiverEmail String No

Email associated with the given product in the basket (usually in electronic gift cards).
lineItems[].sku String No

Stock keeping unit.
lineItems[].manufacturer String No

Manufacturer of the item.
lineItems[].taxPercentage Integer No

Tax percentage, in minor units.
lineItems[].upc String No

Universal Product Code.
lineItems[].color String No

Color of the item.
platformChargebackLogic Object No

Defines how to book chargebacks when using Adyen for Platforms.
platformChargebackLogic.costAllocationAccount String No

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.
platformChargebackLogic.targetAccount String No

The unique identifier of the balance account against which the disputed amount is booked.

Required if behavior is deductFromOneBalanceAccount.
platformChargebackLogic.behavior String No

The method of handling the chargeback.

Possible values: deductFromLiableAccount, deductFromOneBalanceAccount, deductAccordingToSplitRatio.

Possible values:

  • "deductAccordingToSplitRatio"
  • "deductFromOneBalanceAccount"
  • "deductFromLiableAccount"
merchantOrderReference String No

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.
deliveryAddress Object No

The address where the purchased goods should be delivered.
deliveryAddress.postalCode String Yes

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

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.
deliveryAddress.firstName String No
deliveryAddress.country String Yes

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.
deliveryAddress.houseNumberOrName String Yes

The number or name of the house. Maximum length: 3000 characters.
deliveryAddress.street String Yes

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.
deliveryAddress.city String Yes

The name of the city. Maximum length: 3000 characters.
deliverAt String No

The date and time when the purchased goods should be delivered.

ISO 8601 format: YYYY-MM-DDThh:mm:ss+TZD, for example, 2020-12-18T10:15:30+01:00.
captureDelayHours Integer No

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

Request fields for 3D Secure 2. To check if any of the following fields are required for your integration, refer to Online payments.
threeDS2RequestData.threeDSRequestorChallengeInd String No

Indicates whether a challenge is requested for this transaction. Possible values:

  • 01 — No preference
  • 02 — No challenge requested
  • 03 — Challenge requested (3DS Requestor preference)
  • 04 — Challenge requested (Mandate)
  • 05 — No challenge (transactional risk analysis is already performed)
  • 06 — Data Only

Possible values:

  • "06"
  • "05"
  • "04"
  • "03"
  • "02"
  • "01"
threeDS2RequestData.workPhone Object No

The work phone number provided by the Cardholder.
threeDS2RequestData.workPhone.cc String No

Country code. Length: 1–3 characters.
threeDS2RequestData.workPhone.subscriber String No

Subscriber number. Maximum length: 15 characters.
threeDS2RequestData.mobilePhone Object No

The mobile phone number provided by the Cardholder.
threeDS2RequestData.mobilePhone.cc String No

Country code. Length: 1–3 characters.
threeDS2RequestData.mobilePhone.subscriber String No

Subscriber number. Maximum length: 15 characters.
threeDS2RequestData.homePhone Object No

The home phone number provided by the Cardholder.
threeDS2RequestData.homePhone.cc String No

Country code. Length: 1–3 characters.
threeDS2RequestData.homePhone.subscriber String No

Subscriber number. Maximum length: 15 characters.
mode String No

Indicates the type of front end integration. Possible values:

  • embedded (default): Drop-in or Components integration
  • hosted: Hosted Checkout integration

Possible values:

  • "embedded"
  • "hosted"

Default value: "embedded"
additionalAmount Object No

If you want a BIN or card verification request to use a non-zero value, assign this value to additionalAmount (while the amount must be still set to 0 to trigger BIN or card verification). Required to be in the same currency as the amount.
additionalAmount.value Integer Yes

The amount of the transaction, in minor units.
additionalAmount.currency String Yes

The three-character ISO currency code.
showRemovePaymentMethodButton Boolean No

Set to true to show a button that lets the shopper remove a stored payment method.
applicationInfo Object No

Information about your application. For more details, see Building Adyen solutions.
applicationInfo.merchantApplication Object No

Merchant developed software, such as cashier application, used to interact with the Adyen API.
applicationInfo.merchantApplication.name String No

Name of the field. For example, Name of External Platform.
applicationInfo.merchantApplication.version String No

Version of the field. For example, Version of External Platform.
applicationInfo.externalPlatform Object No

Third-party developed platform used to initiate payment requests. For example, Magento, Zuora, etc.
applicationInfo.externalPlatform.integrator String No

External platform integrator.
applicationInfo.externalPlatform.name String No

Name of the field. For example, Name of External Platform.
applicationInfo.externalPlatform.version String No

Version of the field. For example, Version of External Platform.
applicationInfo.merchantDevice Object No

Merchant device information.
applicationInfo.merchantDevice.osVersion String No

Version of the operating system on the merchant device.
applicationInfo.merchantDevice.os String No

Operating system running on the merchant device.
applicationInfo.merchantDevice.reference String No

Merchant device reference.
applicationInfo.adyenLibrary Object No

Adyen-developed software, such as libraries and plugins, used to interact with the Adyen API. For example, Magento plugin, Java API library, etc.
applicationInfo.adyenLibrary.name String No

Name of the field. For example, Name of External Platform.
applicationInfo.adyenLibrary.version String No

Version of the field. For example, Version of External Platform.
applicationInfo.shopperInteractionDevice Object No

Shopper interaction device, such as terminal, mobile device or web browser, to initiate payment requests.
applicationInfo.shopperInteractionDevice.osVersion String No

Version of the operating system on the shopper interaction device.
applicationInfo.shopperInteractionDevice.locale String No

Locale on the shopper interaction device.
applicationInfo.shopperInteractionDevice.os String No

Operating system running on the shopper interaction device.
applicationInfo.adyenPaymentSource Object No

Adyen-developed software to get payment details. For example, Checkout SDK, Secured Fields SDK, etc.
applicationInfo.adyenPaymentSource.name String No

Name of the field. For example, Name of External Platform.
applicationInfo.adyenPaymentSource.version String No

Version of the field. For example, Version of External Platform.
themeId String No

Sets a custom theme for Hosted Checkout. The value can be any of the Theme ID values from your Customer Area.
shopperEmail String No

The shopper's email address.
mandate Object No

The mandate details to initiate recurring transaction.
mandate.billingAttemptsRule String No

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.

Possible values:

  • "on"
  • "before"
  • "after"
mandate.frequency String Yes

The frequency with which a shopper should be charged.

Possible values: adhoc, daily, weekly, biWeekly, monthly, quarterly, halfYearly, yearly.

Possible values:

  • "biWeekly"
  • "monthly"
  • "adhoc"
  • "weekly"
  • "halfYearly"
  • "yearly"
  • "daily"
  • "quarterly"
mandate.count String No

The number of transactions that can be performed within the given frequency.
mandate.startsAt String No

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

The message shown by UPI to the shopper on the approval screen.
mandate.endsAt String Yes

End date of the billing plan, in YYYY-MM-DD format.
mandate.amount String Yes

The billing amount (in minor units) of the recurring transactions.
mandate.amountRule String No

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.

Possible values:

  • "exact"
  • "max"
mandate.billingDay String No

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.
fundOrigin Object No

The person or entity funding the money.
fundOrigin.shopperEmail String No

The email address of the person funding the money.
fundOrigin.shopperName Object No

The name of the person funding the money.
fundOrigin.shopperName.lastName String Yes

The last name.
fundOrigin.shopperName.firstName String Yes

The first name.
fundOrigin.billingAddress Object No

The address where to send the invoice.
fundOrigin.billingAddress.postalCode String Yes

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

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.
fundOrigin.billingAddress.country String Yes

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.
fundOrigin.billingAddress.houseNumberOrName String Yes

The number or name of the house. Maximum length: 3000 characters.
fundOrigin.billingAddress.street String Yes

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.
fundOrigin.billingAddress.city String Yes

The name of the city. Maximum length: 3000 characters.
fundOrigin.telephoneNumber String No

The phone number of the person funding the money.
fundOrigin.walletIdentifier String No

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

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

The shopper's IP address. In general, 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).

For 3D Secure 2 transactions, schemes require shopperIP for all browser-based implementations. This field is also mandatory for some merchants depending on your business model. For more information, contact Support.
shopperName Object No

The shopper's full name. This object is required for some payment methods such as AfterPay, Klarna, or if you're enrolled in the PayPal Seller Protection program.
shopperName.lastName String Yes

The last name.
shopperName.firstName String Yes

The first name.
recurringFrequency String No

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

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.
shopperStatement String No

The text to be shown on the shopper's bank statement. We recommend sending a maximum of 22 characters, otherwise banks might truncate the string. Allowed characters: a-z, A-Z, 0-9, spaces, and special characters . , ' _ - ? + * /.
telephoneNumber String No

The shopper's telephone number.
storePaymentMethod Boolean No

When true and shopperReference is provided, the payment details will be stored for future recurring payments.
shopperInteraction String No

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.

Possible values:

  • "ContAuth"
  • "Ecommerce"
  • "POS"
  • "Moto"
company Object No

Information regarding the company.
company.homepage String No

The company website's home page.
company.name String No

The company name.
company.registrationNumber String No

Registration number of the company.
company.registryLocation String No

Registry location of the company.
company.type String No

The company type.
company.taxId String No

Tax ID of the company.
returnUrl String Yes

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.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. Example: my-app://
  • For Android, use a custom URL handled by an Activity on your app. You can configure it with an intent filter. 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.
socialSecurityNumber String No

The shopper's social security number.
store String No

Required for Adyen for Platforms integrations if you are a platform model. This is your reference (on balance platform) or the storeReference (in the classic integration) for the ecommerce or point-of-sale store that is processing the payment.
fundRecipient Object No

the person or entity receiving the money
fundRecipient.walletPurpose String No

The purpose of a digital wallet transaction.

Possible values:

  • "transferOwnWallet"
  • "transferDifferentWallet"
  • "transferSameWallet"
  • "unidentifiedBoleto"
  • "identifiedBoleto"
fundRecipient.paymentMethod Object No

The payment method used by the shopper.
fundRecipient.paymentMethod.srcTokenReference String No

The reference for the Click to Pay token.
fundRecipient.paymentMethod.encryptedSecurityCode String No

The encrypted card verification code.
fundRecipient.paymentMethod.cvc String No

The card verification code. Only collect raw card data if you are fully PCI compliant.
fundRecipient.paymentMethod.brand String No

Secondary brand of the card. For example: plastix, hmclub.
fundRecipient.paymentMethod.number String No

The card number. Only collect raw card data if you are fully PCI compliant.
fundRecipient.paymentMethod.expiryMonth String No

The card expiry month. Only collect raw card data if you are fully PCI compliant.
fundRecipient.paymentMethod.fundingSource String No

The funding source that should be used when multiple sources are available. For Brazilian combo cards, by default the funding source is credit. To use debit, set this value to debit.

Possible values:

  • "credit"
  • "debit"
fundRecipient.paymentMethod.srcCorrelationId String No

An identifier used for the Click to Pay transaction.
fundRecipient.paymentMethod.encryptedExpiryYear String No

The encrypted card expiry year.
fundRecipient.paymentMethod.srcScheme String No

The scheme that is being used for Click to Pay.
fundRecipient.paymentMethod.encryptedExpiryMonth String No

The encrypted card expiry month.
fundRecipient.paymentMethod.networkPaymentReference String No

The transaction identifier from card schemes. This is the networkTxReference from the response to the first payment.
fundRecipient.paymentMethod.srcDigitalCardId String No

The SRC reference for the Click to Pay token.
fundRecipient.paymentMethod.threeDS2SdkVersion String No

Required for mobile integrations. Version of the 3D Secure 2 mobile SDK.
fundRecipient.paymentMethod.recurringDetailReference String No

This is the recurringDetailReference returned in the response when you created the token.
fundRecipient.paymentMethod.cupsecureplus.smscode String No
fundRecipient.paymentMethod.shopperNotificationReference String No

The shopperNotificationReference returned in the response when you requested to notify the shopper. Used only for recurring payments in India.
fundRecipient.paymentMethod.holderName String No

The name of the card holder.
fundRecipient.paymentMethod.type String No

Default payment method details. Common for scheme payment methods, and for simple payment method details.

Possible values:

  • "bcmc"
  • "giftcard"
  • "card"
  • "scheme"
  • "networkToken"

Default value: "scheme"
fundRecipient.paymentMethod.storedPaymentMethodId String No

This is the recurringDetailReference returned in the response when you created the token.
fundRecipient.paymentMethod.encryptedCardNumber String No

The encrypted card number.
fundRecipient.paymentMethod.checkoutAttemptId String No

The checkout attempt identifier.
fundRecipient.paymentMethod.expiryYear String No

The card expiry year. Only collect raw card data if you are fully PCI compliant.
fundRecipient.shopperReference String No

Required for recurring payments. Your reference to uniquely identify this shopper, for example user ID or account ID. Minimum length: 3 characters.

Your reference must not include personally identifiable information (PII), for example name or email address.
fundRecipient.shopperEmail String No

The email address of the shopper.
fundRecipient.subMerchant Object No

Required for back-to-back/purchase-driven-load transactions, where the funds are taken from the shopper's stored card when the wallet balance is insufficient. The final merchant who will receive the money, also known as a sub-merchant.
fundRecipient.subMerchant.mcc String No

The sub-merchant's 4-digit Merchant Category Code (MCC).

  • Format: Numeric
  • Fixed length: 4 digits
fundRecipient.subMerchant.name String No

The name of the sub-merchant. Based on scheme specifications, this value will overwrite the shopper statement that will appear in the card statement.

  • Format: Alphanumeric
  • Maximum length: 22 characters
fundRecipient.subMerchant.taxId String No

The tax ID of the sub-merchant.

  • Format: Numeric
  • Fixed length: 11 digits for the CPF or 14 digits for the CNPJ
fundRecipient.subMerchant.country String No

The three-letter country code of the sub-merchant's address. For example, BRA for Brazil.

  • Format: ISO 3166-1 alpha-3
  • Fixed length: 3 characters
fundRecipient.subMerchant.city String No

The city of the sub-merchant's address.

  • Format: Alphanumeric
  • Maximum length: 13 characters
fundRecipient.shopperName Object No

The name of the shopper.
fundRecipient.shopperName.lastName String Yes

The last name.
fundRecipient.shopperName.firstName String Yes

The first name.
fundRecipient.walletOwnerTaxId String No

The tax identifier of the person receiving the funds.
fundRecipient.IBAN String No

The IBAN of the bank account where the funds are being transferred to.
fundRecipient.billingAddress Object No

The address where to send the invoice.
fundRecipient.billingAddress.postalCode String Yes

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

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.
fundRecipient.billingAddress.country String Yes

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.
fundRecipient.billingAddress.houseNumberOrName String Yes

The number or name of the house. Maximum length: 3000 characters.
fundRecipient.billingAddress.street String Yes

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.
fundRecipient.billingAddress.city String Yes

The name of the city. Maximum length: 3000 characters.
fundRecipient.storedPaymentMethodId String No

This is the recurringDetailReference returned in the response when you created the token.
fundRecipient.telephoneNumber String No

The telephone number of the shopper.
fundRecipient.walletIdentifier String No

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

When true and shopperReference is provided, the payment details will be stored for recurring payments where the shopper is not present, such as subscription or automatic top-up payments.
accountInfo Object No

Shopper account information for 3D Secure 2.

For 3D Secure 2 transactions, we recommend that you include this object to increase the chances of achieving a frictionless flow.
accountInfo.deliveryAddressUsageDate String No

Date the selected delivery address was first used.
accountInfo.passwordChangeIndicator String No

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

  • notApplicable
  • thisTransaction
  • lessThan30Days
  • from30To60Days
  • moreThan60Days

Possible values:

  • "moreThan60Days"
  • "notApplicable"
  • "thisTransaction"
  • "lessThan30Days"
  • "from30To60Days"
accountInfo.accountAgeIndicator String No

Indicator for the length of time since this shopper account was created in the merchant's environment. Allowed values:

  • notApplicable
  • thisTransaction
  • lessThan30Days
  • from30To60Days
  • moreThan60Days

Possible values:

  • "moreThan60Days"
  • "notApplicable"
  • "thisTransaction"
  • "lessThan30Days"
  • "from30To60Days"
accountInfo.addCardAttemptsDay Integer No

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

Date when the shopper's account was created.
accountInfo.purchasesLast6Months Integer No

Number of successful purchases in the last six months.
accountInfo.pastTransactionsDay Integer No

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

Indicator for the length of time since the shopper's account was last updated. Allowed values:

  • thisTransaction
  • lessThan30Days
  • from30To60Days
  • moreThan60Days

Possible values:

  • "moreThan60Days"
  • "thisTransaction"
  • "lessThan30Days"
  • "from30To60Days"
accountInfo.homePhone String No

Shopper's home phone number (including the country code).
accountInfo.deliveryAddressUsageIndicator String No

Indicator for the length of time since this delivery address was first used. Allowed values:

  • thisTransaction
  • lessThan30Days
  • from30To60Days
  • moreThan60Days

Possible values:

  • "moreThan60Days"
  • "thisTransaction"
  • "lessThan30Days"
  • "from30To60Days"
accountInfo.suspiciousActivity Boolean No

Whether suspicious activity was recorded on this account.
accountInfo.workPhone String No

Shopper's work phone number (including the country code).
accountInfo.passwordChangeDate String No

Date when the shopper last changed their password.
accountInfo.paymentAccountIndicator String No

Indicator for the length of time since this payment method was added to this shopper's account. Allowed values:

  • notApplicable
  • thisTransaction
  • lessThan30Days
  • from30To60Days
  • moreThan60Days

Possible values:

  • "moreThan60Days"
  • "notApplicable"
  • "thisTransaction"
  • "lessThan30Days"
  • "from30To60Days"
accountInfo.mobilePhone String No

Shopper's mobile phone number (including the country code).
accountInfo.accountChangeDate String No

Date when the shopper's account was last changed.
accountInfo.accountType String No

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

  • notApplicable
  • credit
  • debit

Possible values:

  • "credit"
  • "notApplicable"
  • "debit"
accountInfo.paymentAccountAge String No

Date this payment method was added to the shopper's account.
accountInfo.pastTransactionsYear Integer No

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

Authentication data produced by an MPI (Mastercard SecureCode, Visa Secure, or Cartes Bancaires).
mpiData.riskScore String No

Risk score calculated by Directory Server (DS). Required for Cartes Bancaires integrations.
mpiData.eci String No

The electronic commerce indicator.
mpiData.cavvAlgorithm String No

The CAVV algorithm used. Include this only for 3D Secure 1.
mpiData.authenticationResponse String No

In 3D Secure 1, the authentication response if the shopper was redirected.

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

Possible values:

  • "A"
  • "N"
  • "Y"
  • "U"
mpiData.directoryResponse String No

In 3D Secure 1, this is the enrollment response from the 3D directory server.

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

Possible values:

  • "D"
  • "C"
  • "R"
  • "A"
  • "N"
  • "I"
  • "Y"
  • "U"
mpiData.threeDSVersion String No

The version of the 3D Secure protocol.
mpiData.challengeCancel String No

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.

Possible values:

  • "07"
  • "06"
  • "05"
  • "04"
  • "03"
  • "02"
  • "01"
mpiData.dsTransID String No

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

Network token authentication verification value (TAVV). The network token cryptogram.
mpiData.xid String No

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

Provides information on why the transStatus field has the specified value. For possible values, refer to our docs.
mpiData.cavv String No

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

The address where to send the invoice.
billingAddress.postalCode String Yes

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

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.
billingAddress.country String Yes

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.
billingAddress.houseNumberOrName String Yes

The number or name of the house. Maximum length: 3000 characters.
billingAddress.street String Yes

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.
billingAddress.city String Yes

The name of the city. Maximum length: 3000 characters.
countryCode String No

The shopper's two-letter country code.
allowedPaymentMethods[] Array No

List of payment methods to be presented to the shopper. To refer to payment methods, use their payment method type.

Example: "allowedPaymentMethods":["ideal","giropay"]
channel String No

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

Possible values:

  • "iOS"
  • "Web"
  • "Android"
amount Object Yes

The amount of the payment.
amount.value Integer Yes

The amount of the transaction, in minor units.
amount.currency String Yes

The three-character ISO currency code.
showInstallmentAmount Boolean No

Set to true to show the payment amount per installment.
splitCardFundingSources Boolean No

Boolean value indicating whether the card payment method should be split into separate debit and credit options.

Default value: false
riskData Object No

Any risk-related settings to apply to the payment.
riskData.customFields Object No

Any custom fields used as part of the input to configured risk rules.
riskData.profileReference String No

The risk profile to assign to this payment. When left empty, the merchant-level account's default risk profile will be applied.
riskData.clientData String No

Contains client-side data, like the device fingerprint, cookies, and specific browser settings.
riskData.fraudOffset Integer No

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

Specifies how payment methods should be filtered based on the 'store' parameter:

  • 'exclusive': Only payment methods belonging to the specified 'store' are returned.
  • 'inclusive': Payment methods from the 'store' and those not associated with any other store are returned.

Possible values:

  • "inclusive"
  • "exclusive"
  • "skipFilter"
dateOfBirth String No

The shopper's date of birth.

Format ISO-8601: YYYY-MM-DD

How to start integrating

  1. Add HTTP Task to your workflow definition.
  2. Search for the API you want to integrate with and click on the name.
    • This loads the API reference documentation and prepares the Http request settings.
  3. Click Test request to test run your request to the API and see the API's response.
All third party trademarks (including logos and icons) are the property of their respective owners, which do not sponsor, authorize, or endorse this website.
Pricing Templates Integrations Blog Contact Us Help
© 2024 SimWorkflow
Terms of Service Privacy Policy