# 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 — Apple Pay above all rejects 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 page Apple Pay runs on. 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 report that name to GoPay for Apple Pay testing. 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. Even in the sandbox, it needs a hostname over HTTPS that the merchant has reported to GoPay — see the Setting up 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. 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.
