canonical: https://jentic.com/apis/adyen.com/adyen-terminal # Adyen Terminal API The Adyen Terminal API is the JSON message protocol for in-person payments and point-of-sale interactions on Adyen-supplied terminals. The 19 endpoints cover the full POS lifecycle: login and logout, payment, card acquisition, loyalty, stored value, reversal, reconciliation, totals reporting, balance inquiry, transaction status, abort, diagnosis, and direct device interactions such as display, input, print, and card-reader APDU. Both synchronous and asynchronous transport modes are supported, and the same protocol is used for cloud and local terminal integrations. ## For AI agents Drive in-person payments and POS interactions on Adyen terminals - accept payments, refunds, loyalty, stored-value, displays, prints, and reconciliation. ## Scope Does not handle online card-not-present payments, terminal hardware ordering, or merchant onboarding - use only for driving payments and POS interactions on Adyen-supplied terminals. ## Capabilities - Initiate an in-person card payment via POST /payment with the SaleToPOIRequest envelope and PaymentRequest body - Reverse an in-flight or completed payment via POST /reversal using the original transactionID - Run end-of-day totals and reconciliation via POST /reconciliation and POST /gettotals - Display custom prompts on the terminal via POST /display and collect input via POST /input - Process loyalty enquiries and redemption via POST /loyalty alongside the payment - Acquire card details for a non-payment use case via POST /cardacquisition - Print a custom receipt on the terminal via POST /print and abort a request via POST /abort ## Use cases ### In-Person Card Payment at the Till A POS application sends a SaleToPOIRequest containing a PaymentRequest to POST /payment. The terminal prompts the shopper to tap, dip, or swipe; runs PIN, signature, or contactless flows as required; and returns a SaleToPOIResponse with the result. The same call handles EMV, magstripe, contactless, and mobile wallets, as well as gratuity and split tender. Synchronous mode waits for the result on the HTTP call; asynchronous returns immediately and pushes the result to a configured webhook. Example prompt: Send a SaletoPOIRequest to POST /payment with MessageHeader.SaleID, MessageHeader.POIID, and a PaymentRequest body containing PaymentTransaction.AmountsReq and currency ### Reversals and End-of-Day Reconciliation A cashier can void the immediately previous transaction with POST /reversal, passing the original transactionID, before the shopper leaves the till. At end-of-day, POST /reconciliation totals all transactions for the period and POST /gettotals returns the figures the till expects to match against the cash drawer. Both endpoints are part of the same SaleToPOI envelope used for payments, keeping operational tooling on a single transport. Example prompt: Send a SaletoPOIRequest to POST /reversal with the OriginalPOITransaction.POITransactionID matching the previous payment transactionID ### Custom Display and Input on the Terminal Retailers running cashier-prompt flows (loyalty enrolment, age check, signature on screen) use POST /display to render text or buttons on the terminal screen, then POST /input to capture the cashier's or shopper's response. POST /print pushes a custom receipt to the terminal printer for warranty terms, marketing inserts, or legal disclosures. POST /cardacquisition acquires card data without authorising a payment, useful for loyalty enrolment or tokenisation. Example prompt: Send a SaletoPOIRequest to POST /display with a DisplayRequest containing OutputContent.PredefinedContent and OutputText for each line ### AI Agent POS Operations via Jentic An ops agent monitoring store reconciliations searches Jentic for 'run Adyen terminal reconciliation', loads the schema for /reconciliation, and triggers it for each store at close-of-business. The agent receives the totals payload, compares to the till's expected figures, and flags discrepancies in the operations dashboard. Jentic injects X-API-Key and the SaleID/POIID context per store from its encrypted vault. Example prompt: Search Jentic for 'run Adyen terminal reconciliation', load the reconciliation schema, then execute one call per store at close-of-business and compare totals to till figures ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /payment | Take an in-person payment | | POST | /reversal | Reverse a previous payment | | POST | /reconciliation | Run end-of-day reconciliation | | POST | /gettotals | Pull terminal totals | | POST | /transactionstatus | Query the status of a prior transaction | | POST | /cardacquisition | Acquire card data without payment | | POST | /display | Display content on the terminal screen | | POST | /print | Print a receipt on the terminal | ## Key resources - **Payment** — Initiate in-person payments, reversals, and refunds on the terminal - **Card Acquisition & Loyalty** — Acquire card data for non-payment flows and run loyalty enquiries and redemption - **Stored Value** — Drive gift and prepaid card flows directly through the terminal - **Operations & Reporting** — Reconciliation, totals, transaction status, abort, diagnosis, and login/logout - **Device Interaction** — Display prompts, capture input, print receipts, and run card-reader APDU ## Why Jentic - **Setup:** Wiring the Adyen Terminal API by hand means handling its X-API-Key or basic auth over cloud transport and assembling the SaleToPOIRequest envelope for each POS interaction. Through Jentic you install once, import the Terminal API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** The Terminal API takes the terminal and transaction details 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 reading transaction status or running a reconciliation. Because you pick the operations, taking a payment or a reversal stays out unless you include it. - **Credential handling:** Your Adyen Terminal 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 'take an in-person payment' or 'run a terminal reconciliation', and Jentic returns the matching Terminal operation with its SaleToPOIRequest schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Adyen POS Terminal Management API** — Manage the fleet of terminals that drive Terminal API requests - **Adyen Checkout API** — Online (CNP) equivalent of the in-person Terminal API - **Adyen Payment API** — Server-to-server card payments used in classic integrations - **Adyen Management API** — Manage merchant accounts and stores referenced by Terminal API requests ## FAQ ### What authentication does the Adyen Terminal API use? Cloud Terminal API requests are signed with an API key in the X-API-Key header (ApiKeyAuth); HTTP Basic auth (BasicAuth) is also supported, as declared in the spec. Local terminal integrations use a different transport that goes directly to the terminal's IP address. Through Jentic, the cloud credential is held encrypted in the vault and only a scoped token is exposed to the agent. ### Can I take an in-person payment with the Adyen Terminal API? Yes. POST /payment accepts a SaleToPOIRequest envelope containing a PaymentRequest body with the amount, currency, and SaleID/POIID identifiers. The terminal handles tap, chip, and contactless flows; the response carries the SaleToPOIResponse with the result and any printed receipt content. ### Does the Terminal API support synchronous and asynchronous modes? Yes. Both transport modes are documented in the API description: synchronous responses use https://terminal-api-test.adyen.com/sync and asynchronous responses use https://terminal-api-test.adyen.com/async, with results pushed to a configured webhook in async mode. Choose async for long-running flows such as signature capture; choose sync for simple tap-and-go. ### How do I run end-of-day reconciliation through Jentic with the Adyen Terminal API? Search Jentic for 'run Adyen terminal reconciliation', load the reconciliation schema, then execute with the SaleID, POIID, and a ReconciliationRequest specifying the period. 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 Terminal API? Adyen does not publish a fixed numeric rate limit for Terminal in the spec; throughput is bounded by the terminal hardware itself for sync flows. For cloud transport, contact Adyen support if you receive 429 responses on a busy estate of terminals. ### Can I print a custom receipt or display a prompt on the terminal? Yes. POST /print accepts a PrintRequest with output content for the terminal printer; POST /display accepts a DisplayRequest with text and predefined content for the terminal screen. POST /input collects the cashier's or shopper's response from the screen, which is useful for cashier-prompt flows like loyalty enrolment or age verification. ### Can I limit what my agent is allowed to do with the Adyen Terminal API? Yes. Because Jentic One is self-hosted, your own rules decide which Terminal API operations and credentials the agent may use, and you grant only the ones it needs, such as querying transaction status via POST /transactionstatus or running end-of-day totals via POST /reconciliation and POST /gettotals. The Terminal API passes the terminal and transaction details in the request body rather than a resource id in the URL path, so you scope access by choosing operations rather than paths. Since you pick the operations, sensitive calls like taking a payment with POST /payment or reversing one with POST /reversal stay out of the agent's reach unless you explicitly include them.