canonical: https://jentic.com/apis/getalma.eu/alma # Getalma Alma Payments API Jentic publishes the only available OpenAPI specification for Alma Payments API, keeping it validated and agent-ready. Alma is a European buy-now-pay-later (BNPL) provider used by merchants to offer instalment and deferred payment plans at checkout. The API covers payment creation, eligibility checks, refunds, captures, customer and order management, balance transactions, data exports, and webhook configuration across 22 endpoints. It is most often integrated by e-commerce platforms and merchant of record systems that need BNPL alongside card payment flows. ## For AI agents Create and capture buy-now-pay-later payments through Alma, check shopper eligibility, issue refunds, and manage orders and customers for European merchants. Configure webhooks and pull balance transactions for reconciliation. ## Scope Does not handle direct card processing, accounting ledgers, or KYC issuance - use for buy-now-pay-later payment creation, capture, refund, and reconciliation only. ## Capabilities - Create a buy-now-pay-later payment with a chosen instalment plan and surface the redirect URL to the shopper - Check whether a basket is eligible for Alma instalments before showing the option at checkout - Capture a deferred payment once goods ship and refund a captured payment when the customer returns it - Send the payment link to the shopper by SMS or email when checkout cannot be completed in-session - Manage customers and orders associated with payments, including shipment status updates - Pull balance transactions for reconciliation and configure webhooks for asynchronous event delivery ## Use cases ### Checkout BNPL Integration European e-commerce sites want to offer 2x, 3x, or 4x instalment plans at checkout to lift conversion on baskets above a certain threshold. The Alma API supports running an eligibility check on the basket and then creating a payment with the chosen plan, returning a hosted redirect URL the merchant displays to the shopper. This is the core merchant integration for BNPL. Example prompt: Run `POST /eligibility/purchases` on the basket, then call `POST /payments` with the selected instalment plan and return the hosted redirect URL to the shopper. ### Deferred Payment for Shipped Goods Merchants selling physical goods often defer the customer charge until the order ships. The Alma API exposes a capture endpoint that finalises a previously authorised payment when fulfilment occurs, so the merchant only collects funds against confirmed shipments. Refunds and partial refunds are also supported on the same payment object. Example prompt: On shipment confirmation, call `POST /payments/{id}/capture` for the matching payment ID and update the order with the capture timestamp. ### Reconciliation and Balance Reporting Finance teams need to reconcile Alma payouts with internal sales records on a daily basis. The API's balance-transactions and data-exports endpoints provide structured records of every payment, refund, and fee, so an automated job can pull the day's activity and match it to the merchant's ledger. Example prompt: Call `GET /balance-transactions` for yesterday's date range and write the records to a finance warehouse table for reconciliation. ### Agent-Driven Refund Workflow An AI agent embedded in customer support tooling can resolve a refund request by looking up the Alma payment, calling the refund endpoint through Jentic, and confirming the result back to the agent. The agent never handles the Alma API key directly - Jentic manages the credential and surfaces only the operation contract. Example prompt: Look up the payment ID for an order, call `POST /refunds` with the amount and reason, and reply to the customer with the refund confirmation. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /payments | Create a payment with an instalment plan | | POST | /eligibility/purchases | Check basket eligibility for BNPL | | POST | /payments/{id}/capture | Capture a deferred payment | | POST | /refunds | Create a refund | | POST | /payments/{id}/email | Send the payment link by email | | GET | /balance-transactions | List balance transactions for reconciliation | | POST | /webhooks | Configure a webhook for payment events | ## Key resources - **Payments** — Create, retrieve, modify, capture, and cancel BNPL payments. - **Eligibility** — Check whether a basket qualifies for Alma instalment plans. - **Refunds** — Issue refunds against captured payments. - **Orders** — Manage orders associated with payments, including shipment status. - **Customers** — Create and retrieve customer records linked to payments. - **Balance Transactions** — Retrieve transaction history for reconciliation. - **Webhooks** — Configure event delivery for asynchronous payment updates. ## Why Jentic - **Setup:** Wiring the Alma Payments API by hand means setting up its Authorization-header key, choosing between the live and sandbox hosts, and sequencing payment, capture, and refund calls yourself. Through Jentic you install once, import Alma from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Alma puts the payment id in the URL path (/payments/{id}/capture), so a rule can pin your agent to acting on one payment: it can capture or email that payment and nothing else. You choose the operations it may call, so money-moving ones like refunds or creating new payments are not included unless you add them. - **Credential handling:** Your Alma API key is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a buy-now-pay-later payment' or 'refund an Alma payment', and Jentic returns the matching Alma operation with its input schema and required fields so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Afterpay** — Buy-now-pay-later provider with strong presence in the US, UK, and APAC. - **Affirm** — US-focused buy-now-pay-later provider supporting longer-term financing. - **Stripe** — General-purpose card and wallet processor frequently paired with BNPL providers at checkout. - **Adyen Account Service** — Global payment platform often integrated alongside BNPL providers in marketplace and platform setups. ## FAQ ### Why is there no official OpenAPI spec for Alma Payments API? Alma does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Alma Payments API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Alma Payments API use? The Alma API uses an API key passed in the `Authorization` header (`AlmaAuth` scheme). Through Jentic, the key is stored encrypted in the vault and injected at execution time so agents never see the raw key. ### Can I check eligibility before showing BNPL at checkout? Yes. Call `POST /eligibility/purchases` with the basket details to determine which Alma plans (e.g. 3x, 4x) are available, then only display eligible plans to the shopper. ### How do I refund an Alma payment through Jentic? Search Jentic for `refund a buy-now-pay-later payment via Alma`, load the schema for `POST /refunds`, and execute with the payment ID and amount. Jentic handles the API key automatically. ### Does the Alma API support capturing a deferred payment when the order ships? Yes. Call `POST /payments/{id}/capture` to finalise a previously authorised payment, typically triggered by your fulfilment system. ### Can the Alma API process card payments outside of BNPL? No. Alma is purchase-financing only - it offers instalment and deferred plans, not standalone card processing. Pair it with a card processor for the non-BNPL portion of your checkout. ### Can I limit what my agent is allowed to do with the Alma Payments API? Yes. Jentic One runs on your own infrastructure, and you decide which Alma operations your agent may call and which credentials it may use. Because Alma puts the payment id in the URL path, you can pin the agent to a single payment so it can only capture or email that payment (POST /payments/{id}/capture, POST /payments/{id}/email) and nothing else. Money-moving operations such as creating payments (POST /payments) or issuing refunds (POST /refunds) stay out of reach unless you explicitly grant them.