canonical: https://jentic.com/apis/paymentsos.com/paymentsos # PaymentsOS API Jentic publishes the only available OpenAPI specification for PaymentsOS API, keeping it validated and agent-ready. The PaymentsOS API provides a unified payment orchestration layer from PayU that routes transactions across multiple payment providers. It enables creating payments, retrieving payment details, and tokenizing payment instruments through a single integration point. The orchestration approach lets merchants switch between providers without code changes, optimizing approval rates across geographies. ## For AI agents Create payments, retrieve transaction details, and tokenize payment methods through PaymentsOS unified orchestration layer that routes across multiple payment providers. ## Scope Does not handle subscription management, invoicing, or dispute resolution - use for payment creation, status retrieval, and token generation only. ## Capabilities - Create payment transactions routed across multiple underlying payment providers - Retrieve detailed payment status and transaction metadata by payment ID - Tokenize payment instruments for secure reuse without storing card data - Route transactions to optimal providers based on geography and payment method - Unify payment operations across providers through a single API interface ## Use cases ### Payment Orchestration Route payment transactions across multiple payment service providers through a single API call. PaymentsOS acts as an orchestration layer that selects the optimal provider based on the payment method, currency, and geography. Merchants integrate once and gain access to dozens of providers without building individual integrations, improving approval rates through intelligent routing. Example prompt: Create a payment for 99.99 USD via POST /payments with card token and let PaymentsOS route to the optimal provider for the transaction ### Payment Instrument Tokenization Tokenize credit cards and other payment methods for secure storage and reuse. The tokens endpoint accepts raw card data and returns a provider-agnostic token that can be used in subsequent payment requests. This eliminates PCI scope for the merchant application while enabling one-click checkout experiences and recurring payment collection. Example prompt: Create a payment token for a Visa card via POST /tokens with card number, expiry, and CVV, then use the token in a payment creation request ### AI Agent Payment Operations via Jentic AI agents use Jentic to create payments and manage tokens through PaymentsOS without handling API key authentication or constructing provider-specific request payloads. Jentic provides the operation schemas so agents can initiate payments and tokenize cards with validated inputs while PaymentsOS handles provider routing automatically. Example prompt: Search Jentic for 'create a payment with provider routing', load the PaymentsOS operation schema, and execute it to process a 50.00 EUR transaction ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/payments` | Create a new payment transaction | | GET | `/payments/{paymentId}` | Retrieve payment details and status | | POST | `/tokens` | Tokenize a payment instrument | ## Key resources - **Payments** — Create payment transactions and retrieve payment details and status - **Tokens** — Tokenize payment instruments for secure storage and reuse in future payments ## Why Jentic - **Setup:** Wiring PaymentsOS by hand means learning its API key headers, managing the private signing key, and building request handling against its payment and token endpoints yourself. Through Jentic you install once, import PaymentsOS from the API Directory, store the API key once, and your agent calls it. - **Permission scoping:** PaymentsOS puts the payment id in the URL path (`/payments/{paymentId}`), so a rule can pin your agent to reading the status of one payment. You choose the operations it may call, so creating new payments or minting tokens is not included unless you add them. - **Credential handling:** Your PaymentsOS API key and signing 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 'create a payment with provider routing' or 'check a payment status', and Jentic returns the matching PaymentsOS operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Stripe API** — Direct payment processing with built-in fraud detection and global method support - **Adyen Checkout API** — Enterprise payment platform with built-in intelligent routing and risk management - **Mollie API** — European payment gateway focused on local payment methods ## FAQ ### Why is there no official OpenAPI spec for PaymentsOS API? PaymentsOS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call PaymentsOS 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 PaymentsOS API use? The PaymentsOS API uses an API key passed in the Authorization header. Additional headers include x-payments-os-env (test or live), app-id, and private-key for request signing. Through Jentic, all credentials are stored in your Jentic One instance and injected automatically. ### Can I route payments to different providers with PaymentsOS? Yes. PaymentsOS acts as an orchestration layer that routes each transaction to the configured payment provider based on rules you set in the PaymentsOS dashboard. You can configure routing by payment method, currency, amount threshold, or geography without changing your API integration. ### What are the rate limits for the PaymentsOS API? PaymentsOS applies rate limits based on your account tier and configured providers. Standard accounts support hundreds of transactions per second. The API returns 429 when limits are exceeded. Jentic handles retry logic and rate limiting when executing operations on your behalf. ### How do I create a payment through PaymentsOS via Jentic? Search Jentic for 'create a payment with orchestration' to find the POST /payments operation. Jentic returns the input schema showing required fields like amount, currency, and payment_method (or token). Execute through Jentic and PaymentsOS routes to your configured provider automatically. Install with pip install jentic. ### Can I limit what my agent is allowed to do with the PaymentsOS API? Yes. Jentic One is self-hosted by you, so your own rules decide which PaymentsOS operations your agent may call and which credentials it may use. Because PaymentsOS puts the payment id in the URL path (GET `/payments/{paymentId}`), you can pin the agent to reading the status of a single payment while withholding money-moving operations like creating payments (POST /payments) or tokenizing cards (POST /tokens). The agent can only invoke the operations you explicitly grant, and your API key and signing credentials stay stored on your instance rather than in the agent's context.