# Přehled

GoPay Payments API v4 je HTTP rozhraní pro přijímání plateb prostřednictvím GoPay. Stránky v této sekci vysvětlují, jak jednotlivé operace navazují na sebe. OpenAPI reference dokumentuje každý tvar požadavku a odpovědi.

## Aktéři

Při integraci si vyměňují data čtyři strany. Následující stránky na ně odkazují těmito názvy.

- **Server obchodníka.** Backend obchodníka. Uchovává dlouhodobé přihlašovací údaje obchodníka a provádí vše, co musí být autentizováno jako obchodník.
- **Klient obchodníka.** Webový frontend nebo mobilní aplikace obchodníka. Při operacích na konkrétní platbu obdrží od serveru obchodníka přihlašovací údaje platby.
- **GoPay klientský SDK.** Zahrnutý v klientovi obchodníka. Vykresluje platební formulář, zpracovává Apple Pay a Google Pay, zajišťuje, aby data držitele karty nezůstala v kódu obchodníka, a za obchodníka provádí volání API na straně klienta. Distribuován jako balíčky pro TypeScript, Swift a Kotlin.
- **GoPay API.** Dostupné na `https://gate.gopay.com/gp-gw/api/4.0` v produkci a `https://gw.sandbox.gopay.com/gp-gw/api/4.0` v sandboxu.

Přihlašovací údaje, toky OAuth 2.0, scopy a envelope pro data karty jsou popsány na stránce bezpečnosti.

## Verze API

Segment verze v základní URL — `4.0` — určuje REST kontrakt. Není to verze této dokumentace ani žádného GoPay SDK a neřídí se semver: posouvá se o minorní bod, `4.0` → `4.1`, a to pouze tehdy, když by změna rozbila existující integrace. Změna, která nic nerozbíjí, se přidává do stávající verze, takže obchodníkovi, který ji ignoruje, integrace dál funguje.

Po vydání nové verze běží obě verze současně po přechodné období. Předchozí verze je na konci tohoto období označena za zastaralou, s koncovým datem oznámeným předem. Obchodníci přecházejí na novou základní URL kdykoliv v jeho průběhu a v den vydání nové verze není potřeba měnit nic.

## Tvary integrace

Jsou podporovány dva tvary integrace. Každý odpovídá jinému způsobu, jakým zákazník interaguje s GoPay při placení. Názvy jsou historické.

**Checkout.** Obchodník vlastní UI pokladny. GoPay klientský SDK shromažďuje data karty, zpracovává peněženky a ve výchozím nastavení platbu strhne a dovede ji do konečného stavu. Alternativně platbu strhne server obchodníka se zašifrovanou kartou, kterou SDK vrátí. Obchodník má pod kontrolou vzhled pokladny včetně stylu platebního formuláře. Na rozdíl od Přesměrování nenačítá prohlížeč zákazníka hostovanou bránu GoPay, ale jen SDK a to, co vyžadují platební metody na stránce obchodníka. Viz stránka checkout integrace.

**Přesměrování.** Zákazník je odeslán na hostované UX od GoPay na adrese `Payment Details.gw_url` — hostovaná platební brána GoPay, která nabídne všechny platební metody povolené pro daný eshop. Je to cíl, kam se zákazník odešle, a nejde ji zaintegrovat do vlastního checkoutu obchodníka. Server obchodníka vytvoří platbu; GoPay vede zbytek. Výsledek je doručen webhookem a lze ho také získat dotazováním na platbu; platba zůstává plně pozorovatelná přes v4 po celou dobu. Klient obchodníka nepotřebuje GoPay SDK. Viz stránka hostovaných integrací.

Obchodníci by neměli na jedné platbě kombinovat různé tvary integrace — výsledné toky jsou obtížně laditelné. Dokumentovanou výjimkou je kombinace QR platby s kartou nebo peněženkou na téže platbě, popsaná na stránce QR platby.

Oblasti sdílené napříč tvary — životní cyklus platby, uložené karty, peněženky, vrácení plateb, opakované platby, platební odkazy, události a webhooky, chyby — mají vlastní stránky a jsou z každé stránky tvaru odkazovány.

## Požadavky na web

Vývoj i produkce musí běžet na hostname přes HTTPS. Samotná IP adresa nestačí a `localhost` ji nenahradí — odmítne ho především Apple Pay.

Pro lokální vývoj postačí self-signed certifikát a záznam v hosts souboru na všechno, čeho se dotkne prohlížeč zákazníka — `return_url`, kam je zákazník přesměrován, a stránku, na které běží Apple Pay. Nasměrujte jméno jako `dev.example.com` na `127.0.0.1` v hosts souboru, servírujte web přes HTTPS s lokálně důvěryhodným certifikátem a toto jméno nahlaste GoPay pro testování Apple Pay. Některé části na straně prohlížeče proti `https://localhost` fungují, ale jméno z hosts souboru vyhoví i Apple Pay, takže se vyplatí nastavit ho jednou provždy.

Výjimkou je `notification_url`. Notifikaci doručují servery GoPay, takže musí jít o HTTPS endpoint, na který dosáhnou — alias v hosts souboru mířící na `127.0.0.1` existuje jen na stroji vývojáře. Pro cokoliv, co má přijímat notifikace nebo webhooky, použijte tunel na lokální stroj nebo nasazené prostředí.

