# GoPay Payments API v4 — full documentation

The complete GoPay Payments API v4 documentation as one Markdown file: the integration guides, then the API reference.

- One guide as Markdown: `/en/docs/<page>.md`, for example `/en/docs/00-overview.md`. The Czech translation is under `/cs/docs/`.
- The API reference as Markdown: `/en/api.md` (Czech: `/cs/api.md`).
- The OpenAPI 3.1 specification: `/spec/en/payments.yaml` (Czech: `/spec/cs/payments.yaml`).

## Contents

- Overview — `/en/docs/00-overview.md`
- Security and credentials — `/en/docs/01-security.md`
- Payment states and lifecycle — `/en/docs/02-payment-lifecycle.md`
- Hosted integrations — `/en/docs/03-hosted-integrations.md`
- Checkout integration — `/en/docs/04-checkout-integration.md`
- Saved cards — `/en/docs/05-saved-cards.md`
- Apple Pay — `/en/docs/06-apple-pay.md`
- Google Pay — `/en/docs/07-google-pay.md`
- QR Payment — `/en/docs/08-qr-payment.md`
- Refunds — `/en/docs/09-refunds.md`
- Payment links — `/en/docs/10-payment-links.md`
- Recurrences — `/en/docs/11-recurrences.md`
- Events and webhooks — `/en/docs/12-events-and-webhooks.md`
- Errors — `/en/docs/98-errors.md`
- Payments — `/en/api.md`

---

## Overview

GoPay Payments API v4 is the HTTP interface for accepting payments through GoPay. The pages in this set explain how the operations fit together. The OpenAPI reference documents every request and response shape.

### Actors

Four parties exchange data during an integration. The pages that follow refer to them by these names.

- **Merchant's server.** The merchant's backend. Holds the long-lived merchant credentials and performs everything that must be authenticated as the merchant.
- **Merchant's client.** The merchant's web frontend or mobile application. Receives a per-payment credential from the merchant's server when it has to act on a specific payment.
- **GoPay client SDK.** Embedded in the merchant's client. Renders the card form, runs Apple Pay and Google Pay, keeps cardholder data outside the merchant's code, and makes the client-side API calls on the merchant's behalf. Distributed as TypeScript, Swift, and Kotlin packages.
- **GoPay API.** Reachable at `https://gate.gopay.com/gp-gw/api/4.0` in production and `https://gw.sandbox.gopay.com/gp-gw/api/4.0` in sandbox.

Credentials, OAuth 2.0 flows, scopes, and the card-data envelope are covered on the security page.

### API version

The version segment in the base URL — `4.0` — identifies the REST contract. It is not the version of this documentation or of any GoPay SDK, and it does not follow semver: it moves by a minor point, `4.0` → `4.1`, and only when a change would break existing integrations. A change that breaks nothing is added to the current version, so a merchant who ignores it keeps working.

When a new version is published, both versions run at the same time for a transition period. The previous version is deprecated at the end of that period, with the end date announced in advance. Merchants move to the new base URL at any point within it, and nothing has to change on the day the new version appears.

### Integration shapes

Two integration shapes are supported. Each one corresponds to a distinct way the customer interacts with GoPay during checkout. The names are historical.

**Checkout.** The merchant owns the checkout UI. The GoPay client SDK collects cardholder data, runs the wallets and, by default, charges the payment and drives it to a final state. Alternatively, the merchant's server charges the payment with the encrypted card the SDK returns. The merchant controls how the checkout looks, including the styling of the card form. Unlike with Redirect, the customer's browser does not load GoPay's hosted gateway, only the SDK and what the payment methods on the merchant's page require. See the checkout integration page.

**Redirect.** The customer is sent to GoPay's hosted UX at `Payment Details.gw_url` — GoPay's hosted payment gateway, which offers every payment method the eshop has enabled. It is a destination the customer is sent to and cannot be embedded in the merchant's own checkout. The merchant's server creates the payment; GoPay drives the rest. The outcome is delivered by webhook and is also available by polling the payment; the payment stays fully v4-observable throughout. The merchant's client does not need the GoPay SDK. See the hosted integrations page.

Merchants should not mix integration shapes on the same payment — the resulting flows are difficult to troubleshoot. The documented exception is combining a QR option with a card or wallet on the same payment, described on the QR Payment page.

Concerns shared across shapes — payment lifecycle, saved cards, wallets, refunds, recurrences, payment links, events and webhooks, errors — have their own pages and are referenced from each shape's page.

### Site requirements

Both development and production must run on a hostname over HTTPS. A bare IP address will not do, and `localhost` is not a substitute either — the parts of the integration that match the origin against a domain registered with GoPay, Apple Pay above all, reject it.

For local development a self-signed certificate and a hosts-file entry are enough for everything the customer's browser touches — the `return_url` it is redirected to, and the origin Apple Pay matches against. Point a name such as `dev.example.com` at `127.0.0.1` in the hosts file, serve the site over HTTPS with a locally trusted certificate, and register that name with GoPay. Some browser-side pieces do work against `https://localhost`, but the hosts-file name is what also satisfies Apple Pay, so it is the setup worth standing up once.

`notification_url` is the exception. GoPay's own servers deliver the notification, so it has to be an HTTPS endpoint they can reach — a hosts-file alias pointing at `127.0.0.1` exists only on the developer's machine. Use a tunnel to the local machine, or a deployed environment, for anything that has to receive notifications or webhooks.

The sandbox is more tolerant than production, so a payment created successfully there is no evidence that the same request will be accepted in production, where a `return_url` that is not HTTPS is rejected with `403`. That check is on the scheme alone — passing it does not exempt an integration from the hostname requirement above. Apple Pay is stricter than the API itself and does not work without a registered HTTPS origin — see the Apple Pay page.

A checkout page that sends a Content-Security-Policy must allow the GoPay hosts and the wallet hosts. The list is on the checkout integration page.

### Client SDKs

The GoPay client SDK is published as three packages.

