diff --git a/specs/3.0/CheckoutService-v41.yaml b/specs/3.0/CheckoutService-v41.yaml index 1792a60..66ef472 100644 --- a/specs/3.0/CheckoutService-v41.yaml +++ b/specs/3.0/CheckoutService-v41.yaml @@ -7,10 +7,10 @@ info: description: |- Adyen Checkout API provides a simple and flexible way to initiate and authorise online payments. You can use the same integration for payments made with cards (including One-Click and 3D Secure), mobile wallets, and local payment methods (e.g. iDEAL and Sofort). - This API reference provides information on available endpoints and how to interact with them. To learn more about the API, visit [Checkout documentation](https://docs.adyen.com/developers/checkout). + This API reference provides information on available endpoints and how to interact with them. To learn more about the API, visit [Checkout documentation](https://docs.adyen.com/checkout). ## Authentication - Each request to the Checkout API must be signed with an API key. For this, obtain an API Key from your Customer Area, as described in [How to get the API key](https://docs.adyen.com/developers/user-management/how-to-get-the-api-key). Then set this key to the `X-API-Key` header value, for example: + Each request to the Checkout API must be signed with an API key. For this, obtain an API Key from your Customer Area, as described in [How to get the API key](https://docs.adyen.com/user-management/how-to-get-the-api-key). Then set this key to the `X-API-Key` header value, for example: ``` curl @@ -18,7 +18,7 @@ info: -H "X-API-Key: Your_Checkout_API_key" \ ... ``` - Note that when going live, you need to generate a new API Key to access the [live endpoints](https://docs.adyen.com/developers/development-resources/live-endpoints). + Note that when going live, you need to generate a new API Key to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints). ## Versioning Checkout API supports versioning of its endpoints through a version suffix in the endpoint URL. This suffix has the following format: "vXX", where XX is the version number. @@ -27,7 +27,7 @@ info: ``` https://checkout-test.adyen.com/v41/payments ``` - termsOfService: 'https://www.adyen.com/platform/terms-and-conditions' + termsOfService: 'https://www.adyen.com/legal/terms-and-conditions' contact: name: Adyen Support url: 'https://support.adyen.com/' @@ -73,7 +73,7 @@ paths: description: |- Provides the data object that can be used to start the Checkout SDK. To set up the payment, pass its amount, currency, and other required parameters. We use this to optimise the payment flow and perform better risk assessment of the transaction. - For more information, refer to [How it works](https://docs.adyen.com/developers/checkout#howitworks). + For more information, refer to [How it works](https://docs.adyen.com/checkout#howitworks). x-groupName: SDK Integration x-sortIndex: 1 requestBody: @@ -168,7 +168,7 @@ paths: description: |- Verifies the payment result using the payload returned from the Checkout SDK. - For more information, refer to [How it works](https://docs.adyen.com/developers/checkout#howitworks). + For more information, refer to [How it works](https://docs.adyen.com/checkout#howitworks). x-groupName: SDK Integration x-sortIndex: 2 requestBody: @@ -199,7 +199,7 @@ components: properties: accountAgeIndicator: description: |- - Indicator of how long this shopper account exists in the merchant's environment. + Indicator for the length of time since this shopper account was created in the merchant's environment. Allowed values: * notApplicable * thisTransaction @@ -219,7 +219,7 @@ components: type: string accountChangeIndicator: description: |- - Indicator when the shopper's account was last changed. + Indicator for the length of time since the shopper's account was last updated. Allowed values: * thisTransaction * lessThan30Days @@ -245,7 +245,7 @@ components: type: string deliveryAddressUsageIndicator: description: |- - Indicator for when this delivery address was last used. + Indicator for the length of time since this delivery address was last used. Allowed values: * thisTransaction * lessThan30Days @@ -264,7 +264,7 @@ components: description: Shopper's mobile phone number (including the country code). type: string passwordChangeDate: - description: Date when the shopper has changed their password. + description: Date when the shopper last changed their password. format: date-time type: string passwordChangeIndicator: @@ -284,11 +284,11 @@ components: - moreThan60Days type: string pastTransactionsDay: - description: Number of transactions of this shopper in the past 24 hours. + description: Number of all transactions (successful and abandoned) from this shopper in the past 24 hours. format: int32 type: integer pastTransactionsYear: - description: Number of transactions of this shopper in the past year. + description: Number of all transactions (successful and abandoned) from this shopper in the past year. format: int32 type: integer paymentAccountAge: @@ -297,7 +297,7 @@ components: type: string paymentAccountIndicator: description: |- - Indicator for the amount of time this payment method was enrolled with this account. + Indicator for the length of time since this payment method was added to this shopper's account. Allowed values: * notApplicable * thisTransaction @@ -312,7 +312,7 @@ components: - moreThan60Days type: string purchasesLast6Months: - description: Number of purchases in the last 6 months. + description: Number of successful purchases in the last six months. format: int32 type: integer suspiciousActivity: @@ -340,7 +340,6 @@ components: description: |- 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. type: string stateOrProvince: description: |- @@ -359,7 +358,7 @@ components: Amount: properties: currency: - description: 'The three-character [ISO currency code](https://docs.adyen.com/developers/development-resources/currency-codes).' + description: 'The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).' maxLength: 3 minLength: 3 type: string @@ -367,7 +366,7 @@ components: description: |- 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](https://docs.adyen.com/developers/development-resources/currency-codes). + The transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/development-resources/currency-codes). format: int64 type: integer required: @@ -442,14 +441,17 @@ components: minLength: 10 type: string colorDepth: - description: The color depth of the shopper's device in bits per pixel. Should be obtained by using the browser's screen.colorDepth property. + description: 'The color depth of the shopper''s browser in bits per pixel. This should be obtained by using the browser''s `screen.colorDepth` property. Accepted values: 1, 4, 8, 15, 16, 24, 32 or 48 bit color depth.' format: int32 type: integer javaEnabled: description: Boolean value indicating if the shopper's browser is able to execute Java. type: boolean + javaScriptEnabled: + description: Boolean value indicating if the shopper's browser is able to execute JavaScript. A default 'true' value is assumed if the field is not present. + type: boolean language: - description: The navigator.language value of the shopper's browser (as defined in IETF BCP 47). + description: The `navigator.language` value of the shopper's browser (as defined in IETF BCP 47). type: string screenHeight: description: The total height of the shopper's device screen in pixels. @@ -481,11 +483,11 @@ components: properties: cvc: description: |- - The [card verification code](https://docs.adyen.com/developers/payment-glossary#cardsecuritycodecvccvvcid) (1-20 characters). Depending on the card brand, it is known also as: + The [card verification code](https://docs.adyen.com/payments-essentials/payment-glossary#card_security_code_cvc_cvv_cid_) (1-20 characters). Depending on the card brand, it is known also as: * CVV2/CVC2 – length: 3 digits * CID – length: 4 digits - > If you are using [Client-Side Encryption](https://docs.adyen.com/developers/features/client-side-encryption), the CVC code is present in the encrypted data. You must never post the card details to the server. - > This field must be always present in a [one-click payment request](https://docs.adyen.com/developers/classic-integration/recurring-payments). + > If you are using [Client-Side Encryption](https://docs.adyen.com/classic-integration/cse-integration-ecommerce), the CVC code is present in the encrypted data. You must never post the card details to the server. + > This field must be always present in a [one-click payment request](https://docs.adyen.com/classic-integration/recurring-payments). > When this value is returned in a response, it is always empty because it is not stored. maxLength: 20 minLength: 1 @@ -577,7 +579,7 @@ components: - REQUIRED type: string installments: - description: 'Describes the configuration for [installment payments](https://docs.adyen.com/developers/payment-methods/installment-payments).' + description: 'Describes the configuration for [installment payments](https://docs.adyen.com/payment-methods/installment-payments).' $ref: '#/components/schemas/Installments' shopperInput: description: Determines how to display the details fields. @@ -590,19 +592,34 @@ components: paymentData: description: The `paymentData` value that you received in the response to the `/payments` call. type: string + threeDSAuthenticationOnly: + description: Change the `authenticationOnly` indicator originally set in the `/payments` request. Only needs to be set if you want to modify the value set previously. + type: boolean required: - details DeviceRenderOptions: properties: sdkInterface: - description: Supported SDK interface types. + description: |- + Supported SDK interface types. + Allowed values: + * Native + * Html + * both enum: - Html - Native - both type: string sdkUiType: - description: UI types supported for displaying specific challenges. + description: |- + UI types supported for displaying specific challenges. + Allowed values: + * text + * singleSelect + * outOfBand + * otherHtml + * multiSelect items: enum: - multiSelect @@ -706,21 +723,12 @@ components: key: description: The value to provide in the result. type: string - name: - description: 'The default name for this input field, which will be displayed by the SDKs.' - type: string optional: description: True if this input value is optional. type: boolean type: description: The type of the required input. type: string - validationType: - description: The type of validation to be applied to the input value. - enum: - - IBAN - - Name - type: string value: description: 'The value can be pre-filled, if available.' type: string @@ -833,10 +841,10 @@ components: format: date-time type: string preOrderPurchase: - description: Whether this transaction is for pre-ordering a product. + description: Indicator for whether this transaction is for pre-ordering a product. type: boolean reorderItems: - description: Whether the shopper has already purchased the same items in the past. + description: Indicator for whether the shopper has already purchased the same items in the past. type: boolean Name: properties: @@ -921,18 +929,18 @@ components: description: |- 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](https://docs.adyen.com/developers/api-reference/payments-api#paymentrequestadditionaldata). + 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](https://docs.adyen.com/api-reference/payments-api#paymentrequestadditionaldata). type: object allowedPaymentMethods: - description: 'List of payments methods to be presented to the shopper. To refer to payment methods, use their `brandCode` from [Payment methods overview](https://docs.adyen.com/developers/payment-methods/payment-methods-overview).' + description: 'List of payments methods to be presented to the shopper. To refer to payment methods, use their `brandCode` from [Payment methods overview](https://docs.adyen.com/payment-methods/payment-methods-overview).' items: type: string type: array amount: - description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).' + description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).' $ref: '#/components/schemas/Amount' blockedPaymentMethods: - description: 'List of payments methods to be hidden from the shopper. To refer to payment methods, use their `brandCode` from [Payment methods overview](https://docs.adyen.com/developers/payment-methods/payment-methods-overview).' + description: 'List of payments methods to be hidden from the shopper. To refer to payment methods, use their `brandCode` from [Payment methods overview](https://docs.adyen.com/payment-methods/payment-methods-overview).' items: type: string type: array @@ -984,22 +992,28 @@ components: PaymentRequest: properties: accountInfo: - description: Shopper account information for 3D Secure 2. + description: |- + 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. $ref: '#/components/schemas/AccountInfo' additionalData: description: |- 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](https://docs.adyen.com/developers/api-reference/payments-api#paymentrequestadditionaldata). + 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](https://docs.adyen.com/api-reference/payments-api#paymentrequestadditionaldata). type: object amount: - description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).' + description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).' $ref: '#/components/schemas/Amount' billingAddress: - description: The address where to send the invoice. + description: |- + The address where to send the invoice. + > For 3D Secure 2 transactions, schemes require the `billingAddress` for both `deviceChannel` **browser** and **app**. Include all of the fields within this object. $ref: '#/components/schemas/Address' browserInfo: - description: The shopper's browser information. + description: |- + The shopper's browser information. + > For 3D Secure 2 transactions, `browserInfo` is required for `channel` **web** (or `deviceChannel` **browser**). $ref: '#/components/schemas/BrowserInfo' captureDelayHours: description: 'The delay between the authorisation and scheduled auto-capture, specified in hours.' @@ -1051,7 +1065,7 @@ components: format: date-time type: string deviceFingerprint: - description: 'A string containing the shopper''s device fingerprint. For more information, refer to [Device fingerprinting](https://docs.adyen.com/developers/risk-management/device-fingerprinting).' + description: 'A string containing the shopper''s device fingerprint. For more information, refer to [Device fingerprinting](https://docs.adyen.com/risk-management/device-fingerprinting).' type: string enableOneClick: description: 'When true and `shopperReference` is provided, the shopper will be asked if the payment details should be stored for future one-click payments.' @@ -1073,7 +1087,7 @@ components: format: int32 type: integer installments: - description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/developers/payment-methods/installment-payments).' + description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/payment-methods/installment-payments).' $ref: '#/components/schemas/Installments' lineItems: description: Line items regarding the payment. @@ -1086,31 +1100,33 @@ components: merchantAccount: description: 'The merchant account identifier, with which you want to process the transaction.' type: string - merchantData: - description: | - Holds different merchant data points like product, purchase, customer, and so on. It takes data in a JSON string. - type: string merchantOrderReference: description: |- - This reference allows linking multiple transactions to each other. + 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`. type: string merchantRiskIndicator: - description: Additional risk fields for 3D Secure 2. + description: |- + Additional risk fields 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. $ref: '#/components/schemas/MerchantRiskIndicator' metadata: description: |- Metadata consists of entries, each of which includes a key and a value. Limitations: Error "177", "Metadata size exceeds limit" type: object + mpiData: + description: Authentication data produced by an MPI (Mastercard SecureCode or Verified By Visa). + $ref: '#/components/schemas/ThreeDSecureData' orderReference: description: '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 `merchantOrderReference`instead.' type: string origin: description: |- - Required for the 3DS2.0 Web integration. + Required for the 3D Secure 2 `channel` **Web** integration. - Set this parameter to the origin URL of the page that you are loading the SDK from. + Set this parameter to the origin URL of the page that you are loading the 3D Secure Component from. type: string paymentMethod: description: The collection that contains the type of the payment method and its specific information (e.g. `idealIssuer`). @@ -1146,7 +1162,9 @@ components: description: The maximum validity of the session. type: string shopperEmail: - description: 'The shopper''s email address. We recommend that you provide this data, as it is used in velocity fraud checks.' + description: |- + The shopper's email address. We recommend that you provide this data, as it is used in velocity fraud checks. + > For 3D Secure 2 transactions, schemes require the `shopperEmail` for both `deviceChannel` **browser** and **app**. type: string shopperIP: description: |- @@ -1241,27 +1259,33 @@ components: When a transaction fails, the authorisation response includes `resultCode` and `refusalReason` values. type: string refusalReasonCode: - description: 'Code that specifies the refusal reason. For more information, see [Authorisation refusal reasons](https://docs.adyen.com/developers/development-resources/response-handling#authorisationrefusalreasons).' + description: 'Code that specifies the refusal reason. For more information, see [Authorisation refusal reasons](https://docs.adyen.com/development-resources/refusal-reasons).' type: string resultCode: - description: |- + description: | The result of the payment. Possible values: - * **Authorised** – Indicates the payment authorisation was successfully completed. This state serves as an indicator to proceed with the delivery of goods and services. This is a final state. - * **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. This is a final state. - * **RedirectShopper** – Indicates the shopper should be redirected to an external web page or app to complete the authorisation. - * **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments. + * **AuthenticationFinished** – The payment has been successfully authenticated with 3D Secure 2. Returned for 3D Secure 2 authentication-only transactions. + * **Authorised** – The payment was successfully authorised. This state serves as an indicator to proceed with the delivery of goods and services. This is a final state. * **Cancelled** – Indicates the payment has been cancelled (either by the shopper or the merchant) before processing was completed. This is a final state. - * **Pending** – Indicates that it is not possible to obtain the final status of the payment. This can happen if the systems providing final status information for the payment are unavailable, or if the shopper needs to take further action to complete the payment. For more information on handling a pending payment, refer to [Payments with pending status](https://docs.adyen.com/developers/development-resources/payments-with-pending-status). - * **Error** – Indicates an error occurred during processing of the payment. The reason is given in the `refusalReason` field. This is a final state. + * **ChallengeShopper** – The issuer requires further shopper interaction before the payment can be authenticated. Returned for 3D Secure 2 transactions. + * **Error** – There was an error when the payment was being processed. The reason is given in the `refusalReason` field. This is a final state. + * **IdentifyShopper** – The issuer requires the shopper's device fingerprint before the payment can be authenticated. Returned for 3D Secure 2 transactions. + * **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. This is a final state. + * **Pending** – Indicates that it is not possible to obtain the final status of the payment. This can happen if the systems providing final status information for the payment are unavailable, or if the shopper needs to take further action to complete the payment. For more information on handling a pending payment, refer to [Payments with pending status](https://docs.adyen.com/development-resources/payments-with-pending-status). + * **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments. + * **RedirectShopper** – Indicates the shopper should be redirected to an external web page or app to complete the authorisation. enum: + - AuthenticationFinished - Authorised - - PartiallyAuthorised - - Refused - - Error - Cancelled + - ChallengeShopper + - Error + - IdentifyShopper + - Pending - Received - RedirectShopper + - Refused type: string PaymentSetupRequest: properties: @@ -1269,21 +1293,23 @@ components: description: |- 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](https://docs.adyen.com/developers/api-reference/payments-api#paymentrequestadditionaldata). + 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](https://docs.adyen.com/api-reference/payments-api#paymentrequestadditionaldata). type: object allowedPaymentMethods: - description: 'List of payments methods to be presented to the shopper. To refer to payment methods, use their `brandCode` from [Payment methods overview](https://docs.adyen.com/developers/payment-methods/payment-methods-overview).' + description: 'List of payments methods to be presented to the shopper. To refer to payment methods, use their `brandCode` from [Payment methods overview](https://docs.adyen.com/payment-methods/payment-methods-overview).' items: type: string type: array amount: - description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).' + description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).' $ref: '#/components/schemas/Amount' billingAddress: - description: The address where to send the invoice. + description: |- + The address where to send the invoice. + > For 3D Secure 2 transactions, schemes require the `billingAddress` for both `deviceChannel` **browser** and **app**. Include all of the fields within this object. $ref: '#/components/schemas/Address' blockedPaymentMethods: - description: 'List of payments methods to be hidden from the shopper. To refer to payment methods, use their `brandCode` from [Payment methods overview](https://docs.adyen.com/developers/payment-methods/payment-methods-overview).' + description: 'List of payments methods to be hidden from the shopper. To refer to payment methods, use their `brandCode` from [Payment methods overview](https://docs.adyen.com/payment-methods/payment-methods-overview).' items: type: string type: array @@ -1359,7 +1385,7 @@ components: format: int32 type: integer installments: - description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/developers/payment-methods/installment-payments).' + description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/payment-methods/installment-payments).' $ref: '#/components/schemas/Installments' lineItems: description: Line items regarding the payment. @@ -1372,13 +1398,10 @@ components: merchantAccount: description: 'The merchant account identifier, with which you want to process the transaction.' type: string - merchantData: - description: | - Holds different merchant data points like product, purchase, customer, and so on. It takes data in a JSON string. - type: string merchantOrderReference: description: |- - This reference allows linking multiple transactions to each other. + 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`. type: string metadata: @@ -1411,7 +1434,9 @@ components: description: The maximum validity of the session. type: string shopperEmail: - description: 'The shopper''s email address. We recommend that you provide this data, as it is used in velocity fraud checks.' + description: |- + The shopper's email address. We recommend that you provide this data, as it is used in velocity fraud checks. + > For 3D Secure 2 transactions, schemes require the `shopperEmail` for both `deviceChannel` **browser** and **app**. type: string shopperIP: description: |- @@ -1513,27 +1538,33 @@ components: When a transaction fails, the authorisation response includes `resultCode` and `refusalReason` values. type: string refusalReasonCode: - description: 'Code that specifies the refusal reason. For more information, see [Authorisation refusal reasons](https://docs.adyen.com/developers/development-resources/response-handling#authorisationrefusalreasons).' + description: 'Code that specifies the refusal reason. For more information, see [Authorisation refusal reasons](https://docs.adyen.com/development-resources/refusal-reasons).' type: string resultCode: - description: |- + description: | The result of the payment. Possible values: - * **Authorised** – Indicates the payment authorisation was successfully completed. This state serves as an indicator to proceed with the delivery of goods and services. This is a final state. - * **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. This is a final state. - * **RedirectShopper** – Indicates the shopper should be redirected to an external web page or app to complete the authorisation. - * **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments. + * **AuthenticationFinished** – The payment has been successfully authenticated with 3D Secure 2. Returned for 3D Secure 2 authentication-only transactions. + * **Authorised** – The payment was successfully authorised. This state serves as an indicator to proceed with the delivery of goods and services. This is a final state. * **Cancelled** – Indicates the payment has been cancelled (either by the shopper or the merchant) before processing was completed. This is a final state. - * **Pending** – Indicates that it is not possible to obtain the final status of the payment. This can happen if the systems providing final status information for the payment are unavailable, or if the shopper needs to take further action to complete the payment. For more information on handling a pending payment, refer to [Payments with pending status](https://docs.adyen.com/developers/development-resources/payments-with-pending-status). - * **Error** – Indicates an error occurred during processing of the payment. The reason is given in the `refusalReason` field. This is a final state. + * **ChallengeShopper** – The issuer requires further shopper interaction before the payment can be authenticated. Returned for 3D Secure 2 transactions. + * **Error** – There was an error when the payment was being processed. The reason is given in the `refusalReason` field. This is a final state. + * **IdentifyShopper** – The issuer requires the shopper's device fingerprint before the payment can be authenticated. Returned for 3D Secure 2 transactions. + * **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. This is a final state. + * **Pending** – Indicates that it is not possible to obtain the final status of the payment. This can happen if the systems providing final status information for the payment are unavailable, or if the shopper needs to take further action to complete the payment. For more information on handling a pending payment, refer to [Payments with pending status](https://docs.adyen.com/development-resources/payments-with-pending-status). + * **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments. + * **RedirectShopper** – Indicates the shopper should be redirected to an external web page or app to complete the authorisation. enum: + - AuthenticationFinished - Authorised - - PartiallyAuthorised - - Refused - - Error - Cancelled + - ChallengeShopper + - Error + - IdentifyShopper + - Pending - Received - RedirectShopper + - Refused type: string serviceError: description: The type of the error. @@ -1551,10 +1582,10 @@ components: description: |- 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)](https://docs.adyen.com/developers/payment-glossary#cardsecuritycodecvccvvcid). - * `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/developers/payment-glossary#cardnotpresentcnp). + * `ONECLICK` – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/payments-essentials/payment-glossary#card_security_code_cvc_cvv_cid_). + * `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/payment-glossary#cardnotpresentcnp). * `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](https://docs.adyen.com/developers/features/third-party-payouts). + * `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/features/third-party-payouts). enum: - ONECLICK - RECURRING @@ -1727,7 +1758,7 @@ components: properties: currency: description: |- - The three-character [ISO currency code](https://docs.adyen.com/developers/development-resources/currency-codes). + The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes). If this value is not provided, the currency in which the payment is made will be used. maxLength: 3 @@ -1737,7 +1768,7 @@ components: description: |- 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](https://docs.adyen.com/developers/development-resources/currency-codes). + The transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/development-resources/currency-codes). format: int64 type: integer required: @@ -1778,7 +1809,7 @@ components: ThreeDS2RequestData: properties: authenticationOnly: - description: 'If set to true, you will only do the 3D Secure 2 authentication, not the payment authorization.' + description: 'If set to true, you will only perform the [3D Secure 2 authentication](https://docs.adyen.com/checkout/3d-secure-2/3ds2-checkout-authentication-only-integration), and not the payment authorisation.' type: boolean challengeIndicator: description: | @@ -1800,30 +1831,30 @@ components: * `browser` type: string deviceRenderOptions: - description: Display options for the 3D Secure 2 SDK. Only for `deviceChannel` set to **app**. + description: |- + Display options for the 3D Secure 2 SDK. + Required for `deviceChannel` **app**. $ref: '#/components/schemas/DeviceRenderOptions' messageVersion: description: The `messageVersion` value indicating the 3D Secure 2 protocol version. type: string notificationURL: - description: |- - URL the `CRes` value will be sent. - Only for `deviceChannel` set to **browser**. + description: URL to where the issuer should send the `CRes`. Required if you are not using components for `channel` **Web** or if you are using classic integration `deviceChannel` **browser**. type: string sdkAppID: description: |- The `sdkAppID` value as received from the 3D Secure 2 SDK. - Only for `deviceChannel` set to **app**. + Required for `deviceChannel` set to **app**. type: string sdkEncData: description: |- The `sdkEncData` value as received from the 3D Secure 2 SDK. - Only for `deviceChannel` set to **app**. + Required for `deviceChannel` set to **app**. type: string sdkEphemPubKey: description: |- The `sdkEphemPubKey` value as received from the 3D Secure 2 SDK. - Only for `deviceChannel` set to **app**. + Required for `deviceChannel` set to **app**. $ref: '#/components/schemas/SDKEphemPubKey' sdkMaxTimeout: description: |- @@ -1841,11 +1872,14 @@ components: The `sdkTransID` value as received from the 3D Secure 2 SDK. Only for `deviceChannel` set to **app**. type: string + threeDSCompInd: + description: Completion indicator for the device fingerprinting. + type: string threeDSRequestorID: - description: Unique 3D Secure requestor identifier assigned by the Directory Server. + description: 'Required for [authentication-only integration](https://docs.adyen.com/checkout/3d-secure-2/3ds2-checkout-authentication-only-integration) for Visa. Unique 3D Secure requestor identifier assigned by the Directory Server when you enrol for 3D Secure 2.' type: string threeDSRequestorName: - description: Unique 3D Secure requestor name assigned by the Directory Server. + description: 'Required for [authentication-only integration](https://docs.adyen.com/checkout/3d-secure-2/3ds2-checkout-authentication-only-integration) for Visa. Unique 3D Secure requestor name assigned by the Directory Server when you enrol for 3D Secure 2.' type: string threeDSRequestorURL: description: URL of the (customer service) website that will be shown to the shopper in case of technical errors during the 3D Secure 2 process. @@ -1891,9 +1925,6 @@ components: description: The version of the 3D Secure protocol. type: string xid: - description: |- - The transaction identifier (Base64-encoded, 20 bytes in a decoded form). - - In 3D Secure 2, this is the `threeDSServerTransID`. + description: 'Supported for 3D Secure 1. The transaction identifier (Base64-encoded, 20 bytes in a decoded form).' format: byte type: string