Sandbox je tolerantnější než produkce, takže úspěšně vytvořená platba v sandboxu není důkazem, že stejný požadavek projde i na produkci, kde je `return_url` bez HTTPS odmítnuto stavem `403`. Tato kontrola se týká pouze schématu — její splnění nezbavuje integraci požadavku na hostname výše. Apple Pay je přísnější než samotné API. I v sandboxu potřebuje hostname přes HTTPS, které obchodník nahlásil GoPay — viz stránka Zprovoznění Apple Pay.

Stránka pokladny, která posílá Content-Security-Policy, musí povolit hostitele GoPay a hostitele peněženek. Seznam je na stránce checkout integrace.

## Klientské SDK

GoPay klientský SDK je publikován jako tři balíčky.

- TypeScript (prohlížeč) — `@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` nebo CocoaPods `pod 'GopaySDK'`
- Kotlin — [`cz.gopay:sdk`](https://github.com/gopaycommunity/gopay-android-sdk) · Maven Central `implementation("cz.gopay:sdk:<version>")`

Checkout postavený na balíčku pro prohlížeč funguje i v mobilních prohlížečích. Balíčky pro Swift a Kotlin jsou určené pro nativní mobilní aplikace, takže obchodník bez nativní aplikace je nepotřebuje. Balíček pro Swift vyžaduje iOS 13 nebo novější a balíček pro Kotlin vyžaduje Android 7.0 (API level 24) nebo novější.

Každý balíček vykresluje platební formulář, strhává platbu, obsluhuje krok 3-D Secure a čte platbu a její QR kód. Apple Pay je k dispozici v balíčcích pro prohlížeč a Swift, Google Pay v balíčcích pro prohlížeč a Kotlin. Příklady pro jednotlivé jazyky jsou na stránce checkout integrace a na stránkách uložených karet, Apple Pay a Google Pay.

## Serverové knihovny

GoPay publikuje serverové knihovny pro PHP a 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`

Knihovna pro PHP vyžaduje PHP 8.1 nebo novější a funguje s jakýmkoli HTTP klientem podle PSR-18, například s Guzzle.

Pro ostatní jazyky lze serverovou knihovnu vygenerovat z OpenAPI specifikace pomocí [OpenAPI Generator](https://openapi-generator.tech/). Vygenerovaný klient přesně zrcadlí specifikaci a je regenerován vždy, když se specifikace změní.

Níže uvedené příklady generují klientské knihovny pro Python, C# a Java pomocí Docker obrazu OpenAPI Generatoru. Generátorové volby lze upravit z dokumentace konkrétního generátoru odkazované v každé sekci.

### Python

Kompletní sadu voleb najdete v [dokumentaci Python generátoru](https://openapi-generator.tech/docs/generators/python/).

```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\#

Kompletní sadu voleb najdete v [dokumentaci C# generátoru](https://openapi-generator.tech/docs/generators/csharp/).

```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

Kompletní sadu voleb najdete v [dokumentaci Java generátoru](https://openapi-generator.tech/docs/generators/java/).

```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"
```

Výstupní adresář obsahuje vygenerovaný `README.md` popisující, jak výsledného klienta používat.

## Provozní kontakt

Některá nastavení na straně GoPay nejsou přístupná přes API a mění se e-mailem na `integrace@gopay.cz`. Nejčastější jsou: registrace Apple Pay domény, odeslání identifikátoru obchodníka Google Pay, úpravy omezení `ON_DEMAND` opakování, výchozí timeout platby na eshop, notifikační koncový bod a události, které e-shop dostává, provisionování sandboxu a povolení tokenizace. Každá stránka tématu se na toto místo zpětně odkazuje.

## Slovník

- `goid` — identifikátor eshopu v rámci účtu obchodníka, přenášený v cestách `/eshops/{goid}/…`.
- `payment_secret` — přihlašovací údaj pro jednu platbu, vrácený v `Payment Details`, který server obchodníka předá GoPay klientskému SDK. Viz stránka bezpečnosti.
- `shareable_key` — klientský klíč spárovaný s `client_id` a nastavený v GoPay klientském SDK. Je bezpečné ho vložit do sestavení pro klienty.
- JWE — obálka JSON Web Encryption, ve které GoPay klientský SDK nese zašifrovanou kartu. Je jednorázová a platná deset minut.
- token karty — trvalý token, který zastupuje uloženou kartu a strhává se jako vstup `CARD_TOKEN`. Viz stránka Uložené karty.
- síťový token — token vydaný karetní společností místo čísla karty. Jeho maskovaná podoba je `masked_virtual_pan` u uložené karty.
- `fingerprint` — hodnota u uložené karty, která zůstává stejná napříč tokenizacemi téže fyzické karty.
- platební prostředek — prostředek, kterým se platba vypořádá, předávaný v `payment_instrument` v požadavku na stržení. Dnes je to vždy platební karta.
- PCI DSS SAQ-A / SAQ-D — úrovně sebehodnocení karetního průmyslu, které platí, když data karty shromažďuje GoPay klientský SDK (SAQ-A), nebo když je shromažďuje vlastní kód obchodníka (SAQ-D). Viz stránka bezpečnosti.