- TypeScript (browser) — `@gopaycz/gopay-js-sdk-browser` · `npm install @gopaycz/gopay-js-sdk-browser`
- Swift — [`GopaySDK`](https://github.com/gopaycommunity/gopay-ios-sdk) · Swift Package Manager `https://github.com/gopaycommunity/gopay-ios-sdk.git` or CocoaPods `pod 'GopaySDK'`
- Kotlin — [`cz.gopay:sdk`](https://github.com/gopaycommunity/gopay-android-sdk) · Maven Central `implementation("cz.gopay:sdk:<version>")`

A checkout built on the browser package also runs in mobile browsers. The Swift and Kotlin packages are for native mobile applications, so a merchant without a native application does not need them. The Swift package requires iOS 13 or later, and the Kotlin package requires Android 7.0 (API level 24) or later.

Each package renders the card form, charges the payment, handles the 3-D Secure step, and reads the payment and its QR code. With the Swift and Kotlin packages, the application polls the charge state itself. Apple Pay is available in the browser and Swift packages, and Google Pay in the browser and Kotlin packages. Per-language examples are on the checkout integration page and on the saved cards, Apple Pay, and Google Pay pages.

### Server-side libraries

GoPay publishes server-side libraries for PHP and TypeScript.

- PHP — [`gopaycommunity/gopay-php-api-v4`](https://github.com/gopaycommunity/gopay-php-api-v4) · `composer require gopaycommunity/gopay-php-api-v4`
- TypeScript (server) — `@gopaycz/gopay-js-sdk` · `npm install @gopaycz/gopay-js-sdk`

The PHP library requires PHP 8.1 or later and works with any PSR-18 HTTP client, such as Guzzle.

For other languages, a server-side library may be generated from the OpenAPI specification using the [OpenAPI Generator](https://openapi-generator.tech/). The generated client mirrors the spec exactly and is regenerated whenever the spec changes.

The examples below produce client libraries for Python, C#, and Java using the OpenAPI Generator Docker image. Generator-specific options may be adjusted from the per-generator documentation linked from each section.

#### Python

See the [Python generator documentation](https://openapi-generator.tech/docs/generators/python/) for the full option set.

```shell
docker run --rm \
  -v "${PWD}:/local" \
  openapitools/openapi-generator-cli generate \
  -i /local/Payments.yaml \
  -g python \
  -o /local/payments-python-client \
  --additional-properties="\
library=asyncio,\
generateSourceCodeOnly=true,\
useOneOfDiscriminatorLookup=true,\
disallowAdditionalPropertiesIfNotPresent=false,\
enumUnknownDefaultCase=true,\
projectName=payments-client"
```

#### C\#

See the [C# generator documentation](https://openapi-generator.tech/docs/generators/csharp/) for the full option set.

```shell
docker run --rm \
  -v "${PWD}:/local" \
  openapitools/openapi-generator-cli generate \
  -i /local/Payments.yaml \
  -g csharp \
  -o /local/payments-csharp-client \
  --additional-properties="\
library=restsharp,\
equatable=true,\
netCoreProjectFile=true,\
nullableReferenceTypes=true,\
useOneOfDiscriminatorLookup=true,\
disallowAdditionalPropertiesIfNotPresent=false,\
packageName=GoPay.Payments"
```

#### Java

See the [Java generator documentation](https://openapi-generator.tech/docs/generators/java/) for the full option set.

```shell
docker run --rm \
  -v "${PWD}:/local" \
  openapitools/openapi-generator-cli generate \
  -i /local/Payments.yaml \
  -g java \
  -o /local/payments-java-client \
  --additional-properties="\
library=native,\
serializationLibrary=jackson,\
useJackson3=true,\
useJakartaEe=true,\
useOneOfInterfaces=true,\
useOneOfDiscriminatorLookup=true,\
disallowAdditionalPropertiesIfNotPresent=false,\
enumUnknownDefaultCase=true,\
legacyDiscriminatorBehavior=false,\
generateBuilders=true,\
generateConstructorWithAllArgs=true,\
groupId=com.gopay,\
artifactId=payments-client,\
invokerPackage=com.gopay.payments"
```

The output directory contains a generated `README.md` describing how to consume the resulting client.

### Operational contact

Some settings on GoPay's side are not exposed through the API and are changed by emailing `integration@gopay.com`. The most common ones are Apple Pay domain registration, Google Pay merchant identifier submission, recurrence `ON_DEMAND` throttle adjustments, the default payment timeout per eshop, the notification endpoint and the events an eshop receives, sandbox provisioning, and tokenisation enablement. Each topic page links back here.

### Glossary

- `goid` — identifier of an eshop within the merchant's account, carried in `/eshops/{goid}/…` paths.
- `payment_secret` — per-payment credential returned in `Payment Details`, which the merchant's server passes to the GoPay client SDK. See the security page.
- `shareable_key` — client-side key paired with `client_id` and configured in the GoPay client SDK. It is safe to embed in client builds.
- JWE — JSON Web Encryption envelope in which the GoPay client SDK carries an encrypted card. It is single-use and valid for ten minutes.
- card token — permanent token that stands in for a saved card and is charged as a `CARD_TOKEN` input. See the saved cards page.
- network token — token issued by the card scheme in place of the card number. Its masked form is `masked_virtual_pan` on a saved card.
- `fingerprint` — value on a saved card that stays the same across tokenisations of the same physical card.
- payment instrument — the means that settles a payment, carried in `payment_instrument` on the charge request. Today it is always a payment card.
- PCI DSS SAQ-A / SAQ-D — the card-industry self-assessment levels that apply when the GoPay client SDK collects card data (SAQ-A), or when the merchant's own code does (SAQ-D). See the security page.

---

## Security and credentials

Every authenticated call against the GoPay Payments API is made by one of two actors: the merchant's server, or the merchant's client (a browser frontend or a mobile application) through the GoPay client SDK. Each actor authenticates differently, and the two are not interchangeable. A third concern — getting cardholder data into a charge call without the merchant's code ever seeing it — is handled by a separate envelope and is covered in the last section.

### Credentials

Five credentials cover every authenticated call. Each one is introduced below at the point it is used; the list here is a quick reference.

- `client_id` — public identifier of the merchant.
- `client_secret` — server-side secret paired with `client_id`. Format: `cs_` followed by 32 alphanumeric characters, for example `cs_4f9a2b7e6d8c1a3e5b9d2f7c8a4e6b1d`.
- `shareable_key` — client-side key paired with `client_id`, configured in the GoPay client SDK. Format: `sk_` followed by 32 alphanumeric characters, for example `sk_2d8e7c1a4f9b3e5d6a2c8f7b9e4d1a3c`.
- `payment_secret` — per-payment credential returned on payment creation, which the merchant's server passes to the GoPay client SDK. Format: `ps_` followed by 32 alphanumeric characters, for example `ps_6c1a9f4e7d2b8c3a5e9d6f2c1a4b7e8d`.
- `goid` — eshop identifier within the merchant. Carried as a path parameter on `/eshops/{goid}/…`.

### Server-side

The merchant's server holds the long-lived merchant credentials and may call any operation in the API except those that are explicitly client-only. It is the only actor that authenticates as the merchant itself.

#### Storage

`client_secret` must stay on the merchant's server. It must not appear in client builds, in version control, in log output, or in any file reachable from the browser. `client_id` is public and may appear in client builds and browser-reachable code.

#### Obtaining an access token

The merchant's server authenticates itself by exchanging its credentials for a JSON Web Token. The exchange happens at `POST /oauth2/token`, using the `client_credentials` grant.

The request is form-encoded. `client_id:client_secret` is presented as HTTP Basic; the requested scopes are listed in the body.

```http
POST /gp-gw/api/4.0/oauth2/token HTTP/1.1
Host: gate.gopay.com
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=payment:read%20payment:write
```

At least one scope must be requested. The response is an `Access Token`, whose `access_token` field is a JWT.

The available scopes are:

- `payment:read` — reads on payments, charges, refunds, recurrences, and payment links.
- `payment:write` — creating, charging, canceling, modifying, and refunding payments, and managing recurrences and payment links.
- `card:read` — reads on saved card tokens.
- `card:write` — saving and deleting card tokens.
- `event:read` — reads on the eshop's event log.
- `shared:read` — public resources, such as the keys that verify webhook signatures.

#### Using the access token

The JWT is presented on every subsequent API call as a Bearer token in the `Authorization` header.

```http
GET /gp-gw/api/4.0/payments/123456 HTTP/1.1
Host: gate.gopay.com
Authorization: Bearer eyJraWQiOiJzaWduLTIwMjYtMDIiLCJ0eXAiOiJKV1QiLCJhbGciOi…
```

The JWT is valid for fifteen minutes. When the JWT expires the merchant's server obtains a new one by repeating the exchange.

The full claim set is documented on the `JWT` schema in the OpenAPI reference and includes `sub`, `scope`, `iat`, `exp`, and `domain`. The claims may be read — reading `exp` to schedule refresh and `scope` to confirm what was granted is supported and recommended.

#### Reach of the merchant access token

The merchant access token unlocks every operation. Operations grouped under SDK Services in the OpenAPI reference are called by the GoPay client SDKs; the merchant's server does not need them. The merchant's server also receives the per-payment credential that the merchant's client uses.

### Client-side

The merchant's client cannot hold `client_secret`. It works through the GoPay client SDK, which holds the two client-side credentials and makes the client-side calls with them.

#### Configuring the SDK

`shareable_key` is a static credential issued to the merchant alongside `client_id`. It is safe to embed in published application builds and browser-reachable JavaScript. The merchant's client initialises the GoPay client SDK with `client_id` and `shareable_key` once, at startup. `shareable_key` alone cannot read or change payments.

#### Handing the payment to the SDK

`payment_secret` gives the GoPay client SDK access to one payment. It is created by GoPay when the payment is created and returned to the merchant's server in `Payment Details.payment_secret`, next to the payment's `id`.

1. The merchant's server delivers `id` and `payment_secret` to the merchant's client over its own authenticated HTTPS channel, such as an API response or server-rendered HTML.
2. The merchant's client passes both values to the SDK: `attachPayment()` in the browser, `startPaymentSession()` in the iOS and Android applications.
3. The SDK obtains a payment-scoped access token with them and renews it when needed. The merchant's code does not handle that token.

The payment-scoped token carries one or both of two scopes:

- `payment:read` — reading the payment.
- `payment:charge` — charging the payment.

`payment_secret` must not be stored, logged, or embedded in a URL. A URL ends up in browser history, access logs and analytics, so a page that needs the payment again — such as the page the customer returns to after 3-D Secure — receives a fresh delivery from the merchant's server.

`payment_secret` does not expire. What the SDK may do with it depends on the state of the payment: an operation that the current state no longer allows, such as charging a payment that is already paid, is rejected, mostly with `409`. See the errors page.

#### Reach of the client-side credentials

Through the SDK, the merchant's client only ever calls operations that are reachable with `shareable_key` or `payment_secret`. All other operations — payment creation, issuing refunds, managing recurrences and payment links, saved-card management — are reserved for the merchant's server.

#### Flow

The end-to-end client-side flow from a payment creation to a status read.

```mermaid
sequenceDiagram
    autonumber
    participant MS as Merchant's server
    participant API as GoPay API
    participant MC as Merchant's client
    participant SDK as GoPay client SDK

    MC->>SDK: initialise with client_id and shareable_key
    MS->>API: POST /oauth2/token (client_credentials)
    API-->>MS: merchant access token
    MS->>API: POST /eshops/{goid}/payments
    API-->>MS: Payment Details (id, payment_secret)
    MS->>MC: id, payment_secret
    MC->>SDK: attach the payment (id, payment_secret)
    SDK->>API: obtain payment-scoped access
    SDK->>API: GET /payments/{id}
    API-->>SDK: Payment Details
```

### Card data encryption

Cardholder data never reaches GoPay's API as plaintext. The GoPay client SDK produces a JWE (a JSON Web Encryption envelope) that wraps the encrypted card. The merchant's code receives the JWE only when it has to pass it on: to the SDK's charge call in the iOS and Android applications, or to the merchant's server when the server tokenises the card or charges the payment. In the browser, a card form that charges keeps the JWE to itself. The card-data flows are described on the checkout integration and saved cards pages; the constraints that bind the merchant are listed here.

- The JWE is valid for ten minutes from production.
- The JWE is single-use. It may be spent on one charge or one tokenisation, never both, never twice.
- The JWE must not be stored beyond the immediate call that consumes it, must not be logged, and must not be cached.

### PCI DSS scope

The PCI DSS scope of a v4 integration depends on whether the merchant's code ever sees cardholder data.

- If the GoPay client SDK collects and encrypts cardholder data — the merchant's code only handles the resulting JWE or card token — the integration qualifies for SAQ-A.
- If the merchant's code collects cardholder data directly and constructs the JWE itself instead of using the GoPay client SDK, the integration is in SAQ-D scope. Direct collection is supported only for merchants already operating under SAQ-D.

---

## Payment states and lifecycle

The payment is the central object of the GoPay Payments API. It carries an amount, a currency, a customer, and callback URLs; it has a state that progresses from creation to a terminal outcome; and it owns a charge sub-process that runs whenever a payment instrument attempts to settle it. This page documents the state catalogue, the charge sub-process, the cancel operation, the polling and notification mechanisms, and the per-method timeouts.

### Creating a payment

A payment is created with `POST /eshops/{goid}/payments`. The body is a `Payment Create Request`; the full shape is in the OpenAPI reference. The merchant's server authenticates with a merchant access token holding the `payment:write` scope; see the security page.

The response is a `Payment Details` object. Three fields drive every subsequent step.

- `id` — the payment identifier used in every operation on this payment.
- `gw_url` — the address of GoPay's hosted payment gateway, offering every payment method the eshop has enabled. It cannot be embedded in the merchant's own checkout. Used by the Redirect integration shape; see the hosted integrations page.
- `payment_secret` — the per-payment credential the merchant's server passes to the GoPay client SDK, so that the SDK can act on this payment. See the security page.

The newly created payment is in the `CREATED` state. From this point the customer is either sent to the hosted gateway at `gw_url` or pays through a checkout integration, where the GoPay client SDK or the merchant's server charges it.

### Payment states

The lifecycle of a payment is described by `Payment State`.

- `CREATED` — the payment exists and is awaiting a charge attempt. No instrument has been engaged.
- `PAYMENT_METHOD_CHOSEN` — a charge attempt is in flight; the outcome is not yet known. The name is historical and is best read as "pending".
- `PAID` — the payment was charged successfully and the funds were authorised.
- `CANCELED` — the customer abandoned the payment, the charge was rejected at authorisation, or the merchant canceled the payment before it was charged.
- `TIMEOUTED` — the payment did not reach a terminal outcome within the applicable timeout. The per-instrument values are listed below.
- `REFUNDED` — the payment was fully refunded. See the refunds page.
- `PARTIALLY_REFUNDED` — part of the payment was refunded. A payment may move through `PARTIALLY_REFUNDED` more than once before reaching `REFUNDED`. See the refunds page.
- `AUTHORIZED` — only relevant for the pre-authorisation flow.

```mermaid
stateDiagram-v2
    [*] --> CREATED
    CREATED --> PAYMENT_METHOD_CHOSEN
    CREATED --> CANCELED
    CREATED --> TIMEOUTED
    PAYMENT_METHOD_CHOSEN --> AUTHORIZED
    PAYMENT_METHOD_CHOSEN --> PAID
    PAYMENT_METHOD_CHOSEN --> CANCELED
    PAYMENT_METHOD_CHOSEN --> TIMEOUTED
    AUTHORIZED --> PAID
    AUTHORIZED --> CANCELED
    PAID --> REFUNDED
    PAID --> PARTIALLY_REFUNDED
    PARTIALLY_REFUNDED --> PARTIALLY_REFUNDED
    PARTIALLY_REFUNDED --> REFUNDED
```

### Charging a payment

This section applies to the checkout integration. For Redirect, the hosted gateway charges the payment itself; the merchant does not call the charge endpoint. See the hosted integrations page.

A charge is the sub-process that attempts to settle a payment with a specific instrument. It is initiated with `POST /payments/{payment_id}/charge`. The body is a `Payment Charge Input` carrying the instrument.

Only card payments are charged through the API today: a new card, a saved card, or an Apple Pay or Google Pay payment. See the checkout integration page. Other payment methods (online banking, BNPL, PayPal, mobile payments, crypto) are reachable only through the hosted gateway.

The charge is asynchronous. The response is a `Payment Charge Response` whose `state` is one of:

- `REQUESTED` — the charge has been accepted and is queued.
- `PROCESSING` — the charge is in flight with the payment processor.
- `ACTION_REQUIRED` — the customer must complete an external step. The response carries an `action` describing what is required. The action shapes and their handling are documented on the integration page for the instrument that produced them; for card payments, see the checkout integration page.
- `SUCCEEDED` — the charge completed successfully. The payment is `PAID`.
- `FAILED` — the charge did not succeed. The reason is delivered in `Payment Charge Status Response.fail_reason`.

A charge reaches a terminal state at `SUCCEEDED` or `FAILED`. In a checkout integration, the GoPay client SDK follows the charge to that state: the browser package on its own, the iOS and Android packages through the payment session's charge-state read and 3-D Secure call, which the application drives.

A payment is charged once. A second `POST /payments/{payment_id}/charge` against the same payment fails; no idempotency mechanism is exposed, see the errors page. A charge rejected at authorisation moves the payment to `CANCELED`. If the customer tries again, the merchant's server creates a new payment and hands it to the merchant's client in the same way as the first.

### Canceling a payment

A payment that has not been charged can be canceled with `DELETE /payments/{payment_id}`. The merchant's server authenticates with a merchant access token holding the `payment:write` scope. A successful call returns `204`.

The payment is not deleted. Its state moves to `CANCELED` and the payment stays readable through `GET /payments/{payment_id}`.

Only a payment in `CREATED` can be canceled. Any other state returns `409` and leaves the payment unchanged. See the errors page.

The state decides this, not the charge attempt. A charge rejected before it engages a payment instrument — one carrying an invalid card token, for example — leaves the payment in `CREATED`, so it can still be canceled. Once a charge moves the payment to `PAYMENT_METHOD_CHOSEN`, the outcome belongs to the charge sub-process.

### Polling and notifications

The charge's terminal state is observed in two ways.

`GET /payments/{payment_id}/charge` returns the current `Payment Charge Status Response`. The recommended polling cadence is one second. Polling continues until `state` reaches `SUCCEEDED`, `FAILED` or `ACTION_REQUIRED`. In the browser, the GoPay client SDK polls. In the iOS and Android applications, the application polls through the payment session. The merchant's server polls only when it reads the charge itself.

The merchant's server is also notified through a webhook. When a charge reaches a terminal state, the payment produces an event — `payments.paid`, `payments.canceled` or `payments.timeouted` — and GoPay `POST`s it to the notification endpoint configured for the eshop. The merchant's server acknowledges with any `2xx` and re-fetches the payment. The event shape, the delivery contract and the retry behaviour are on the events and webhooks page. The webhook is the authoritative signal for server-side flows; polling is the natural choice when the merchant's client is waiting in-page for a charge to terminate.

### Return URL and notification URL

Two URLs carry the payment outcome back to the merchant. They are not interchangeable. Both are supplied at payment creation on `Payment Callback`.

`return_url` is where the customer's browser is sent at the end of the hosted flow. The redirect is a `GET` carrying `id` (and, for recurring children, `parent_id`) as query parameters. The body is empty. The merchant's server re-fetches the payment with `GET /payments/{payment_id}` to learn the outcome.

In a checkout integration, the customer's browser is also sent to `return_url` after the 3-D Secure step. The GoPay client SDKs for iOS and Android watch for this address to close their 3-D Secure screen, so `return_url` must not carry a fragment (`#…`).

Both URLs must be absolute HTTPS URLs with a hostname. They point at the merchant's site, which the site requirements on the overview page cover. A merchant with an iOS or Android application and no website uses the SDK's return address as `return_url`, as described on the checkout integration page. `notification_url` must additionally be reachable by GoPay's servers, which a local hosts-file alias is not. In production a `return_url` that is not HTTPS is rejected with `403` when the payment is created; the sandbox is more tolerant.

`notification_url` receives a notification when the state of the payment changes: a `GET` request carrying the payment `id` as a query parameter, with an empty body. The merchant's server re-fetches the payment to learn the new state. Webhooks do not go to `notification_url`; they are sent to the endpoint configured for the eshop, as described on the events and webhooks page.

The merchant's server should treat the webhook as the authoritative trigger.

### Timeouts

When a payment is created, an initial timeout starts. If no charge is attempted before it expires, the payment transitions to `TIMEOUTED`. The default is one hour. The default may be adjusted per eshop through `integration@gopay.com`.

Once a charge is attempted, a second, instrument-specific timeout takes over. This timeout is independent of how much of the initial window had elapsed. The per-instrument values are:

| Instrument | Timeout |
| --- | --- |
| Card payment (any card input type) | 1 hour |
| Online bank payment | 1 to 7 days, depending on the bank |
| PSD2 bank payment (PIS) | 1 hour |
| BNPL Twisto | 4 hours |
| BNPL Skip Pay | 13 hours |
| PayPal | 1 hour |
| Mobile payment / Premium SMS | 1 hour |
| Crypto | 48 hours |

Requesting a QR code for a payment extends the initial timeout to four days. The payment state is not changed by the request. See the QR Payment page.

---

## Hosted integrations

Hosted integrations hand the payment over to GoPay's hosted gateway, which offers the customer every payment method the eshop has enabled. The gateway is a destination the customer is sent to — it cannot be embedded in the merchant's own checkout. A merchant who needs the payment step inside their own UI can use the checkout integration, which today covers card, Google Pay, Apple Pay and QR payments and is being extended to further methods; every method the eshop has enabled is already available here on the gateway. In a hosted integration, the customer is sent to the GoPay-hosted payment UX to choose a payment method and complete the payment. The merchant's code never collects card data, never handles a wallet payload, and never calls the charge endpoint.

### Flow

1. The merchant's server obtains a merchant access token with the `payment:write` scope. See the security page.
2. The merchant's server creates the payment with `POST /eshops/{goid}/payments`. The body is a `Payment Create Request`; `Payment Callback.return_url` and `Payment Callback.notification_url` must be supplied. See the payment lifecycle page.
3. The merchant's server reads `Payment Details.gw_url` from the response and uses it to send the customer to the gateway, as described below.
4. The customer is taken to the gateway, picks a payment method, and completes the payment. At the end, the customer's browser is redirected to `return_url` with the payment `id` (and `parent_id` for recurring children) as query parameters.
5. The merchant's server reacts to the `payments.*` event delivered as a webhook and re-fetches the payment with `GET /payments/{payment_id}` to learn the new state. The webhook is the authoritative trigger; the return-URL handling is for the customer-facing page. See the events and webhooks page.

The merchant should not call `POST /payments/{payment_id}/charge` for hosted payments. The hosted gateway charges the payment itself.

### Redirect

The customer's browser is sent to `Payment Details.gw_url` with a normal full-page navigation. The customer leaves the merchant's site for the duration of the payment and returns through `return_url`.

Three techniques are equivalent at the API level. The choice is a matter of how the merchant's server hands the URL to the browser.

- HTML link. The merchant's server renders a page containing `<a href="<gw_url>">…</a>`.
- HTTP redirection. The merchant's server returns a `302 Found` with `Location: <gw_url>`.
- Client-side JavaScript. The merchant's client receives `gw_url` from its server (for example through an AJAX call) and assigns it to `window.location`.

```html
<!-- HTML link -->
<a href="https://gate.gopay.com/gw/300000001">Pay</a>
```

```http
HTTP/1.1 302 Found
Location: https://gate.gopay.com/gw/300000001
```

### Hosted gateway in a mobile application

A merchant whose checkout runs inside a native mobile application should open `gw_url` in a system browser component — Chrome Custom Tabs on Android and `SFSafariViewController` on iOS. In-app web views (Android `WebView`, iOS `WKWebView`) do not run a full browser environment, so online banking redirects may not behave correctly. A merchant with a native checkout UI on mobile can use the checkout integration instead as far as it reaches — card, Google Pay, Apple Pay and QR today; anything beyond that still goes through `gw_url` in a system browser component.

### Sequence

```mermaid
sequenceDiagram
    autonumber
    participant MS as Merchant's server
    participant MC as Merchant's client
    participant GW as GoPay hosted gateway
    participant API as GoPay API

    MS->>API: POST /eshops/{goid}/payments
    API-->>MS: Payment Details (id, gw_url)
    MS->>MC: gw_url
    MC->>GW: open gw_url
    Note over MC,GW: customer picks a method and completes the payment
    GW-->>MC: return_url with id
    API-->>MS: webhook with payments.* event
    MS->>API: GET /payments/{id}
    API-->>MS: Payment Details (terminal state)
```

---

## Checkout integration

In a checkout integration, the merchant owns the checkout UI and the GoPay client SDK takes the payment inside it. The SDK collects card data, runs the wallets, and charges the payment, including the 3-D Secure step. Cardholder data passes through the SDK only, never through merchant-written code, so the integration remains within PCI DSS SAQ-A scope. The hosted gateway is not used.

Saving cards is covered on the saved cards page, the wallet setup on the Apple Pay and Google Pay pages, and the QR option offered next to the card form on the QR payment page.

### Flow

The checkout follows the same steps whichever way the customer pays.

1. The merchant's server creates the payment with `POST /eshops/{goid}/payments`, authenticated with a merchant access token holding the `payment:write` scope. See the payment lifecycle page.
2. The merchant's server hands `Payment Details.id` and `Payment Details.payment_secret` to the merchant's client. See the security page.
3. The merchant's client attaches the payment to the GoPay client SDK.
4. The customer pays with a new card in the SDK card form, with a saved card, or with a wallet.
5. The SDK charges the payment and handles the 3-D Secure step if the card issuer requires one.
6. The merchant's client reads the outcome from the SDK. The merchant's server reacts to the `payments.*` event delivered as a webhook, which is the authoritative signal. See the events and webhooks page.

```mermaid
sequenceDiagram
    autonumber
    participant MS as Merchant's server
    participant MC as Merchant's client
    participant SDK as GoPay client SDK
    participant API as GoPay API

    MS->>API: POST /eshops/{goid}/payments
    API-->>MS: Payment Details (id, payment_secret)
    MS->>MC: id, payment_secret
    MC->>SDK: attach the payment
    Note over MC,SDK: customer pays with a new card, a saved card or a wallet
    SDK->>API: POST /payments/{id}/charge
    API-->>SDK: Payment Charge Response
    opt state = ACTION_REQUIRED
        SDK->>MC: present the 3-D Secure step
        Note over MC: in the browser, the outcome is then read on the return_url page
    end
    loop until SUCCEEDED or FAILED
        SDK->>API: GET /payments/{id}/charge
        API-->>SDK: Payment Charge Status Response
    end
    SDK-->>MC: charge outcome
    API-->>MS: webhook with payments.* event
    MS->>API: GET /payments/{id}
    API-->>MS: Payment Details (terminal state)
```

The SDK may also hand the encrypted card back instead of charging, so that the merchant's server charges the payment. See Charging from the merchant's server below.

A payment is charged once. If the charge ends in `FAILED`, a further attempt by the customer needs a new payment, handed to the merchant's client and attached in the same way. See the payment lifecycle page.

### SDK initialisation

The merchant's client initialises the GoPay client SDK with `client_id` and `shareable_key` once, at application startup. Before a payment is charged, the merchant's client attaches it: it passes `Payment Details.id` and `Payment Details.payment_secret` to `attachPayment()` in the browser, or to `startPaymentSession()` in the iOS and Android applications. The SDK obtains the access it needs for that payment itself. See the security page.

In the browser, the SDK works on one payment at a time. A later `attachPayment()` replaces the earlier payment. While a card form is mounted, `attachPayment()` is refused with `INVALID_ARGUMENT`, so the merchant's client calls `unmount()` on the card form before it attaches another payment. In the iOS and Android applications, the SDK keeps one payment session per payment, and sessions for several payments may be open at once. A second session for the same payment is refused while the first one is open.

The look of the card form — colours, fonts and borders — is set through a theme when the form is created. The Swift and Kotlin card forms accept a subset of the browser theme's keys. In the browser, `setTheme()` changes the theme of a card form that is already mounted, and the card form accepts font names only, not font files or URLs, so only typefaces installed on the customer's device are available.

#### Browser: initialise and attach a payment

```typescript
import { createGoPayBrowserSDK } from '@gopaycz/gopay-js-sdk-browser';

// Initialise once with keys obtained server-side via serverSdk.getBrowserKeys()
const sdk = createGoPayBrowserSDK({
  environment: 'production',
  shareableKey: 'sk_live_…',
  clientId: 'your-client-id',
});

// Before any payment-scoped operation, attach the payment.
// paymentId and paymentSecret come from serverSdk.createPayment() on your server.
await sdk.attachPayment({
  paymentId: payment.id,
  paymentSecret: payment.payment_secret,
});
```

#### iOS: initialise and start a payment session

```swift
import GopaySDK

// Initialise once at app start. clientId and shareableKey are safe to embed in the app.
GopaySDK.shared.initialize(
    with: GopaySDKConfig(
        environment: .production,
        clientId: "your-client-id",
        shareableKey: "sk_live_…"
    )
)

// Before any payment-scoped operation, start a session for the payment.
// paymentId and paymentSecret come from serverSdk.createPayment() on your server.
let session = try await GopaySDK.shared.startPaymentSession(
    paymentId: payment.id,
    paymentSecret: payment.paymentSecret
)

// When the checkout is finished, close() wipes paymentSecret from memory.
await session.close()
```

#### Android: initialise and start a payment session

```kotlin
import cz.gopay.sdk.GopaySDK
import cz.gopay.sdk.config.Environment
import cz.gopay.sdk.config.GopayConfig

// Initialise once in Application.onCreate(). clientId and shareableKey are safe to embed in the app.
GopaySDK.initialize(
    GopayConfig(
        environment = Environment.PRODUCTION,
        clientId = "your-client-id",
        shareableKey = "sk_live_…"
    )
)

// Before any payment-scoped operation, start a session for the payment.
// paymentId and paymentSecret come from serverSdk.createPayment() on your server.
val session = GopaySDK.getInstance().startPaymentSession(
    paymentId = payment.id,
    paymentSecret = payment.paymentSecret
)

// When the checkout is finished, close() wipes paymentSecret from memory.
session.close()
```

### Charging with a new card

The customer enters the card in the SDK card form, and the SDK charges the payment with it. The card reaches the charge as an `ENCRYPTED_CARD` input: a JWE (a JSON Web Encryption envelope) produced inside the SDK. Because the SDK makes the charge, it also handles the 3-D Secure step and follows the charge to `SUCCEEDED` or `FAILED`.

- In the browser, the card form is mounted with `flow: 'direct-charge'`. The SDK charges as soon as the customer submits the form, and the card form's `result` carries the outcome, unless a 3-D Secure redirect takes the customer off the page first.
- In the iOS and Android applications, the card form returns the JWE to the application, which passes it straight to the payment session's charge call. The application then follows the charge with the polling loop shown below.

The card is not saved. Saving a card during checkout is covered on the saved cards page.

#### Browser: card form, charge, and polling

```typescript
// Render the card form, charge, and poll until terminal state (direct-charge flow).
// Requires sdk.attachPayment() to have been called first.
// If 3DS is required, the SDK sends the whole page to the issuer (default redirect mode):
// ctrl.result then never settles, and the outcome is read on the return_url page.
const container = document.getElementById('card-form-container')!;
const ctrl = await sdk.mountCardForm(container, { flow: 'direct-charge' });

// Without a 3DS redirect: resolves with PaymentChargeStatusResponse on SUCCEEDED;
// rejects with GoPaySDKError on CHARGE_FAILED or CHARGE_TIMEOUT.
const result = await ctrl.result;
```

#### iOS: card form, charge, and polling

```swift
import SwiftUI
import GopaySDK

// Drives a charge to SUCCEEDED or FAILED. Each new 3DS redirect is presented
// in the SDK's web view, and polling continues afterwards.
func settle(_ session: PaymentSession, _ first: ChargePaymentResponse) async throws -> ChargePaymentResponse {
    var charge = first
    var presented = Set<String>()
    for _ in 0..<30 {
        if charge.state == .succeeded || charge.state == .failed { break }
        if let redirect = charge.action?.redirectUrl, let url = URL(string: redirect),
           presented.insert(redirect).inserted {
            try await session.handle3dsVerification(
                redirectURL: url,
                returnURL: charge.returnUrl.flatMap(URL.init(string:))
            )
        }
        try await Task.sleep(nanoseconds: 1_500_000_000)
        charge = try await session.getChargeState()
    }
    return charge // still in progress after ~45 s — the webhook carries the final state
}

// Render the card form, charge, and poll until terminal state.
// Requires a session from GopaySDK.shared.startPaymentSession().
struct CardCheckoutView: View {
    let session: PaymentSession
    @State private var isCardValid: Bool?

    var body: some View {
        VStack {
            GopayCardForm(validation: .live, isValid: $isCardValid)
            Button("Pay") {
                Task {
                    // The card form returns a JWE; card data never leaves the SDK.
                    let jwe = try await GopaySDK.shared.submitCardForm()
                    let request = ChargePaymentRequest.encryptedCard(
                        jwe,
                        browserData: await BrowserData.deviceDefault()
                    )
                    let result = try await settle(session, session.charge(request))
                }
            }
            .disabled(isCardValid != true)
        }
    }
}
```

#### Android: card form, charge, and polling

```kotlin
import android.app.Activity
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.*
import androidx.compose.ui.platform.LocalContext
import cz.gopay.sdk.model.ChargePaymentResponse
import cz.gopay.sdk.model.ChargeState
import cz.gopay.sdk.session.PaymentSession
import cz.gopay.sdk.ui.CardEncryptionResult
import cz.gopay.sdk.ui.PaymentCardForm
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch

// Drives a charge to SUCCEEDED or FAILED. Each new 3DS redirect is presented
// in the SDK's WebView, and polling continues afterwards.
suspend fun settle(activity: Activity, session: PaymentSession, first: ChargePaymentResponse): ChargePaymentResponse {
    var charge = first
    val presented = mutableSetOf<String>()
    repeat(30) {
        if (charge.state == ChargeState.SUCCEEDED || charge.state == ChargeState.FAILED) return charge
        val redirect = charge.action?.redirectUrl
        if (redirect != null && presented.add(redirect)) {
            session.handle3dsVerification(activity, redirect, charge.returnUrl)
        }
        delay(1_500)
        charge = session.getChargeState()
    }
    return charge // still in progress after ~45 s — the webhook carries the final state
}

// Render the card form, charge, and poll until terminal state.
// Requires a session from GopaySDK.getInstance().startPaymentSession().
@Composable
fun CardCheckout(session: PaymentSession, onResult: (ChargePaymentResponse) -> Unit) {
    val activity = LocalContext.current as Activity
    val scope = rememberCoroutineScope()
    var submit by remember { mutableStateOf<(suspend () -> CardEncryptionResult)?>(null) }

    PaymentCardForm(onEncryptionComplete = {}, onFormReady = { submit = it })
    Button(onClick = {
        scope.launch {
            // The card form returns a JWE; card data never leaves the SDK.
            val jwe = (submit?.invoke() as? CardEncryptionResult.Success)?.jwe ?: return@launch
            val charge = session.chargeWithEncryptedCard(activity, jwe)
            onResult(settle(activity, session, charge))
        }
    }) { Text("Pay") }
}
```

### Charging with a saved card

A card saved earlier is charged without the card form. The merchant's server reads the customer's card token from its own records and hands it to the merchant's client, and the SDK charges the payment with it as a `CARD_TOKEN` input. As with a new card, the SDK handles the 3-D Secure step and follows the charge to `SUCCEEDED` or `FAILED`.

Card tokens are created on the merchant's server; see the saved cards page.

#### Browser: charge with a saved card token

```typescript
// Charge with a saved card token — no card form interaction required.
// Requires sdk.attachPayment() to have been called first.
await sdk.chargePayment({
  payment_instrument: {
    payment_instrument: 'PAYMENT_CARD',
    input: {
      input_type: 'CARD_TOKEN',
      card_token: 'J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv…',
    },
  },
});

// Poll until SUCCEEDED or FAILED. If 3DS is required, the SDK sends the whole page
// to the issuer (default redirect mode), and the outcome is read on the return_url page.
const result = await sdk.awaitChargeState();
```

#### iOS: charge with a saved card token

```swift
// Charge with a saved card token — no card form interaction required.
// The token comes from your server, which stored it when the card was saved.
// Requires a session from GopaySDK.shared.startPaymentSession().
let request = ChargePaymentRequest.cardToken(
    "J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv…",
    browserData: await BrowserData.deviceDefault()
)
let result = try await settle(session, session.charge(request))
```

#### Android: charge with a saved card token

```kotlin
// Charge with a saved card token — no card form interaction required.
// The token comes from your server, which stored it when the card was saved.
// Requires a session from GopaySDK.getInstance().startPaymentSession().
val charge = session.chargeWithCardToken(
    activity = activity,
    cardToken = "J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv…"
)
val result = settle(activity, session, charge)
```

### Wallets

Apple Pay and Google Pay enter the checkout through the SDK. The SDK runs the wallet's payment sheet and charges the payment with the result. In the browser it also follows the charge to a terminal state; in the iOS and Android applications, the application follows the charge in the same way as a card charge. The merchant's code does not handle the wallet payload and does not call the charge endpoint for a wallet payment. A card paid with a wallet cannot be saved for later reuse.

The wallet setup, the availability checks and the per-platform examples are on the Apple Pay and Google Pay pages.

### 3-D Secure

The card issuer may require the customer to confirm a card payment in a 3-D Secure step. The SDK detects the step and presents it. The merchant supplies the challenge preference and the `return_url`, and in the browser also the page the customer returns to.

A completed 3-D Secure step does not mean that the charge succeeded. Authorisation runs after the step and may still fail; only `SUCCEEDED` confirms the payment.

#### Challenge preference

`Payment Card Charge Data.challenge_preference` carries the merchant's preference and accepts three values.

- `AUTO` — GoPay decides whether a challenge is required. This is the default when the field is omitted.
- `CHALLENGE_PREFERRED` — the merchant asks for strong customer authentication. The preference may still be ignored in some situations, for example for Apple Pay and some Google Pay payments.
- `NO_CHALLENGE_PREFERRED` — the merchant asks to skip the challenge. This is not a guarantee; the card issuer can still require a challenge.

The merchant passes the preference on the charge call: `challenge_preference` in the browser's `chargePayment()`, `challengePreference` on the charge calls of the iOS and Android payment session. The preference applies to every card input.

#### In the browser

By default, the SDK sends the whole page to the issuer's 3-D Secure page. The page unloads, so the result the merchant's client was waiting for never settles. When the step is complete, the customer's browser is sent to the `return_url` given when the payment was created.

The return to `return_url` is a new page load. The merchant's server reads the charge with `GET /payments/{payment_id}/charge` under its own access token, and treats the payment as paid only after that check. `return_url` should carry nothing confidential, and never `payment_secret`; an order reference that the merchant's server resolves is enough.

If the return page also shows the result in the browser, the merchant's server delivers a fresh `payment_secret` from its own authenticated endpoint, and the merchant's client attaches the payment again.

#### Browser: return page

```typescript
// On the return_url page. The merchant's server has already confirmed the outcome
// with its own access token; this only shows the result to the customer.
// paymentSecret comes from your own authenticated endpoint, never from the URL.
const { paymentId, paymentSecret } = await fetch('/api/checkout/payment', {
  credentials: 'include',
}).then((r) => r.json());

await sdk.attachPayment({ paymentId, paymentSecret });
const result = await sdk.awaitChargeState();
```

#### In the iOS and Android applications

When a charge state carries a 3-D Secure redirect, the application calls `handle3dsVerification()` on the payment session. The SDK presents the step in its own web view and returns when the issuer sends the customer to `return_url`. The payment session survives the step, and the application continues polling with `getChargeState()` until the charge reaches `SUCCEEDED` or `FAILED`. The `settle()` loop in the card form examples above does both.

The SDK recognises the end of the step by the `return_url`, so `return_url` must not carry a fragment (`#…`). A merchant without a website creates the payment with `https://gopay.com/sdk/charge-return` as `return_url`. The SDK closes its 3-D Secure screen on this address and never loads it.

### Charging from the merchant's server

The merchant's server may charge the payment itself, for example when it has to act on the card before the charge. The SDK then returns the encrypted card instead of charging. The merchant takes over two duties that the SDK otherwise performs: collecting the browser data, and handling the 3-D Secure step.

1. The customer enters the card in the SDK card form. In the browser, the card form is mounted with `flow: 'return-payload'`, and its `result` carries the JWE. In the iOS and Android applications, the card form always returns the JWE.
2. Immediately before the charge, the merchant's client collects the browser data through the SDK: `getBrowserData()` in the browser, `completeBrowserData()` on the payment session in the iOS and Android applications. It sends the browser data to the merchant's server together with the JWE.
3. The merchant's server calls `POST /payments/{payment_id}/charge` with an `ENCRYPTED_CARD` input carrying the JWE in `payload`, and with the browser data in `browser_data`, unchanged. A charge with a saved card carries a `CARD_TOKEN` input instead.
4. If the charge response, or a later poll of `GET /payments/{payment_id}/charge`, is in `ACTION_REQUIRED`, the customer must complete the 3-D Secure step. The merchant either sends the customer's browser to `Emv 3DS Action.redirect_url` itself, or hands the step back to the SDK: `awaitChargeState()` on the attached payment in the browser, `handle3dsVerification()` on the payment session in the iOS and Android applications. The redirect must follow at once, because the issuer keeps the step open only for a short time. The outcome is then read as described under 3-D Secure above.

The JWE is single-use and valid for ten minutes, so the merchant's client forwards it without delay. See the security page.

```mermaid
sequenceDiagram
    autonumber
    participant MC as Merchant's client
    participant SDK as GoPay client SDK
    participant MS as Merchant's server
    participant API as GoPay API

    MC->>SDK: render card form
    SDK-->>MC: JWE
    MC->>SDK: collect browser data
    SDK-->>MC: browser_data
    MC->>MS: JWE, browser_data
    MS->>API: POST /payments/{id}/charge (ENCRYPTED_CARD, browser_data)
    API-->>MS: Payment Charge Response
    opt state = ACTION_REQUIRED
        MS-->>MC: Emv 3DS Action.redirect_url
        MC->>SDK: hand the 3-D Secure step to the SDK, or redirect the customer directly
    end
```

The charge request body is a `Payment Charge Input` carrying a `PAYMENT_CARD` payment instrument.

```http
POST /gp-gw/api/4.0/payments/300000001/charge HTTP/1.1
Host: gate.gopay.com
Authorization: Bearer eyJraWQiOiJzaWduLTIwMjYtMDIiLCJ0eXAiOiJKV1QiLCJhbGciOi…
Content-Type: application/json

{
  "payment_instrument": {
    "payment_instrument": "PAYMENT_CARD",
    "input": {
      "input_type": "ENCRYPTED_CARD",
      "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkI…"
    },
    "browser_data": {
      "language": "cs-CZ",
      "timezone": -60,
      "screen_width": 434,
      "screen_height": 965,
      "color_depth": 24,
      "user_agent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Mobile Safari/537.36",
      "accept_header": "{\"accept-language\":\"cs;q=0.5\",\"accept-encoding\":\"gzip, deflate, br, zstd\",\"accept\":\"application/json, text/plain, */*\"}",
      "javascript_enabled": true,
      "ip": "192.0.2.42"
    },
    "challenge_preference": "AUTO"
  }
}
```

For a charge with a saved card, the `input` block is a `Card Token Input`.

```json
{
  "input_type": "CARD_TOKEN",
  "card_token": "J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv…"
}
```

The response is a `Payment Charge Response`. Its `state` values are listed on the payment lifecycle page; its `action` field carries the 3-D Secure redirect when the state is `ACTION_REQUIRED`.

#### Browser data

`browser_data` is forwarded to the card issuer during 3-D Secure authentication. Its `ip`, `user_agent` and `accept_header` fields describe the customer's connection, so they must originate in the customer's browser or device, collected immediately before the charge and not cached.

The merchant's server must not fill these fields in from the request it received. The address it sees is the one its own proxy or CDN reports, and a charge issued from a queue or a retry has no customer request to read at all. A server that substitutes its own values produces a payload that looks valid and then fails authentication. A charge that runs later carries the values captured when the customer submitted, stored alongside the pending charge.

#### Browser: charge from the merchant's server

```typescript
// The merchant's server charges: the card form returns the encrypted card instead.
// Requires sdk.attachPayment() so that the 3DS step can be handed back to the SDK.
const container = document.getElementById('card-form-container')!;
const ctrl = await sdk.mountCardForm(container, { flow: 'return-payload' });
const { encryptedPayload } = await ctrl.result;

// Browser data is collected in the customer's browser, immediately before the charge.
const browserData = await sdk.getBrowserData();

// Your own endpoint: the server charges with both values, unchanged.
await fetch('/api/charge', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ encryptedPayload, browserData }),
});

// The SDK redirects the page if 3DS is required (the outcome is then read
// on the return_url page); otherwise it polls until SUCCEEDED or FAILED.
const result = await sdk.awaitChargeState();
```

#### iOS: charge from the merchant's server

```swift
// The merchant's server charges: the card form returns the JWE and the app sends it on.
// Requires a session from GopaySDK.shared.startPaymentSession().
let jwe = try await GopaySDK.shared.submitCardForm()

// Browser data is collected on the device, immediately before the charge.
let browserData = try await session.completeBrowserData(await BrowserData.deviceDefault())

// Your own endpoint: the server charges with both values, unchanged.
try await backend.charge(paymentId: paymentId, jwe: jwe, browserData: browserData)

// settle(): presents a 3DS step if one is required, then polls to a terminal state.
let result = try await settle(session, session.getChargeState())
```

#### Android: charge from the merchant's server

```kotlin
// The merchant's server charges: the card form returns the JWE and the app sends it on.
// Requires a session from GopaySDK.getInstance().startPaymentSession().
val jwe = (submit?.invoke() as? CardEncryptionResult.Success)?.jwe ?: return

// Browser data is collected on the device, immediately before the charge.
val browserData = session.completeBrowserData(BrowserData.deviceDefault(activity))

// Your own endpoint: the server charges with both values, unchanged.
backend.charge(paymentId, jwe, browserData)

// settle(): presents a 3DS step if one is required, then polls to a terminal state.
val result = settle(activity, session, session.getChargeState())
```

### Content-Security-Policy

A checkout page that sends a Content-Security-Policy must allow the hosts the SDK and the wallets use.

```
connect-src      https://*.gopay.com
frame-src        https://secure.gopay.com
```

`connect-src` covers the GoPay API and the other GoPay services the SDK contacts. `frame-src` covers the card form.

Apple Pay needs `https://applepay.cdn-apple.com` in five directives.

```
script-src       https://applepay.cdn-apple.com
script-src-elem  https://applepay.cdn-apple.com
img-src          https://applepay.cdn-apple.com
frame-src        https://applepay.cdn-apple.com
font-src         https://applepay.cdn-apple.com
```

If only the script directives allow it, the Apple Pay button appears and the payment sheet then fails. Google Pay loads from `https://pay.google.com`, which the policy must also allow. If the policy refuses a wallet's script, the SDK reports the wallet as unavailable.

---

## Saved cards

A saved card is a permanent token that stands in for a customer's card on subsequent charges. The token is created from an encrypted card payload produced by the GoPay client SDK and exchanged for a `Permanent Card Token Details` object on the merchant's server. The token may then be carried on any later charge through the `CARD_TOKEN` input variant.

A card is saved in one of three ways: outside any payment, during a checkout before the payment is charged with the new token, or during a checkout only if the customer chooses to save it. Charging with a card saved earlier is covered on the checkout integration page.

### Enablement

Tokenisation is disabled by default and must be enabled for the merchant before any of the operations on this page are available. Enablement is requested through `integration@gopay.com`.

### Saving a card without a payment

A card may be saved outside any payment, for example on the customer's account page. No `payment_secret` is involved; the merchant's client initialises the SDK with `client_id` and `shareable_key` only. The SDK card form returns a JWE on submission: in the browser, the card form is mounted with `flow: 'return-payload'`; in the iOS and Android applications, the card form always returns the JWE.

The merchant's client forwards the JWE to the merchant's server. The merchant's server exchanges the JWE for a permanent token at `POST /cards/tokens`. The request body is a `Token Create Request` carrying the JWE in `payload`; the response is a `Permanent Card Token Details` object. Tokenisation requires the `card:write` scope on the merchant access token and is server-side only.

The JWE is single-use and is consumed by the tokenisation; the same JWE cannot also be used to charge a payment.

```http
POST /gp-gw/api/4.0/cards/tokens HTTP/1.1
Host: gate.gopay.com
Authorization: Bearer eyJraWQiOiJzaWduLTIwMjYtMDIiLCJ0eXAiOiJKV1QiLCJhbGciOi…
Content-Type: application/json

{
  "payload": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkI…"
}
```

```json
{
  "card_id": "8007127320",
  "masked_pan": "406821******1234",
  "masked_virtual_pan": "489537******6287",
  "expiration_month": "01",
  "expiration_year": "30",
  "scheme": "VISA",
  "corporate": false,
  "fingerprint": "73c8d0a48d91def897612b54e630997745e1faad43045e732189cfe4acf4961b",
  "token": "J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv…",
  "card_art_url": "https://card.art/pic.png",
  "brand": "GOLD",
  "service_type": "DEBIT",
  "status": "ACTIVE"
}
```

```mermaid
sequenceDiagram
    autonumber
    participant MC as Merchant's client
    participant SDK as GoPay client SDK
    participant MS as Merchant's server
    participant API as GoPay API

    MC->>SDK: initialise with client_id and shareable_key, render card form
    SDK-->>MC: JWE
    MC->>MS: forward JWE
    MS->>API: POST /cards/tokens (JWE)
    API-->>MS: Permanent Card Token Details (card_id, token, …)
```

#### Browser: tokenise a card without a payment

```typescript
// Standalone tokenisation — no payment attached, no paymentSecret required.
import { createGoPayBrowserSDK } from '@gopaycz/gopay-js-sdk-browser';

const sdk = createGoPayBrowserSDK({
  environment: 'production',
  shareableKey: 'sk_live_…',
  clientId: 'your-client-id',
});

const container = document.getElementById('card-form-container')!;
const ctrl = await sdk.mountCardForm(container, { flow: 'return-payload' });
const { encryptedPayload } = await ctrl.result;

// Forward encryptedPayload to your server.
// Server calls: serverSdk.tokenizeEncryptedCard(encryptedPayload)
```

#### iOS: tokenise a card without a payment

```swift
// Standalone tokenisation — no payment session, no paymentSecret required.
// The card form needs only the clientId and shareableKey passed to GopaySDK.shared.initialize(with:).
import SwiftUI
import GopaySDK

struct SaveCardView: View {
    @State private var isCardValid: Bool?

    var body: some View {
        VStack {
            GopayCardForm(validation: .live, isValid: $isCardValid)
            Button("Save card") {
                Task {
                    let jwe = try await GopaySDK.shared.submitCardForm()
                    // Forward jwe to your server.
                    // Server calls: serverSdk.tokenizeEncryptedCard(jwe)
                }
            }
            .disabled(isCardValid != true)
        }
    }
}
```

#### Android: tokenise a card without a payment

```kotlin
// Standalone tokenisation — no payment session, no paymentSecret required.
// The card form needs only the clientId and shareableKey passed to GopaySDK.initialize().
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.*
import cz.gopay.sdk.ui.CardEncryptionResult
import cz.gopay.sdk.ui.PaymentCardForm
import kotlinx.coroutines.launch

@Composable
fun SaveCardForm(onJwe: (String) -> Unit) {
    val scope = rememberCoroutineScope()
    var submit by remember { mutableStateOf<(suspend () -> CardEncryptionResult)?>(null) }

    PaymentCardForm(onEncryptionComplete = {}, onFormReady = { submit = it })
    Button(onClick = {
        scope.launch {
            when (val result = submit?.invoke()) {
                // Forward result.jwe to your server.
                // Server calls: serverSdk.tokenizeEncryptedCard(jwe)
                is CardEncryptionResult.Success -> onJwe(result.jwe)
                is CardEncryptionResult.Error -> { /* show result.message */ }
                null -> Unit
            }
        }
    }) { Text("Save card") }
}
```

### Saving a card during checkout

The card the customer enters at checkout may be saved first and the payment then charged with the new token. The JWE from the card form is spent on the tokenisation, so the charge uses the token, not the JWE.

1. The customer enters the card in the SDK card form, which returns the JWE as described above.
2. The merchant's client forwards the JWE to the merchant's server, which creates the token with `POST /cards/tokens`.
3. The merchant's server hands the token back to the merchant's client, and the SDK charges the payment with it as a `CARD_TOKEN` input. The SDK handles the 3-D Secure step, as for any charge it makes. See Charging with a saved card on the checkout integration page.

Alternatively, the merchant's server charges with the token itself. It then collects the browser data and handles the 3-D Secure step, as described under Charging from the merchant's server on the checkout integration page.

```mermaid
sequenceDiagram
    autonumber
    participant MC as Merchant's client
    participant SDK as GoPay client SDK
    participant MS as Merchant's server
    participant API as GoPay API

    MC->>SDK: render card form
    SDK-->>MC: JWE
    MC->>MS: forward JWE
    MS->>API: POST /cards/tokens (JWE)
    API-->>MS: Permanent Card Token Details (token)
    MS-->>MC: token
    MC->>SDK: charge with the token
    SDK->>API: POST /payments/{id}/charge (CARD_TOKEN)
    API-->>SDK: Payment Charge Response
```

#### Browser: save a card and charge with it

```typescript
// Save the card first, then let the SDK charge with the new token.
// Requires sdk.attachPayment() to have been called first.
const container = document.getElementById('card-form-container')!;
const ctrl = await sdk.mountCardForm(container, { flow: 'return-payload' });
const { encryptedPayload } = await ctrl.result;

// Your own endpoint: the server tokenises the JWE and returns the token.
const { cardToken } = await fetch('/api/cards', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ encryptedPayload }),
}).then((r) => r.json());

await sdk.chargePayment({
  payment_instrument: {
    payment_instrument: 'PAYMENT_CARD',
    input: { input_type: 'CARD_TOKEN', card_token: cardToken },
  },
});
const result = await sdk.awaitChargeState();
```

#### iOS: save a card and charge with it

```swift
// Save the card first, then let the SDK charge with the new token.
// Requires a session from GopaySDK.shared.startPaymentSession().
let jwe = try await GopaySDK.shared.submitCardForm()

// Your own endpoint: the server tokenises the JWE and returns the token.
let cardToken = try await backend.saveCard(jwe: jwe)

let request = ChargePaymentRequest.cardToken(
    cardToken,
    browserData: await BrowserData.deviceDefault()
)
// settle(): the polling loop from "iOS: card form, charge, and polling" on the checkout integration page.
let result = try await settle(session, session.charge(request))
```

#### Android: save a card and charge with it

```kotlin
// Save the card first, then let the SDK charge with the new token.
// Requires a session from GopaySDK.getInstance().startPaymentSession().
val jwe = (submit?.invoke() as? CardEncryptionResult.Success)?.jwe ?: return

// Your own endpoint: the server tokenises the JWE and returns the token.
val cardToken = backend.saveCard(jwe)

val charge = session.chargeWithCardToken(activity = activity, cardToken = cardToken)
// settle(): the polling loop from "Android: card form, charge, and polling" on the checkout integration page.
val result = settle(activity, session, charge)
```

### Letting the customer choose

The merchant may let the customer decide whether the card is saved. The choice is collected in the merchant's checkout UI, next to the SDK card form; the card form does not offer it.

The card form returns the JWE in both cases, and the merchant's client decides what to do with it after the customer submits.

- If the customer chooses to save the card, the merchant's client forwards the JWE to the merchant's server, as in Saving a card during checkout above.
- If the customer declines, the SDK charges the payment with the JWE as an `ENCRYPTED_CARD` input, and the card is not saved.

A JWE is spent on one of the two, never on both. In the iOS and Android applications, the choice selects between a card token and the encrypted card on the payment session's charge call.

#### Browser: save the card only if the customer chooses

```typescript
// The card form returns the JWE; the customer's choice decides where it goes.
// Requires sdk.attachPayment() to have been called first.
const ctrl = await sdk.mountCardForm(container, { flow: 'return-payload' });
const { encryptedPayload } = await ctrl.result;

const input = saveCardCheckbox.checked
  ? { input_type: 'CARD_TOKEN', card_token: await saveCard(encryptedPayload) } // your own endpoint
  : { input_type: 'ENCRYPTED_CARD', payload: encryptedPayload };

await sdk.chargePayment({ payment_instrument: { payment_instrument: 'PAYMENT_CARD', input } });
const result = await sdk.awaitChargeState();
```

### Reading a saved card

`GET /cards/tokens/{card_id}` returns the current `Permanent Card Token Details` for a saved card. The endpoint requires the `card:read` scope on the merchant access token and is server-side only.

The merchant must persist the association between `card_id` and customer; the API does not list saved cards.

### Deleting a saved card

`DELETE /cards/tokens/{card_id}` permanently deletes a saved card. The endpoint requires the `card:write` scope on the merchant access token and is server-side only. A deleted token is not recoverable; if the customer wants the same card saved again, the card must be saved again.

### Card states

`Card Token Status` describes the state of a saved card.

- `ACTIVE` — the token is valid and may be used on a charge.
- `SUSPENDED` — the token has been temporarily suspended by the card issuer and cannot be used. Neither the merchant nor GoPay can put a card into `SUSPENDED`; only the issuer can. The issuer may later move the card back to `ACTIVE` without the merchant's involvement.
- `DELETED` — the token has been deleted and cannot be used.

### Card updates

The instrument behind a token may change while the `card_id` stays the same. The card issuer may reissue the card with a new PAN or expiration date — a network reissue, a replacement after loss or theft, an expiry renewal — and the corresponding `Permanent Card Token Details` fields (`masked_pan`, `expiration_month`, `expiration_year`, and the network-token fields) are updated in place. Subsequent charges with the same `card_id` continue to work.

The merchant learns of an update through the `cards.updated` event. The merchant's server re-fetches the token with `GET /cards/tokens/{card_id}` to read the new fields. See the events and webhooks page.

### Token scope

A `card_id` is scoped to the merchant, not to a single eshop. The same token is usable across every `goid` belonging to that merchant.

`Customer.customer_id` on the payment is a label only; GoPay does not currently use it to scope tokens. The merchant is responsible for tying a `card_id` to a customer in its own systems.

### Single-token rule

Only one token per (merchant, card) pair exists at any time. Re-tokenising the same physical card returns the existing `card_id` with whatever fields the existing token already carries, including any updates the issuer has pushed in the meantime. The `fingerprint` field is stable across tokenisations of the same physical card and may be used to detect a re-tokenisation before the call is made.

To obtain a fresh token for the same card — for example, to discard a `SUSPENDED` token — the existing token must be deleted first.

### Merchant obligations

When saved cards are offered to the customer, the merchant must:

- provide an interface for the customer to view their saved cards;
- provide a way for the customer to delete a saved card.

The merchant may additionally offer a way to add a card outside the checkout, in which case Saving a card without a payment above applies.

At card-save time, the merchant must satisfy one of the following:

- inform the customer that the card will be saved
- have the customer choose whether to save the card
- restrict card saving to logged-in customers

---

## Apple Pay

Apple Pay is offered to the customer through the GoPay client SDK. The SDK shows the Apple Pay sheet, charges the payment with the result, and reports the charge outcome to the merchant's client. The merchant's code does not handle the Apple Pay payload and does not call the charge endpoint for an Apple Pay payment.

This page covers what the SDK does at charge time, the operational setup on the web and in the merchant's mobile application, and the availability checks. The checkout flow itself and the 3-D Secure handoff are covered on the checkout integration page; Apple Pay rides the same end-to-end shape.

### Runtime

The payment is attached to the GoPay client SDK before Apple Pay is offered, as described on the checkout integration page.

- In the browser, the merchant's client mounts the Apple Pay button with `mountApplePayButton`. The SDK draws the button. When the customer pays, the SDK runs the Apple Pay session, charges the payment, and drives the charge to a terminal state.
- In the iOS application, the merchant's application draws its own Apple Pay button and calls `chargeWithApplePay` on the payment session. The SDK presents the Apple Pay sheet and charges the payment with its result. The application then reads the charge state in the same way as for a card charge.

A card paid with Apple Pay cannot be saved for later reuse.

#### Browser: Apple Pay button and charge

```typescript
// Render Apple Pay button, charge payment, and poll until terminal state.
// Requires sdk.attachPayment() to have been called first.
const container = document.getElementById('apple-pay-button-container')!;
const ctrl = await sdk.mountApplePayButton(container, {
  onUnavailable: () => { /* Apple Pay not available — hide the button or show a fallback */ },
  onCancel: () => { /* User dismissed the sheet — update your UI */ },
});

// Resolves with PaymentChargeStatusResponse on SUCCEEDED.
const result = await ctrl.result;

// Call ctrl.unmount() when the component is torn down.
```

#### iOS: Apple Pay charge

```swift
// Charge with Apple Pay, then poll until terminal state.
// Requires a session from GopaySDK.shared.startPaymentSession().
// The app draws its own Apple Pay button (PKPaymentButton) and calls this from its action.
guard GopaySDK.canUseApplePay() else {
    // Apple Pay not available — hide the button or show a fallback
    return
}
do {
    // Presents the Apple Pay sheet and charges the payment with its result.
    let charge = try await session.chargeWithApplePay()
    // settle(): the polling loop from "iOS: card form, charge, and polling" on the checkout integration page.
    let result = try await settle(session, charge)
} catch is CancellationError {
    // User dismissed the 3-D Secure step — the charge state is still read with getChargeState()
} catch {
    // Charge failed, or the user dismissed the Apple Pay sheet — update your UI
}
```

### Web setup

Before Apple Pay on the web can be used, the merchant provides the production and sandbox eshop URLs to GoPay at `integration@gopay.com`. The Apple Pay button must only be offered on the URLs registered with GoPay; offering Apple Pay on any other URL is not supported.

The registered URL must be an absolute HTTPS URL with a hostname. Apple Pay does not work on `localhost` or on a bare IP address, neither in the sandbox nor in production — unlike the rest of the API, which is more tolerant in the sandbox. For local development, the merchant registers a hosts-file name served over HTTPS with a locally trusted certificate; see the site requirements on the overview page.

A page that sends a Content-Security-Policy must allow `https://applepay.cdn-apple.com` in five directives, not only in the script directives. The list is on the checkout integration page.

### App setup

Apple Pay inside the merchant's iOS application requires the merchant to enrol the application with Apple and exchange a payment-processing certificate with GoPay.

1. The merchant registers in the Apple Developer Portal.
2. The merchant requests a Certificate Signing Request from GoPay at `integration@gopay.com`.
3. The merchant creates an Apple Merchant Identifier in the Apple Developer Portal, enables the Apple Pay capability for the application, and links the Merchant Identifier to the application.
4. The merchant uploads the CSR to Apple as the Payment Processing certificate for that Merchant Identifier.
5. The merchant sends the resulting certificate file and the Apple Merchant Identifier to GoPay at `integration@gopay.com`.

After the certificate is in place with GoPay, no Apple Pay-specific step happens on the merchant's server at charge time.

### Availability

The GoPay client SDK checks whether Apple Pay is available before it offers it.

- In the browser, `mountApplePayButton` calls the `onUnavailable` callback instead of drawing the button when the customer's device or browser cannot pay with Apple Pay. A checkout that shows one payment method at a time asks `getApplePayAvailability()` before it renders the Apple Pay step. The call does not need an attached payment, so it answers before the payment is created.
- In the iOS application, `GopaySDK.canUseApplePay()` answers the same question.

The SDK loads Apple's Apple Pay script itself. The merchant's page does not include it, and an existing `<script>` tag for it may be removed.

Besides Safari, Apple Pay is offered in some desktop browsers, where the customer completes the payment by scanning a code with an iPhone. Mobile browsers other than Safari report Apple Pay as unavailable. The device toolbar of Chrome's developer tools makes the browser report itself as mobile, so Apple Pay is reported as unavailable while the toolbar is on.

### Operational contact

Domain registration, CSR requests, certificate uploads, and other Apple Pay enablement matters are handled at `integration@gopay.com`.

---

## Google Pay

Google Pay is offered to the customer through the GoPay client SDK. The SDK shows the Google Pay sheet, charges the payment with the result, and reports the charge outcome to the merchant's client. The merchant's code does not handle the Google Pay payload and does not call the charge endpoint for a Google Pay payment.

This page covers what the SDK does at charge time, the operational setup on the web and in the merchant's Android application, the availability check, and sandbox testing. The checkout flow itself and the 3-D Secure handoff are covered on the checkout integration page; Google Pay rides the same end-to-end shape.

### Runtime

The payment is attached to the GoPay client SDK before Google Pay is offered, as described on the checkout integration page.

- In the browser, the merchant's client mounts the Google Pay button with `mountGooglePayButton`. The SDK checks that Google Pay is available and draws the button. When the customer pays, the SDK runs Google Pay, charges the payment, and drives the charge to a terminal state.
- In the Android application, the merchant's application reads the Google Pay configuration with `getGooglePayInfo`, checks it with `isGooglePayAvailable`, and calls `chargeWithGooglePay` on the payment session. The SDK presents the Google Pay sheet and charges the payment with its result. The application then reads the charge state in the same way as for a card charge.

A card paid with Google Pay cannot be saved for later reuse.

#### Browser: Google Pay button and charge

```typescript
// Render Google Pay button, charge payment, and poll until terminal state.
// Requires sdk.attachPayment() to have been called first.
const container = document.getElementById('google-pay-button-container')!;
const ctrl = await sdk.mountGooglePayButton(container, {
  onUnavailable: () => { /* Google Pay not available — hide the button or show a fallback */ },
  onCancel: () => { /* User dismissed the payment sheet — update your UI */ },
});

// Resolves with PaymentChargeStatusResponse on SUCCEEDED.
const result = await ctrl.result;

// Call ctrl.unmount() when the component is torn down.
```

#### Android: Google Pay charge

```kotlin
// Charge with Google Pay, then poll until terminal state.
// Requires a session from GopaySDK.getInstance().startPaymentSession(), and
// com.google.android.gms:play-services-wallet in the app's dependencies.
val info = session.getGooglePayInfo()
if (!GopaySDK.getInstance().isGooglePayAvailable(activity, info)) {
    // Google Pay not available — hide the button or show a fallback
    return
}
try {
    // Presents the Google Pay sheet and charges the payment with its result.
    val charge = session.chargeWithGooglePay(activity)
    // settle(): the polling loop from "Android: card form, charge, and polling" on the checkout integration page.
    val result = settle(activity, session, charge)
} catch (e: CancellationException) {
    // User dismissed the payment sheet or the 3-D Secure step — update your UI
}
```

### Web setup

Google Pay on the web requires the merchant to register the production domains in the Google Pay & Wallet Console and to supply the resulting merchant identifier to GoPay. The Google Pay button must only be offered on the domains registered in the console.

1. The merchant signs in to the [Google Pay & Wallet Console](https://pay.google.com/business/console) with a Google account that will own the merchant record.
2. The merchant creates a business profile, chooses "Merchant" as the business type, and completes the requested business information.
3. The merchant opens the Google Pay API tab, clicks "Get Started", and accepts the Google Pay API Terms of Service and the Acceptable Use Policy. After acceptance, a merchant identifier appears in the top-right of the console.
4. The merchant navigates to `Google Pay API > Integrations > Integrate with your website` and adds each top-level production domain on which Google Pay will run.
5. The merchant integrates Google Pay on the site through the GoPay client SDK.
6. The merchant selects "Gateway" as the integration type, uploads screenshots of the running Google Pay integration on the site, and submits for approval.
7. The merchant sends the merchant identifier from step 3 to GoPay at `integration@gopay.com`.

Once Google approves the submission, the merchant is cleared to run Google Pay in production on the registered domains.

A page that sends a Content-Security-Policy must allow `https://pay.google.com`. The list is on the checkout integration page.

### App setup

Google Pay inside the merchant's Android application requires the merchant to register the application in the Google Pay & Wallet Console. No additional artefact has to be exchanged with GoPay for the in-app case — the same merchant identifier registered for the web side covers the application.

1. The merchant signs in to the [Google Pay & Wallet Console](https://pay.google.com/business/console). The business profile and the Terms-of-Service acceptance are not repeated if they have already been done for the web side.
2. The merchant opens `Google Pay API > Integrations > Integrate with your Android app` and selects the application from the Google Play Console listing. If the application is owned by a separate Google account, the merchant invites the Google Play Console account owner or administrator to gain access to the Google Pay & Wallet Console.
3. The merchant integrates Google Pay in the application through the GoPay client SDK.
4. The merchant builds an APK signed with the release signing key.
5. The merchant selects "Gateway" as the integration type, uploads screenshots of the integration in the application, and submits for approval. After approval, the merchant publishes the application on Google Play.

If the merchant ships an Android-only integration with no web side, the merchant identifier is still obtained from step 3 of the web procedure above and sent to GoPay at `integration@gopay.com` before the integration goes live in production.

### Availability

The GoPay client SDK offers Google Pay only where it can be used. In the browser, `mountGooglePayButton` calls the `onUnavailable` callback instead of drawing the button when the customer's browser cannot pay with Google Pay. In the Android application, availability depends on the payment's Google Pay configuration, so it is checked after the payment session starts, with `getGooglePayInfo` and `isGooglePayAvailable`.

### Sandbox testing

The sandbox relaxes the production requirements on the Google Pay side.

- The Google Pay & Wallet Console domain or application registration is not required.
- The merchant identifier is not required. The sandbox runs Google Pay in its test environment.
- The payment sheet displays a "Pay Unverified Merchant" banner and Google Pay returns dummy payment methods.
- The Android case does not require the release signing key for sandbox.

What the merchant still has to do for sandbox is on GoPay's side — sandbox credentials and the SDK pointed at the GoPay sandbox environment. The Google Pay & Wallet Console registration becomes a prerequisite only when the merchant moves to production.

### Operational contact

Merchant-identifier exchange, environment switches, and other Google Pay enablement matters are handled at `integration@gopay.com`.

---

## QR Payment

A QR payment lets the customer settle an existing payment by bank transfer. The merchant requests a QR image for the payment, displays it to the customer, and the customer scans it with a banking app. When the corresponding transfer is credited to GoPay's account, GoPay charges the payment and transitions it to `PAID`.

This page covers requesting the QR, the effect on the payment timeout, coexistence with a card or wallet option on the same payment, and how the merchant learns of the settlement.

### Requesting the QR

A QR for an existing payment is requested with `GET /payments/{payment_id}/qr-payment/info`. The endpoint accepts either the merchant access token with the `payment:read` scope or the payment-scoped token with the `payment:read` scope; see the security page. The merchant's server may call it, and the merchant's client reads the same response through the GoPay client SDK: `getQRPaymentInfo()` in the browser, `getQrPaymentInfo()` on the payment session in the iOS and Android applications.

The response is a `QR Payment Details` object carrying the payment amount, the recipient bank account, and the generated QR image. The image is delivered in `qr_code` as a base64-encoded string under one of the regional formats:

- `spayd` — SPAYD (Short Payment Descriptor), used in the Czech Republic.
- `paybysquare` — Pay by Square, used in Slovakia.
- `sepa` — SEPA, used for EUR payments.
- `mnb_qr` — MNB (Magyar Nemzeti Bank), used in Hungary.

The available formats depend on the payment currency and the recipient country. The merchant displays the format relevant for the customer.

The `format` query parameter selects the image encoding — `png` (the default) or `svg`. It does not select between the regional formats above.

```http
GET /gp-gw/api/4.0/payments/300000001/qr-payment/info?format=png HTTP/1.1
Host: gate.gopay.com
Authorization: Bearer eyJraWQiOiJzaWduLTIwMjYtMDIiLCJ0eXAiOiJKV1QiLCJhbGciOi…
```

```json
{
  "amount": 10000,
  "currency": "CZK",
  "recipient": {
    "name": "GoPay Czech",
    "bank_account": {
      "local": {
        "prefix": "000000",
        "account_number": "9878039",
        "bank_code": "2010",
        "variable_symbol": "3123456789"
      },
      "international": {
        "bic": "FIOBCZPP",
        "iban": "CZ5120100000000009878039",
        "reference": "3123456789"
      }
    },
    "address": {
      "street": "Senovazne nam. 1736",
      "city": "Ceske Budejovice",
      "zip_code": "37001",
      "country": "Czech Republic"
    }
  },
  "qr_code": {
    "spayd": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIC…"
  }
}
```

```html
<img alt="QR" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADIC…" />
```

### Effect on the payment

Requesting a QR extends the initial timeout of the payment to four days. The payment state is not changed by the request; the payment stays in whichever state it was in. The four-day window is intended to cover non-instant transfers that may settle across weekends or public holidays.

Requesting a QR does not commit the payment to settlement by bank transfer. If no transfer arrives within the extended window, the payment transitions to `TIMEOUTED` in the same way as any other payment.

### Coexistence with a card or wallet

A single payment may be offered to the customer with a QR option alongside a card-input variant on the same payment. The merchant displays the QR image next to the SDK card form or the Apple Pay or Google Pay button. The customer chooses which path to take. Whichever path settles first wins the payment.

If the payment has already been charged through the card or wallet path when a bank transfer subsequently arrives for the same payment, the transfer is returned to the debtor's account. The merchant takes no action.

### Settlement

A QR payment does not have a charge object created by the merchant's call. When the corresponding bank transfer is credited to GoPay's account, GoPay creates the charge against the payment and transitions the payment to `PAID`.

The merchant learns of the settlement through the `payments.paid` event; the merchant's server re-fetches the payment with `GET /payments/{payment_id}` to read the new state. The event and its delivery are described on the events and webhooks page. While the customer stays on the page, the browser SDK's `awaitPaymentStatus()` waits for the payment to reach a terminal state. The wait also ends on states such as `CANCELED` or `TIMEOUTED`, so the merchant's client reads `state` from the result. In the iOS and Android applications, the payment session's `getStatus()` reads the payment state.

```mermaid
sequenceDiagram
    autonumber
    participant MS as Merchant's server
    participant MC as Merchant's client
    participant SDK as GoPay client SDK
    participant API as GoPay API
    participant CUST as Customer
    participant BANK as Customer's bank

    MS->>API: POST /eshops/{goid}/payments
    API-->>MS: Payment Details (id, payment_secret)
    MS-->>MC: id, payment_secret
    MC->>SDK: attach the payment, request the QR
    SDK->>API: GET /payments/{id}/qr-payment/info
    API-->>SDK: QR Payment Details (qr_code)
    SDK-->>MC: qr_code
    MC->>CUST: display QR image
    CUST->>BANK: scan, confirm transfer
    BANK-->>API: transfer credited
    API->>MS: webhook with payments.paid
    MS->>API: GET /payments/{id}
    API-->>MS: Payment Details (PAID)
```

---

## Refunds

A refund returns funds from a paid payment back to the customer. In API v4 a refund is its own resource, with its own ID and its own state, separate from the payment it belongs to. A payment can carry several refunds.

This page covers issuing a refund, the refund states, the effect on the payment, and how to read refunds back.

### Issuing a refund

A refund is issued with `POST /payments/{payment_id}/refunds`. The body is a `Refund Create Request` carrying `amount` in cents.

`amount` equal to the payment amount refunds it in full; a lower value refunds it in part. A payment can be refunded repeatedly until the sum of its refunds reaches the original amount; a request that would take the total above the payment amount is rejected with `409 Conflict`.

The endpoint accepts only the merchant access token with the `payment:write` scope. It is not reachable with the payment-scoped token or the shareable key, so it is always called from the merchant's server — never from the merchant's client. See the security page.

```http
POST /gp-gw/api/4.0/payments/300000001/refunds HTTP/1.1
Host: gate.gopay.com
Authorization: Bearer eyJraWQiOiJzaWduLTIwMjYtMDIiLCJ0eXAiOiJKV1QiLCJhbGciOi…
Content-Type: application/json

{
  "amount": 10000
}
```

```json
{
  "id": "3050123456",
  "state": "REQUESTED",
  "amount": 10000,
  "currency": "CZK",
  "created_at": "2025-12-10T10:30:00Z"
}
```

### Refund states

A refund is asynchronous. The `201` response describes the refund as accepted, not as settled. The lifecycle is described by `Refund State`:

- `REQUESTED` — the refund was accepted and is being processed.
- `SUCCESS` — the refund was settled.
- `FAILED` — the refund could not be processed.

`SUCCESS` and `FAILED` are terminal. A `FAILED` refund does not change the payment amount that remains refundable; the merchant may issue a new refund.

### Effect on the payment

A settled refund moves the payment to `REFUNDED` when the full amount has been returned, or to `PARTIALLY_REFUNDED` when part of it has. A payment may move through `PARTIALLY_REFUNDED` more than once before reaching `REFUNDED`. See the lifecycle page.

The merchant learns of the transition through the `refunds.succeeded` event and re-fetches the payment with `GET /payments/{payment_id}` to read the new state. See the events and webhooks page.

A `FAILED` refund leaves the payment state untouched. It is announced by `refunds.failed`, and a merchant that does not receive that type polls `GET /refunds/{refund_id}` instead.

```mermaid
sequenceDiagram
    autonumber
    participant MS as Merchant's server
    participant API as GoPay API
    participant CUST as Customer

    MS->>API: POST /payments/{id}/refunds (amount)
    API-->>MS: Refund Details (REQUESTED)
    API->>CUST: funds returned
    API->>MS: webhook with refunds.succeeded
    MS->>API: GET /payments/{id}
    API-->>MS: Payment Details (PARTIALLY_REFUNDED)
```

### Reading refunds

`GET /payments/{payment_id}/refunds` returns every refund issued against the payment as an array of `Refund Details`.

`GET /refunds/{refund_id}` returns a single refund by its own ID.

Both reads accept the merchant access token with the `payment:read` scope; the list endpoint also accepts the payment-scoped token with the `payment:read` scope.

```http
GET /gp-gw/api/4.0/refunds/3050123456 HTTP/1.1
Host: gate.gopay.com
Authorization: Bearer eyJraWQiOiJzaWduLTIwMjYtMDIiLCJ0eXAiOiJKV1QiLCJhbGciOi…
```

```json
{
  "id": "3050123456",
  "state": "SUCCESS",
  "amount": 10000,
  "currency": "CZK",
  "created_at": "2025-12-10T10:30:00Z",
  "updated_at": "2025-12-10T10:35:00Z"
}
```

### Constraints

Only a `PAID` or `PARTIALLY_REFUNDED` payment can be refunded. Refunding a payment in any other state is rejected with `409 Conflict`; see the errors page.

A card payment can only be refunded in full at first. Partial refunds become possible later, once the card transaction has been processed by the acquirer; a partial refund attempted before that is rejected with `409 Conflict`. The merchant may refund the whole amount instead, or retry the partial refund later.

The refund is always returned to the instrument that paid. The API offers no way to redirect a refund to a different card or account.

---

## Payment links

A payment link lets a merchant collect a payment without integrating anything. The merchant creates the link through the API and shares the resulting URL — by email, in an invoice, as a QR code. The link stores the payment data; the payment itself is created only when a customer opens the link, and the browser is redirected straight to the payment gateway.

This page covers creating a link, what the customer's URL does, the difference between reusable and one-shot links, how a link stops being usable, and the validation rules.

### Creating a link

A link is created with `POST /eshops/{goid}/links`. The body is a `Link Create Request`:

- `payment` — the payment data every payment from this link will use. The same shape as a directly created payment, with the length limits listed under Constraints below.
- `expires_in` — optional lifetime in seconds, counted from creation. Without it, the link never expires.
- `reusable` — optional, `true` by default. See below.

The endpoint accepts only the merchant access token with the `payment:write` scope. It is not reachable with the payment-scoped token or the shareable key, so it is always called from the merchant's server — never from the merchant's client. See the security page.

```http
POST /gp-gw/api/4.0/eshops/8398119642/links HTTP/1.1
Host: gate.gopay.com
Authorization: Bearer eyJraWQiOiJzaWduLTIwMjYtMDIiLCJ0eXAiOiJKV1QiLCJhbGciOi…
Content-Type: application/json

{
  "expires_in": 3600,
  "reusable": true,
  "payment": {
    "amount": 15000,
    "currency": "CZK",
    "order_number": "2026-00042",
    "order_description": "Invoice 2026-00042",
    "customer": {
      "email": "payer@example.com"
    },
    "callback": {
      "notification_url": "https://eshop.example.com/gopay/notify",
      "return_url": "https://eshop.example.com/gopay/return"
    }
  }
}
```

```json
{
  "id": "3405871122",
  "url": "https://gate.gopay.com/gp-gw/l/Xk8mQ2pR7t",
  "active": true,
  "reusable": true,
  "expires_at": "2026-08-18T14:35:12Z",
  "payment": { … }
}
```

#### Two different identifiers

`id` and `url` identify the same link but are not interchangeable, and neither can be derived from the other.

- `id` is the link's numeric ID. It is what the status and disable calls take, and it is never shown to the customer.
- `url` ends in a random ten-character code drawn from a 62-character alphabet. That code is the only thing protecting the link, so it is deliberately unguessable.

### The link the customer opens

The customer's URL is not part of this API. It is served by a separate application that takes no authentication at all — the code in the URL is the only credential — and its single job is to turn a visit into a payment:

```http
GET /gp-gw/l/Xk8mQ2pR7t HTTP/1.1
Host: gate.gopay.com
```

```http
HTTP/1.1 302 Found
Location: https://gate.gopay.com/gw/123456789
Cache-Control: no-cache, no-store
```

The response is never cached. A reusable link mints a new payment on every visit, so a cached redirect would send the next customer to somebody else's payment.

The address is derived from the gateway's own base URL, so it always lives under `/gp-gw/l/`.

When the visit cannot produce a payment, the customer gets a plain error page rather than a redirect:

| Situation | Status |
|---|---|
| The code is not ten alphanumeric characters | `404` |
| No link with that code exists | `404` |
| The link is disabled or expired | `410` |
| The payment behind a used one-shot link is no longer available | `410` |
| Another visit is claiming the link right now | `503` |
| The visit failed for a transient reason | `503` |

The `503` cases leave the link valid — an outage deliberately does not present itself as an expiry, and the page tells the customer to try again shortly. The error page is bilingual, chosen from `Accept-Language` and defaulting to Czech; a link cannot carry a language preference of its own, because the v4 payment payload has no language field.

### Reusable and one-shot links

`reusable` decides what the second visit does.

| | `reusable: true` (default) | `reusable: false` |
|---|---|---|
| First visit | Creates a payment, redirects | Creates a payment, redirects; the link goes inactive with `stop_reason` `USED` |
| Every later visit | Creates another new payment | Redirects to the same payment, even though the link is inactive |
| After disabling or expiry | `410` error page | `410` if it was never opened; if it was, it still redirects to its payment |
| Two simultaneous visits | Each gets its own payment | One payment only — the second visit follows the first |

A used one-shot link keeps working as a pointer to its single payment on purpose. A customer who refreshes the page, or comes back to the message two days later, must not land on an error page for a payment that was already created for them.

Because a one-shot link is claimed before its payment is created, a double click — or a mail client's link preview racing the recipient — cannot produce two payments.

A reusable link reuses everything, including `order_number`. Every payment it creates carries the same `order_number` and the same `notification_url`, so the merchant's server can receive notifications for several payments that all look like one order. Before a reusable link is shared, the merchant should confirm that its server handles this.

### Link state, expiry, and disabling

A link is either active or not. When it is not, `stop_reason` says why; while it is active, `stop_reason` is absent from the response entirely.

- `FROM_API` — the merchant disabled it.
- `USED` — a one-shot link was opened and created its payment.
- `EXPIRED` — the link passed its `expires_at`.

Expiry is evaluated when the link is read or visited. A read of a link past its `expires_at` reports `active: false` with `stop_reason` `EXPIRED`, even if nothing else has touched the link since it expired.

A link is read with `GET /eshops/{goid}/links/{link_id}` (`payment:read`), which returns the same body as creation, including the payment data.

A link is disabled with `DELETE /eshops/{goid}/links/{link_id}` (`payment:write`), which returns `204`. Disabling is not deleting: the link can still be read back and reports `stop_reason` `FROM_API`.

Disabling a link that is already inactive returns `409`. That includes a used one-shot link — it is already inactive, so it cannot be disabled, and it goes on redirecting to its payment. A merchant who shared such a link by mistake has to cancel the payment instead. See the lifecycle page.

A link belonging to another eshop answers `404`, not `403`, so that the response does not reveal whether it exists. This matches how payments and refunds behave.

### Constraints

Validation runs before anything is stored, and every failure is a `400`.

| Field | Required | Rule |
|---|---|---|
| `payment` | yes | Must be present; a `null` value is rejected with `400` |
| `payment.amount` | yes | Must not be negative; `0` is accepted |
| `payment.currency` | yes | A v4 currency the eshop has an enabled payment channel for |
| `payment.order_number` | yes | Non-empty, at most 128 characters |
| `payment.order_description` | no | At most 256 characters |
| `payment.customer.email` | yes | Non-empty, at most 128 characters |
| `payment.customer.*` | no | First and last name 256 characters, the rest 128 |
| `payment.callback.notification_url` | yes | http or https, at most 512 characters |
| `payment.callback.return_url` | yes | http or https, at most 512 characters |
| `payment.additional_params` | no | At most 4 entries; `name` must not contain `=`; `name` and `value` non-empty and together at most 511 characters |
| `expires_in` | no | Greater than zero, at most a hundred years |

A currency check at creation only confirms that the eshop has a payment channel enabled for it. An eshop configured with a channel in a currency it holds no account for is an inconsistent setup, and such a link fails later, when the payment is created — the customer sees the `503` page.

The number of times a link may be opened is not limited by the API. A reusable link creates a payment on every visit.

---

## Recurrences

A recurrence charges a customer repeatedly from a single card authorisation. In API v4 a recurrence is a standalone resource with its own ID and state — it is not attached to a payment. It holds a payment template, and every payment it creates is built from that template.

This page covers creating a recurrence, starting it, requesting further payments, the recurrence states, and how a recurrence ends.

### Recurrence types

A recurrence is either scheduled or driven by the merchant:

- `AUTO` — GoPay creates the payments itself on a fixed schedule. `schedule` is required.
- `ON_DEMAND` — no schedule; the merchant asks for each further payment with `POST /recurrences/{rec_id}/next`. `schedule` must be omitted.

Sending `schedule` with `ON_DEMAND`, or omitting it for `AUTO`, is rejected with `400`.

### Creating a recurrence

A recurrence is created with `POST /eshops/{goid}/recurrences`. The body is a `Recurrence Create Request` — a discriminated union on `type`, so which fields are required depends on the kind being created:

- `AUTO` — `type`, `schedule`, `recurrence_date_to` and the `payment` template.
- `ON_DEMAND` — `type`, `recurrence_date_to` and the `payment` template. `schedule` must not be sent.

`recurrence_date_to` is the last day the recurrence may create a payment, written as `yyyy-MM-dd` — a value carrying a time component is rejected with `400`.

```http
POST /gp-gw/api/4.0/eshops/8761908826/recurrences HTTP/1.1
Host: gate.gopay.com
Authorization: Bearer eyJraWQiOiJzaWduLTIwMjYtMDIiLCJ0eXAiOiJKV1QiLCJhbGciOi…
Content-Type: application/json

{
  "type": "ON_DEMAND",
  "recurrence_date_to": "2027-09-04",
  "payment": {
    "amount": 1500,
    "currency": "CZK",
    "order_number": "2025010199",
    "order_description": "Monthly subscription",
    "customer": { "email": "john.doe@example.com" },
    "callback": {
      "notification_url": "https://example.com/notify",
      "return_url": "https://example.com/return"
    }
  }
}
```

```json
{
  "id": "8008013370",
  "type": "ON_DEMAND",
  "state": "NEW",
  "recurrence_date_to": "2027-09-04",
  "payment": {
    "amount": 1500,
    "currency": "CZK",
    "order_number": "2025010199",
    "customer": { "email": "john.doe@example.com" }
  }
}
```

Creating a recurrence creates no payment. The recurrence starts in state `NEW` and stays there until it is started.

### Starting a recurrence

`POST /recurrences/{rec_id}/start` creates the first payment and returns it as `Payment Details`, with the `gw_url` of GoPay's hosted gateway the customer opens and the `payment_secret` the client SDK needs. As with any use of `payment_secret`, it must not be embedded in URLs, logged, or stored. The recurrence moves to `REQUESTED`.

This first payment is the one the customer actually authorises — it is paid like any other payment, through the gateway. Once it is paid, the recurrence becomes `STARTED`.

Calling `start` again while the first payment is still unpaid is rejected with `409`. The gateway explains the conflict in the response message; the wording is not part of the contract, so the merchant's server should branch on the status code rather than on the text.

### Overriding the template for one payment

`start` and `next` both accept an optional body — a `Payment Instance Override`. It replaces fields of the stored template for that one payment and leaves the recurrence itself unchanged:

```http
POST /gp-gw/api/4.0/recurrences/8008013370/start HTTP/1.1
Host: gate.gopay.com
Authorization: Bearer eyJraWQiOiJzaWduLTIwMjYtMDIiLCJ0eXAiOiJKV1QiLCJhbGciOi…
Content-Type: application/json

{
  "amount": 9900,
  "order_number": "2025010199-JAN"
}
```

Two details are worth knowing:

- Omitted fields keep the stored value, and `customer` is merged field by field rather than replaced — overriding only `first_name` leaves the stored `last_name` in place.
- Unknown fields are rejected with `400`. The override is not a free-form bag.

An empty body (`{}`) creates the payment from the stored template unchanged.

### Requesting further payments

`POST /recurrences/{rec_id}/next` creates a further payment from the template. It needs no customer interaction — the card authorisation from the first payment carries it.

The recurrence must be in state `STARTED`. While it is `NEW` or `REQUESTED` the call is rejected with `409`. In practice this means: `next` only works after the customer has actually paid the first payment.

For an `AUTO` recurrence GoPay creates the scheduled payments itself; `next` is the `ON_DEMAND` counterpart.

### Recurrence states

`Recurrence State` describes the lifecycle:

- `NEW` — created, no payment exists yet.
- `REQUESTED` — the first payment was created and is waiting to be paid.
- `STARTED` — the first payment was paid; further payments can be created.
- `STOPPED` — the recurrence ended and creates no further payments.

### Stopping a recurrence

`DELETE /recurrences/{rec_id}` stops the recurrence permanently and answers `204`. It moves to `STOPPED` with `stop_reason` `CANCELLED_VIA_API`. Stopping cannot be undone — a new recurrence has to be created, which means authorising a card again.

A recurrence can also end on its own. `Recurrence Stop Reason` covers the possibilities:

| Reason | Meaning |
|---|---|
| `RECURRENCE_EXPIRED` | `recurrence_date_to` passed |
| `CARD_EXPIRED` | the authorised card expired |
| `CANCELLED_VIA_API` | stopped with `DELETE /recurrences/{rec_id}` |
| `CANCELLED_VIA_BACKOFFICE` | stopped by a GoPay operator on the merchant's behalf |
| `CANCELLED_BY_GOPAY` | stopped by GoPay |
| `UNKNOWN` | reason not available |

Reading a stopped recurrence still works — `GET /recurrences/{rec_id}` returns it with its `stop_reason` and its last payment.

### Constraints

- All five operations take the merchant access token only. `payment:read` reads the recurrence; `payment:write` creates, starts, advances, and stops it. Neither the payment-scoped token nor the shareable key reaches them, so a recurrence is always driven from the merchant's server. See the security page.
- An unknown recurrence ID answers `404` on every operation.
- `schedule.cycle` must be at least `1`, and `schedule.period` is one of `DAY`, `WEEK`, `MONTH`.
- `ON_DEMAND` throttle limits are a per-merchant setting and are changed by emailing `integration@gopay.com` — see the overview page.

---

## Events and webhooks

An event is a record that something happened to one of the eshop's entities: a payment was paid, a refund failed, a saved card was reissued. GoPay delivers events on two channels the merchant may use independently — an event of a type the eshop receives as webhooks is sent to the endpoint configured for the eshop, and every event is kept in a log the merchant's server can read for 30 days. The event is the same object on both channels.

### The event

An event carries identifiers, not data. It states which entity changed and how, and nothing about the contents of that entity.

```json
{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "type": "payments.paid",
  "occurred_at": "2026-07-08T12:04:39.123Z",
  "data": {
    "payment_id": "300000001",
    "charge_id": "9123456789"
  }
}
```

- `id` identifies the event. It is unique, and it is the value the merchant's server deduplicates on.
- `type` states what happened. It is prefixed with the entity the event is about.
- `occurred_at` is when the fact happened, in UTC. It may carry fractional seconds.
- `data` carries the identifiers of every entity the event concerns.

Because an event carries no amounts, no states and no customer data, it is not a source of truth about anything. The merchant's server reads the identifiers and fetches the current state of those entities over the Payments API. A duplicate event, or one that arrives after a later one, therefore cannot corrupt anything: the re-fetch returns current state either way.

### Event types

| Type | Sent when | Identifiers in `data` |
| --- | --- | --- |
| `payments.paid` | the payment reached `PAID` | `payment_id`, and `charge_id` if a charge paid it |
| `payments.canceled` | the payment reached `CANCELED` | `payment_id` |
| `payments.timeouted` | the payment reached `TIMEOUTED` | `payment_id` |
| `links.payment_created` | a customer opened a payment link and a payment was created from it | `link_id`, `payment_id` |
| `links.disabled` | the merchant deactivated a payment link | `link_id` |
| `refunds.succeeded` | a refund settled | `payment_id`, `refund_id` |
| `refunds.failed` | a refund could not be settled | `payment_id`, `refund_id` |
| `recurrences.started` | a recurrence was activated | `recurrence_id`, `payment_id` |
| `recurrences.payment_created` | a scheduled payment was created from a recurrence | `recurrence_id`, `payment_id` |
| `recurrences.stopped` | a recurrence was stopped | `recurrence_id` |
| `cards.updated` | a saved card token changed in place, for instance after the issuer reissued the card | `card_id` |
| `cards.deleted` | a saved card token was deleted | `card_id` |

If a charge paid the payment, `payments.paid` carries `charge_id`, the charge that succeeded, alongside `payment_id`. A payment paid on the hosted gateway at `gw_url` carries `payment_id` only.

The reason behind an event is never in the event. `recurrences.stopped` has one type whatever stopped the recurrence; the reason is a field on the recurrence and is read from it.

`links.disabled` is sent only when the merchant deactivates a link. Every payment created from a link is announced by `links.payment_created`, and a single-use link used up by its payment produces no `links.disabled`. A link that reaches its expiry produces no event; the expiry is read from the link.

A payment created from a link or from a recurrence is announced as `links.payment_created` or `recurrences.payment_created`, because that is the context the merchant is tracking. Everything that happens to that payment afterwards is announced as `payments.*`, whatever its origin.

New types are added over time. A `type` the merchant's code does not recognise must be ignored rather than treated as an error, so that a new type does not break a working integration.

### Receiving a webhook

GoPay sends one event per request, as a `POST` with the event as the body, to the notification endpoint configured for the eshop. The endpoint must be a public HTTPS URL without credentials in it. The request shape is defined in the Webhooks specification, which describes the endpoint from the merchant's side: there the merchant is the server and GoPay is the client.

The merchant's server acknowledges with any `2xx`. The response body is ignored and may be empty. Anything else — a non-`2xx` status, a timeout, a connection or TLS failure — counts as a failed delivery and is handled according to the eshop's notification strategy. GoPay waits up to 25 seconds for the response status. A redirect is not followed, so a `3xx` also counts as a failed delivery. Acknowledgement should be prompt, with the work done afterwards, because the acknowledgement is what closes the delivery.

Delivery is at least once and unordered. Two events for the same payment may arrive in either order, and the same event may arrive twice. The merchant's server must therefore be idempotent on `id`: an event whose `id` has already been processed is discarded.

Card tokens belong to the merchant rather than to one eshop. A `cards.*` event is therefore sent to every eshop of the merchant that receives that type, each to its own endpoint.

### Endpoint configuration

Four things are configured per eshop, and per environment, by GoPay rather than through the API. To have them set or changed, the merchant contacts `integration@gopay.com` with:

1. the notification endpoint, one per eshop per environment;
2. the event types the eshop is to receive as webhooks;
3. the notification strategy, with the request rate or the deadline where the strategy needs one;
4. the retry schedule, if the default is not wanted.

An eshop has one strategy. It decides what happens when the endpoint fails or cannot keep up.

- **Guaranteed** — every event is sent, and a failed delivery is retried on the eshop's schedule. This is the default. The default schedule is the first attempt followed by 20 retries: twelve at five-minute intervals, then eight at hourly intervals, so the last attempt falls nine hours after the first.
- **Rate-limited** — as guaranteed, but no more than the agreed number of requests per minute reaches the endpoint. An event above the rate waits for its turn and is not shed.
- **Throttled** — no more than the agreed number of requests per minute reaches the endpoint, and an event that cannot be sent within ten seconds, unless agreed otherwise, is shed. While events wait, a newer event of the same type for the same entity replaces an older one, since the merchant's server re-fetches current state in any case. A failed delivery is retried on the schedule at the same rate, and a retry that finds no free slot is shed as well. An eshop on this strategy reconciles through the event log.
- **Deadline** — the eshop agrees a time within which an event is to be delivered, counted from `occurred_at`. Events closest to their deadline are sent first, and retries are packed into the time that remains. An event that misses its deadline is still delivered, on the default schedule.

An event that is never delivered — the endpoint stayed down for the whole schedule, or the event was shed or replaced under the throttled strategy — stays in the log for the full 30 days and is read there like any other.

An eshop that reads events only from the log configures no notification endpoint and no types. Its events are recorded and kept for the same 30 days.

### Verifying the signature

Every webhook carries an `X-GoPay-Signature` header holding a signature over the exact bytes of the request body. It is a JSON Web Signature in compact form with the payload segment left empty — `<protected>..<signature>`, the detached form described in RFC 7515 Appendix F — so the body arrives as plain JSON. The protected header names the algorithm, always `RS256`, and the key, as `kid`.

GoPay signs with a private key and publishes the matching public keys at `GET /webhooks/public-keys` as a JWK Set. The merchant's server authenticates the call with a merchant access token holding the `shared:read` scope, as described on the security page. It may instead present `client_id:shareable_key` as HTTP Basic, under the `shareable_key` security scheme in the OpenAPI reference. Several keys may be published at once while a key is being rotated, which is why the key is selected by `kid` and not by position.

To verify one webhook, the merchant's server:

1. reads `kid` from the protected header and selects that key from the JWK Set;
2. rebuilds the signing input from the raw bytes of the received body, before any parsing or re-serialisation;
3. verifies the signature with the selected key.

Verification is optional and is recommended. An event is a plain HTTP request that anyone can send, and a forged one reaches the merchant's code before a re-fetch corrects it. Verification and re-fetching answer different questions, and a merchant's server should do both.

### Reading the event log

`GET /eshops/{goid}/events` returns the eshop's events, newest first. The call is authenticated with a merchant access token holding the `event:read` scope; see the security page. Events remain available for 30 days.

The log is the merchant's own recovery channel. It answers "what did the eshop miss while its endpoint was down" and "everything that ever happened to payment X".

Events are ordered by `id`, which is the order GoPay recorded them in. That order closely follows `occurred_at`, but the two are not identical: an event that occurred a moment earlier may be recorded a moment later.

#### Filtering

The full parameter list is in the OpenAPI reference. Three filters shape the result:

- `type` — the types to include, comma-separated in one parameter, up to twenty items. An item is either an exact type, `payments.paid`, or a whole namespace, `payments.*`. An unknown type is rejected with `400`. Omitted, every type is returned.
- `occurred_after` and `occurred_before` — a time window over `occurred_at`. The lower bound is inclusive, the upper bound is not.
- `related_type` and `related_id` — one entity, given as a kind and an identifier: `related_type=payments&related_id=300000001`. The pair matches every event that carries that identifier, whichever position it appears in, so a payment's own events and the refund and recurrence events that reference it all come back together. Both parameters are required together.

`max_items` sets the size of a page, up to 100. The direction cannot be changed: events are always returned newest first.

#### Paging

The response carries the events in `items`, and the address of the next page in `next_page_url` while one exists.

A page holds up to `max_items` events that match the filters. `next_page_url` is present while further matching events exist, and the last page of a walk does not carry it at all.

```
GET /eshops/8123456789/events?type=refunds.*&max_items=20
→ 200 { "items": [ … 20 events … ], "next_page_url": "https://gate.gopay.com/gp-gw/api/4.0/eshops/8123456789/events?type=refunds.*&max_items=20&prev_item=01H8ZQ7X9K4Q0M2V6T8B3C5D7E" }
```

`next_page_url` is complete: the filters of the request, `max_items`, and `prev_item`, the `id` of the last event of the page. The merchant's server follows it as it stands and stops when a response does not carry it. `max_items` is the one value that may be changed between pages.

A `prev_item` value that has aged out of the 30-day window points at events that no longer exist, and is rejected with `400`. The walk is restarted from a fresh time bound.

#### Catching up after an outage

The merchant's server records the `occurred_at` of the last event it processed. To catch up:

1. call `GET /eshops/{goid}/events?occurred_after=<last processed occurred_at, less a margin of a few minutes>`;
2. process each event in the page, skipping any `id` already processed;
3. follow `next_page_url` and repeat until a response does not carry one.

The walk runs from the newest event back to the lower bound, so it ends. The margin covers the gap between when an event occurred and when it was recorded; it returns a few already-processed events again, which the merchant's server discards on `id`. The order in which a page is processed does not matter — an event is a trigger to re-fetch, and a re-fetch returns current state.

When a response carries no `next_page_url`, every event available at that moment has been returned. Events recorded while the walk was running are returned by the next walk.

#### One event by identifier

`GET /eshops/{goid}/events/{event_id}` returns a single event. It confirms that an event a merchant's server received was really sent by GoPay, and it resolves an event `id` found in the merchant's own logs.

---

## Errors

An error response is the HTTP response returned when the GoPay API rejects a request before it produces a domain resource. The response status describes the category of the rejection; the response body identifies it precisely and points the merchant at the part of the request that caused it.

This page covers the error response shape, what each HTTP status means in practice, and the boundary between an API error and a business failure carried on a resource. Errors met in the merchant's client surface as errors of the GoPay client SDK, with their own codes documented with each SDK.

### The error response

Every error response carries an `Error Response Body` payload, regardless of the HTTP status. The shape is the same across all error statuses.

The merchant's server should log the full payload alongside the request identifier; `detail` and `path` are the fields that most often shorten an investigation.

The `error` field tracks the HTTP status — there are no business sub-codes nested inside an `error` value.

```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
```

```json
{
  "code": 400,
  "error": "BAD_REQUEST",
  "message": "Invalid request parameter",
  "detail": "amount must be a positive integer",
  "path": "/eshops/8123456789/payments",
  "timestamp": "2026-05-29T10:30:00Z"
}
```

### Status meanings

#### `400 Bad Request`

The request body does not conform to the schema declared for the operation.

Typical causes:

- A `POST` request with no body where the schema requires one.
- Invalid JSON syntax.
- A negative number sent for a field declared as a non-negative integer.

#### `401 Unauthorized`

The request could not be authenticated.

Typical causes:

- A missing or malformed `Authorization` header.
- A `client_secret` that does not match the `client_id` on `POST /oauth2/token`.
- A `payment_id` and `payment_secret` pair that does not match. In the GoPay client SDK, this surfaces when the payment is attached.
- A JWT that does not parse or whose signature does not verify.

#### `403 Forbidden`

The credential authenticates successfully but is not allowed to perform the operation. The same operation may succeed with a different credential.

Typical causes:

- A merchant access token without `payment:write` calling `POST /payments/{payment_id}/charge`.
- A payment-scoped token used on an endpoint outside its reach.

One `403` is not credential-related: in production `POST /eshops/{goid}/payments` refuses a `return_url` that is not HTTPS. The payload itself is rejected, so the call fails the same way with every credential. The sandbox is more tolerant.

#### `404 Not Found`

The entity addressed by a path parameter is not visible in the credential's available space.

Typical causes:

- A `payment_id` that has never been issued.
- A `payment_id` that belongs to another merchant.

#### `409 Conflict`

The request is well-formed and the credential is allowed to perform the operation, but the operation cannot complete in the current state of the system. The merchant's typical reaction is to refresh the resource and re-evaluate, not to retry the same call.

Typical causes:

- `POST /payments/{payment_id}/charge` against a payment that is already `TIMEOUTED`, `PAID`, or `CANCELED`.
- `GET /payments/{payment_id}/qr-payment/info` against an eshop where QR payments are disabled.
- A second `POST /payments/{payment_id}/charge` against a payment that has already been charged.
- `DELETE /payments/{payment_id}` against a payment in any state other than `CREATED`.
- `POST /payments/{payment_id}/refunds` against a payment that is neither `PAID` nor `PARTIALLY_REFUNDED`, or for an amount that would take the total refunded above the payment amount.
- A partial `POST /payments/{payment_id}/refunds` against a card payment whose transaction has not been processed by the acquirer yet — until then the payment can only be refunded in full.
- `DELETE /eshops/{goid}/links/{link_id}` against a payment link that is already inactive, whether it was disabled earlier, expired, or was a one-shot link that has already been used.
- `POST /recurrences/{rec_id}/next` against a recurrence that has not reached `STARTED` — the first payment has to be paid first.
- A second `POST /recurrences/{rec_id}/start` while the first payment of the recurrence is still unpaid, or a `start` against a recurrence that is already `STOPPED`.
- `DELETE /recurrences/{rec_id}` against a recurrence that is already `STOPPED`, whether it was stopped through the API, expired, or was stopped by GoPay.

#### `500 Internal Server Error`

An unexpected condition on the GoPay side. Persistent occurrences should be reported to `integration@gopay.com`.

### Business failures

An API success is not a business success. When a request produced a domain resource, the HTTP response is a success status, `200` or `201`; the resource itself records whether the business outcome was successful.

A payment charge is the canonical case. After the merchant initiates a charge, polling may show it reaching `Charge State` of `FAILED` with the cause in `fail_reason`. The HTTP status stays `200`; the merchant reads the charge to learn what happened.

```json
{
  "id": "9123456789",
  "state": "FAILED",
  "fail_reason": "Issuer declined the authorisation"
}
```

---

## API Reference — Payments v4.0

**Create and manage payments**

REST API for creating and managing GoPay payments: creating a payment, charging it with a payment instrument, following it through to a terminal outcome, and managing saved card tokens. The long-form integration guides are published alongside this reference.

### Servers

- `https://gw.sandbox.gopay.com/gp-gw/api/4.0` — Sandbox
- `https://gate.gopay.com/gp-gw/api/4.0` — Production

### Security schemes

- `basic` (http; basic) — Only used to obtain a JWT on `POST /oauth2/token`.
  - The merchant's server uses `client_id:client_secret`
  - The GoPay client SDK uses `payment_id:payment_secret`
  See [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617) for the scheme.
- `merchant_credentials` (oauth2) — Authorizes the merchant's server using `client_id:client_secret`.
  The secret and the JWT must never leave the merchant's server.
- `payment_credentials` (oauth2) — Authorizes a client for payment-specific operations using `payment_id:payment_secret`.
  These credentials and the JWT are used by the GoPay client SDK in the merchant's web or mobile app.
  The client presents `payment_id:payment_secret` as HTTP Basic on `POST /oauth2/token` with `grant_type=payment_credentials` and requests `payment:read`, `payment:charge`, or both. The returned JWT is bound to the payment and valid for fifteen minutes. The exchange may be repeated to obtain a fresh JWT; `payment_secret` does not expire, and an operation that the payment's state no longer allows is rejected, mostly with `409`.
- `shareable_key` (http; basic) — `client_id:shareable_key` encoded in base64 in the Authorization header. `shareable_key` is configured in the GoPay client SDK.
  Used to authenticate to endpoints holding public resources such as public keys and URLs, and values derived from the request itself.
  See [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617) for the scheme.

### Operations

#### Authentication

Exchanging merchant and per-payment credentials for the access tokens that authorise every other call.

<a id="operation-post-oauth2-token"></a>

##### Authenticate

`POST /oauth2/token` · Operation ID: `post-oauth2-token`

Requires: `basic`

Exchanges credentials for an access token.

The merchant's server presents `client_id:client_secret` with the `client_credentials` grant; the GoPay client SDK presents `payment_id:payment_secret` with the `payment_credentials` grant to obtain a payment-scoped token. Credentials are sent as HTTP Basic and at least one scope must be requested. The returned `access_token` is a JWT valid for fifteen minutes and is presented as a Bearer token on the calls that authenticate with it; the `shareable_key` endpoints use HTTP Basic instead and involve no token exchange.

**Request body** (required)

`application/x-www-form-urlencoded`: [Client-Credentials-Request](#schema-Client-Credentials-Request) | [Payment-Credentials-Request](#schema-Payment-Credentials-Request)

Example — Client Credentials:

```json
{
  "grant_type": "client_credentials",
  "scope": "payment:write payment:read"
}
```

**Responses**

- `200` The access token — [Access-Token](#schema-Access-Token)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

#### Payments

Creating a payment, charging it with a payment instrument, and following it through to a terminal outcome.

<a id="operation-post-eshops-goid-payments"></a>

##### Create a payment

`POST /eshops/{goid}/payments` · Operation ID: `post-eshops-goid-payments`

Requires: `merchant_credentials` (scopes: `payment:write`)

Creates a payment for the given eshop.

The response carries the payment `id`, the per-payment client credential `payment_secret`, and `gw_url` — the address of GoPay's hosted payment gateway, which offers the customer every payment method the eshop has enabled but cannot be embedded in the merchant's own checkout. The new payment is in the `CREATED` state and awaits a charge attempt; if none is made before the initial timeout expires, it transitions to `TIMEOUTED`.

**Parameters**

- `goid` (string; path; required) — Unique identifier of a registered merchant website

**Request body** (optional)

`application/json`: [Payment-Create-Request](#schema-Payment-Create-Request)

**Responses**

- `201` The new payment — [Payment-Details](#schema-Payment-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-payments-payment_id"></a>

##### Payment Status

`GET /payments/{payment_id}` · Operation ID: `get-payments-payment_id`

Requires: `merchant_credentials` (scopes: `payment:read`) or `payment_credentials` (scopes: `payment:read`)

Returns the current state of a payment.

Called after a webhook notification or a return-URL redirect to learn the outcome, since both carry only the payment `id`. The `state` field follows the payment lifecycle from `CREATED` to a terminal outcome.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`

**Responses**

- `200` The payment — [Payment-Details](#schema-Payment-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-delete-payments-payment_id"></a>

##### Cancel a payment

`DELETE /payments/{payment_id}` · Operation ID: `delete-payments-payment_id`

Requires: `merchant_credentials` (scopes: `payment:write`)

Cancels a payment that has not been charged yet.

The payment transitions to `CANCELED` and remains readable; it is not deleted. Only a payment in the `CREATED` state can be canceled; any other state returns `409`. The operation is server-side only.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`

**Responses**

- `204` Done; the response has no body
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-payments-payment_id-charge"></a>

##### Payment charge state

`GET /payments/{payment_id}/charge` · Operation ID: `get-payments-payment_id-charge`

Requires: `merchant_credentials` (scopes: `payment:read`) or `payment_credentials` (scopes: `payment:read`)

Returns the current state of the payment's charge.

Polled while a charge is in flight, at a recommended cadence of one second, until the state reaches `SUCCEEDED`, `FAILED` or `ACTION_REQUIRED`. On `ACTION_REQUIRED` the response carries an `action` describing the step the customer must complete; once they have, polling resumes until the charge reaches `SUCCEEDED` or `FAILED`. When a charge fails, the reason is carried in `fail_reason`.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`

**Responses**

- `200` Current state of the payment's charge — [Payment-Charge-Status-Response](#schema-Payment-Charge-Status-Response)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-post-payments-payment_id-charge"></a>

##### Charge a payment

`POST /payments/{payment_id}/charge` · Operation ID: `post-payments-payment_id-charge`

Requires: `merchant_credentials` (scopes: `payment:write`) or `payment_credentials` (scopes: `payment:charge`)

Attempts to settle a payment with a payment instrument.

Only card payments are charged through this endpoint — `payment_instrument` is always `PAYMENT_CARD`, and the card input type nested under it is one of `ENCRYPTED_CARD`, `CARD_TOKEN`, `APPLE_PAY` or `GOOGLE_PAY`. Other payment methods are reachable only through the hosted gateway. The charge is asynchronous; a state of `ACTION_REQUIRED` means the customer must complete an external step before the charge can terminate.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`

**Request body** (optional)

`application/json`: [Payment-Charge-Input](#schema-Payment-Charge-Input)

**Responses**

- `201` The charge that was started — [Payment-Charge-Response](#schema-Payment-Charge-Response)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-payments-payment_id-qr-payment-info"></a>

##### QR Payment Info

`GET /payments/{payment_id}/qr-payment/info` · Operation ID: `get-payments-payment_id-qr-payment-info`

Requires: `merchant_credentials` (scopes: `payment:read`) or `payment_credentials` (scopes: `payment:read`)

Returns the data needed to display a QR code for settling the payment by bank transfer.

The response carries the amount, the recipient bank account, and the generated image as a base64 string under the regional format applicable to the payment's currency and recipient country. Requesting a QR code extends the payment's initial timeout to four days and does not change the payment state.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
- `format` (string; query; optional; values: `png`, `svg`; default `"png"`) — Image format of the generated QR code

**Responses**

- `200` The QR payment data for the payment — [QR-Payment-Details](#schema-QR-Payment-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

#### Refunds

Returning funds from a paid payment to the customer, and reading back the refunds a payment carries.

<a id="operation-get-payments-payment_id-refunds"></a>

##### List payment refunds

`GET /payments/{payment_id}/refunds` · Operation ID: `get-payments-payment_id-refunds`

Requires: `merchant_credentials` (scopes: `payment:read`) or `payment_credentials` (scopes: `payment:read`)

Returns every refund issued against the payment.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`

**Responses**

- `200` The refunds of the payment — array of [Refund-Details](#schema-Refund-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-post-payments-payment_id-refunds"></a>

##### Refund a payment

`POST /payments/{payment_id}/refunds` · Operation ID: `post-payments-payment_id-refunds`

Requires: `merchant_credentials` (scopes: `payment:write`)

Refunds a paid payment in full or in part. Set `amount` to the payment amount for a
full refund, or to a lower value for a partial refund. A payment can be refunded
repeatedly until the sum of its refunds reaches the original amount.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`

**Request body** (required)

`application/json`: [Refund-Create-Request](#schema-Refund-Create-Request)

**Responses**

- `201` The new refund — [Refund-Details](#schema-Refund-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-refunds-refund_id"></a>

##### Refund details

`GET /refunds/{refund_id}` · Operation ID: `get-refunds-refund_id`

Requires: `merchant_credentials` (scopes: `payment:read`)

Returns the current state and amount of a single refund.

**Parameters**

- `refund_id` (string; path; required) — Identifier of the refund

**Responses**

- `200` The refund — [Refund-Details](#schema-Refund-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

#### Payment Links

Payment links that carry the data for a payment and create it only when the customer opens the link.

<a id="operation-post-eshops-goid-links"></a>

##### Create a payment link

`POST /eshops/{goid}/links` · Operation ID: `post-eshops-goid-links`

Requires: `merchant_credentials` (scopes: `payment:write`)

Creates a payment link for the given eshop. The link only stores the payment data — no payment exists until a customer opens the link.

The response carries `id`, used on the status and disable calls, and `url`, the address to share with the customer. The two are different identifiers: `url` ends in a random ten-character code that cannot be derived from `id`, nor `id` from the code.

**Parameters**

- `goid` (string; path; required) — Unique identifier of a registered merchant website

**Request body** (required)

`application/json`: [Link-Create-Request](#schema-Link-Create-Request)

**Responses**

- `201` The new payment link — [Link-Details](#schema-Link-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-eshops-goid-links-link_id"></a>

##### Link status

`GET /eshops/{goid}/links/{link_id}` · Operation ID: `get-eshops-goid-links-link_id`

Requires: `merchant_credentials` (scopes: `payment:read`)

Returns the current settings and state of a payment link, including the payment data it carries.

Expiry is evaluated on read: a link past its `expires_at` is reported as `active: false` with `stop_reason` `EXPIRED`, without anything being written first.

**Parameters**

- `goid` (string; path; required) — Unique identifier of a registered merchant website
- `link_id` (string; path; required; pattern `^[0-9]+$`) — Link ID returned when the link was created. A non-numeric or negative value is rejected with `400`

**Responses**

- `200` The payment link — [Link-Details](#schema-Link-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-delete-eshops-goid-links-link_id"></a>

##### Disable a link

`DELETE /eshops/{goid}/links/{link_id}` · Operation ID: `delete-eshops-goid-links-link_id`

Requires: `merchant_credentials` (scopes: `payment:write`)

Deactivates a payment link so that it can no longer start a new payment. This is not a delete: the link can still be read back, and reports `stop_reason` `FROM_API`.

Disabling a link that is already inactive returns `409`. A one-shot link that has already been used is inactive too, so it cannot be disabled — it keeps redirecting to the payment it created. To stop that payment, cancel the payment itself.

**Parameters**

- `goid` (string; path; required) — Unique identifier of a registered merchant website
- `link_id` (string; path; required; pattern `^[0-9]+$`) — Link ID returned when the link was created. A non-numeric or negative value is rejected with `400`

**Responses**

- `204` Done; the response has no body
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

#### Recurrences

Recurring payments that hold a payment template and create payments from it, either on a schedule or when the merchant asks for the next one.

<a id="operation-post-eshops-goid-recurrences"></a>

##### Create a recurrence

`POST /eshops/{goid}/recurrences` · Operation ID: `post-eshops-goid-recurrences`

Requires: `merchant_credentials` (scopes: `payment:write`)

Registers a recurrence for the eshop and returns it in state `NEW`. The recurrence only stores the payment template — no payment exists until the recurrence is started. `schedule` is required for an `AUTO` recurrence and must be omitted for an `ON_DEMAND` one.

**Parameters**

- `goid` (string; path; required) — Unique identifier of a registered merchant website

**Request body** (required)

`application/json`: [Recurrence-Create-Request](#schema-Recurrence-Create-Request)

**Responses**

- `201` The new recurrence — [Recurrence-Details](#schema-Recurrence-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-recurrences-rec_id"></a>

##### Recurrence status

`GET /recurrences/{rec_id}` · Operation ID: `get-recurrences-rec_id`

Requires: `merchant_credentials` (scopes: `payment:read`)

Returns the current state of the recurrence and the payment it last created.

**Parameters**

- `rec_id` (string; path; required) — Unique ID of a previously created recurrence

**Responses**

- `200` The recurrence — [Recurrence-Details](#schema-Recurrence-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-delete-recurrences-rec_id"></a>

##### Stop a recurrence

`DELETE /recurrences/{rec_id}` · Operation ID: `delete-recurrences-rec_id`

Requires: `merchant_credentials` (scopes: `payment:write`)

Stops the recurrence permanently. It moves to state `STOPPED` with `stop_reason` `CANCELLED_VIA_API` and creates no further payments. Stopping cannot be undone.

**Parameters**

- `rec_id` (string; path; required) — Unique ID of a previously created recurrence

**Responses**

- `204` Done; the response has no body
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-post-recurrences-rec_id-start"></a>

##### Start a recurrence

`POST /recurrences/{rec_id}/start` · Operation ID: `post-recurrences-rec_id-start`

Requires: `merchant_credentials` (scopes: `payment:write`)

Creates the first payment of the recurrence and moves it to state `REQUESTED`. The customer pays that payment at its `gw_url`; once it is paid the recurrence becomes `STARTED` and further payments can be requested. The optional body overrides fields of the stored payment template for this payment only.

**Parameters**

- `rec_id` (string; path; required) — Unique ID of a previously created recurrence

**Request body** (optional)

`application/json`: [Payment-Instance-Override](#schema-Payment-Instance-Override)

**Responses**

- `201` The new payment — [Payment-Details](#schema-Payment-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-post-recurrences-rec_id-next"></a>

##### Create a next payment for a recurrence

`POST /recurrences/{rec_id}/next` · Operation ID: `post-recurrences-rec_id-next`

Requires: `merchant_credentials` (scopes: `payment:write`)

Creates a further payment from a recurrence that has already reached state `STARTED`. Returns `409` while the recurrence has not been started and its first payment paid. The optional body overrides fields of the stored payment template for this payment only.

**Parameters**

- `rec_id` (string; path; required) — Unique ID of a previously created recurrence

**Request body** (optional)

`application/json`: [Payment-Instance-Override](#schema-Payment-Instance-Override)

**Responses**

- `201` The new payment — [Payment-Details](#schema-Payment-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

#### Cards

Saved card tokens that stand in for a customer's card on later charges.

<a id="operation-post-cards-tokens"></a>

##### Create card token

`POST /cards/tokens` · Operation ID: `post-cards-tokens`

Requires: `merchant_credentials` (scopes: `card:write`)

Exchanges an encrypted card payload for a permanent card token.

The JWE produced by the GoPay client SDK is submitted in `payload` and exchanged for a `Permanent Card Token Details` object. Its `token` is what a later charge carries as `card_token` in the `CARD_TOKEN` input; its `card_id` addresses the saved card in the read and delete operations. The JWE is single-use. Tokenisation is disabled by default and must be enabled for the merchant; the operation is server-side only.

**Request body** (optional)

`application/json`: [Token-Create-Request](#schema-Token-Create-Request)

**Responses**

- `201` The new saved card token — [Permanent-Card-Token-Details](#schema-Permanent-Card-Token-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-cards-tokens-card_id"></a>

##### Card details

`GET /cards/tokens/{card_id}` · Operation ID: `get-cards-tokens-card_id`

Requires: `merchant_credentials` (scopes: `card:read`)

Returns the current details of a saved card.

Called after the `cards.updated` event to read fields the issuer has updated in place — a reissued PAN or a new expiration date — while the `card_id` stays the same. The API does not list saved cards; the merchant persists the association between `card_id` and customer. Server-side only.

**Parameters**

- `card_id` (string; path; required) — ID of the saved payment card

**Responses**

- `200` The saved card — [Permanent-Card-Token-Details](#schema-Permanent-Card-Token-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-delete-cards-tokens-card_id"></a>

##### Delete a card

`DELETE /cards/tokens/{card_id}` · Operation ID: `delete-cards-tokens-card_id`

Requires: `merchant_credentials` (scopes: `card:write`)

Permanently deletes a saved card.

A deleted token is not recoverable; saving the same card again requires a new tokenisation. Server-side only.

**Parameters**

- `card_id` (string; path; required) — ID of the saved payment card

**Responses**

- `204` Done; the response has no body
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

#### Events

The eshop's event log and the public keys that verify the signature of a webhook.

<a id="operation-get-eshops-goid-events"></a>

##### List events

`GET /eshops/{goid}/events` · Operation ID: `get-eshops-goid-events`

Requires: `merchant_credentials` (scopes: `event:read`)

Returns one page of the eshop's events, newest first.

Each page carries the URL of the next one in `next_page_url`, with the filters of the
request and the position to continue from already in it. The field is absent once the
last matching event has been returned.

**Parameters**

- `goid` (string; path; required) — Unique identifier of a registered merchant website
- `max_items` (integer; query; optional; default `20`; minimum 1; maximum 100) — Maximum number of events in one page
- `prev_item` (string; query; optional) — The `id` of the last event of the previous page. The page starts at the event after it.
  GoPay writes the value into `next_page_url` and the caller follows that URL rather than
  assembling the parameter. A value that has aged out of the 30-day window is rejected.
- `type` (string; query; optional) — The event types to include, comma-separated in a single parameter, up to 20 items. An item
  is either an exact type (`payments.paid`) or a whole namespace (`payments.*`). An unknown
  type is rejected. Omitted, every type matches.
- `occurred_after` (string (date-time); query; optional) — Include events that occurred at or after this instant. Must be earlier than `occurred_before` when both are given
- `occurred_before` (string (date-time); query; optional) — Include events that occurred before this instant
- `related_type` (string; query; optional; values: `payments`, `links`, `refunds`, `recurrences`, `cards`) — The kind of entity `related_id` refers to. Required together with `related_id`
- `related_id` (string; query; optional) — Include only events that carry this identifier, whichever position it appears in within
  `data`. Required together with `related_type`.

**Responses**

- `200` One page of the eshop's events, newest first — [Event-List](#schema-Event-List)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-eshops-goid-events-event_id"></a>

##### Event details

`GET /eshops/{goid}/events/{event_id}` · Operation ID: `get-eshops-goid-events-event_id`

Requires: `merchant_credentials` (scopes: `event:read`)

Returns a single event of the eshop by its `id`.

**Parameters**

- `goid` (string; path; required) — Unique identifier of a registered merchant website
- `event_id` (string; path; required) — Identifier of the event

**Responses**

- `200` The event — [Event](#schema-Event)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-webhooks-public-keys"></a>

##### Fetch webhook signing keys

`GET /webhooks/public-keys` · Operation ID: `get-webhooks-public-keys`

Requires: `shareable_key` or `merchant_credentials` (scopes: `shared:read`)

Returns the public keys that verify the signature of a webhook.

The keys are structured as a JWK Set described by
[RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517). Several keys may be published at
once while a key is being rotated.

**Responses**

- `200` The webhook signing keys currently in use — [JWK-Set](#schema-JWK-Set)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

#### SDK Services

Operations the GoPay client SDKs call from the customer's browser or app while collecting card or wallet data for a charge. The merchant's code does not normally call them. When the merchant's server performs the charge, it needs the browser data, which the GoPay client SDK also collects for it. The operations are documented for fully custom integrations; a custom card-data integration additionally requires a PCI DSS SAQ.

<a id="operation-get-payments-payment_id-info-google-pay"></a>

##### Google Pay Payment Info

`GET /payments/{payment_id}/google-pay/info` · Operation ID: `get-payments-payment_id-info-google-pay`

Requires: `payment_credentials` (scopes: `payment:read`) or `merchant_credentials` (scopes: `payment:read`)

Returns the Google Pay payment request configuration for the payment.

Intended for the GoPay client SDK; the merchant's code does not normally call it. The same endpoint serves both the web and the in-app case — the configured environment is carried in `environment`.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`

**Responses**

- `200` Google Pay payment request configuration consumed by the Google Pay button — object
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-payments-payment_id-info-apple-pay"></a>

##### Apple Pay Payment Info

`GET /payments/{payment_id}/apple-pay/info` · Operation ID: `get-payments-payment_id-info-apple-pay`

Requires: `payment_credentials` (scopes: `payment:read`) or `merchant_credentials` (scopes: `payment:read`)

Returns the Apple Pay payment request configuration for the payment on the web.

Intended for the GoPay client SDK; the merchant's code does not normally call it.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`

**Responses**

- `200` Apple Pay payment request object consumed by the Apple Pay button — object
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-payments-payment_id-apple-pay-app-info"></a>

##### Apple Pay Payment Info For Apps

`GET /payments/{payment_id}/apple-pay/app-info` · Operation ID: `get-payments-payment_id-apple-pay-app-info`

Requires: `payment_credentials` (scopes: `payment:read`) or `merchant_credentials` (scopes: `payment:read`)

Returns the Apple Pay payment request configuration for the payment in a native application. It carries `paymentSummaryItems` where the web variant carries a single `total`.

Intended for the GoPay client SDK; the merchant's code does not normally call it.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`

**Responses**

- `200` Apple Pay payment request object for a native application — object
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-post-payments-payment_id-apple-pay-validate"></a>

##### Validate Merchant

`POST /payments/{payment_id}/apple-pay/validate` · Operation ID: `post-payments-payment_id-apple-pay-validate`

Requires: `payment_credentials` (scopes: `payment:read`) or `merchant_credentials` (scopes: `payment:read`)

Completes the Apple Pay merchant validation handshake for the payment session.

The `validationUrl` issued by Apple is forwarded to GoPay, which returns the merchant session that the Apple Pay sheet expects. Intended for the GoPay client SDK; the merchant's code does not normally call it.

**Parameters**

- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
- `Origin` (string; header; required) — The origin of the page where the Apple Pay button is displayed. The browser adds it automatically

**Request body** (required)

`application/json`: [Validate-Merchant-Request](#schema-Validate-Merchant-Request)

**Responses**

- `200` The merchant session for the Apple Pay sheet — [Validate-Merchant-Response](#schema-Validate-Merchant-Response)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-encryption-public-key"></a>

##### Fetch public key

`GET /cards/public-key` · Operation ID: `get-encryption-public-key`

Requires: `shareable_key` or `merchant_credentials` (scopes: `shared:read`)

Returns the public encryption key to be used for encrypting card data.

It is structured as a JWK described by [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).

Intended for the GoPay client SDK; the merchant's code does not normally call it.

**Responses**

- `200` The public encryption key — [JWK](#schema-JWK)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-card-form-url"></a>

##### Card Form URL

`GET /cards/card-form-url` · Operation ID: `get-card-form-url`

Requires: `shareable_key` or `merchant_credentials` (scopes: `shared:read`)

Returns the URL of the hosted card input form.

Intended for the GoPay browser SDK, which embeds the form; the merchant's code does not normally call it.

**Responses**

- `200` The URL of the hosted card form — [Card-Form-URL](#schema-Card-Form-URL)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

<a id="operation-get-browser-data"></a>

##### Fetch browser data

`GET /cards/browser-data` · Operation ID: `get-browser-data`

Requires: `shareable_key`

Returns the `Browser Data` fields that the customer's browser cannot determine on its own — the source IP address, the `User-Agent` header, and the `Accept` headers — derived from the request that fetched them.

The GoPay client SDK calls it from the customer's browser or device immediately before a charge. A call made from the merchant's server returns the server's own values, which the card issuer rejects during 3-D Secure authentication.

**Responses**

- `200` The browser data derived from the request — [Browser-Data-Detected](#schema-Browser-Data-Detected)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)

### Schemas

<a id="schema-Client-Credentials-Request"></a>

#### Client-Credentials-Request

**Client Credentials Request**

Requests a merchant access token with the `client_credentials` grant

Type: `object`

- `grant_type` (string = `"client_credentials"`; required; example `"client_credentials"`) — Always `client_credentials` for this flow
- `scope` (string; required; example `"payment:write payment:read"`) — List of required token scopes, separated with a space.
  - `payment:read` reads payments and the resources built on them, such as charges, refunds, recurrences and payment links
  - `payment:write` creates, charges, cancels and modifies payments and those same resources
  - `card:read` reads saved card tokens
  - `card:write` saves and deletes card tokens
  - `event:read` reads the eshop's events
  - `shared:read` reads public resources such as public keys

<a id="schema-Payment-Credentials-Request"></a>

#### Payment-Credentials-Request

**Payment Credentials Request**

Requests a payment-scoped access token with the `payment_credentials` grant

Type: `object`

- `grant_type` (string = `"payment_credentials"`; required; example `"payment_credentials"`) — Always `payment_credentials` for this flow
- `scope` (string; required; example `"payment:charge payment:read"`) — List of required token scopes, separated with a space.
  - `payment:read` reads the payment
  - `payment:charge` charges the payment

<a id="schema-Access-Token"></a>

#### Access-Token

**Access Token**

The access token and its meta information.

Type: `object`

- `token_type` (string = `"bearer"`; optional; default `"bearer"`; example `"bearer"`) — Always `bearer`
- `access_token` ([JWT](#schema-JWT); optional) — The access token, presented as a Bearer token
- `scope` (string; optional; example `"payment:write payment:read"`) — Space-separated list of token scopes.
- `expires_in` (integer; optional; minimum 0; example `900`) — The expiration of the access JWT in seconds

<a id="schema-JWT"></a>

#### JWT

The JWT string as described by [RFC 7519: JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)

The JWT claims contain:
- `sub` -> the Client ID for which the token was issued
- `scope` -> the scopes of the token
- `iat` -> timestamp of token issuing
- `exp` -> timestamp of token expiration
- `domain` -> `merchant` for tokens issued to the merchant's server with the `client_credentials` grant, `payment` for payment-scoped tokens issued with the `payment_credentials` grant to the GoPay client SDK

Type: `string`

<a id="schema-Payment-Create-Request"></a>

#### Payment-Create-Request

**Payment Create Request**

Representation of a request for a new payment

Type: `object`

- `amount` (integer; required; minimum 0; example `100`) — Total amount in cents
- `currency` ([Currency](#schema-Currency); required) — Payment currency
- `order_number` (string; required; max length 128; example `"2025010199"`) — Order identification for the online shop, alphanumeric characters
- `order_description` (string; optional; example `"Test order"`) — Order description, alphanumeric characters
- `additional_params` (array of [Additional-Param](#schema-Additional-Param); optional; max items 4) — Additional parameters for the payment
- `customer` ([Customer](#schema-Customer); required) — Information about the customer
- `callback` ([Payment-Callback](#schema-Payment-Callback); required) — URLs for the return redirect and the notifications

Example:

```json
{
  "amount": 100,
  "currency": "CZK",
  "order_number": "2025010199",
  "order_description": "Test order",
  "additional_params": [
    {
      "name": "Custom param",
      "value": "Custom value"
    }
  ],
  "customer": {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+420123456789",
    "city": "Testington",
    "street": "Example st. 10",
    "postal_code": "10000",
    "country_code": "CZE",
    "customer_id": "customer420"
  },
  "callback": {
    "notification_url": "https://example.com/notify",
    "return_url": "https://example.com/return"
  }
}
```

<a id="schema-Currency"></a>

#### Currency

Supported payment currencies in ISO 4217 format

Type: `string`

Values: `CZK`, `EUR`, `PLN`, `USD`, `GBP`, `HUF`, `RON`

<a id="schema-Additional-Param"></a>

#### Additional-Param

**Additional Parameter**

Additional payment parameters

Type: `object`

- `name` (string; required; example `"Custom param"`) — Parameter name
- `value` (string; required; example `"Custom value"`) — Parameter value

Example:

```json
{
  "name": "Custom param",
  "value": "Custom value"
}
```

<a id="schema-Payment-Details"></a>

#### Payment-Details

**Payment Details**

Representation of an existing payment

Type: `object`

- `id` (string; required; example `"300000001"`) — Identifier of the payment
- `order_number` (string; required; example `"2025010199"`) — Order number given when the payment was created
- `state` ([Payment-State](#schema-Payment-State); required) — Payment state
- `amount` (integer; required; example `100`) — Total amount in cents
- `currency` ([Currency](#schema-Currency); required) — Payment currency
- `customer` ([Customer](#schema-Customer); required) — Customer data
- `gw_url` (string (uri); required; example `"https://gate.gopay.com/gw/123456789"`) — Address of GoPay's hosted payment gateway for this payment, used by the Redirect
  integration. It offers the customer every payment method the eshop has enabled,
  and GoPay drives the payment while the customer is on it. It is a destination the
  customer is sent to and cannot be embedded in the merchant's own checkout.
  `GET /payments/{payment_id}` reports the outcome of a payment paid there in the
  same way as for any other payment.
- `charge` ([Payment-Charge-Status-Response](#schema-Payment-Charge-Status-Response); optional) — The payment's charge, once a charge has been attempted
- `payment_secret` (string; required; example `"ps_4d2f9a51b7e30c68a1c5e9f03b7d2e46"`) — Payment secret that the merchant's server passes to the GoPay client SDK, so that the SDK can act on this payment. **Do not embed in URLs, log or store!**

<a id="schema-Customer"></a>

#### Customer

Customer details associated with the payment. The email address is required as it is used for authentication and notification purposes.

Type: `object`

- `email` (string (email); required; max length 128; example `"john.doe@example.com"`) — Customer email
- `first_name` (string; optional; max length 256; example `"John"`) — Customer first name
- `last_name` (string; optional; max length 256; example `"Doe"`) — Customer last name
- `phone_number` (string; optional; max length 128; example `"+420123456789"`) — Customer phone number (home or mobile)
- `city` (string; optional; max length 128; example `"Testington"`) — Customer address city
- `street` (string; optional; max length 128; example `"Example st. 10"`) — Customer address street
- `postal_code` (string; optional; max length 128; example `"10000"`) — Customer address ZIP (postal code)
- `country_code` (string; optional; max length 128; example `"CZE"`) — Customer country code according to [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
- `customer_id` (string; optional; max length 128; example `"customer420"`) — Unique customer ID (used to customise the checkout experience)

Example:

```json
{
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+420123456789",
  "city": "Testington",
  "street": "Example st. 10",
  "postal_code": "10000",
  "country_code": "CZE",
  "customer_id": "customer420"
}
```

<a id="schema-Payment-Callback"></a>

#### Payment-Callback

**Payment Callback**

Object holding URLs for callback purposes related to a payment

Type: `object`

- `notification_url` (string; required; example `"https://example.com/notify"`) — URL that receives a notification whenever the state of the payment changes
- `return_url` (string; required; example `"https://example.com/return"`) — URL the customer's browser is sent to at the end of the hosted gateway flow, and after the 3-D Secure step in a checkout integration. It must not carry a fragment (`#…`)

Example:

```json
{
  "notification_url": "https://example.com/notify",
  "return_url": "https://example.com/return"
}
```

<a id="schema-Payment-State"></a>

#### Payment-State

**Payment State**

The lifecycle state of a payment.
- `CREATED` - The payment exists and is awaiting a charge attempt
- `PAID` - The payment was charged successfully
- `CANCELED` - The customer abandoned the payment, the charge was rejected at authorisation, or the merchant canceled the payment before it was charged
- `PAYMENT_METHOD_CHOSEN` - A charge attempt is in flight and its outcome is not known yet
- `TIMEOUTED` - The payment did not reach a terminal outcome within its timeout
- `AUTHORIZED` - The payment has been authorised but not yet captured; only relevant for the pre-authorisation flow
- `REFUNDED` - The payment has been fully refunded
- `PARTIALLY_REFUNDED` - The payment has been partially refunded

Type: `string`

Values: `CREATED`, `PAID`, `CANCELED`, `PAYMENT_METHOD_CHOSEN`, `TIMEOUTED`, `AUTHORIZED`, `REFUNDED`, `PARTIALLY_REFUNDED`

<a id="schema-Charge-State"></a>

#### Charge-State

**Charge State**

The lifecycle state of a payment charge.
- `REQUESTED` - The charge has been initiated
- `PROCESSING` - The charge is being processed by the payment provider
- `ACTION_REQUIRED` - The customer must complete a step, such as 3-D Secure authentication, before the charge can continue
- `SUCCEEDED` - The charge completed successfully
- `FAILED` - The charge failed

Type: `string`

Values: `REQUESTED`, `PROCESSING`, `ACTION_REQUIRED`, `SUCCEEDED`, `FAILED`

<a id="schema-Payment-Charge-Data"></a>

#### Payment-Charge-Data

**Payment Charge Data**

The payment instrument used for the charge. The `payment_instrument` field selects the case, taking values from the [Payment Instrument](#schema-Payment-Instrument) enum.

Type: `oneOf`

One of: [Payment-Card-Charge-Data](#schema-Payment-Card-Charge-Data)

Discriminator: `payment_instrument` (`PAYMENT_CARD` → [Payment-Card-Charge-Data](#schema-Payment-Card-Charge-Data))

<a id="schema-Payment-Charge-Input"></a>

#### Payment-Charge-Input

**Payment Charge Input**

Model holding all data necessary to perform a payment charge

Type: `object`

- `payment_instrument` ([Payment-Charge-Data](#schema-Payment-Charge-Data); required) — Payment instrument data specifying how the payment should be charged

<a id="schema-Payment-Instrument"></a>

#### Payment-Instrument

**Payment Instrument**

The values of the field that selects the case of [Payment Charge Data](#schema-Payment-Charge-Data)

Type: `string`

Values: `PAYMENT_CARD`

<a id="schema-Payment-Card-Charge-Data"></a>

#### Payment-Card-Charge-Data

**Payment Card Charge Data**

The `PAYMENT_CARD` variant of the [Payment Charge Data](#schema-Payment-Charge-Data) union. Holds the card input, the browser data and the 3-D Secure preference.

Type: `object`

- `payment_instrument` (string = `"PAYMENT_CARD"`; required) — Always `PAYMENT_CARD`
- `input` ([Payment-Card-Input](#schema-Payment-Card-Input); required) — One of the possible inputs for a card payment
- `browser_data` ([Browser-Data](#schema-Browser-Data); required)
- `challenge_preference` ([Payment-Card-Challenge-Preference](#schema-Payment-Card-Challenge-Preference); optional)

<a id="schema-Payment-Card-Input"></a>

#### Payment-Card-Input

**Payment Card Input**

The card the payment is charged with. The `input_type` field selects the case, taking values from the [Payment Card Input Type](#schema-Payment-Card-Input-Type) enum.

Type: `oneOf`

One of: [Card-Token-Input](#schema-Card-Token-Input), [Google-Pay-Input](#schema-Google-Pay-Input), [Apple-Pay-Input](#schema-Apple-Pay-Input), [Encrypted-Card-Input](#schema-Encrypted-Card-Input)

Discriminator: `input_type` (`CARD_TOKEN` → [Card-Token-Input](#schema-Card-Token-Input), `GOOGLE_PAY` → [Google-Pay-Input](#schema-Google-Pay-Input), `APPLE_PAY` → [Apple-Pay-Input](#schema-Apple-Pay-Input), `ENCRYPTED_CARD` → [Encrypted-Card-Input](#schema-Encrypted-Card-Input))

<a id="schema-Payment-Card-Input-Type"></a>

#### Payment-Card-Input-Type

**Payment Card Input Type**

The values of the field that selects the case of [Payment Card Input](#schema-Payment-Card-Input)

Type: `string`

Values: `CARD_TOKEN`, `APPLE_PAY`, `GOOGLE_PAY`, `ENCRYPTED_CARD`

<a id="schema-Card-Token-Input"></a>

#### Card-Token-Input

**Card Token Input**

The `CARD_TOKEN` variant of the [Payment Card Input](#schema-Payment-Card-Input) union. Carries a saved card token

Type: `object`

- `input_type` (string = `"CARD_TOKEN"`; required) — Always `CARD_TOKEN`
- `card_token` (string; required; example `"J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjG..."`) — Permanent card token acquired using the [Create Card Token](#operation-post-cards-tokens) API call

<a id="schema-Payment-Card-Challenge-Preference"></a>

#### Payment-Card-Challenge-Preference

**Payment Card Challenge Preference**

The merchant's preference for the 3-D Secure authentication of a card payment.
- `AUTO` - let GoPay decide
- `CHALLENGE_PREFERRED` - ask for a 3-D Secure challenge for stronger authentication; it may still be skipped, for example for Apple Pay
- `NO_CHALLENGE_PREFERRED` - ask to skip the challenge; the card issuer can still require one

Type: `string`

Values: `CHALLENGE_PREFERRED`, `NO_CHALLENGE_PREFERRED`, `AUTO`

<a id="schema-Google-Pay-Input"></a>

#### Google-Pay-Input

**Google Pay Input**

The `GOOGLE_PAY` variant of the [Payment Card Input](#schema-Payment-Card-Input) union. Carries the payment data returned by Google Pay.
See [Payment Data Cryptography](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography) in Google Pay documentation for details.

Type: `object`

- `input_type` (string = `"GOOGLE_PAY"`; optional; example `"GOOGLE_PAY"`) — Always `GOOGLE_PAY`
- `protocolVersion` (string; optional; example `"ECv2"`) — Version of the Google Pay API protocol used to encrypt the payment data
- `signature` (string; optional; example `"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q=="`) — Digital signature of the payment data
- `intermediateSigningKey` (object; optional) — Intermediate signing key from Google used to verify the signature
  - `signedKey` (string; optional; example `"{\"keyExpiration\":\"1542323393147\",\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw==\"}"`) — JSON-encoded string containing the key value and expiration
  - `signatures` (array of string; optional) — Signatures of the intermediate signing key
- `signedMessage` (string; optional; example `"{\"tag\":\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U=\",\"ephemeralPublicKey\":\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs=\",\"encryptedMessage\":\"mKOoXwi8OavZ\"}"`) — JSON-encoded string containing the encrypted payment data

<a id="schema-Apple-Pay-Input"></a>

#### Apple-Pay-Input

**Apple Pay Input**

The `APPLE_PAY` variant of the [Payment Card Input](#schema-Payment-Card-Input) union. Carries the payment token returned by Apple Pay.
See [Payment token format reference](https://developer.apple.com/documentation/passkit/payment-token-format-reference) in the Apple Pay documentation for details.

Type: `object`

- `input_type` (string = `"APPLE_PAY"`; required; example `"APPLE_PAY"`) — Always `APPLE_PAY`
- `data` (string; required; example `"V7OcjttPJnUJaQH7x7OjbIeZSINuc..."`) — Encrypted payment data from the Apple Pay token
- `signature` (string; required; example `"MIAGCSqGSIb3DQEHAqCAM..."`) — Signature of the payment and header data, signed by Apple
- `version` (string; required; example `"EC_v1"`) — Version of the Apple Pay payment token format
- `header` (object; required) — Header containing additional data for decrypting and verifying the payment token
  - `applicationData` (string; optional; example `"94ee059335e587e5f6b717fb172c5c3841659d892a84b7c6c47d0d13c58f7ea4"`) — Hash of the `applicationData` carried on the Apple Pay payment request. Apple includes it only for sessions created with that value, so the field is optional; forward it unchanged when the Apple Pay session returns it
  - `ephemeralPublicKey` (string; required; example `"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwpd0HT6uOdE2pZTBZXsJF7IK7EvJQDq4LnQS5B5g8fiD9sEZNt4P9DhWRO44kEbbyiQ1FVgPcSsvJ2Z5I+qPTw=="`) — Ephemeral public key used for deriving the shared secret
  - `publicKeyHash` (string; required; example `"L6vppo38t31Q/9npxRy/xbA1+cs13h1LV+pMO/FYwvo="`) — SHA-256 hash of the merchant's public key certificate
  - `transactionId` (string; required; example `"4f4fac7a179ae30ce4c839e85efa4a34811a5ea2af88280c847a6a8ba2c0e8c5"`) — Unique transaction identifier generated by Apple Pay

Example:

```json
{
  "input_type": "APPLE_PAY",
  "data": "V7OcjttPJnUJaQH7x7OjbIeZSINuc...",
  "signature": "MIAGCSqGSIb3DQEHAqCAM...",
  "version": "EC_v1",
  "header": {
    "applicationData": "94ee059335e587e5f6b717fb172c5c3841659d892a84b7c6c47d0d13c58f7ea4",
    "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwpd0HT6uOdE2pZTBZXsJF7IK7EvJQDq4LnQS5B5g8fiD9sEZNt4P9DhWRO44kEbbyiQ1FVgPcSsvJ2Z5I+qPTw==",
    "publicKeyHash": "L6vppo38t31Q/9npxRy/xbA1+cs13h1LV+pMO/FYwvo=",
    "transactionId": "4f4fac7a179ae30ce4c839e85efa4a34811a5ea2af88280c847a6a8ba2c0e8c5"
  }
}
```

<a id="schema-Bank-Swift"></a>

#### Bank-Swift

**Bank Swift**

SWIFT/BIC code identifying a supported bank. Use `OTHERS` for banks not explicitly listed.
- `GIBACZPX` - Česká spořitelna (Czech Republic)
- `KOMBCZPP` - Komerční banka (Czech Republic)
- `SUBASKBX` - VÚB banka (Slovakia)
- `GIBASKBX` - Slovenská sporiteľňa (Slovakia)
- `OTHERS` - Any other supported bank

Type: `string`

Values: `GIBACZPX`, `KOMBCZPP`, `SUBASKBX`, `GIBASKBX`, `OTHERS`

<a id="schema-Browser-Data"></a>

#### Browser-Data

**Browser Data**

Customer browser data collected for 3-D Secure authentication purposes. This data is forwarded to the card issuer during the authentication flow.

Type: `object`

- `language` (string; required; example `"cs-CZ"`) — Language or locale of the customer environment
- `timezone` (integer; required; example `-60`) — Timezone offset of the customer environment in minutes (e.g. -60 for CET)
- `screen_width` (integer; required; example `434`) — Width of the customer's screen in pixels
- `screen_height` (integer; required; example `965`) — Height of the customer's screen in pixels
- `color_depth` (integer; required; example `24`) — Color depth of the customer's screen in bits
- `user_agent` (string; required; example `"Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Mobile Safari/537.36"`) — User-Agent string of the customer's browser, as returned by the browser data endpoint. Take it from the same source as `ip` — a pair that disagrees fails 3-D Secure authentication
- `accept_header` (string; required; example `"{\"accept-language\":\"cs;q=0.5\",\"accept-encoding\":\"gzip, deflate, br, zstd\",\"accept\":\"application/json, text/plain, */*\"}"`) — JSON-encoded Accept headers from the customer's browser, as returned by the browser data endpoint. Take it from the same source as `ip`
- `javascript_enabled` (boolean; required; example `true`) — Whether JavaScript is enabled in the customer's browser
- `ip` (string; required; max length 45; example `"192.0.2.42"`) — IP address of the customer's browser, as returned by the browser data endpoint. A merchant's server charging on the customer's behalf must forward the value collected in the browser, never its own address

<a id="schema-Browser-Data-Detected"></a>

#### Browser-Data-Detected

**Browser Data Detected**

The `Browser Data` fields the customer's browser cannot determine on its own, derived from the request that fetched them.
Merge them into `Browser Data` when charging the payment.

Type: `object`

- `ip` (string; required; max length 45; example `"192.0.2.42"`) — IP address the request originated from
- `user_agent` (string; required; example `"Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Mobile Safari/537.36"`) — User-Agent header sent with the request
- `accept_header` (string; required; example `"{\"accept-language\":\"cs;q=0.5\",\"accept-encoding\":\"gzip, deflate, br, zstd\",\"accept\":\"application/json, text/plain, */*\"}"`) — JSON-encoded Accept headers sent with the request

<a id="schema-Payment-Charge-Response"></a>

#### Payment-Charge-Response

**Payment Charge Response**

The charge started by `POST /payments/{payment_id}/charge`: its state, the instrument used, and any step the customer must complete.

Type: `object`

- `id` (string; required; example `"9123456789"`) — Unique identifier of the charge
- `state` ([Charge-State](#schema-Charge-State); required) — Current state of the charge
- `payment_instrument` ([Payment-Instrument-Data](#schema-Payment-Instrument-Data); required) — Details of the payment instrument used for this charge
- `action` ([Payment-Charge-Action](#schema-Payment-Charge-Action); optional) — The step the customer must complete, such as 3-D Secure authentication. Present when `state` is `ACTION_REQUIRED`

<a id="schema-Payment-Charge-Status-Response"></a>

#### Payment-Charge-Status-Response

**Payment Charge Status Response**

The current state of the payment's charge, the instrument used, any step the customer must complete and, for a failed charge, the reason.

Type: `object`

- `id` (string; required; example `"9123456789"`) — Unique identifier of the charge
- `state` ([Charge-State](#schema-Charge-State); required) — Current state of the charge
- `payment_instrument` ([Payment-Instrument-Data](#schema-Payment-Instrument-Data); optional) — Details of the payment instrument used for this charge
- `action` ([Payment-Charge-Action](#schema-Payment-Charge-Action); optional) — The step the customer must complete, such as 3-D Secure authentication. Present when `state` is `ACTION_REQUIRED`
- `fail_reason` (string; optional; example `"Issuer declined the authorisation"`) — Reason for the charge's failure. Only present when state is `FAILED`

<a id="schema-Payment-Instrument-Data"></a>

#### Payment-Instrument-Data

**Payment Instrument Data**

The payment instrument a charge used. The `payment_instrument` field selects the case, taking values from the [Payment Instrument](#schema-Payment-Instrument) enum.

Type: `oneOf`

One of: [Payment-Card-Instrument-Out](#schema-Payment-Card-Instrument-Out)

Discriminator: `payment_instrument` (`PAYMENT_CARD` → [Payment-Card-Instrument-Out](#schema-Payment-Card-Instrument-Out))

Example:

```json
{
  "payment_instrument": "PAYMENT_CARD",
  "details": {
    "input_type": "CARD_TOKEN",
    "masked_pan": "406821******1234",
    "expiration_month": "01",
    "expiration_year": "30",
    "scheme": "VISA",
    "fingerprint": "73c8d0a48d91def89761..."
  }
}
```

<a id="schema-Payment-Card-Instrument-Out"></a>

#### Payment-Card-Instrument-Out

**Payment Card Instrument Out**

The `PAYMENT_CARD` variant of the Payment Instrument Data union. Contains the card-specific details of the instrument used in a charge.

Type: `object`

- `payment_instrument` ([Payment-Instrument](#schema-Payment-Instrument); required) — Always `PAYMENT_CARD`
- `details` ([Payment-Card-Charge-Details](#schema-Payment-Card-Charge-Details); optional) — Card-specific details of the payment instrument

Example:

```json
{
  "payment_instrument": "PAYMENT_CARD",
  "details": {
    "input_type": "CARD_TOKEN",
    "masked_pan": "406821******1234",
    "expiration_month": "01",
    "expiration_year": "30",
    "scheme": "VISA",
    "fingerprint": "73c8d0a48d91def89761..."
  }
}
```

<a id="schema-Payment-Card-Charge-Details"></a>

#### Payment-Card-Charge-Details

**Payment Card Charge Details**

Output details of a card payment instrument as returned in a charge response. Contains masked card data identifying the card used.

Type: `object`

- `input_type` ([Payment-Card-Input-Type](#schema-Payment-Card-Input-Type); required) — The type of card input that was used for the charge
- `masked_pan` (string; optional; example `"406821******1234"`) — Masked primary account number with only the first six and last four digits visible
- `expiration_month` (string; optional; pattern `^(?:0[0-9]|1[0-2])$`; example `"01"`) — Card expiration month (01–12)
- `expiration_year` (string; optional; pattern `^[0-9]{2}$`; example `"30"`) — Card expiration year (two-digit format)
- `scheme` ([Card-scheme](#schema-Card-scheme); optional) — Card network scheme
- `fingerprint` (string; optional; example `"73c8d0a48d91def89761..."`) — A unique hash identifying the physical card

Example:

```json
{
  "input_type": "CARD_TOKEN",
  "masked_pan": "406821******1234",
  "expiration_month": "01",
  "expiration_year": "30",
  "scheme": "VISA",
  "fingerprint": "73c8d0a48d91def89761..."
}
```

<a id="schema-Card-scheme"></a>

#### Card-scheme

**Card Scheme**

The card network scheme (VISA or MASTERCARD)

Type: `string`

Values: `VISA`, `MASTERCARD`

<a id="schema-Payment-Charge-Action"></a>

#### Payment-Charge-Action

**Payment Charge Action**

A step the customer must complete before the charge can continue, such as 3-D Secure authentication on the card issuer's page. The `action_type` field selects the case.

Type: `oneOf`

One of: [Emv-3DS-Action](#schema-Emv-3DS-Action)

Discriminator: `action_type` (`EMV3DS` → [Emv-3DS-Action](#schema-Emv-3DS-Action))

Example:

```json
{
  "action_type": "EMV3DS",
  "state": "CREATED",
  "redirect_url": "https://gate.gopay.com/redirect"
}
```

<a id="schema-Payment-Charge-Action-Type"></a>

#### Payment-Charge-Action-Type

**Payment Charge Action Type**

The values of the field that selects the case of Payment Charge Action.
- `EMV3DS` - EMV 3-D Secure authentication for card payments

Type: `string`

Values: `EMV3DS`

<a id="schema-Emv-3DS-Action"></a>

#### Emv-3DS-Action

**Emv 3DS Action**

The `EMV3DS` variant of the Payment Charge Action union. Represents an EMV 3-D Secure authentication action for card payments.

Type: `object`

- `action_type` ([Payment-Charge-Action-Type](#schema-Payment-Charge-Action-Type); required) — Always `EMV3DS`
- `state` ([Emv-3DS-State](#schema-Emv-3DS-State); required) — Current state of the 3-D Secure authentication
- `redirect_url` (string (uri); optional; example `"https://gate.gopay.com/redirect"`) — URL the customer's browser is sent to for the 3-D Secure step. Present while the charge is in `ACTION_REQUIRED`

Example:

```json
{
  "action_type": "EMV3DS",
  "state": "CREATED",
  "redirect_url": "https://gate.gopay.com/redirect"
}
```

<a id="schema-Emv-3DS-State"></a>

#### Emv-3DS-State

**Emv 3DS State**

The lifecycle state of an EMV 3-D Secure authentication.
- `CREATED` - The 3-D Secure authentication has been initiated
- `CHALLENGE_REQUIRED` - The customer must complete a 3-D Secure challenge, such as a one-time code or a confirmation in the banking app
- `AUTHENTICATED_CHALLENGE` - The customer was authenticated through a challenge
- `AUTHENTICATED_FRICTIONLESS` - The customer was authenticated without a challenge (frictionless flow)
- `NOT_AUTHENTICATED` - The 3-D Secure authentication was not completed
- `FAILED` - The 3-D Secure authentication failed

Type: `string`

Values: `CREATED`, `CHALLENGE_REQUIRED`, `AUTHENTICATED_CHALLENGE`, `AUTHENTICATED_FRICTIONLESS`, `NOT_AUTHENTICATED`, `FAILED`

<a id="schema-QR-Payment-Details"></a>

#### QR-Payment-Details

**QR Payment Details**

Details of a QR code payment including the payment amount, recipient bank account information, and the generated QR codes in various formats.

Type: `object`

- `amount` (integer; required; example `10000`) — Payment amount in cents
- `currency` ([Currency](#schema-Currency); required) — Payment currency
- `recipient` ([Bank-Transfer-Recipient](#schema-Bank-Transfer-Recipient); required) — Information about the recipient
- `qr_code` ([QR-Code-List](#schema-QR-Code-List); required) — Generated QR code images in various regional formats

<a id="schema-Bank-Transfer-Recipient"></a>

#### Bank-Transfer-Recipient

**Bank Transfer Recipient**

Information about the recipient of a bank transfer payment, including their name, bank account details, and address.

Type: `object`

- `name` (string; optional; example `"GoPay Czech"`) — Name of the payment recipient
- `bank_account` ([Recipient-Bank-Account](#schema-Recipient-Bank-Account); optional) — Bank account details of the recipient in both local and international formats
- `address` ([Recipient-Address](#schema-Recipient-Address); optional) — Physical address of the recipient

<a id="schema-Recipient-Bank-Account"></a>

#### Recipient-Bank-Account

**Recipient Bank Account**

Recipient bank account details provided in both local (country-specific) and international (IBAN/SWIFT) formats.

Type: `object`

- `local` ([Bank-Account-Local-Details](#schema-Bank-Account-Local-Details); optional) — Bank account details in the local (country-specific) format
- `international` ([Bank-Account-International-Details](#schema-Bank-Account-International-Details); optional) — Bank account details in the international IBAN/BIC format

<a id="schema-Bank-Account-Local-Details"></a>

#### Bank-Account-Local-Details

**Bank Account Local Details**

Bank account details in the local Czech/Slovak format, including the account number prefix, bank code, and variable symbol for payment identification.

Type: `object`

- `prefix` (string; required; example `"000000"`) — Account number prefix (may be all zeros)
- `account_number` (string; required; example `"9878039"`) — The local bank account number
- `bank_code` (string; required; example `"2010"`) — Numeric bank code identifying the bank
- `variable_symbol` (string; required; example `"3123456789"`) — Variable symbol used to match the payment to an order

<a id="schema-Bank-Account-International-Details"></a>

#### Bank-Account-International-Details

**Bank Account International Details**

Bank account details in the international IBAN/BIC format, used for cross-border and SEPA payments.

Type: `object`

- `bic` ([Bank-Swift](#schema-Bank-Swift); optional) — BIC (Bank Identifier Code) / SWIFT code of the bank
- `iban` (string; optional; example `"CZ5120100000000009878039"`) — International Bank Account Number
- `reference` (string; optional; example `"3123456789"`) — Payment reference number used to match the payment to an order

<a id="schema-Recipient-Address"></a>

#### Recipient-Address

**Recipient Address**

Physical address of the payment recipient.

Type: `object`

- `street` (string; optional; example `"Senovazne nam. 1736"`) — Street address including the building number
- `city` (string; optional; example `"Ceske Budejovice"`) — City name
- `zip_code` (string; optional; example `"37001"`) — ZIP or postal code
- `country` (string; optional; example `"Czech Republic"`) — Country name

<a id="schema-QR-Code-List"></a>

#### QR-Code-List

**QR Code List**

A collection of QR code images in various regional formats, each encoded as a base64 string. The available formats depend on the payment currency and recipient country.

Type: `object`

- `spayd` (string; optional; example `"iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAAAklEQVR4AewaftIAAAglSURBVO3BUa4cuZYEwXCi9r9lH30WDh6RBJVXrekOM/wlVfU/rVTV1kpVba1U1dZKVW2tVNXWSlVtrVTV1kpVba1U1dYnh4D8DdRMQE6omYBMat4CZFIzATmhZgLyk9ScADKpmYD8DdQ8WamqrZWq2lqpqq2Vqtr65Deo+WlA3gJkUnMLyBM1t9RMQCY1E5BvaiYgJ4CcUHNDzU8DcmOlqrZWqmprpaq2Vqpq65OXAbml5i1qJiATkEnNBOQtQN4EZFLzFjUngExqbgC5peYtK1W1tVJVWytVtbVSVVuf/AuomYC8Sc0TILfUTEAmNSeAfFNzQs0EZFLzX7BSVVsrVbW1UlVbK1W19cm/AJBJzQRkUnMCyKTmCZATQCY1E5BJzaTmG5A3AZnU/NusVNXWSlVtrVTV1kpVbX3yMjV/mpoTak4AOQHkiZoJyJuATGp+kpoJyKTmhpq/wUpVba1U1dZKVW2tVNXWJ78ByN8AyKRmAjKpOaFmAvJNzQRkUjMBuaVmAvJNzQTkbwDkb7VSVVsrVbW1UlVb+Ev+hYBMam4BmdR8AzKpuQXklppvQCY1E5ATav4LVqpqa6WqtlaqamulqrY+OQRkUnMCyN8AyKRmAjKpuQFkUjMBmdRMQG6omYBMak4AuaXmCZBJzQTklponK1W1tVJVWytVtbVSVVufHFIzAZnUTGpOAJnUPAHyJjUTkCdqTgCZ1NxSMwH5puafoGYC8hY1P2mlqrZWqmprpaq2Vqpq65NDQCY1Pw3IEzX/BDU31NxSc0LNW4BMak4AmdR8AzKpOQFkUvOWlaraWqmqrZWq2lqpqi38Jf8AIJOaJ0AmNSeAnFBzAsgTNROQSc0tIDfU3ALyk9RMQCY1E5ATap6sVNXWSlVtrVTV1kpVbX3yG4BMat4E5AaQE2omIDfUTEAmNSeATGpOqLkB5E1qngCZgExqTqiZgNxYqaqtlaraWqmqrZWq2vrkEJBbQG6p+QbkTUAmNROQtwCZ1ExqTqiZgHxTMwGZ1ExAJjUngExqfhKQSc2NlaraWqmqrZWq2lqpqi38JZeAnFBzC8g3NROQSc0E5ISaCcik5gaQSc0tIDfUTED+NDUngJxQMwGZ1DxZqaqtlaraWqmqLfwlB4BMaiYgJ9S8BcgJNROQE2reAuSEmgnIpOYJkFtqJiBvUXMLyKTmLStVtbVSVVsrVbW1UlVb+EsuAZnUnAByQ80EZFIzAZnUnADyk9RMQG6puQFkUnMCyKTmCZATav60laraWqmqrZWq2lqpqq1P/gAgt9R8AzKpOaHmlpobQCY1E5BJzQRkUnMDyKTmlpoJyBM1t4BMaiYgk5onK1W1tVJVWytVtbVSVVuf/AY1E5BJzQTkBJC3ALmlZgLyRM1PA3JDzQkgk5oTap4AOaFmUvOTVqpqa6WqtlaqamulqrY++Q1Abql5C5CfBmRS8xY1J9S8BcikZlIzAZnUnADyFiCTmresVNXWSlVtrVTV1kpVbeEvOQBkUjMBOaFmAvJEzQkgk5oTQP4Gak4AeaLmBJATaiYgb1EzAZnUnAAyqXmyUlVbK1W1tVJVWytVtfXJy9RMQG6peQLkFpBJzQkg39TcAjIB+UlAJjVvUjMBeQLkBJBJzaTmxkpVba1U1dZKVW2tVNUW/pIXAZnUnADyRM0JIJOanwTkTWomIJOaCcifpmYCMqn5SUBOqHmyUlVbK1W1tVJVW58cAvImICfUPAEyqTkBZFLzFjUTkEnNBGRSMwF5i5oJyKRmAjKpmYC8Rc2kZgJyY6WqtlaqamulqrZWqmoLf8klIH+amgnICTUngExqngB5k5oTQCY1bwFyQs0E5ImaCcgtNROQSc2TlaraWqmqrZWq2lqpqq1PDgE5oWYCMqmZgExqvgGZ1LxJzQkg39RMQE6omYCcUPOT1ExA3gLkhJoJyATkLStVtbVSVVsrVbW1UlVbn/zlgHxTMwF5k5oTam6oeROQJ2omIJOaW0AmNROQb2pOAJnUTEDeslJVWytVtbVSVVsrVbX1yW9QMwGZ1ExAJjVPgExqfhqQSc03IJOaCcgJNROQE2qeqJmATGpOqJmA3AByAsgJNTdWqmprpaq2Vqpqa6WqtvCXHAAyqTkBZFIzAXmLmgnICTUTkCdqJiCTmjcBeYuaW0B+kppbQCY1T1aqamulqrZWqmprpaq2Pjmk5paaE2puAJmAnFAzATmh5icBmdRMap4AOQFkUnNLzQ0gJ4BMat6yUlVbK1W1tVJVWytVtfXJISB/AzW31ExA3gLknwDkiZoJyKTmBJBbQL6peROQt6xU1dZKVW2tVNXWJ79BzU8DckPNLTU31JwAcgvIpGYC8kTNBGRSM6mZgJxQ8xY1E5C3rFTV1kpVba1U1dZKVW198jIgt9T8aWreAmRSM6k5AWRSMwG5AWRScwLICSB/mpq3rFTV1kpVba1U1dZKVW198h8CZFLzFjUTkEnNBGRSc0vNNyCTmgnIpGZSMwG5oWYCcgLIpGYCMql5slJVWytVtbVSVVsrVbX1yb+AmgnICSCTmhNAbgA5AeQnAZnUTEDepOYbkEnNCTUTkLesVNXWSlVtrVTV1kpVbX3yMjX/n6i5peYJkBNqJiC3gHxTcwLIpOZNQP40NTdWqmprpaq2Vqpqa6Wqtj75DUD+BkBuAZnUnADyRM0EZAIyqZmAvAXIpOYEkBNq3gLkFpBJzZOVqtpaqaqtlaraWqmqLfwlVfU/rVTV1kpVba1U1dZKVW2tVNXWSlVtrVTV1kpVbf0fJGLzp4ep9m8AAAAASUVORK5CYII="`) — QR code in the SPAYD (Short Payment Descriptor) format, commonly used in the Czech Republic. Encoded as a base64 image in the requested format.
- `paybysquare` (string; optional; example `"{QR code in base64}"`) — QR code in the Pay by Square format, commonly used in Slovakia. Encoded as a base64 image in the requested format.
- `sepa` (string; optional; example `"{QR code in base64}"`) — QR code in the SEPA (Single Euro Payments Area) format for EUR payments. Encoded as a base64 image in the requested format.
- `mnb_qr` (string; optional; example `"{QR code in base64}"`) — QR code in the MNB (Magyar Nemzeti Bank) format, commonly used in Hungary. Encoded as a base64 image in the requested format.

<a id="schema-Token-Create-Request"></a>

#### Token-Create-Request

**Token Create Request**

Request body for creating a card token. Contains the encrypted card data.

Type: `object`

- `payload` ([JWE](#schema-JWE); required) — The encrypted card data payload in JWE compact serialization format

<a id="schema-Permanent-Card-Token-Details"></a>

#### Permanent-Card-Token-Details

**Permanent Card Token Details**

Details of a saved card token. The token is reused on later charges until it is deleted; issuer updates such as a new expiration date are applied to it in place.

Type: `object`

- `card_id` (string; required; example `"8007127320"`) — Unique identifier of the stored card token
- `masked_pan` (string; required; example `"406821******1234"`) — Masked primary account number with only the first six and last four digits visible
- `masked_virtual_pan` (string; required; example `"489537******6287"`) — Masked virtual PAN (network token) associated with the card
- `expiration_month` (string; required; pattern `^(?:0[0-9]|1[0-2])$`; example `"01"`) — Card expiration month (01–12)
- `expiration_year` (string; required; pattern `^[0-9]{2}$`; example `"30"`) — Card expiration year (two-digit format)
- `scheme` ([Card-scheme](#schema-Card-scheme); required) — Card network scheme
- `corporate` (boolean; required; default `false`; example `false`) — Whether the card is a corporate (business) card
- `fingerprint` (string; required; example `"73c8d0a48d91def897612b54e630997745e1faad43045e732189cfe4acf4961b"`) — A unique hash identifying the physical card, stable across repeated tokenisations of the same card
- `token` (string; required; example `"J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv9DtCT3HLSlWHRYAbVTBLbouV77YtVSgavhi4uRZTwDy218Gog4MbZJ+umL/BkfFlNQ80PCdOjwYr8DtqZr71LHwkvg91ywirZp0="`) — The permanent card token value to be used in charge requests
- `card_art_url` (string (uri); required; example `"https://card.art/pic.png"`) — URL of the card art image provided by the issuing bank
- `brand` (string; optional; example `"GOLD"`) — Card brand or tier (e.g. GOLD, PLATINUM, STANDARD)
- `service_type` ([Card-Service-Type](#schema-Card-Service-Type); optional) — Whether the card is a debit or credit card
- `status` ([Card-Token-Status](#schema-Card-Token-Status); optional) — Current status of the stored card token

Example:

```json
{
  "card_id": "8007127320",
  "masked_pan": "406821******1234",
  "masked_virtual_pan": "489537******6287",
  "expiration_month": "01",
  "expiration_year": "30",
  "scheme": "VISA",
  "corporate": false,
  "fingerprint": "73c8d0a48d91def897612b54e630997745e1faad43045e732189cfe4acf4961b",
  "token": "J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv9DtCT3HLSlWHRYAbVTBLbouV77YtVSgavhi4uRZTwDy218Gog4MbZJ+umL/BkfFlNQ80PCdOjwYr8DtqZr71LHwkvg91ywirZp0=",
  "card_art_url": "https://card.art/pic.png",
  "brand": "GOLD",
  "service_type": "DEBIT"
}
```

<a id="schema-Card-Service-Type"></a>

#### Card-Service-Type

**Card Service Type**

Indicates whether the card is a debit or credit card.
- `DEBIT` - Funds are drawn directly from the cardholder's bank account
- `CREDIT` - Funds are drawn from the cardholder's credit line

Type: `string`

Values: `DEBIT`, `CREDIT`

<a id="schema-Card-Token-Status"></a>

#### Card-Token-Status

**Card Token Status**

Current status of a permanent card token.
- `ACTIVE` - The token is valid and can be used for payments
- `SUSPENDED` - The token is temporarily suspended and cannot be used
- `DELETED` - The token has been permanently deleted

Type: `string`

Values: `ACTIVE`, `SUSPENDED`, `DELETED`

<a id="schema-JWK"></a>

#### JWK

The structure of the public encryption key. It is formatted according to RFC 7517: JSON Web Key (JWK)

Type: `object`

- `kty` (string = `"RSA"`; required; example `"RSA"`) — Key type. Always `RSA` for the encryption keys used by GoPay.
- `use` (string = `"enc"`; required; example `"enc"`) — Key usage. Always `enc` (encryption).
- `kid` (string; required; example `"key_20250406"`) — Key ID
- `alg` (string; required; default `"RSA-OAEP-256"`; example `"RSA-OAEP-256"`) — Algorithm to be used for encryption with the key.
- `n` (string; required; example `"oR79tj1xAaqr1TfmkGS03EfEZjU_5DMomKJXGK8cnmtGivG5XnFodcbztzSOrlrKmhoxrKRR0LiRRjYJIgTP3dGK9KOv7JRH4adnDClckQkxupwoz1dcm6cLDzjuVS1a4et8lQlwYKm5r52fG9VShckwNZgvmK0uYcE7717wLkX3JM2vA_F_-2oRCjG3l2E4cjhQzzstTFPkW35ZjuKut4If8LOnKH0h9tdblUOSB_VtZBNY6PCXeUTDfbCb85-eGrwWXEajq4uegPDbV2oSnTLxOXR8ctWURZ8XjS1PgsoDD4go9BQchv-9Q2m0NbS5s71WVJ9LOW7Xt-Napsoftw"`) — The `RSA` public key modulus part.
- `e` (string; required; default `"AQAB"`; example `"AQAB"`) — The `RSA` public key exponent part.

Example:

```json
{
  "kty": "RSA",
  "kid": "key_20250406",
  "use": "enc",
  "alg": "RSA-OAEP-256",
  "n": "oR79tj1xAaqr1TfmkGS03EfEZjU_5DMomKJXGK8cnmtGivG5XnFodcbztzSOrlrKmhoxrKRR0LiRRjYJIgTP3dGK9KOv7JRH4adnDClckQkxupwoz1dcm6cLDzjuVS1a4et8lQlwYKm5r52fG9VShckwNZgvmK0uYcE7717wLkX3JM2vA_F_-2oRCjG3l2E4cjhQzzstTFPkW35ZjuKut4If8LOnKH0h9tdblUOSB_VtZBNY6PCXeUTDfbCb85-eGrwWXEajq4uegPDbV2oSnTLxOXR8ctWURZ8XjS1PgsoDD4go9BQchv-9Q2m0NbS5s71WVJ9LOW7Xt-Napsoftw",
  "e": "AQAB"
}
```

<a id="schema-JWE"></a>

#### JWE

The structure containing the encrypted payload. It is described by [RFC 7516: JSON Web Encryption (JWE)](https://datatracker.ietf.org/doc/html/rfc7516)

It is produced by the GoPay client SDK.

Type: `string`

<a id="schema-Card-Form-URL"></a>

#### Card-Form-URL

**Card Form URL**

The URL of the hosted card input form, which the GoPay browser SDK embeds in the merchant's page.

Type: `object`

- `card_form_url` (string; optional; example `"https://secure.gopay.com/gp-card-comm/q/form"`) — URL of the hosted card input form

<a id="schema-Error-Response-Body"></a>

#### Error-Response-Body

**Error Response Body**

Standard error response body returned for all API error responses. Contains the HTTP status code, error type, a human-readable message, and additional diagnostic details.

Type: `object`

- `code` (integer; required; example `400`) — HTTP status code
- `error` (string; required; example `"BAD_REQUEST"`) — Error type
- `message` (string; required; example `"Invalid request parameter"`) — Error message
- `detail` (string; required; example ``"The field `payment_instrument` is required"``) — Detailed error description
- `path` (string; required; example `"/payments/123/charge"`) — Request path
- `timestamp` (string (date-time); required; example `"2025-12-10T10:30:00Z"`) — Error timestamp

<a id="schema-Encrypted-Card-Input"></a>

#### Encrypted-Card-Input

**Encrypted Card Input**

The `ENCRYPTED_CARD` variant of the [Payment Card Input](#schema-Payment-Card-Input) union. Carries a card the customer entered, encrypted by the GoPay client SDK. Single-use and valid for ten minutes.

Type: `object`

- `input_type` (string = `"ENCRYPTED_CARD"`; required; example `"ENCRYPTED_CARD"`) — Always `ENCRYPTED_CARD`
- `payload` ([JWE](#schema-JWE); required) — The encrypted card

<a id="schema-Refund-Create-Request"></a>

#### Refund-Create-Request

**Refund Create Request**

The amount to refund from a paid payment

Type: `object`

- `amount` (integer; required; minimum 1; example `100`) — Amount to be refunded in cents. For a full amount, set it equal to the payment amount

<a id="schema-Refund-Details"></a>

#### Refund-Details

**Refund Details**

A refund issued against a payment

Type: `object`

- `id` (string; required; example `"3050123456"`) — Refund ID
- `state` ([Refund-State](#schema-Refund-State); required) — Refund state
- `amount` (integer; required; example `100`) — Refunded amount in cents
- `currency` ([Currency](#schema-Currency); required) — Refund currency
- `created_at` (string (date-time); required; example `"2025-12-10T10:30:00Z"`) — When the refund was requested
- `updated_at` (string | null (date-time); optional; example `"2025-12-10T10:35:00Z"`) — When the refund state last changed. Null until the state changes for the first time

<a id="schema-Refund-State"></a>

#### Refund-State

**Refund State**

Refund lifecycle state:
- `REQUESTED` - The refund was accepted and is being processed
- `SUCCESS` - The refund was settled
- `FAILED` - The refund could not be processed

Type: `string`

Values: `REQUESTED`, `SUCCESS`, `FAILED`

<a id="schema-Recurrence-Schedule"></a>

#### Recurrence-Schedule

**Recurrence Schedule**

How often an `AUTO` recurrence creates a payment

Type: `object`

- `period` (string; required; values: `DAY`, `WEEK`, `MONTH`; example `"MONTH"`) — Unit the cycle is counted in
- `cycle` (integer; required; minimum 1; example `1`) — Number of periods between two payments

Example:

```json
{
  "period": "MONTH",
  "cycle": 1
}
```

<a id="schema-Recurrence-Create-Request"></a>

#### Recurrence-Create-Request

**Recurrence Create Request**

One of the two recurrence kinds. The `type` field selects the case, taking values from the [Recurrence Type](#schema-Recurrence-Type) enum. An `AUTO` recurrence carries a `schedule`; an `ON_DEMAND` one must not, because the merchant asks for each further payment itself.

Type: `oneOf`

One of: [Recurrence-Create-Auto](#schema-Recurrence-Create-Auto), [Recurrence-Create-On-Demand](#schema-Recurrence-Create-On-Demand)

Discriminator: `type` (`AUTO` → [Recurrence-Create-Auto](#schema-Recurrence-Create-Auto), `ON_DEMAND` → [Recurrence-Create-On-Demand](#schema-Recurrence-Create-On-Demand))

<a id="schema-Recurrence-Create-Auto"></a>

#### Recurrence-Create-Auto

**Recurrence Create Auto**

The `AUTO` variant of the [Recurrence Create Request](#schema-Recurrence-Create-Request) union. GoPay creates the payments itself on the schedule, so `schedule` is required here.

Type: `object`

- `type` (string = `"AUTO"`; required; example `"AUTO"`) — Always `AUTO`
- `schedule` ([Recurrence-Schedule](#schema-Recurrence-Schedule); required) — How often the recurrence creates a payment
- `recurrence_date_to` (string (date); required; example `"2027-09-04"`) — Last day on which the recurrence may create a payment, as yyyy-MM-dd
- `payment` ([Payment-Create-Request](#schema-Payment-Create-Request); required) — Payment template every payment of this recurrence is created from

Example:

```json
{
  "type": "AUTO",
  "schedule": {
    "period": "MONTH",
    "cycle": 1
  },
  "recurrence_date_to": "2027-09-04",
  "payment": {
    "amount": 1500,
    "currency": "CZK",
    "order_number": "2025010199",
    "order_description": "Monthly subscription",
    "customer": {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "callback": {
      "notification_url": "https://example.com/notify",
      "return_url": "https://example.com/return"
    }
  }
}
```

<a id="schema-Recurrence-Create-On-Demand"></a>

#### Recurrence-Create-On-Demand

**Recurrence Create On Demand**

The `ON_DEMAND` variant of the [Recurrence Create Request](#schema-Recurrence-Create-Request) union. There is no schedule — the merchant asks for each further payment with the next operation — so `schedule` must not be sent.

Type: `object`

- `type` (string = `"ON_DEMAND"`; required; example `"ON_DEMAND"`) — Always `ON_DEMAND`
- `recurrence_date_to` (string (date); required; example `"2027-09-04"`) — Last day on which the recurrence may create a payment, as yyyy-MM-dd
- `payment` ([Payment-Create-Request](#schema-Payment-Create-Request); required) — Payment template every payment of this recurrence is created from

Example:

```json
{
  "type": "ON_DEMAND",
  "recurrence_date_to": "2027-09-04",
  "payment": {
    "amount": 1500,
    "currency": "CZK",
    "order_number": "2025010199",
    "order_description": "Monthly subscription",
    "customer": {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "callback": {
      "notification_url": "https://example.com/notify",
      "return_url": "https://example.com/return"
    }
  }
}
```

<a id="schema-Recurrence-Details"></a>

#### Recurrence-Details

**Recurrence Details**

State of a recurrence and the payment it last created

Type: `object`

- `id` (string; required; example `"8008013370"`) — Unique ID of the recurrence
- `type` ([Recurrence-Type](#schema-Recurrence-Type); required) — Whether payments are created on a schedule or only on request
- `state` ([Recurrence-State](#schema-Recurrence-State); required) — Current state of the recurrence
- `schedule` ([Recurrence-Schedule](#schema-Recurrence-Schedule); optional) — Present only for an `AUTO` recurrence
- `recurrence_date_to` (string (date); required; example `"2027-09-04"`) — Last day on which the recurrence may create a payment, as yyyy-MM-dd
- `stop_reason` ([Recurrence-Stop-Reason](#schema-Recurrence-Stop-Reason); optional) — Why the recurrence stopped — present only in state `STOPPED`
- `payment` ([Recurrence-Payment](#schema-Recurrence-Payment); required) — Payment the recurrence carries — the stored template until one is created

Example:

```json
{
  "id": "8008013370",
  "type": "ON_DEMAND",
  "state": "NEW",
  "recurrence_date_to": "2027-09-04",
  "payment": {
    "amount": 1500,
    "currency": "CZK",
    "order_number": "2025010199",
    "customer": {
      "email": "john.doe@example.com"
    }
  }
}
```

<a id="schema-Recurrence-Payment"></a>

#### Recurrence-Payment

**Recurrence Payment**

The payment the recurrence carries. Before the recurrence is started this is the stored template only; once a payment exists, `id`, `state`, `gw_url` and `payment_secret` are filled in as well.

Type: `object`

- `id` (string; optional; example `"7310142951"`) — Payment ID. Absent until the recurrence has created a payment
- `state` ([Payment-State](#schema-Payment-State); optional) — State of the created payment. Absent until the recurrence has created one
- `amount` (integer; required; minimum 0; example `1500`) — Total amount in cents
- `currency` ([Currency](#schema-Currency); required) — Payment currency
- `order_number` (string; required; max length 128; example `"2025010199"`) — Order identification for the online shop, alphanumeric characters
- `customer` ([Customer](#schema-Customer); required) — Information about the customer
- `gw_url` (string; optional; example `"https://gate.gopay.com/gw/123456789"`) — Address of GoPay's hosted payment gateway, where the customer pays the created payment. It cannot be embedded in the merchant's own checkout — see `Payment Details.gw_url`. Absent until the recurrence has created one
- `payment_secret` (string; optional; example `"ps_6aa48c5fadd5ca9ccbc2a30bb13d7e8e"`) — Secret the merchant's server passes to the GoPay client SDK, so that the SDK can act on the payment. Absent until the recurrence has created a payment. **Do not embed in URLs, log or store!**

Example:

```json
{
  "amount": 1500,
  "currency": "CZK",
  "order_number": "2025010199",
  "customer": {
    "email": "john.doe@example.com"
  }
}
```

<a id="schema-Recurrence-Type"></a>

#### Recurrence-Type

**Recurrence Type**

`AUTO` creates payments on the schedule, `ON_DEMAND` only when the merchant asks for the next payment.

Type: `string`

Values: `AUTO`, `ON_DEMAND`

<a id="schema-Recurrence-State"></a>

#### Recurrence-State

**Recurrence State**

`NEW` after creation, `REQUESTED` once the first payment was created and is waiting to be paid, `STARTED` once it was paid and further payments can be requested, `STOPPED` when the recurrence ended.

Type: `string`

Values: `NEW`, `REQUESTED`, `STARTED`, `STOPPED`

<a id="schema-Recurrence-Stop-Reason"></a>

#### Recurrence-Stop-Reason

**Recurrence Stop Reason**

Why a recurrence in state `STOPPED` ended.
- `RECURRENCE_EXPIRED` - `recurrence_date_to` passed
- `CARD_EXPIRED` - The authorised card expired
- `CANCELLED_VIA_API` - Stopped with `DELETE /recurrences/{rec_id}`
- `CANCELLED_VIA_BACKOFFICE` - Stopped by a GoPay operator on the merchant's behalf
- `CANCELLED_BY_GOPAY` - Stopped by GoPay
- `UNKNOWN` - The reason is not available

Type: `string`

Values: `RECURRENCE_EXPIRED`, `CARD_EXPIRED`, `CANCELLED_VIA_API`, `CANCELLED_VIA_BACKOFFICE`, `CANCELLED_BY_GOPAY`, `UNKNOWN`

<a id="schema-Customer-Override"></a>

#### Customer-Override

**Customer Override**

Customer fields to replace for a single payment. Unlike `Customer` no field is required — the recurrence's stored customer supplies whatever is omitted, merged field by field. Unknown fields are rejected.

Type: `object`

- `email` (string (email); optional; max length 128; example `"john.doe@example.com"`) — Customer email
- `first_name` (string; optional; max length 256; example `"John"`) — Customer first name
- `last_name` (string; optional; max length 256; example `"Doe"`) — Customer last name
- `phone_number` (string; optional; max length 128; example `"+420123456789"`) — Customer phone number (home or mobile)
- `city` (string; optional; max length 128; example `"Testington"`) — Customer address city
- `street` (string; optional; max length 128; example `"Example st. 10"`) — Customer address street
- `postal_code` (string; optional; max length 128; example `"10000"`) — Customer address ZIP (postal code)
- `country_code` (string; optional; max length 128; example `"CZE"`) — Customer country code according to [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
- `customer_id` (string; optional; max length 128; example `"customer420"`) — Unique customer ID (used to customise the checkout experience)

Example:

```json
{
  "first_name": "John",
  "last_name": "Doe"
}
```

<a id="schema-Payment-Instance-Override"></a>

#### Payment-Instance-Override

**Payment Instance Override**

Fields that replace the recurrence's stored payment template for a single payment. Omitted fields keep the stored value; `customer` is merged field by field rather than replaced. Unknown fields are rejected.

Type: `object`

- `amount` (integer; optional; minimum 0; example `9900`) — Total amount in cents
- `order_number` (string; optional; max length 128; example `"2025010199"`) — Order identification for the online shop, alphanumeric characters
- `order_description` (string; optional; example `"Test order"`) — Order description, alphanumeric characters
- `additional_params` (array of [Additional-Param](#schema-Additional-Param); optional; max items 4) — Additional parameters for the payment
- `customer` ([Customer-Override](#schema-Customer-Override); optional) — Customer fields to replace; omitted ones keep the stored value
- `callback` ([Payment-Callback](#schema-Payment-Callback); optional) — URLs for the return redirect and the notifications

Example:

```json
{
  "amount": 9900,
  "order_number": "2025010199",
  "order_description": "Test order",
  "customer": {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "callback": {
    "notification_url": "https://example.com/notify",
    "return_url": "https://example.com/return"
  }
}
```

<a id="schema-Link-Create-Request"></a>

#### Link-Create-Request

**Link Create Request**

The payment data a new payment link carries, its lifetime, and whether it may be used more than once

Type: `object`

- `payment` ([Payment-From-Link-Request](#schema-Payment-From-Link-Request); required) — Payment data used for every payment this link creates
- `expires_in` (integer; optional; minimum 1; example `3600`) — Link lifetime in seconds, counted from creation. Omit it for a link that never expires. The upper bound is a hundred years
- `reusable` (boolean; optional; default `true`; example `true`) — Whether the link may start more than one payment. A one-shot link is consumed by the first visit; see `Link Stop Reason`

<a id="schema-Link-Details"></a>

#### Link-Details

**Link Details**

A payment link, its state, and the payment data it carries

Type: `object`

- `id` (string; required; example `"3405871122"`) — Link ID, used on the status and disable calls. Not the code that appears in `url`
- `url` (string; required; example `"https://gate.gopay.com/gp-gw/l/Xk8mQ2pR7t"`) — Address to share with the customer. Opening it creates a payment and redirects the customer to the payment gateway. It ends in a random ten-character code unrelated to `id`
- `active` (boolean; required; example `true`) — Whether the link can still start a payment. Reported as false once the link expires, even before that is recorded
- `reusable` (boolean; required; example `true`) — Whether the link may start more than one payment
- `expires_at` (string (date-time); optional; example `"2026-08-18T14:35:12Z"`) — When the link stops being usable, computed at creation from `expires_in`. Absent for a link that never expires
- `stop_reason` ([Link-Stop-Reason](#schema-Link-Stop-Reason); optional) — Why the link is no longer active. Absent while the link is active
- `payment` ([Payment-From-Link-Request](#schema-Payment-From-Link-Request); optional) — Payment data the link carries

<a id="schema-Link-Stop-Reason"></a>

#### Link-Stop-Reason

**Link Stop Reason**

Why a payment link is no longer active:
- `FROM_API` - The merchant disabled the link
- `USED` - A one-shot link was opened and created its payment
- `EXPIRED` - The link passed its `expires_at`

Type: `string`

Values: `FROM_API`, `USED`, `EXPIRED`

<a id="schema-Payment-From-Link-Request"></a>

#### Payment-From-Link-Request

**Payment From Link Request**

Representation of a payment created from a payment link. The same data is used for every payment the link creates, so a reusable link gives all of them the same `order_number` and the same `notification_url`.

Type: `object`

- `amount` (integer; required; minimum 0; example `15000`) — Total amount in cents
- `currency` ([Currency](#schema-Currency); required) — Payment currency. It must be a currency the eshop has an enabled payment channel for, otherwise the link is rejected with `400`
- `order_number` (string; required; max length 128; example `"2026-00042"`) — Order identification for the online shop, alphanumeric characters
- `order_description` (string; optional; max length 256; example `"Invoice 2026-00042"`) — Order description, alphanumeric characters
- `additional_params` (array of [Additional-Param](#schema-Additional-Param); optional; max items 4) — Additional parameters for the payment. Each `name` must not contain `=`, and `name` and `value` together may not exceed 511 characters
- `customer` ([Customer](#schema-Customer); required) — Information about the customer. The email address is required
- `callback` ([Payment-Callback](#schema-Payment-Callback); required) — URLs for the return redirect and the notifications. Both must be http or https and at most 512 characters long

Example:

```json
{
  "amount": 15000,
  "currency": "CZK",
  "order_number": "2026-00042",
  "order_description": "Invoice 2026-00042",
  "additional_params": [
    {
      "name": "invoice",
      "value": "INV-2026-001"
    }
  ],
  "customer": {
    "email": "payer@example.com",
    "first_name": "Jan",
    "last_name": "Novák",
    "phone_number": "+420123456789",
    "city": "Praha",
    "street": "Testovací 42",
    "postal_code": "11000",
    "country_code": "CZE",
    "customer_id": "cust-001"
  },
  "callback": {
    "notification_url": "https://eshop.example.com/gopay/notify",
    "return_url": "https://eshop.example.com/gopay/return"
  }
}
```

<a id="schema-Validate-Merchant-Request"></a>

#### Validate-Merchant-Request

**Validate Merchant Request**

The Apple Pay merchant validation request

Type: `object`

- `validationUrl` (string (uri); required; example `"https://apple-pay-gateway.apple.com/paymentservices/paymentSession"`) — The validation URL Apple Pay issued for the session

<a id="schema-Validate-Merchant-Response"></a>

#### Validate-Merchant-Response

**Validate Merchant Response**

The merchant session object Apple Pay expects, passed to the Apple Pay sheet unchanged

Type: `object`

<a id="schema-Event"></a>

#### Event

One of the events GoPay records. The `type` field selects the case, taking values from the [Event Type](#schema-Event-Type) enum. A `type` the merchant's code does not recognise is ignored rather than treated as an error, so that a new type does not break a working integration.

Type: `oneOf`

One of: [Payment-Paid-Event](#schema-Payment-Paid-Event), [Payment-Canceled-Event](#schema-Payment-Canceled-Event), [Payment-Timeouted-Event](#schema-Payment-Timeouted-Event), [Link-Payment-Created-Event](#schema-Link-Payment-Created-Event), [Link-Disabled-Event](#schema-Link-Disabled-Event), [Refund-Succeeded-Event](#schema-Refund-Succeeded-Event), [Refund-Failed-Event](#schema-Refund-Failed-Event), [Recurrence-Started-Event](#schema-Recurrence-Started-Event), [Recurrence-Payment-Created-Event](#schema-Recurrence-Payment-Created-Event), [Recurrence-Stopped-Event](#schema-Recurrence-Stopped-Event), [Card-Updated-Event](#schema-Card-Updated-Event), [Card-Deleted-Event](#schema-Card-Deleted-Event)

Discriminator: `type` (`payments.paid` → [Payment-Paid-Event](#schema-Payment-Paid-Event), `payments.canceled` → [Payment-Canceled-Event](#schema-Payment-Canceled-Event), `payments.timeouted` → [Payment-Timeouted-Event](#schema-Payment-Timeouted-Event), `links.payment_created` → [Link-Payment-Created-Event](#schema-Link-Payment-Created-Event), `links.disabled` → [Link-Disabled-Event](#schema-Link-Disabled-Event), `refunds.succeeded` → [Refund-Succeeded-Event](#schema-Refund-Succeeded-Event), `refunds.failed` → [Refund-Failed-Event](#schema-Refund-Failed-Event), `recurrences.started` → [Recurrence-Started-Event](#schema-Recurrence-Started-Event), `recurrences.payment_created` → [Recurrence-Payment-Created-Event](#schema-Recurrence-Payment-Created-Event), `recurrences.stopped` → [Recurrence-Stopped-Event](#schema-Recurrence-Stopped-Event), `cards.updated` → [Card-Updated-Event](#schema-Card-Updated-Event), `cards.deleted` → [Card-Deleted-Event](#schema-Card-Deleted-Event))

Example:

```json
{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "type": "payments.paid",
  "occurred_at": "2026-07-08T12:04:39.123Z",
  "data": {
    "payment_id": "300000001",
    "charge_id": "9123456789"
  }
}
```

<a id="schema-Event-Type"></a>

#### Event-Type

**Event Type**

The values of the field that selects the case of [Event](#schema-Event)

Type: `string`

Values: `payments.paid`, `payments.canceled`, `payments.timeouted`, `links.payment_created`, `links.disabled`, `refunds.succeeded`, `refunds.failed`, `recurrences.started`, `recurrences.payment_created`, `recurrences.stopped`, `cards.updated`, `cards.deleted`

<a id="schema-Payment-Paid-Event"></a>

#### Payment-Paid-Event

**Payment Paid Event**

The `payments.paid` variant of the [Event](#schema-Event) union. The payment reached `PAID`.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `payments.paid`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Payment-Paid-Data](#schema-Payment-Paid-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Payment-Canceled-Event"></a>

#### Payment-Canceled-Event

**Payment Canceled Event**

The `payments.canceled` variant of the [Event](#schema-Event) union. The payment reached `CANCELED`: the customer abandoned it, the charge was rejected at authorisation, or the merchant canceled it before it was charged.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `payments.canceled`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Payment-Event-Data](#schema-Payment-Event-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Payment-Timeouted-Event"></a>

#### Payment-Timeouted-Event

**Payment Timeouted Event**

The `payments.timeouted` variant of the [Event](#schema-Event) union. The payment did not reach a terminal outcome within its timeout.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `payments.timeouted`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Payment-Event-Data](#schema-Payment-Event-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Link-Payment-Created-Event"></a>

#### Link-Payment-Created-Event

**Link Payment Created Event**

The `links.payment_created` variant of the [Event](#schema-Event) union. A customer opened a payment link and a payment was created from it.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `links.payment_created`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Link-Payment-Created-Data](#schema-Link-Payment-Created-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Link-Disabled-Event"></a>

#### Link-Disabled-Event

**Link Disabled Event**

The `links.disabled` variant of the [Event](#schema-Event) union. The merchant deactivated a payment link.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `links.disabled`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Link-Event-Data](#schema-Link-Event-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Refund-Succeeded-Event"></a>

#### Refund-Succeeded-Event

**Refund Succeeded Event**

The `refunds.succeeded` variant of the [Event](#schema-Event) union. A refund settled.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `refunds.succeeded`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Refund-Event-Data](#schema-Refund-Event-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Refund-Failed-Event"></a>

#### Refund-Failed-Event

**Refund Failed Event**

The `refunds.failed` variant of the [Event](#schema-Event) union. A refund could not be settled.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `refunds.failed`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Refund-Event-Data](#schema-Refund-Event-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Recurrence-Started-Event"></a>

#### Recurrence-Started-Event

**Recurrence Started Event**

The `recurrences.started` variant of the [Event](#schema-Event) union. A recurrence was activated by the payment named in `data`.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `recurrences.started`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Recurrence-Payment-Data](#schema-Recurrence-Payment-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Recurrence-Payment-Created-Event"></a>

#### Recurrence-Payment-Created-Event

**Recurrence Payment Created Event**

The `recurrences.payment_created` variant of the [Event](#schema-Event) union. A scheduled payment was created from a recurrence.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `recurrences.payment_created`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Recurrence-Payment-Data](#schema-Recurrence-Payment-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Recurrence-Stopped-Event"></a>

#### Recurrence-Stopped-Event

**Recurrence Stopped Event**

The `recurrences.stopped` variant of the [Event](#schema-Event) union. A recurrence was stopped.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `recurrences.stopped`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Recurrence-Event-Data](#schema-Recurrence-Event-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Card-Updated-Event"></a>

#### Card-Updated-Event

**Card Updated Event**

The `cards.updated` variant of the [Event](#schema-Event) union. A saved card token changed in place, for instance after the issuer reissued the card.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `cards.updated`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Card-Event-Data](#schema-Card-Event-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Card-Deleted-Event"></a>

#### Card-Deleted-Event

**Card Deleted Event**

The `cards.deleted` variant of the [Event](#schema-Event) union. A saved card token was deleted.

Type: `object`

- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `cards.deleted`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Card-Event-Data](#schema-Card-Event-Data); required) — Identifiers of the entities the event concerns

<a id="schema-Payment-Paid-Data"></a>

#### Payment-Paid-Data

**Payment Paid Data**

Identifies the payment and, if a charge paid it, the charge.

Type: `object`

- `payment_id` (string; required; example `"300000001"`) — Identifier of the payment
- `charge_id` (string; optional; example `"9123456789"`) — Identifier of the charge that paid the payment. Absent when no charge paid it, for instance on the hosted gateway at `gw_url`

<a id="schema-Payment-Event-Data"></a>

#### Payment-Event-Data

**Payment Event Data**

Identifies the payment the event concerns.

Type: `object`

- `payment_id` (string; required; example `"300000001"`) — Identifier of the payment

<a id="schema-Link-Payment-Created-Data"></a>

#### Link-Payment-Created-Data

**Link Payment Created Data**

Identifies the payment link and the payment created from it.

Type: `object`

- `link_id` (string; required; example `"346346346"`) — Identifier of the payment link
- `payment_id` (string; required; example `"300000001"`) — Identifier of the payment

<a id="schema-Link-Event-Data"></a>

#### Link-Event-Data

**Link Event Data**

Identifies the payment link the event concerns.

Type: `object`

- `link_id` (string; required; example `"346346346"`) — Identifier of the payment link

<a id="schema-Refund-Event-Data"></a>

#### Refund-Event-Data

**Refund Event Data**

Identifies the refund and the payment it belongs to.

Type: `object`

- `payment_id` (string; required; example `"300000001"`) — Identifier of the payment
- `refund_id` (string; required; example `"3050123456"`) — Identifier of the refund

<a id="schema-Recurrence-Payment-Data"></a>

#### Recurrence-Payment-Data

**Recurrence Payment Data**

Identifies the recurrence and the payment the event concerns. For `recurrences.started` the payment is the one that started the recurrence; for `recurrences.payment_created` it is the newly created payment.

Type: `object`

- `recurrence_id` (string; required; example `"5521002"`) — Identifier of the recurrence
- `payment_id` (string; required; example `"300000001"`) — Identifier of the payment

<a id="schema-Recurrence-Event-Data"></a>

#### Recurrence-Event-Data

**Recurrence Event Data**

Identifies the recurrence the event concerns.

Type: `object`

- `recurrence_id` (string; required; example `"5521002"`) — Identifier of the recurrence

<a id="schema-Card-Event-Data"></a>

#### Card-Event-Data

**Card Event Data**

Identifies the saved card token the event concerns. Card tokens belong to the merchant and are shared across the merchant's eshops.

Type: `object`

- `card_id` (string; required; example `"8007127320"`) — Identifier of the saved card token

<a id="schema-Event-List"></a>

#### Event-List

**Event List**

One page of events of an eshop, newest first

Type: `object`

- `items` (array of [Event](#schema-Event); required) — The events in this page
- `next_page_url` (string (uri); optional; example `"https://gate.gopay.com/gp-gw/api/4.0/eshops/8123456789/events?type=refunds.*&max_items=20&prev_item=01H8ZQ7X9K4Q0M2V6T8B3C5D7E"`) — The full address of the next page, carrying the filters of the request and the `id` of
  the last event of this page as the position to continue from. Absent when no further
  matching event exists.

<a id="schema-JWK-Set"></a>

#### JWK-Set

**JWK Set**

A set of public keys holding the webhook signing keys currently in use. It is formatted according to RFC 7517: JSON Web Key Set (JWK Set)

Type: `object`

- `keys` (array of [Signing-JWK](#schema-Signing-JWK); required) — The webhook signing keys currently in use

<a id="schema-Signing-JWK"></a>

#### Signing-JWK

**Signing JWK**

The structure of a public webhook signing key. It is formatted according to RFC 7517: JSON Web Key (JWK)

Type: `object`

- `kty` (string = `"RSA"`; required; example `"RSA"`) — Key type. Always `RSA` for the signing keys used by GoPay.
- `use` (string = `"sig"`; required; example `"sig"`) — Key usage. Always `sig` (signature).
- `kid` (string; required; example `"sign-2026-02"`) — Key ID. Matches the `kid` of the protected header of the `X-GoPay-Signature` the key verifies
- `alg` (string = `"RS256"`; required; example `"RS256"`) — Algorithm the signature was produced with. Always `RS256`.
- `n` (string; required; example `"4JHqz4QwbiVuVzLhjJwwgK_EC86qVTPhQIpmiQCoGNzLBQlsBdt13Y10AlzRSMMF65LyF5Y8doKR-gJlCR9J5P9YPr1IgU0wVyqJ349yL7O_lMWy5TfWdGz7KOrq9tyHVtjH0i5ztAIQHPvQ02LayjdNgUA4Z8RxFsSz03nCU-dJLJOg63BS23VfxEs4J_kmbITSACIxiIAerc-wUwIQkjlHyHQQtac7kcCQfSqDB3F2YqxFkWOC66drt2zcMutjxcK-ZcnjdBiQnTI_9izbJB9mX4CoErMWre7GNt_krHoi6OP6DoOvjEsABAS2Dyf13xLuNVH-QHpCUaYqR70OTQ"`) — The `RSA` public key modulus part.
- `e` (string; required; default `"AQAB"`; example `"AQAB"`) — The `RSA` public key exponent part.

Example:

```json
{
  "kty": "RSA",
  "use": "sig",
  "kid": "sign-2026-02",
  "alg": "RS256",
  "n": "4JHqz4QwbiVuVzLhjJwwgK_EC86qVTPhQIpmiQCoGNzLBQlsBdt13Y10AlzRSMMF65LyF5Y8doKR-gJlCR9J5P9YPr1IgU0wVyqJ349yL7O_lMWy5TfWdGz7KOrq9tyHVtjH0i5ztAIQHPvQ02LayjdNgUA4Z8RxFsSz03nCU-dJLJOg63BS23VfxEs4J_kmbITSACIxiIAerc-wUwIQkjlHyHQQtac7kcCQfSqDB3F2YqxFkWOC66drt2zcMutjxcK-ZcnjdBiQnTI_9izbJB9mX4CoErMWre7GNt_krHoi6OP6DoOvjEsABAS2Dyf13xLuNVH-QHpCUaYqR70OTQ",
  "e": "AQAB"
}
```