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

# GoPay REST API

The GoPay REST API processes online payments through the GoPay payment gateway, with support for one-time payments, recurring payments, preauthorizations, refunds, and account statement retrieval. It serves Central European e-commerce merchants with payment instruments specific to local markets such as bank buttons, GoPay wallet, and card payments. Authentication uses OAuth2 client credentials over HTTP Basic to obtain bearer tokens scoped to payment-create, payment-all, or account-statement permissions. Integration covers the full payment lifecycle from creation through capture, recurrence, and void.

## For AI agents

Create GoPay payments, refund or capture transactions, manage recurring billing cycles, and pull eshop account statements via OAuth2-scoped bearer tokens.

## Scope

Does not handle accounting, payouts, or fraud scoring - use for GoPay payment creation, capture, refund, and recurrence only.

## Capabilities

- Create a payment with redirect or inline checkout for cards, bank buttons, and the GoPay wallet
- Capture a previously preauthorized payment to settle funds at fulfillment time
- Refund a captured payment in full or partial amount with reason metadata
- Trigger an on-demand recurrence on a parent payment for subscription billing
- Void an outstanding preauthorization or cancel an active recurrence chain
- List the supported payment instruments and currencies for a given eshop GoID
- Download an eshop account statement for reconciliation across a date range

## Use cases

### Czech and Slovak Checkout

Accept payments from Central European shoppers using locally preferred methods including bank buttons, the GoPay wallet, and major card schemes. The API creates a payment object that returns a hosted gateway URL or inline payload, then exposes status, capture, and refund endpoints to drive the order lifecycle. Settlement currencies and instruments adjust automatically per eshop GoID.

Example prompt: Create a GoPay payment for 1500 CZK with payer email customer@example.com, return the gateway URL, then poll `/payments/payment/{id}` until state is PAID.

### Subscription and Recurring Billing

Power subscription products by creating a parent recurring payment and triggering on-demand or scheduled recurrences against it. The `/payments/payment/{id}/create-recurrence` endpoint charges the same payer using the saved instrument, while void-recurrence ends the chain when a customer cancels. Refunds operate on individual recurrences without breaking the parent.

Example prompt: Trigger a 499 CZK monthly recurrence on parent payment id 3000123456 and confirm the new payment state is PAID before extending the subscription.

### Preauthorize and Capture

Hold funds at order placement and settle only after fulfillment using the preauthorization flow. Create a payment in PREAUTHORIZED state, then call `/payments/payment/{id}/capture` when the order ships or void-authorization to release the hold. This pattern matches travel, marketplace, and made-to-order workflows where the final amount or fulfillment timing is uncertain.

Example prompt: Capture 250.00 EUR on preauthorized payment id 3000999111 once the warehouse confirms shipment, otherwise call void-authorization.

### AI Agent Reconciliation Workflow

An autonomous finance agent pulls daily eshop account statements from `/accounts/account-statement`, joins them against internal order records, and flags mismatches for review. Using Jentic, the agent discovers GoPay endpoints by intent, fetches scoped OAuth2 tokens from the credential vault, and never sees raw client secrets in its prompt window.

Example prompt: Fetch the GoPay account statement for goid 8123456789 between 2026-06-01 and 2026-06-08, then return any payments with status PAID that have no matching internal order id.

## Key endpoints

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

## Key resources

- **Payments** — Create, retrieve, capture, refund, and void payments and authorizations
- **Recurrences** — Trigger on-demand recurrences and end recurrence chains tied to a parent payment
- **Eshops** — List available payment instruments and currencies per eshop GoID
- **Accounts** — Download account statements for settlement reconciliation
- **OAuth2** — Issue bearer tokens scoped to payment-create, payment-all, or account-statement

## 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}/capture`), 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 'create a recurring payment' or 'capture a preauthorized 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 payment processor with broader currency and method coverage than GoPay
- **Adyen Checkout** — Enterprise payment platform with unified European acquiring
- **Braintree** — PayPal-owned gateway with vault and recurring billing

## FAQ

### What authentication does the GoPay REST API use?

The API uses OAuth2 client credentials. You POST your client_id and client_secret as HTTP Basic to `/oauth2/token` requesting a scope of payment-create, payment-all, or account-statement, and receive a bearer token used in the Authorization header for subsequent calls. Through Jentic, the client secret stays in the encrypted vault and the agent only ever sees a short-lived scoped token.

### Can I issue a partial refund with the GoPay API?

Yes. POST to `/payments/payment/{id}/refund` with an amount smaller than the original payment to refund partially, or omit it to refund in full. The endpoint returns the refund result and updates the parent payment so subsequent retrievals reflect the new outstanding balance.

### How do I set up recurring payments through GoPay?

Create an initial payment with a recurrence object describing the period and end date, then trigger each subsequent charge by POSTing to `/payments/payment/{id}/create-recurrence` on the parent payment id. Call `/payments/payment/{id}/void-recurrence` when the customer cancels to stop future charges.

### What payment methods does the GoPay API support?

GET `/eshops/eshop/{goid}/payment-instruments/{currency}` returns the live list of instruments available for your eshop and currency. Typical instruments include cards, bank buttons for Czech and Slovak banks, the GoPay wallet, Apple Pay, Google Pay, and bank transfer.

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

Run pip install jentic, then use the Jentic search query 'create a gopay payment' to discover the POST `/payments/payment` operation, load its input schema, and execute the call. Jentic handles the OAuth2 token exchange and credential isolation automatically. Get started with Jentic One, the self-hosted execution layer.

### 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.

### 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 grant it only the calls it needs, such as creating a payment or reading status, while withholding refund or void-authorization. Since the payment id sits in the URL path (for example `/payments/payment/{id}/capture`), a rule can pin the agent to a single payment, letting it read and capture that one payment and nothing else. Your GoPay client_id and client_secret are stored once and injected only at execution time, so they never enter the agent's prompt or logs.