canonical: https://jentic.com/apis/adyen.com/adyen-payment # Adyen Payment API The Adyen Payment API is the classic-integration interface for authorising, capturing, modifying, and reversing card and alternative-payment-method transactions on Adyen's payment platform. The 13 endpoints cover the full authorise-capture-refund lifecycle, plus 3D Secure 1 and 3DS2 step-up flows, donation collection, and technical cancellations by merchant reference. New integrations should use the Checkout API; the Payment API remains the right choice for legacy classic integrations and server-to-server card processing where the integrator collects the PAN. ## For AI agents Authorise, capture, cancel, and refund card payments through Adyen's classic server-to-server interface, including 3D Secure and 3DS2 step-up flows. ## Scope Does not handle hosted checkout pages, payment method discovery, or payouts - use only for classic server-to-server card authorisation, capture, refund, and 3DS challenge completion. ## Capabilities - Authorise a card payment via POST /authorise with card data, amount, and merchantAccount - Capture an authorised payment via POST /capture and refund a settled payment via POST /refund - Complete 3D Secure 1 challenges via POST /authorise3d and 3DS2 challenges via POST /authorise3ds2 - Cancel an outstanding authorisation by pspReference via POST /cancel or by merchant reference via POST /technicalCancel - Adjust an existing authorised amount up or down via POST /adjustAuthorisation before capture - Combine cancel and refund logic in one call via POST /cancelOrRefund based on settlement state - Retrieve 3DS and 3DS2 authentication results via POST /getAuthenticationResult and POST /retrieve3ds2Result ## Use cases ### Server-to-Server Card Authorisation and Capture Merchants with classic integrations send card data directly to Adyen via POST /authorise, receive a pspReference, and later capture the funds via POST /capture when the order ships. The same flow handles 3D Secure 1 and 3DS2 step-up: an Authorised resultCode means the funds are reserved, while ChallengeShopper or RedirectShopper means the front end must collect the challenge and post the result to /authorise3d or /authorise3ds2. Example prompt: Call POST /authorise with card.number, card.expiryMonth, card.expiryYear, card.cvc, amount, and merchantAccount, then POST /capture with originalReference and modificationAmount once the order ships ### Refunds and Cancellations Lifecycle When a customer cancels before settlement, POST /cancel voids the authorisation by pspReference. After settlement, POST /refund returns money to the original card. POST /cancelOrRefund chooses the right behaviour based on the current state, which is useful for support tooling that does not know whether a payment has captured yet. POST /technicalCancel handles the same void using the integrator's own reference rather than Adyen's pspReference. Example prompt: Call POST /cancelOrRefund with originalReference set to the pspReference from the original authorisation and merchantAccount set to the merchant identifier ### Authorisation Adjustment for Hospitality and Travel Hotels, car rentals, and travel merchants frequently need to increase or decrease an authorised amount before final capture as the cart total changes. POST /adjustAuthorisation modifies the held amount on a still-open authorisation, preserving the original 3DS authentication context. This avoids re-authorising the card and going through 3DS again, which improves authorisation rates. Example prompt: Call POST /adjustAuthorisation with originalReference, modificationAmount.value, and modificationAmount.currency to change the held amount on an open authorisation ### AI Agent Payment Processing via Jentic An agent processing refunds for customer service tickets searches Jentic for 'refund an Adyen card payment', loads the schema for /refund, and executes with the pspReference and amount from the ticket. Jentic injects the X-API-Key from the encrypted vault, so the agent never holds the raw secret. The agent receives the new pspReference for the refund modification and writes it back to the ticket. Example prompt: Search Jentic for 'refund an Adyen card payment', load the refund schema, then execute with originalReference, modificationAmount, and merchantAccount from the support ticket ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /authorise | Create a card authorisation | | POST | /capture | Capture an authorised payment | | POST | /refund | Refund a captured payment | | POST | /cancel | Cancel an open authorisation | | POST | /cancelOrRefund | Cancel or refund based on settlement state | | POST | /authorise3ds2 | Complete a 3DS2 challenge | | POST | /adjustAuthorisation | Change an authorised amount | | POST | /technicalCancel | Cancel using merchant reference | ## Key resources - **Payments** — Authorise card payments, complete 3DS and 3DS2 challenges, retrieve authentication results, and donate - **Modifications** — Capture, refund, cancel, technical cancel, adjust authorised amount, cancelOrRefund, and void pending in-person refunds ## Why Jentic - **Setup:** Wiring the Adyen Payment API by hand means handling its X-API-Key or basic auth, targeting the classic PAL host, and sequencing authorise, capture, and refund calls server to server. Through Jentic you install once, import the Payment API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** The Payment API takes the payment reference in the request body rather than a resource id in the URL path, so you limit the agent to the operations it needs, such as authorising a card payment or capturing it. Because you pick the operations, refund, cancel, and technicalCancel stay out unless you include them. - **Credential handling:** Your Adyen X-API-Key and basic auth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'authorise a card payment' or 'refund a settled payment', and Jentic returns the matching Payment operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Adyen Checkout API** — Modern hosted-and-headless checkout surface that supersedes the classic Payment API - **Adyen Recurring API** — Manage stored payment tokens created during Payment API authorisations - **Adyen Payout API** — Send funds back to consumers from the same classic platform balance - **Adyen Disputes API** — Defend chargebacks raised against Payment API transactions ## FAQ ### What authentication does the Adyen Payment API use? The API supports an API key in the X-API-Key header (ApiKeyAuth) and HTTP Basic auth using web-service user credentials (BasicAuth), as declared in the OpenAPI spec. Through Jentic, the credential is held encrypted in the vault and the agent receives only a scoped execution token. ### Can I process 3D Secure 2 payments with the Adyen Payment API? Yes. POST /authorise initiates the payment and may return resultCode=ChallengeShopper or IdentifyShopper for 3DS2. The integrator collects the challenge result on the front end and submits it via POST /authorise3ds2; POST /retrieve3ds2Result fetches the final authentication outcome. The classic 3DS1 equivalents are /authorise3d and /getAuthenticationResult. ### Should I use the Payment API or the Checkout API? Use the Checkout API for any new integration; it includes Drop-in, Components, payment links, and 50+ payment methods out of the box. Use the Payment API when you have a classic server-to-server integration that already collects card PANs under PCI scope, or when you need direct authorise/capture/refund control without Checkout's session orchestration. ### How do I refund an Adyen payment with the Payment API through Jentic? Search Jentic for 'refund an Adyen card payment', load the refund schema, then execute with originalReference set to the pspReference from the original authorisation, modificationAmount.value and modificationAmount.currency, and merchantAccount. Jentic injects X-API-Key from the encrypted vault. Get an account through Jentic One, the self-hosted execution layer. ### What are the rate limits for the Adyen Payment API? Adyen does not publish a fixed quantitative rate limit in the spec; live throughput is provisioned per merchant account based on contract. If your integration receives HTTP 429 or saturation responses, contact Adyen support to raise the limit on the account. ### Can I adjust the authorised amount after creating an authorisation? Yes. POST /adjustAuthorisation lets you increase or decrease the held amount on an open authorisation by passing originalReference and a new modificationAmount. This preserves the original 3DS authentication and is the recommended pattern for hospitality, travel, and any flow where the final amount is known later than authorisation. ### Can I limit what my agent is allowed to do with the Adyen Payment API? Yes. Because Jentic One is self-hosted and you decide which operations it exposes, you choose exactly which Payment API calls the agent may run, such as POST /authorise to authorise a card payment and POST /capture to capture it. This API takes the payment reference in the request body rather than in the URL path, so you scope access at the operation level. Operations like POST /refund, POST /cancel, and POST /technicalCancel stay unavailable to the agent unless you explicitly include them, and your instance injects the stored credentials only for the operations you allow.