canonical: https://jentic.com/apis/adyen.com/adyen-stored-value # Adyen Stored Value API The Adyen Stored Value API manages gift cards, prepaid cards, and other stored-value payment instruments issued through Adyen. The six endpoints cover card issuance, balance inquiries, loading funds onto a card, merging two card balances, voiding a previous transaction, and changing card status (for example to lock a lost card). It is the integration surface for retailers and brands running their own gift card or e-wallet programmes on Adyen rails. ## For AI agents Issue, load, balance-check, merge, status-change, and void transactions on Adyen-issued gift and stored-value cards. ## Scope Does not process credit-card payments, manage payouts, or run loyalty rewards - use only for issuing, loading, and managing Adyen stored-value cards. ## Capabilities - Issue a new stored-value card via POST /issue with brand, currency, and load amount - Check the available balance on a stored-value card via POST /checkBalance - Load additional funds onto a card via POST /load - Merge the remaining balance of two cards into one via POST /mergeBalance - Void a previous stored-value transaction via POST /voidTransaction by reference - Change a card's status via POST /changeStatus to lock, unlock, or expire a stored-value card ## Use cases ### Retailer Gift Card Issuance Retailers running their own gift card programme call POST /issue with the merchantAccount, paymentMethod (gift card brand), and an initial loadAmount. Adyen returns a recurringDetailReference and card data that the retailer can either email to the buyer or print onto a physical card. POST /load tops the same card up later - for example, when a customer adds value at the till - and POST /checkBalance powers self-service balance lookups. Example prompt: Call POST /issue with paymentMethod.type and brand for the gift card, loadAmount.value=5000, loadAmount.currency=EUR, and merchantAccount, then POST /checkBalance with the returned recurringDetailReference ### Lost-Card Lock and Balance Migration When a customer reports a stored-value card lost, POST /changeStatus locks the original card so it can no longer be used, and POST /mergeBalance moves its remaining balance to a freshly issued replacement. This preserves the customer's funds while preventing further use of the lost card. The replacement is issued via POST /issue and the merge runs against both card references. Example prompt: Call POST /changeStatus with the lost card's reference and status=Active=false, then POST /mergeBalance with sourceCard and targetCard references to move funds to the replacement ### Reversal of Stored-Value Transactions When a stored-value transaction is mistakenly applied - wrong amount loaded, wrong card chosen at checkout - POST /voidTransaction reverses it by originalReference. This restores the card balance to its previous state without going through a manual refund flow. It is the standard correction path for stored-value programmes. Example prompt: Call POST /voidTransaction with originalReference set to the pspReference of the transaction to reverse and merchantAccount ### AI Agent Gift Card Operations via Jentic A retail operations agent that issues bulk corporate gift cards searches Jentic for 'issue an Adyen gift card', loads the schema for /issue, and executes once per recipient from a CSV. Jentic injects X-API-Key from the encrypted vault and the agent never touches the raw secret. The agent records each returned recurringDetailReference and load amount in the customer database. Example prompt: Search Jentic for 'issue an Adyen gift card', load the issue schema, then execute one call per recipient row in the corporate gift card CSV ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /issue | Issue a new stored-value card | | POST | /load | Load funds onto a card | | POST | /checkBalance | Check the available balance | | POST | /mergeBalance | Merge two card balances | | POST | /changeStatus | Change card status (lock, unlock) | | POST | /voidTransaction | Void a previous stored-value transaction | ## Key resources - **Stored-Value Cards** — Issue, load, check balance, merge, change status, and void transactions on gift and prepaid cards ## Why Jentic - **Setup:** Wiring the Adyen Stored Value API by hand means handling its X-API-Key or basic auth and targeting the classic PAL host to issue and load stored-value cards. Through Jentic you install once, import the Stored Value API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** The Stored Value API takes the card and account references 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 checking a balance. Because you pick the operations, issue, load, changeStatus, and voidTransaction 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 'issue a gift card' or 'check a stored-value balance', and Jentic returns the matching Stored Value operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Adyen Payment API** — Authorise card payments that may be funded by a stored-value card - **Adyen Checkout API** — Modern checkout surface that supports gift card payment methods - **Adyen BIN Lookup API** — Identify card BIN attributes before issuing or loading - **Adyen Recurring API** — Stores payment tokens for cards rather than stored-value balances ## FAQ ### What authentication does the Adyen Stored Value API use? The API supports an API key in the X-API-Key header (ApiKeyAuth) and HTTP Basic auth (BasicAuth) using web-service user credentials. Through Jentic, credentials are stored encrypted in the vault and only a scoped execution token is exposed to the agent. ### Can I issue a gift card programmatically with the Adyen Stored Value API? Yes. POST /issue creates a new stored-value card and returns a recurringDetailReference identifying it, along with the card data needed to either deliver it digitally or imprint it onto a physical card. Pass the brand on paymentMethod, the initial loadAmount, and merchantAccount. ### How do I check the balance of a stored-value card? POST /checkBalance returns the current and authorised balances on the card identified by recurringDetailReference. This is the standard endpoint for self-service balance lookups in retailer apps and for backend reconciliation. ### What are the rate limits for the Adyen Stored Value API? Adyen does not publish a fixed numeric rate limit in the spec; throughput is provisioned per merchant account based on programme volumes. If 429 responses appear, contact Adyen support to review the limits for the stored-value programme. ### How do I issue a gift card with the Stored Value API through Jentic? Search Jentic for 'issue an Adyen gift card', load the issue schema, then execute with paymentMethod.type, brand, loadAmount.value, loadAmount.currency, and merchantAccount. Jentic injects X-API-Key from the encrypted vault. Get an account through Jentic One, the self-hosted execution layer. ### Can I move balance from one stored-value card to another? Yes. POST /mergeBalance accepts a source card reference and a target card reference and moves the remaining balance from source to target. This is the recommended pattern for replacing lost cards: issue a new card, lock the old one with POST /changeStatus, then merge the balance to the replacement. ### Can I limit what my agent is allowed to do with the Adyen Stored Value API? Yes. Jentic One is self-hosted, so your own rules decide which Stored Value operations the agent may call and which credentials it may use. Because the API passes card and account references in the request body rather than in the URL path, you choose the operations to expose, so you can allow read-only checks like POST /checkBalance while keeping POST /issue, POST /load, POST /changeStatus, and POST /voidTransaction out of reach unless you include them. Your Adyen API key and basic auth credentials stay stored on your instance and are injected only at execution, never entering the agent's prompt or logs.