canonical: https://jentic.com/apis/epaytools.com/epaytools # Epaytools Orchestra API Jentic publishes the only available OpenAPI specification for the ePayTools Orchestra API, keeping it validated and agent-ready. Orchestra is a payment orchestration platform that brokers card operations, payment gateway charges, 3-D Secure sessions, network tokenisation, and PCI-conformant utilities across multiple acquirers. The API exposes 43 endpoints grouped under CardOperations, PaymentGateway, ThreeDsSessions, ThreeDsMerchants, NetworkToken, and CustomForms, allowing merchants to authorise, capture, refund, void, and tokenise payments while keeping card data out of their own environment. Authentication is dual: an X-API-Key header for tenant identification and a JWS bearer token for signed operations. ## For AI agents Orchestrate card payments, 3-D Secure flows, network tokenisation, and refunds across multiple gateways. Authenticate with an X-API-Key header and a JWS bearer token. ## Scope Does not handle accounting reconciliation, payouts to bank accounts, or fraud-scoring decisioning - use for card payment orchestration, 3-D Secure, and tokenisation only. ## Capabilities - Authorise, capture, refund, and void payment-gateway charges across configured acquirers - Issue 3-D Secure session tokens to drive cardholder authentication challenges - Tokenise card numbers via network tokenisation and delete tokens on demand - Validate cards and look up brand by BIN through the CardOperations endpoints - Manage payment gateway accounts and 3-D Secure merchant configuration via REST - Upload and version custom payment-form folders for hosted checkout experiences - Verify operation results through signed-data validation endpoints ## Use cases ### Multi-Acquirer Payment Routing for an E-Commerce Platform Merchants running cross-border checkout need a single API to route charges across multiple acquirers based on currency, BIN country, or reliability. Orchestra's PaymentGateway endpoints (charge, authorise, capture, refund, void) plus PaymentGatewayAccounts management let an agent select an account and execute the charge in one flow, keeping retry and fallback logic out of the storefront. Example prompt: Call POST /PaymentGateway/charge with amount=49.99 EUR, the chosen gateway account name, and a tokenised card reference, then return the gateway response. ### PCI-Scope Reduction via Hosted Card Operations Merchants reducing PCI scope route card capture through Orchestra's CardOperations and CustomForms so card numbers never touch their servers. The /CardOperations token-then-validate-then-charge flow combined with hosted custom forms keeps the merchant out of SAQ-D scope while still supporting tokenisation and storage. Example prompt: Call POST /CardOperations to obtain a session token, render the hosted form, then call POST /CardOperations/charge with the returned reference. ### 3-D Secure 2 Authentication for Strong Customer Authentication European merchants under PSD2 must authenticate cardholders with 3-D Secure 2. Orchestra's ThreeDsSessions and ThreeDsMerchants endpoints provision the session token, register the merchant configuration, and return the challenge URL, so an agent can wire SCA into checkout without a direct directory-server integration. Example prompt: Call POST /ThreeDsSessions with the cardholder details and amount, then return the challenge URL to the checkout page. ### AI Agent Payments Tool via Jentic An AI agent embedded in a back-office assistant can run refunds and lookups against Orchestra without holding raw API keys. Through Jentic the agent searches by intent (for example 'refund a payment'), loads the schema, and executes with the X-API-Key and JWS bearer scoped from the vault - a useful pattern when CSAT or finance bots need to act on transactions on behalf of staff. Example prompt: Use Jentic search('refund a payment'), load the PUT /PaymentGateway/refund operation, and execute it with the original transaction reference and refund amount. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /PaymentGateway/charge | Perform a payment-gateway charge | | POST | /PaymentGateway/authorize | Authorise a payment-gateway charge | | PUT | /PaymentGateway/capture | Capture a previously authorised payment | | PUT | /PaymentGateway/refund | Refund a captured payment | | DELETE | /PaymentGateway/void | Void a pending authorisation | | POST | /CardOperations/charge | Charge through Orchestra-hosted card capture | | POST | /ThreeDsSessions | Get a 3-D Secure session token | | POST | /NetworkToken | Network-tokenise a card | ## Key resources - **CardOperations** — Tokenise, validate, charge, and store cards through Orchestra-hosted flows - **PaymentGateway** — Authorise, capture, refund, and void charges across configured acquirers - **PaymentGatewayAccounts** — Manage acquirer account configuration - **ThreeDsSessions** — Provision 3-D Secure 2 session tokens for SCA - **ThreeDsMerchants** — Manage 3-D Secure merchant directory entries - **NetworkToken** — Create and revoke network tokens for stored cards - **CustomForms** — Upload and version hosted checkout form folders - **CvvOperations** — Run CVV-only validation flows ## Why Jentic - **Setup:** Wiring Orchestra by hand means combining its API-key request header with a JWS bearer token, sequencing the authorize, capture, and refund calls yourself, and building your own retries against api.epaytools.com. Through Jentic you install once, import the Orchestra API from the API Directory, store the key and token once, and your agent calls it. - **Permission scoping:** Orchestra sends the card and payment details in the request body rather than the URL, so scope the agent to the operations it needs, such as POST /PaymentGateway/authorize or POST /ThreeDsSessions. You pick that allowed set, so a money-moving operation like PUT /PaymentGateway/refund or DELETE /PaymentGateway/void is only reachable if you include it. - **Credential handling:** Your Orchestra API-key request header and JWS bearer token 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 'charge a card' or 'refund a payment', and Jentic returns the matching Orchestra operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Escrow.com API** — Escrow service for high-value or item-based transactions - **Esendex Messaging API** — SMS notifications for payment confirmations and 3DS step-up codes - **EODHD Financial Data API** — Currency and market data - pairs with multi-currency payment routing ## FAQ ### Why is there no official OpenAPI spec for the ePayTools Orchestra API? ePayTools publishes integration documentation but not a public OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call the Orchestra 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 ePayTools Orchestra API use? Orchestra requires an X-API-Key header (apiKey scheme) and a JWS HTTP bearer token for signed operations. Through Jentic both are stored encrypted in your Jentic One instance and injected at execution time so raw keys never enter the agent's context. ### Can I run a refund with the ePayTools Orchestra API? Yes. PUT /PaymentGateway/refund refunds a captured payment when supplied with the original transaction reference and refund amount. The acquirer used is determined by the gateway account on the original charge. ### What are the rate limits for the ePayTools Orchestra API? ePayTools does not document hard rate limits in the spec; throughput is governed by the merchant tier and the downstream acquirer. Treat acquirer responses as the authoritative limit and back off on 429. ### How do I tokenise a card through Jentic? Search 'tokenise a card to a network token'. Jentic returns the POST /NetworkToken operation, you load its schema, and execute with the card number and reference. The X-API-Key and JWS bearer are injected from the vault. ### Does the API support 3-D Secure 2 for PSD2 SCA? Yes. POST /ThreeDsSessions issues a session token for a 3-D Secure 2 challenge, and POST /ThreeDsMerchants/{name} registers merchant directory entries used by the SCA flow. ### Can I host a custom checkout form on Orchestra? Yes. PUT /CustomForms/{name} uploads or replaces a custom form folder, and GET /CustomForms lists the forms currently configured on the tenant. ### Can I limit what my agent is allowed to do with the ePayTools Orchestra API? Yes. Because you run Jentic One yourself, you decide which Orchestra operations your agent can call, so you can grant read-and-authorise work like POST /PaymentGateway/authorize or POST /ThreeDsSessions while withholding money-moving calls. A refund via PUT /PaymentGateway/refund or a void via DELETE /PaymentGateway/void is only reachable if you include it in the allowed set. Your X-API-Key header and JWS bearer token are held encrypted by your own instance and injected at execution time, so the agent operates strictly within the operations and credentials you permit.