Sample - Adyen Checkout API
POST/payments/details

Submit details for a payment

Submits details for a payment created using /payments. This step is only needed when no final state has been reached on the /payments request, for example when the shopper was redirected to another page to complete the payment.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 4 body fields
Idempotency-Keystringoptional
A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).
authenticationDataobjectoptional
Data for 3DS authentication.
detailsobjectrequired
Use this collection to submit the details that were returned as a result of the `/payments` call.
paymentDatastringoptional
Encoded payment data. For [authorizing a payment after using 3D Secure 2 Authentication-only](https://docs.adyen.com/online-payments/3d-secure/other-3ds-flows/authentication-only/#authorise-the-payment-with-adyen): If you received `resultCode`: **AuthenticationNotRequired** in the `/payments` response, use the `threeDSPaymentData` from the same response. If you received `resultCode`: **AuthenticationFinished** in the `/payments` response, use the `action.paymentData` from the same response.
threeDSAuthenticationOnlybooleandeprecatedoptional
Change the `authenticationOnly` indicator originally set in the `/payments` request. Only needs to be set if you want to modify the value set previously.

6 status codes
200OK - the request has succeeded.
actionobjectoptional
Action to be taken for completing the payment. When returned, only the 3D Secure action is needed in most cases.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first: Go to **Customer Area** > **Developers** > **Additional data**.
amountobjectoptional
Authorised amount in the transaction.
donationTokenstringoptional
Donation Token containing payment details for Adyen Giving.
fraudResultobjectoptional
The fraud result properties of the payment.
merchantReferencestringoptional
The reference used during the /payments request.
orderobjectoptional
Contains updated information regarding the order in case order information was provided in the request.
paymentMethodobjectoptional
Details about the payment method used in the transaction. Only returned if `resultCode` is **Authorised**.
paymentValidationsobjectoptional
The object that contains the validation outcomes. Only returned if `resultCode` is **Authorised** and if you have requested a payment validation in the request.
pspReferencestringoptional
Adyen's 16-character string reference associated with the transaction/request. This value is globally unique; quote it when communicating with us about this request.
refusalReasonstringoptional
If the payment's authorisation is refused or an error occurs during authorisation, this field holds Adyen's mapped reason for the refusal or a description of the error. When a transaction fails, the authorisation response includes `resultCode` and `refusalReason` values. For more information, see [Refusal reasons](https://docs.adyen.com/development-resources/refusal-reasons).
refusalReasonCodestringoptional
Code that specifies the refusal reason. For more information, see [Authorisation refusal reasons](https://docs.adyen.com/development-resources/refusal-reasons).
resultCodestringoptional
The result of the payment. For more information, see [Result codes](https://docs.adyen.com/online-payments/payment-result-codes). Possible values: * **AuthenticationFinished** – The payment has been successfully authenticated with 3D Secure 2. Returned for 3D Secure 2 authentication-only transactions. * **AuthenticationNotRequired** – The transaction does not require 3D Secure authentication. Returned for [standalone authentication-only integrations](https://docs.adyen.com/online-payments/3d-secure/other-3ds-flows/authentication-only). * **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. * **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. * **PartiallyAuthorised** – The payment has been authorised for a partial amount. This happens for card payments when the merchant supports Partial Authorisations and the cardholder has insufficient funds. * **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. * **PresentToShopper** – Indicates that the response contains additional information that you need to present to a shopper, so that they can use it to complete a payment. * **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. * **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. This is a final state.
Allowed:AuthenticationFinishedAuthenticationNotRequiredAuthorisedCancelledChallengeShopperErrorIdentifyShopperPartiallyAuthorisedPendingPresentToShopperReceivedRedirectShopper
shopperLocalestringoptional
The shopperLocale.
threeDS2ResponseDataobjectoptional
Response of the 3D Secure 2 authentication.
threeDS2Resultobjectoptional
Result of the 3D Secure 2 authentication.
threeDSPaymentDatastringoptional
When non-empty, contains a value that you must submit to the `/payments/details` endpoint as `paymentData`.
400Bad Request - a problem reading or understanding the request.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
errorCodestringoptional
The error code mapped to the error message.
errorTypestringoptional
The category of the error.
messagestringoptional
A short explanation of the issue.
pspReferencestringoptional
The PSP reference of the payment.
statusintegeroptional
The HTTP response status.
401Unauthorized - authentication required.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
errorCodestringoptional
The error code mapped to the error message.
errorTypestringoptional
The category of the error.
messagestringoptional
A short explanation of the issue.
pspReferencestringoptional
The PSP reference of the payment.
statusintegeroptional
The HTTP response status.
403Forbidden - insufficient permissions to process the request.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
errorCodestringoptional
The error code mapped to the error message.
errorTypestringoptional
The category of the error.
messagestringoptional
A short explanation of the issue.
pspReferencestringoptional
The PSP reference of the payment.
statusintegeroptional
The HTTP response status.
422Unprocessable Entity - a request validation error.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
errorCodestringoptional
The error code mapped to the error message.
errorTypestringoptional
The category of the error.
messagestringoptional
A short explanation of the issue.
pspReferencestringoptional
The PSP reference of the payment.
statusintegeroptional
The HTTP response status.
500Internal Server Error - the server could not process the request.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
errorCodestringoptional
The error code mapped to the error message.
errorTypestringoptional
The category of the error.
messagestringoptional
A short explanation of the issue.
pspReferencestringoptional
The PSP reference of the payment.
statusintegeroptional
The HTTP response status.

Error handling

A 400 is returned: Bad Request - a problem reading or understanding the request. A 401 is returned: Unauthorized - authentication required. A 403 is returned: Forbidden - insufficient permissions to process the request. A 422 is returned: Unprocessable Entity - a request validation error. A 500 is returned: Internal Server Error - the server could not process the request.