canonical: https://jentic.com/apis/gopay.cz/gopay-cz

# Gopay Cz GoPay REST API

Jentic publishes the only available OpenAPI specification for GoPay REST API, keeping it validated and agent-ready. The GoPay REST API processes online payments via the Czech and Slovak GoPay gateway, covering payment creation, status retrieval, refunds, captures, on-demand recurrences, and authorization voids. It exposes 10 endpoints under https://gate.gopay.cz/api with OAuth2 bearer tokens issued from a client_id and client_secret over HTTP Basic. The same spec also surfaces eshop payment instrument lookup and account statement download for reconciliation.

## For AI agents

Create payments, manage recurrences and preauthorizations, and pull account statements through the GoPay payment gateway with OAuth2 scoped tokens.

## Scope

Does not handle accounting, fraud scoring, or merchant onboarding - use for GoPay payment processing, recurrences, and refunds only.

## Capabilities

- Create a payment with hosted redirect or inline checkout against a specific eshop GoID
- Capture a preauthorized payment when an order is fulfilled
- Issue a partial or full refund on any captured payment
- Trigger an on-demand recurrence against a parent recurring payment
- Void an open authorization or cancel a recurrence chain
- List eshop payment instruments and currencies for live checkout configuration
- Download an eshop account statement for daily reconciliation

## Use cases

### Local Czech Checkout

Accept payments from Czech and Slovak shoppers using bank buttons, the GoPay wallet, and card schemes. The integration creates a payment, redirects the shopper to the hosted gateway, and exposes a status endpoint for the merchant backend to confirm settlement before fulfillment.

Example prompt: Create a GoPay payment for 2499 CZK against goid 8123456789, return the gateway redirect URL, and verify state transitions to PAID.

### Recurring Subscription Billing

Run subscription products by creating a parent recurring payment and triggering each scheduled charge against it. Recurrences inherit the saved instrument, succeed without redirecting the shopper, and can be ended at any point with the void-recurrence endpoint when the customer cancels.

Example prompt: Trigger a 299 CZK monthly recurrence on parent payment id 3000222333 on the first of each month and stop the chain if a recurrence fails twice in a row.

### Marketplace Authorization Hold

Hold funds at order placement using a preauthorization, then capture only the portion that ships. Authorization holds can be released entirely with void-authorization or settled with capture, matching marketplace and made-to-order patterns where the final billable amount is unknown at checkout.

Example prompt: Capture 1450 CZK on preauthorized payment id 3000777888 when the seller marks the order shipped, otherwise call void-authorization within seven days.

### AI Agent Settlement Reconciliation

An automated finance agent pulls the GoPay account statement on a schedule, joins it against internal orders, and surfaces unmatched transactions. Through Jentic, the agent searches by intent, receives the right operation and schema, and uses scoped OAuth2 tokens issued from the encrypted vault.

Example prompt: Fetch `/accounts/account-statement` for the date range 2026-06-01 to 2026-06-09 and return any PAID payments missing from the orders database.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/oauth2/token` | Issue an OAuth2 bearer token |
| POST | `/payments/payment` | Create a new payment |
| GET | `/payments/payment/{id}` | Retrieve a payment by id |
| POST | `/payments/payment/{id}/refund` | Refund a captured payment |
| POST | `/payments/payment/{id}/create-recurrence` | Trigger a recurrence on a parent payment |
| POST | `/payments/payment/{id}/capture` | Capture a preauthorized payment |
| POST | `/payments/payment/{id}/void-authorization` | Void an open authorization |
| GET | `/accounts/account-statement` | Download an eshop account statement |

## Key resources

- **Payments** — Create, retrieve, refund, capture, and void payments
- **Recurrences** — Trigger and end recurring charges tied to a parent payment
- **Eshops** — List supported payment instruments per GoID and currency
- **Accounts** — Download account statements for reconciliation
- **OAuth2** — Issue scoped bearer tokens for API access

## Why Jentic

- **Setup:** Wiring the GoPay REST API by hand means running the OAuth2 token exchange with basic client credentials, refreshing bearer tokens, and matching payment calls against the gate.gopay.cz host. Through Jentic you install once, import the GoPay REST API from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** The GoPay REST API puts the payment id in the URL path (`/payments/payment/{id}/refund`), so a rule can pin your agent to one payment: it can read and capture that payment and nothing else. You choose the operations it may call, so refunds or void-authorization are not included unless you add them.
- **Credential handling:** Your GoPay client_id and client_secret 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 'capture a preauthorization' or 'set up a recurring payment', and Jentic returns the matching GoPay operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe** — Global card processor with broader market reach than GoPay
- **Adyen Checkout** — European unified acquirer with multi-country support
- **Braintree** — PayPal-owned gateway with vault and subscriptions

## FAQ

### Why is there no official OpenAPI spec for GoPay REST API?

GoPay does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call GoPay REST 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 GoPay REST API use?

OAuth2 client credentials over HTTP Basic. POST client_id and client_secret to `/oauth2/token`, request a scope of payment-create, payment-all, or account-statement, and use the returned bearer token in the Authorization header. Jentic stores the secret in its encrypted vault and rotates tokens automatically.

### Can I issue partial refunds through the GoPay API?

Yes. POST `/payments/payment/{id}/refund` with an amount field smaller than the original payment to refund partially. Omitting the amount issues a full refund. The parent payment is updated so subsequent GETs reflect the remaining captured balance.

### How do recurring payments work on GoPay?

Create the first payment with a recurrence object describing the cycle, then POST `/payments/payment/{id}/create-recurrence` against the parent payment id for each charge. POST `/payments/payment/{id}/void-recurrence` ends the chain when a customer cancels.

### How do I integrate the GoPay API with an AI agent through Jentic?

Run pip install jentic, search 'create a gopay payment' to find POST `/payments/payment`, load the input schema, and execute. Jentic handles the OAuth2 token exchange so the agent never sees the client secret. Get started with Jentic One, the self-hosted execution layer.

### Can I limit what my agent is allowed to do with the GoPay REST API?

Yes. Because you run Jentic One yourself, your own rules decide which GoPay operations and credentials the agent may use, so you can allow it to create a payment or check status while withholding refunds, capture, and void-authorization. Since the GoPay REST API carries the payment id in the URL path, such as `/payments/payment/{id}/refund`, a rule can pin the agent to a single payment and let it read or capture only that one. The client_id and client_secret you store are injected at execution time and never enter the agent's prompt or logs, so the agent calls only the endpoints you permit.