{ "openapi" : "3.1.0", "info" : { "title" : "Account-to-Account (A2A) payments API", "description" : "The A2A payments API provides endpoints for A2A payment flows, enabling issuers to facilitate direct payments through Adyen for users with an Adyen business account.\n\nWith these endpoints, you can:\n- **Retrieve payment details**: Retrieve transaction information for specific payments.\n- **Confirm payments**: Confirm payments with Strong Customer Authentication (SCA).\n- **Cancel payments**: Cancel pending transactions.\n\n## Authentication\nEach request made to the A2A Payments API must be signed with an API key. Generate an API key in your Customer Area.\n\nTo connect to the API, add an `X-API-Key` header with the API key as the value, for example:\n\n ```\ncurl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\" \\\n...\n```\n\n## Roles and permissions\nTo use the A2A Payments API, your API credential must have the following roles:\n- **Role for A2A Issuer payments - API**\n\nReach out to your Adyen contact to set up these roles.\n## Going live\nWhen going live, generate an API key in your [live Customer Area](https://ca-live.adyen.com/ca). You can then use the API key to send requests to `https://balanceplatform-api-live.adyen.com/a2aissuer-api/v{version}/payments`.\n\n", "termsOfService" : "https://www.adyen.com/legal/terms-and-conditions", "contact" : { "name" : "Adyen Developer Experience team", "url" : "https://github.com/Adyen/adyen-openapi" }, "version" : "1" }, "servers" : [ { "url" : "https://balanceplatform-api-test.adyen.com/a2aissuer-api/v1", "description" : "Test Environment" }, { "url" : "https://balanceplatform-api-live.adyen.com/a2aissuer-api/v1", "description" : "Live Environment" } ], "tags" : [ { "name" : "Payments", "x-groupIndex" : 1 }, { "name" : "iDEAL profiles", "x-groupIndex" : 2 } ], "paths" : { "/ideal/profile/auth-link" : { "post" : { "tags" : [ "iDEAL profiles" ], "summary" : "Manage an iDEAL profile", "description" : "Manage an already registered iDEAL profile. Generates a redirection URL to manage the iDEAL profile linked to the account holder from the request.", "operationId" : "post-ideal-profile-auth-link", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdealAuthLinkRequest" }, "examples" : { "Manage iDEAL profile request" : { "summary" : "Requests generating a link to manage the iDEAL profile linked to an account holder.", "description" : "Specifies the account holder linked to the iDEAL profile to be managed.", "value" : { "accountHolderId" : "AH00000000000000000000000" } } } } }, "required" : true }, "responses" : { "200" : { "description" : "OK - The request has succeeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdealAuthLinkResponse" }, "examples" : { "Manage iDEAL profile response" : { "summary" : "Redirect URL to manage the iDEAL profile.", "description" : "Specifies the redirect URL the user must be redirected to, to manage their iDEAL profile.", "value" : { "redirectUrl" : { "href" : "https://ideal.auth/someUrl" } } } } } } }, "400" : { "description" : "Bad Request - The request is malformed or is not the expected format.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "00_400" : { "summary" : "00_400 - Bad request", "description" : "Bad request, tunable to map the request body", "value" : { "type" : "https://docs.adyen.com/errors/bad-request", "errorCode" : "00_400", "title" : "Bad request", "detail" : "Unable to map request body", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 400 } } } } } }, "422" : { "description" : "Unprocessable Entity - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "1069_008" : { "summary" : "1069_008 - iDEAL profile not found", "description" : "Unprocessable entity, the received account holder does not have an iDEAL profile registered.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_008", "title" : "No iDEAL profile is registered. Register a profile before continuing", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "29_001" : { "summary" : "29_001 - Request has missing or invalid fields.", "description" : "Unprocessable entity, request has missing or invalid fields.", "value" : { "type" : "https://docs.adyen.com/errors/validation", "errorCode" : "29_001", "title" : "The request is missing required fields or contains invalid data.", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422, "invalidFields" : [ { "name" : "payload", "value" : "null", "message" : "must not be null" } ] } }, "30_012" : { "summary" : "30_012 - Account holder not found", "description" : "Not found, the requested account holder could not be not found.", "value" : { "type" : "https://docs.adyen.com/errors/unprocessable-entity/", "errorCode" : "30_012", "title" : "Account holder not found", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } } } } } }, "500" : { "description" : "Internal Service Error - An unrecoverable error occurred while trying to perform the request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "1069_001" : { "summary" : "1069_001 - Internal error.", "description" : "Internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_001", "title" : "An unexpected internal error has occurred", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } }, "1069_002" : { "summary" : "1069_002 - Internal error in the payment method.", "description" : "Internal error, payment method returned an internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_002", "title" : "The payment method returned an error", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } } } } } } }, "x-methodName" : "authLink", "x-sortIndex" : 2 } }, "/ideal/profile/authenticate" : { "post" : { "tags" : [ "iDEAL profiles" ], "summary" : "Authenticate iDEAL profile", "description" : "Generates an redirection URL to finish the authentication flow when requested by iDEAL. Before calling this endpoint, make sure that your user has completed multi-factor authentication.", "operationId" : "post-ideal-profile-authenticate", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdealAuthenticateRequest" }, "examples" : { "Authenticate iDEAL profile request" : { "summary" : "Requests completing an iDEAL profile authentication.", "description" : "Specifies the account holder that has authenticated and the payload this authentication is for.", "value" : { "accountHolderId" : "AH00000000000000000000000", "payload" : "https://ideal.auth/somePayload" } } } } }, "required" : true }, "responses" : { "200" : { "description" : "OK - The request has succeeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdealAuthenticateResponse" }, "examples" : { "Authenticate iDEAL profile response" : { "summary" : "Redirect URL to finish iDEAL profile authentication", "description" : "Specifies the redirect URL the user must be redirected to, to complete the iDEAL authentication flow.", "value" : { "redirectUrl" : { "href" : "https://ideal.auth/someUrl" } } } } } } }, "400" : { "description" : "Bad Request - The request is malformed or is not the expected format.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "00_400" : { "summary" : "00_400 - Bad request", "description" : "Bad request, tunable to map the request body", "value" : { "type" : "https://docs.adyen.com/errors/bad-request", "errorCode" : "00_400", "title" : "Bad request", "detail" : "Unable to map request body", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 400 } } } } } }, "422" : { "description" : "Unprocessable Entity - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "1069_008" : { "summary" : "1069_008 - iDEAL profile not found", "description" : "Unprocessable entity, the received account holder does not have an iDEAL profile registered.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_008", "title" : "No iDEAL profile is registered. Register a profile before continuing", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "1069_009" : { "summary" : "1069_009 - iDEAL authenticate payload expired", "description" : "Unprocessable entity, the iDEAL authenticate payload has expired and is no longer available.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_009", "title" : "iDEAL authenticate payload has expired and is no longer available", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "30_012" : { "summary" : "30_012 - Account holder not found", "description" : "Not found, the requested account holder could not be not found.", "value" : { "type" : "https://docs.adyen.com/errors/unprocessable-entity/", "errorCode" : "30_012", "title" : "Account holder not found", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } } } } } }, "500" : { "description" : "Internal Service Error - An unrecoverable error occurred while trying to perform the request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "1069_001" : { "summary" : "1069_001 - Internal error.", "description" : "Internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_001", "title" : "An unexpected internal error has occurred", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } }, "1069_002" : { "summary" : "1069_002 - Internal error in the payment method.", "description" : "Internal error, payment method returned an internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_002", "title" : "The payment method returned an error", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } } } } } } }, "x-methodName" : "authenticateUser", "x-sortIndex" : 3 } }, "/ideal/profile/register" : { "post" : { "tags" : [ "iDEAL profiles" ], "summary" : "Register an iDEAL profile", "description" : "Register a new iDEAL profile. The profile is linked to the account holder and payment instruments included in the request. The user must be redirected to the URL in the response to finish their IDEAL profile registration.", "operationId" : "post-ideal-profile-register", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProfileRegistrationRequest" }, "examples" : { "Register iDEAL profile request" : { "summary" : "Request registering an iDEAL profile linked to an account holder and payment instruments.", "description" : "Specifies the account holder and payment instruments for registering an iDEAL profile.", "value" : { "accountHolderId" : "AH00000000000000000000000", "paymentInstrumentIds" : [ "PI00000000000000000000000", "PI11111111111111111111111" ] } } } } }, "required" : true }, "responses" : { "200" : { "description" : "OK - The request has succeeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProfileRegistrationResponse" }, "examples" : { "Register iDEAL profile response" : { "summary" : "Redirect URL to finish iDEAL profile registration.", "description" : "Specifies the redirect URL the user must be redirected to, to finish the iDEAL profile registration.", "value" : { "redirectUrl" : { "href" : "https://ideal.auth/someUrl" } } } } } } }, "400" : { "description" : "Bad Request - The request is malformed or is not the expected format.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "00_400" : { "summary" : "00_400 - Bad request", "description" : "Bad request, tunable to map the request body", "value" : { "type" : "https://docs.adyen.com/errors/bad-request", "errorCode" : "00_400", "title" : "Bad request", "detail" : "Unable to map request body", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 400 } } } } } }, "422" : { "description" : "Unprocessable Entity - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "1069_007" : { "summary" : "1069_007 - iDEAL profile already registered", "description" : "Unprocessable entity, the received account holder already has an iDEAL profile registered.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_007", "title" : "A iDEAL profile is already registered", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "29_001" : { "summary" : "29_001 - Request has missing or invalid fields.", "description" : "Unprocessable entity, request has missing or invalid fields.", "value" : { "type" : "https://docs.adyen.com/errors/validation", "errorCode" : "29_001", "title" : "The request is missing required fields or contains invalid data.", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422, "invalidFields" : [ { "name" : "payload", "value" : "null", "message" : "must not be null" } ] } }, "30_012" : { "summary" : "30_012 - Account holder not found", "description" : "Not found, the requested account holder could not be not found.", "value" : { "type" : "https://docs.adyen.com/errors/unprocessable-entity/", "errorCode" : "30_012", "title" : "Account holder not found", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "30_032" : { "summary" : "30_032 - Payment instrument not found", "description" : "Not found, the requested payment instrument could not be not found.", "value" : { "type" : "https://docs.adyen.com/errors/unprocessable-entity/", "errorCode" : "30_032", "title" : "Payment instrument not found", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } } } } } }, "500" : { "description" : "Internal Service Error - An unrecoverable error occurred while trying to perform the request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "1069_001" : { "summary" : "1069_001 - Internal error.", "description" : "Internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_001", "title" : "An unexpected internal error has occurred", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } }, "1069_002" : { "summary" : "1069_002 - Internal error in the payment method.", "description" : "Internal error, payment method returned an internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_002", "title" : "The payment method returned an error", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } } } } } } }, "x-methodName" : "registerProfile", "x-sortIndex" : 1 } }, "/payments/cancel" : { "post" : { "tags" : [ "Payments" ], "summary" : "Cancel payment", "description" : "Cancels the payment. Returns a URL for user redirection.", "operationId" : "post-payments-cancel", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CancelPaymentRequest" }, "examples" : { "Cancel payment request." : { "summary" : "Cancel payment request.", "description" : "Specifies the token for the payment to be canceled.", "value" : { "token" : "TOKEN_PLACEHOLDER" } } } } }, "required" : true }, "responses" : { "200" : { "description" : "OK - The request has succeeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CancelPaymentResponse" }, "examples" : { "Cancel payment response." : { "summary" : "Cancel payment response.", "description" : "Specifies the link to where the user should be redirected to. Will always only contain a `cancel` link.", "value" : { "links" : { "cancel" : { "href" : "https://cancelUrl.com" } } } } } } } }, "400" : { "description" : "Bad Request - The request is malformed or is not the expected format.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "00_400" : { "summary" : "00_400 - Bad request", "description" : "Bad request, tunable to map the request body", "value" : { "type" : "https://docs.adyen.com/errors/bad-request", "errorCode" : "00_400", "title" : "Bad request", "detail" : "Unable to map request body", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 400 } } } } } }, "422" : { "description" : "Unprocessable Entity - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "1069_003" : { "summary" : "1069_003 - Token invalid.", "description" : "Unprocessable entity, token is invalid.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_003", "title" : "The payment token provided in the request is invalid", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "1069_004" : { "summary" : "1069_004 - Payment expired.", "description" : "Unprocessable entity, payment has expired.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_004", "title" : "Payment has expired and is no longer available", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "1069_005" : { "summary" : "1069_005 - Payment in final state.", "description" : "Unprocessable entity, payment is in final state.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_005", "title" : "The payment is in a final state and cannot be processed.", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "1069_006" : { "summary" : "1069_006 - Payment method returned unprocessable entity error", "description" : "Unprocessable entity, payment method returned an unprocessable entity error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_006", "title" : "he payment method returned an unprocessable entity error", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "29_001" : { "summary" : "29_001 - Request has missing or invalid fields.", "description" : "Unprocessable entity, request has missing or invalid fields.", "value" : { "type" : "https://docs.adyen.com/errors/validation", "errorCode" : "29_001", "title" : "The request is missing required fields or contains invalid data.", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422, "invalidFields" : [ { "name" : "payload", "value" : "null", "message" : "must not be null" } ] } } } } } }, "500" : { "description" : "Internal Service Error - An unrecoverable error occurred while trying to perform the request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "1069_001" : { "summary" : "1069_001 - Internal error.", "description" : "Internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_001", "title" : "An unexpected internal error has occurred", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } }, "1069_002" : { "summary" : "1069_002 - Internal error in the payment method.", "description" : "Internal error, payment method returned an internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_002", "title" : "The payment method returned an error", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } } } } } } }, "x-methodName" : "cancelPayment", "x-sortIndex" : 3 } }, "/payments/confirm" : { "post" : { "tags" : [ "Payments" ], "summary" : "Confirm payment", "description" : " Confirms the payment using Strong Customer Authentication (SCA).\n\n To confirm a payment you must make this request two times:\n\n 1. Make this request to initiate SCA and receive the WWW-Authenticate header.\n 2. After the user completes the SCA challenge, make this request again, including the updated WWW-Authenticate header.\n\n The second response provides a redirection URL that guides the user to a payment success or failure page.\nFor more information, see our [documentation](https://docs.adyen.com/business-accounts/send-funds-ideal-integration).", "operationId" : "post-payments-confirm", "parameters" : [ { "name" : "WWW-Authenticate", "in" : "header", "description" : "Header for authenticating through SCA: Contains information for an SCA challenge for A2A payments.", "required" : false, "style" : "simple", "explode" : false, "schema" : { "type" : "string" }, "example" : "SCA realm=\"Transfer\" auth-param1=\"eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl...\"" } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ConfirmPaymentRequest" }, "examples" : { "Confirm payment request." : { "summary" : "Confirm payment request.", "description" : "Specifies the token for the payment to be confirmed, and a balanceAccountid to pay with.", "value" : { "token" : "TOKEN_PLACEHOLDER", "balanceAccountId" : "BA00000000000000000000000" } } } } }, "required" : true }, "responses" : { "200" : { "description" : "OK - The request has succeeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ConfirmPaymentResponse" }, "examples" : { "Confirm payment response." : { "summary" : "Confirm payment response.", "description" : "Specifies the link to where the user should be redirected to. Will contain a `success` link if payment was made succesfully, and a `cancel` if it failed.", "value" : { "links" : { "success" : { "href" : "https://successUrl.com" } } } } } } } }, "400" : { "description" : "Bad Request - The request is malformed or is not the expected format.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "00_400" : { "summary" : "00_400 - Bad request", "description" : "Bad request, tunable to map the request body", "value" : { "type" : "https://docs.adyen.com/errors/bad-request", "errorCode" : "00_400", "title" : "Bad request", "detail" : "Unable to map request body", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 400 } } } } } }, "401" : { "description" : "Unauthorized - The API credential used in the request is invalid or does not have the right permissions.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "00_401" : { "summary" : "00_401 - Unauthorized", "description" : "User needs to perform SCA before continuing with this operation. There will be a WWW-Authenticate header included with this response with the SCA challenge. For more info on SCA check this documentation: https://docs.adyen.com/business-accounts/implement-sca/", "value" : { "type" : "https://docs.adyen.com/errors/unauthorized", "errorCode" : "00_401", "title" : "Unauthorized", "detail" : "User needs to perform SCA", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 401 } } } } } }, "422" : { "description" : "Unprocessable Entity - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "00_422" : { "summary" : "00_422 - Unprocessable entity.", "description" : "Unprocessable entity.", "value" : { "type" : "https://docs.adyen.com/errors/unprocessable-entity/", "errorCode" : "00_422", "title" : "SCA Challenge invalid.", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "1069_003" : { "summary" : "1069_003 - Token invalid.", "description" : "Unprocessable entity, token is invalid.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_003", "title" : "The payment token provided in the request is invalid", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "1069_004" : { "summary" : "1069_004 - Payment expired.", "description" : "Unprocessable entity, payment has expired.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_004", "title" : "Payment has expired and is no longer available", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "1069_005" : { "summary" : "1069_005 - Payment in final state.", "description" : "Unprocessable entity, payment is in final state.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_005", "title" : "The payment is in a final state and cannot be processed.", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "1069_006" : { "summary" : "1069_006 - Payment method returned unprocessable entity error", "description" : "Unprocessable entity, payment method returned an unprocessable entity error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_006", "title" : "he payment method returned an unprocessable entity error", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "29_001" : { "summary" : "29_001 - Request has missing or invalid fields.", "description" : "Unprocessable entity, request has missing or invalid fields.", "value" : { "type" : "https://docs.adyen.com/errors/validation", "errorCode" : "29_001", "title" : "The request is missing required fields or contains invalid data.", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422, "invalidFields" : [ { "name" : "payload", "value" : "null", "message" : "must not be null" } ] } }, "30_013" : { "summary" : "30_013 - Balance account not found", "description" : "Not found, the requested balance account could not be not found.", "value" : { "type" : "https://docs.adyen.com/errors/unprocessable-entity/", "errorCode" : "30_013", "title" : "Balance account not found", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } } } } } }, "500" : { "description" : "Internal Service Error - An unrecoverable error occurred while trying to perform the request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "00_500" : { "summary" : "00_500 - Internal error.", "description" : "Internal error (generic).", "value" : { "type" : "https://docs.adyen.com/errors/internal", "errorCode" : "00_500", "title" : "An internal error happened", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } }, "1069_001" : { "summary" : "1069_001 - Internal error.", "description" : "Internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_001", "title" : "An unexpected internal error has occurred", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } }, "1069_002" : { "summary" : "1069_002 - Internal error in the payment method.", "description" : "Internal error, payment method returned an internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_002", "title" : "The payment method returned an error", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } } } } } } }, "x-methodName" : "confirmPayment", "x-sortIndex" : 2 } }, "/payments/details" : { "post" : { "tags" : [ "Payments" ], "summary" : "Retrieve payment details", "description" : "Returns the details of an open payment, which you must show to the user. Also provides a token required to [confirm](https://docs.adyen.com/api-explorer/a2a-payments/latest/post/payments/confirm) or [cancel](https://docs.adyen.com/api-explorer/a2a-payments/latest/post/payments/cancel) the payment.", "operationId" : "post-payments-details", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdealPaymentDetailsRequest" }, "examples" : { "Retrieve payment details request - iDEAL" : { "summary" : "Retrieve payment details request for a payment with iDEAL.", "description" : "Specifies the method, source and payload to retrieve payment details for a payment with iDEAL.", "value" : { "method" : "ideal", "source" : "redirect", "payload" : "https://ext.tx.ideal.nl/2/AXE4R72TLPRCRN6Y4FDZX7MZHJQ?sig=BGBCQEIIA2F3CF7KR2SVLSJEDUJABL62V7TI4Y2LJPJIJBZEP6HXCHXPQCLTAEIB2FNUD3COVRNIT27TT7NFKYD5UJCUY4NMPS4NUCTKA6KIBHSRXWI" } } } } }, "required" : true }, "responses" : { "200" : { "description" : "OK - The request has succeeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PaymentDetailsResponse" }, "examples" : { "Retrieve payment details response." : { "summary" : "Open payment details and token.", "description" : "Returns a details object with the amount, counterparty, description and expiration of the payment, and a token required for the requests to confirm or cancel the payment.", "value" : { "details" : { "amount" : { "currency" : "EUR", "value" : 200 }, "counterparty" : { "accountHolder" : { "fullName" : "Test company" }, "accountIdentification" : { "iban" : "NL29ADYX0000000000", "type" : "iban" } }, "description" : "MyStoreDemo-Donation-1754056596388", "expiresAt" : "2025-08-01T14:16:42.887Z" }, "token" : "TOKEN_PLACEHOLDER" } } } } } }, "400" : { "description" : "Bad Request - The request is malformed or is not the expected format.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "00_400" : { "summary" : "00_400 - Bad request", "description" : "Bad request, tunable to map the request body", "value" : { "type" : "https://docs.adyen.com/errors/bad-request", "errorCode" : "00_400", "title" : "Bad request", "detail" : "Unable to map request body", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 400 } } } } } }, "422" : { "description" : "Unprocessable Entity - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "1069_004" : { "summary" : "1069_004 - Payment expired.", "description" : "Unprocessable entity, payment has expired.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_004", "title" : "Payment has expired and is no longer available", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "1069_005" : { "summary" : "1069_005 - Payment in final state.", "description" : "Unprocessable entity, payment is in final state.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_005", "title" : "The payment is in a final state and cannot be processed.", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "1069_006" : { "summary" : "1069_006 - Payment method returned unprocessable entity error", "description" : "Unprocessable entity, payment method returned an unprocessable entity error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_006", "title" : "he payment method returned an unprocessable entity error", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422 } }, "29_001" : { "summary" : "29_001 - Request has missing or invalid fields.", "description" : "Unprocessable entity, request has missing or invalid fields.", "value" : { "type" : "https://docs.adyen.com/errors/validation", "errorCode" : "29_001", "title" : "The request is missing required fields or contains invalid data.", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 422, "invalidFields" : [ { "name" : "payload", "value" : "null", "message" : "must not be null" } ] } } } } } }, "500" : { "description" : "Internal Service Error - An unrecoverable error occurred while trying to perform the request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "1069_001" : { "summary" : "1069_001 - Internal error.", "description" : "Internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_001", "title" : "An unexpected internal error has occurred", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } }, "1069_002" : { "summary" : "1069_002 - Internal error in the payment method.", "description" : "Internal error, payment method returned an internal error.", "value" : { "type" : "https://docs.adyen.com/development-resources/error-codes", "errorCode" : "1069_002", "title" : "The payment method returned an error", "requestId" : "ba5e16ca1ac7e15abcdef01234567890", "status" : 500 } } } } } } }, "x-methodName" : "retrievePaymentDetails", "x-sortIndex" : 1 } } }, "components" : { "schemas" : { "AccountHolder" : { "type" : "object", "properties" : { "fullName" : { "type" : "string", "description" : "Full name of the account holder.", "example" : "John Doe", "minLength" : 1 } }, "required" : [ "fullName" ] }, "AccountIdentification" : { "type" : "object", "discriminator" : { "propertyName" : "type", "mapping" : { "iban" : "#/components/schemas/IbanAccountIdentification" } }, "properties" : { "type" : { "type" : "string" } }, "required" : [ "type" ] }, "Amount" : { "type" : "object", "properties" : { "currency" : { "type" : "string", "description" : "The three-character [ISO 4217 currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes).", "example" : "EUR", "minLength" : 1 }, "value" : { "type" : "integer", "format" : "int64", "description" : "The amount of the transaction in [minor units](https://docs.adyen.com/development-resources/currency-codes#minor-units) (cents).", "example" : 499 } }, "required" : [ "currency", "value" ] }, "CancelPaymentRequest" : { "type" : "object", "properties" : { "token" : { "type" : "string", "description" : "The payment token is an identifier for the payment. It is generated by Adyen on the response of the payment details.", "example" : "ewoJIlNvbWVUb2tlbiIgOiAiU29tZUluZm8iCn0=", "maxLength" : 1000, "minLength" : 1 } }, "required" : [ "token" ] }, "CancelPaymentResponse" : { "type" : "object", "properties" : { "links" : { "$ref" : "#/components/schemas/Links", "description" : "Contains redirection URLs to guide the user to the appropriate page, after a successful payment or a cancellation." } }, "required" : [ "links" ] }, "ConfirmPaymentRequest" : { "type" : "object", "properties" : { "balanceAccountId" : { "type" : "string", "description" : "The balance account ID of the account where the funds should be subtracted.", "example" : "BA00000000000000000000000", "maxLength" : 100, "minLength" : 1 }, "token" : { "type" : "string", "description" : "The payment token is an identifier for the payment. It is generated by Adyen on the response of the payment details.", "example" : "ewoJIlNvbWVUb2tlbiIgOiAiU29tZUluZm8iCn0=", "maxLength" : 1000, "minLength" : 1 } }, "required" : [ "balanceAccountId", "token" ] }, "ConfirmPaymentResponse" : { "type" : "object", "properties" : { "links" : { "$ref" : "#/components/schemas/Links", "description" : "Contains redirection URLs to guide the user to the appropriate page, after a successful payment or a cancellation." } }, "required" : [ "links" ] }, "Counterparty" : { "type" : "object", "properties" : { "accountHolder" : { "$ref" : "#/components/schemas/AccountHolder", "description" : "Contains the full name of the person or entity that receives the payment funds)." }, "accountIdentification" : { "$ref" : "#/components/schemas/AccountIdentification", "description" : "Contains the account number to which the payment funds are sent." } }, "required" : [ "accountHolder", "accountIdentification" ] }, "DefaultErrorResponseEntity" : { "type" : "object", "description" : "Standardized error response following RFC-7807 format", "externalDocs" : { "url" : "https://www.rfc-editor.org/rfc/rfc7807" }, "properties" : { "detail" : { "type" : "string", "description" : "A human-readable explanation specific to this occurrence of the problem." }, "errorCode" : { "type" : "string", "description" : "Unique business error code." }, "instance" : { "type" : "string", "description" : "A URI that identifies the specific occurrence of the problem if applicable." }, "invalidFields" : { "type" : "array", "description" : "Array of fields with validation errors when applicable.", "items" : { "$ref" : "#/components/schemas/InvalidField" } }, "requestId" : { "type" : "string", "description" : "The unique reference for the request." }, "status" : { "type" : "integer", "format" : "int32", "description" : "The HTTP status code." }, "title" : { "type" : "string", "description" : "A short, human-readable summary of the problem type." }, "type" : { "type" : "string", "description" : "A URI that identifies the validation error type. It points to human-readable documentation for the problem type." } } }, "Href" : { "type" : "object", "properties" : { "href" : { "type" : "string", "description" : "The full URL for the redirection.", "example" : "https://someUrl" } }, "required" : [ "href" ] }, "IbanAccountIdentification" : { "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/AccountIdentification" }, { "type" : "object", "properties" : { "iban" : { "type" : "string", "description" : "The IBAN of the bank account.", "example" : "NL00AAAA0000000000", "minLength" : 1 } } } ], "required" : [ "iban" ] }, "IdealAuthLinkRequest" : { "type" : "object", "properties" : { "accountHolderId" : { "type" : "string", "description" : "The unique identifier of the account holder.", "example" : "AH00000000000000000000000", "maxLength" : 150, "minLength" : 1 } }, "required" : [ "accountHolderId" ] }, "IdealAuthLinkResponse" : { "type" : "object", "properties" : { "redirectUrl" : { "$ref" : "#/components/schemas/Href", "description" : "A short-lived URL that redirects the user to the iDEAL profile management page.", "example" : "https://ideal.auth/someUrl" } } }, "IdealAuthenticateRequest" : { "type" : "object", "properties" : { "accountHolderId" : { "type" : "string", "description" : "The unique identifier for an account holder.", "example" : "AH00000000000000000000000", "maxLength" : 150, "minLength" : 1 }, "payload" : { "type" : "string", "description" : "A payload provided by iDEAL to complete the authentication process.", "example" : "https://ideal.auth/somePayload", "maxLength" : 400, "minLength" : 1 } }, "required" : [ "accountHolderId", "payload" ] }, "IdealAuthenticateResponse" : { "type" : "object", "properties" : { "redirectUrl" : { "$ref" : "#/components/schemas/Href", "description" : "A short-lived URL that redirects the user to the iDEAL page that is required for authentication.", "example" : "https://ideal.auth/someUrl" } } }, "IdealPaymentDetailsRequest" : { "type" : "object", "allOf" : [ { "$ref" : "#/components/schemas/PaymentDetailsRequest" }, { "type" : "object", "properties" : { "payload" : { "type" : "string", "description" : "An identifier for the payment, generated by the payment method, such as iDEAL. This is obtained from the specified `source`.", "example" : "https://somePayload", "maxLength" : 200, "minLength" : 1 }, "source" : { "$ref" : "#/components/schemas/PaymentSource", "description" : "The source used to obtain the payload. Possible values: `qr`, `redirect`, and `pushNotification`.", "example" : "redirect" } } } ], "required" : [ "method", "payload", "source" ] }, "InvalidField" : { "type" : "object", "properties" : { "message" : { "type" : "string", "description" : "Description of the validation error." }, "name" : { "type" : "string", "description" : "The field that has an invalid value." }, "value" : { "type" : "string", "description" : "The invalid value." } }, "required" : [ "message", "name", "value" ] }, "Links" : { "type" : "object", "properties" : { "cancel" : { "$ref" : "#/components/schemas/Href", "description" : "The URL to where the user must be redirected after a payment has been canceled.", "example" : "https://someUrl" }, "success" : { "$ref" : "#/components/schemas/Href", "description" : "The URL to where the user must be redirected after a successful payment.", "example" : "https://someUrl" } } }, "PaymentDetails" : { "type" : "object", "properties" : { "amount" : { "$ref" : "#/components/schemas/Amount", "description" : "The amount of the payment." }, "counterparty" : { "$ref" : "#/components/schemas/Counterparty", "description" : "Contains information about the party that receives the payment funds." }, "description" : { "type" : "string", "description" : "The description for the payment. It is generated by the payment method, such as iDEAL, and should be shown to the user.", "example" : "Payment at MyShop. ref:12345678" }, "expiresAt" : { "type" : "string", "format" : "date-time", "description" : "The expiration date of the payment in ISO DateTime format, as described on ISO 20022 (YYYY-MM-DDThh:mm:ss.sss+/-hh:mm).\n\nExample: **2025-12-30T14:15:30+01:00**", "example" : "2025-12-30T14:15:30+01:00" } }, "required" : [ "amount", "counterparty", "description", "expiresAt" ] }, "PaymentDetailsRequest" : { "type" : "object", "discriminator" : { "propertyName" : "method", "mapping" : { "ideal" : "#/components/schemas/IdealPaymentDetailsRequest" } }, "properties" : { "method" : { "$ref" : "#/components/schemas/PaymentMethod", "description" : "The payment method for the transaction.", "example" : "ideal" } }, "required" : [ "method" ] }, "PaymentDetailsResponse" : { "type" : "object", "properties" : { "details" : { "$ref" : "#/components/schemas/PaymentDetails", "description" : "The details of the payment. You must show your user these details before they confirm or cancel the payment." }, "token" : { "type" : "string", "description" : "The token that identifies the payment. It is generated by Adyen and is needed to confirm or cancel the payment.", "example" : "ewoJIlNvbWVUb2tlbiIgOiAiU29tZUluZm8iCn0=", "minLength" : 1 } }, "required" : [ "details", "token" ] }, "PaymentMethod" : { "type" : "string", "enum" : [ "ideal" ] }, "PaymentSource" : { "type" : "string", "enum" : [ "redirect", "qr", "pushNotification" ] }, "ProfileRegistrationRequest" : { "type" : "object", "properties" : { "accountHolderId" : { "type" : "string", "description" : "The unique identifier of the account holder.", "example" : "AH00000000000000000000000", "maxLength" : 150, "minLength" : 1 }, "paymentInstrumentIds" : { "type" : "array", "description" : "The unique identifiers of the payment instruments to be associated with the iDEAL profile.", "example" : [ "PI00000000000000000000000", "PI11111111111111111111111" ], "items" : { "type" : "string", "maxLength" : 150, "minLength" : 1 }, "maxItems" : 100, "minItems" : 1 } }, "required" : [ "accountHolderId", "paymentInstrumentIds" ] }, "ProfileRegistrationResponse" : { "type" : "object", "properties" : { "redirectUrl" : { "$ref" : "#/components/schemas/Href", "description" : "A short-lived URL that redirects the user to the iDEAL profile registration page.", "example" : "https://ideal.auth/someUrl" } } } }, "securitySchemes" : { "ApiKeyAuth" : { "type" : "apiKey", "name" : "X-API-Key", "in" : "header" }, "BasicAuth" : { "type" : "http", "scheme" : "basic" } } }, "jsonSchemaDialect" : "https://spec.openapis.org/oas/3.1/dialect/base" }