# Referenční dokumentace — Platby v4.0
**Vytvářet a spravovat platby**
REST API pro vytváření a správu plateb GoPay: založení platby, její stržení platebním prostředkem, sledování až do koncového stavu a správu tokenů uložených karet. Podrobné integrační postupy jsou publikované společně s touto referencí.
## Servery
- `https://gw.sandbox.gopay.com/gp-gw/api/4.0` — Sandbox
- `https://gate.gopay.com/gp-gw/api/4.0` — Produkce
## Bezpečnostní schémata
- `basic` (http; basic) — Slouží jen k získání JWT na `POST /oauth2/token`.
- Server obchodníka používá `client_id:client_secret`
- Klientské SDK GoPay používá `payment_id:payment_secret`
Schéma popisuje [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617).
- `merchant_credentials` (oauth2) — Autorizuje server obchodníka pomocí `client_id:client_secret`.
Tajný klíč ani JWT nesmí nikdy opustit server obchodníka.
- `payment_credentials` (oauth2) — Autorizuje klienta pro operace s konkrétní platbou pomocí `payment_id:payment_secret`.
Tyto údaje a JWT používá klientské SDK GoPay ve webové nebo mobilní aplikaci obchodníka.
Klient předá `payment_id:payment_secret` jako HTTP Basic na `POST /oauth2/token` s `grant_type=payment_credentials` a vyžádá `payment:read`, `payment:charge` nebo oba. Vrácený JWT je vázaný na platbu a platí patnáct minut. Výměnu lze opakovat a získat tak nový JWT; `payment_secret` neexpiruje a operace, kterou stav platby už nepovoluje, je odmítnuta, většinou stavem `409`.
- `shareable_key` (http; basic) — `client_id:shareable_key` zakódované v base64 v hlavičce Authorization. `shareable_key` se nastavuje v klientském SDK GoPay.
Slouží k autentizaci na endpointech s veřejnými zdroji, jako jsou veřejné klíče a URL, a s hodnotami odvozenými ze samotného requestu.
Schéma popisuje [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617).
## Operace
### Autentizace
Výměna přihlašovacích údajů obchodníka a údajů konkrétní platby za přístupové tokeny, kterými se autorizují všechna ostatní volání.
#### Přihlášení
`POST /oauth2/token` · ID operace: `post-oauth2-token`
Vyžaduje: `basic`
Vymění přihlašovací údaje za přístupový token.
Server obchodníka posílá `client_id:client_secret` s grantem `client_credentials`, klientské SDK GoPay posílá `payment_id:payment_secret` s grantem `payment_credentials` a získá token svázaný s konkrétní platbou. Údaje se předávají jako HTTP Basic a je nutné požádat alespoň o jeden scope. Vrácený `access_token` je JWT s platností patnáct minut a posílá se jako Bearer token při voláních, která se jím autentizují; endpointy se `shareable_key` místo toho používají HTTP Basic a k žádné výměně tokenu u nich nedochází.
**Tělo požadavku** (povinné)
`application/x-www-form-urlencoded`: [Client-Credentials-Request](#schema-Client-Credentials-Request) | [Payment-Credentials-Request](#schema-Payment-Credentials-Request)
Příklad — Client Credentials:
```json
{
"grant_type": "client_credentials",
"scope": "payment:write payment:read"
}
```
**Odpovědi**
- `200` Přístupový token — [Access-Token](#schema-Access-Token)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
### Platby
Založení platby, její stržení platebním prostředkem a sledování až do koncového stavu.
#### Vytvoření platby
`POST /eshops/{goid}/payments` · ID operace: `post-eshops-goid-payments`
Vyžaduje: `merchant_credentials` (scopes: `payment:write`)
Založí platbu pro daný e-shop.
Odpověď obsahuje `id` platby, klientský údaj `payment_secret` platný pro tuto platbu a `gw_url` — adresu hostované platební brány GoPay, která zákazníkovi nabídne všechny platební metody povolené pro daný eshop, ale nejde zaintegrovat do vlastního checkoutu obchodníka. Nová platba je ve stavu `CREATED` a čeká na pokus o stržení; pokud k němu nedojde před vypršením úvodního timeoutu, přejde do stavu `TIMEOUTED`.
**Parametry**
- `goid` (string; path; povinné) — Jedinečný identifikátor registrovaného webu obchodníka
**Tělo požadavku** (nepovinné)
`application/json`: [Payment-Create-Request](#schema-Payment-Create-Request)
**Odpovědi**
- `201` Nová platba — [Payment-Details](#schema-Payment-Details)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Stav platby
`GET /payments/{payment_id}` · ID operace: `get-payments-payment_id`
Vyžaduje: `merchant_credentials` (scopes: `payment:read`) nebo `payment_credentials` (scopes: `payment:read`)
Vrátí aktuální stav platby.
Volá se po notifikaci webhookem nebo po přesměrování na návratovou URL, protože obojí nese pouze `id` platby. Pole `state` sleduje životní cyklus platby od stavu `CREATED` až po koncový stav.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
**Odpovědi**
- `200` Platba — [Payment-Details](#schema-Payment-Details)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Zrušení platby
`DELETE /payments/{payment_id}` · ID operace: `delete-payments-payment_id`
Vyžaduje: `merchant_credentials` (scopes: `payment:write`)
Zruší platbu, která ještě nebyla stržena.
Platba přejde do stavu `CANCELED` a zůstává čitelná; není smazána. Zrušit lze pouze platbu ve stavu `CREATED`; jakýkoli jiný stav vrátí `409`. Operace je pouze serverová.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
**Odpovědi**
- `204` Hotovo; odpověď nemá tělo
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Stav stržení platby
`GET /payments/{payment_id}/charge` · ID operace: `get-payments-payment_id-charge`
Vyžaduje: `merchant_credentials` (scopes: `payment:read`) nebo `payment_credentials` (scopes: `payment:read`)
Vrátí aktuální stav stržení platby.
Dotazuje se opakovaně v průběhu stržení, doporučeně jednou za sekundu, dokud stav nedosáhne hodnoty `SUCCEEDED`, `FAILED` nebo `ACTION_REQUIRED`. U stavu `ACTION_REQUIRED` nese odpověď pole `action` popisující krok, který musí zákazník dokončit; jakmile jej dokončí, dotazování pokračuje, dokud stržení nedosáhne stavu `SUCCEEDED` nebo `FAILED`. Pokud stržení selže, důvod je v poli `fail_reason`.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
**Odpovědi**
- `200` Aktuální stav stržení platby — [Payment-Charge-Status-Response](#schema-Payment-Charge-Status-Response)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Stržení platby
`POST /payments/{payment_id}/charge` · ID operace: `post-payments-payment_id-charge`
Vyžaduje: `merchant_credentials` (scopes: `payment:write`) nebo `payment_credentials` (scopes: `payment:charge`)
Pokusí se strhnout platbu zvoleným platebním prostředkem.
Přes tento endpoint se strhávají pouze karetní platby — `payment_instrument` je vždy `PAYMENT_CARD` a typ karetního vstupu vnořeného pod ním je jeden z `ENCRYPTED_CARD`, `CARD_TOKEN`, `APPLE_PAY` nebo `GOOGLE_PAY`. Ostatní platební metody jsou dostupné jen přes hostovanou bránu. Stržení je asynchronní; stav `ACTION_REQUIRED` znamená, že zákazník musí dokončit externí krok, než stržení skončí.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
**Tělo požadavku** (nepovinné)
`application/json`: [Payment-Charge-Input](#schema-Payment-Charge-Input)
**Odpovědi**
- `201` Zahájené stržení — [Payment-Charge-Response](#schema-Payment-Charge-Response)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Informace o QR platbě
`GET /payments/{payment_id}/qr-payment/info` · ID operace: `get-payments-payment_id-qr-payment-info`
Vyžaduje: `merchant_credentials` (scopes: `payment:read`) nebo `payment_credentials` (scopes: `payment:read`)
Vrátí podklady pro zobrazení QR kódu, kterým zákazník uhradí platbu bankovním převodem.
Odpověď obsahuje částku, bankovní účet příjemce a vygenerovaný obrázek jako base64 řetězec v regionálním formátu odpovídajícím měně platby a zemi příjemce. Vyžádání QR kódu prodlouží úvodní timeout platby na čtyři dny a stav platby nemění.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
- `format` (string; query; nepovinné; hodnoty: `png`, `svg`; výchozí `"png"`) — Obrazový formát generovaného QR kódu
**Odpovědi**
- `200` Údaje QR platby pro tuto platbu — [QR-Payment-Details](#schema-QR-Payment-Details)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
### Vrácení plateb
Vrácení prostředků ze zaplacené platby zákazníkovi a přehled vrácení, která k dané platbě patří.
#### Seznam vrácení platby
`GET /payments/{payment_id}/refunds` · ID operace: `get-payments-payment_id-refunds`
Vyžaduje: `merchant_credentials` (scopes: `payment:read`) nebo `payment_credentials` (scopes: `payment:read`)
Vrátí všechna vrácení provedená k dané platbě.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
**Odpovědi**
- `200` Vrácení platby — array of [Refund-Details](#schema-Refund-Details)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Vrácení platby
`POST /payments/{payment_id}/refunds` · ID operace: `post-payments-payment_id-refunds`
Vyžaduje: `merchant_credentials` (scopes: `payment:write`)
Vrátí zaplacenou platbu celou, nebo její část. Pro plné vrácení nastavte `amount` na
výši platby, pro částečné vrácení na nižší hodnotu. Platbu lze vracet opakovaně,
dokud součet vrácení nedosáhne původní částky.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
**Tělo požadavku** (povinné)
`application/json`: [Refund-Create-Request](#schema-Refund-Create-Request)
**Odpovědi**
- `201` Nové vrácení — [Refund-Details](#schema-Refund-Details)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Detail vrácení
`GET /refunds/{refund_id}` · ID operace: `get-refunds-refund_id`
Vyžaduje: `merchant_credentials` (scopes: `payment:read`)
Vrátí aktuální stav a částku jednoho vrácení.
**Parametry**
- `refund_id` (string; path; povinné) — Identifikátor vrácení
**Odpovědi**
- `200` Vrácení — [Refund-Details](#schema-Refund-Details)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
### Platební odkazy
Platební odkazy, které nesou údaje platby a zakládají ji teprve ve chvíli, kdy je zákazník otevře.
#### Vytvoření platebního odkazu
`POST /eshops/{goid}/links` · ID operace: `post-eshops-goid-links`
Vyžaduje: `merchant_credentials` (scopes: `payment:write`)
Vytvoří platební odkaz pro daný eshop. Odkaz si pouze uloží údaje platby — platba vznikne teprve tím, že zákazník odkaz otevře.
Odpověď nese `id`, které se používá při dotazu na stav a při zneplatnění, a `url`, tedy adresu ke sdílení se zákazníkem. Jde o dva různé identifikátory: `url` končí náhodným desetiznakovým kódem, který se z `id` nedá odvodit, ani naopak.
**Parametry**
- `goid` (string; path; povinné) — Jedinečný identifikátor registrovaného webu obchodníka
**Tělo požadavku** (povinné)
`application/json`: [Link-Create-Request](#schema-Link-Create-Request)
**Odpovědi**
- `201` Nový platební odkaz — [Link-Details](#schema-Link-Details)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Stav platebního odkazu
`GET /eshops/{goid}/links/{link_id}` · ID operace: `get-eshops-goid-links-link_id`
Vyžaduje: `merchant_credentials` (scopes: `payment:read`)
Vrátí aktuální nastavení a stav platebního odkazu včetně údajů platby, které nese.
Expirace se vyhodnocuje až při čtení: odkaz po svém `expires_at` se vrátí jako `active: false` se `stop_reason` `EXPIRED`, aniž by se předtím cokoli zapsalo.
**Parametry**
- `goid` (string; path; povinné) — Jedinečný identifikátor registrovaného webu obchodníka
- `link_id` (string; path; povinné; vzor `^[0-9]+$`) — ID odkazu vrácené při jeho vytvoření. Nečíselná nebo záporná hodnota je odmítnuta s `400`
**Odpovědi**
- `200` Platební odkaz — [Link-Details](#schema-Link-Details)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Zneplatnění odkazu
`DELETE /eshops/{goid}/links/{link_id}` · ID operace: `delete-eshops-goid-links-link_id`
Vyžaduje: `merchant_credentials` (scopes: `payment:write`)
Zneaktivní platební odkaz tak, aby jím už nešlo založit novou platbu. Nejde o smazání: odkaz lze dál dotázat a hlásí `stop_reason` `FROM_API`.
Zneplatnění odkazu, který už aktivní není, vrací `409`. Jednorázový odkaz, který už byl použit, je také neaktivní, takže ho zneplatnit nelze — dál přesměrovává na platbu, kterou vytvořil. Tu je potřeba zrušit samostatně.
**Parametry**
- `goid` (string; path; povinné) — Jedinečný identifikátor registrovaného webu obchodníka
- `link_id` (string; path; povinné; vzor `^[0-9]+$`) — ID odkazu vrácené při jeho vytvoření. Nečíselná nebo záporná hodnota je odmítnuta s `400`
**Odpovědi**
- `204` Hotovo; odpověď nemá tělo
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
### Opakované platby
Opakované platby, které drží šablonu platby a zakládají z ní platby buď podle rozvrhu, nebo když si obchodník o další řekne.
#### Založení opakované platby
`POST /eshops/{goid}/recurrences` · ID operace: `post-eshops-goid-recurrences`
Vyžaduje: `merchant_credentials` (scopes: `payment:write`)
Zaregistruje opakovanou platbu pro daný eshop a vrátí ji ve stavu `NEW`. Opakovaná platba si zatím jen uloží šablonu platby — žádná platba nevzniká, dokud se opakování nespustí. `schedule` je povinné pro typ `AUTO` a pro `ON_DEMAND` se naopak nesmí posílat.
**Parametry**
- `goid` (string; path; povinné) — Jedinečný identifikátor registrovaného webu obchodníka
**Tělo požadavku** (povinné)
`application/json`: [Recurrence-Create-Request](#schema-Recurrence-Create-Request)
**Odpovědi**
- `201` Nová opakovaná platba — [Recurrence-Details](#schema-Recurrence-Details)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Stav opakované platby
`GET /recurrences/{rec_id}` · ID operace: `get-recurrences-rec_id`
Vyžaduje: `merchant_credentials` (scopes: `payment:read`)
Vrátí aktuální stav opakované platby a platbu, kterou naposledy založila.
**Parametry**
- `rec_id` (string; path; povinné) — Jedinečné ID dříve založené opakované platby
**Odpovědi**
- `200` Opakovaná platba — [Recurrence-Details](#schema-Recurrence-Details)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Zastavení opakované platby
`DELETE /recurrences/{rec_id}` · ID operace: `delete-recurrences-rec_id`
Vyžaduje: `merchant_credentials` (scopes: `payment:write`)
Trvale zastaví opakovanou platbu. Přejde do stavu `STOPPED` s důvodem `CANCELLED_VIA_API` a už nezaloží žádnou další platbu. Zastavení nejde vzít zpět.
**Parametry**
- `rec_id` (string; path; povinné) — Jedinečné ID dříve založené opakované platby
**Odpovědi**
- `204` Hotovo; odpověď nemá tělo
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Spuštění opakované platby
`POST /recurrences/{rec_id}/start` · ID operace: `post-recurrences-rec_id-start`
Vyžaduje: `merchant_credentials` (scopes: `payment:write`)
Založí první platbu opakování a přepne ho do stavu `REQUESTED`. Zákazník tuto platbu zaplatí na její adrese `gw_url`; jakmile je zaplacená, opakování přejde do stavu `STARTED` a je možné žádat o další platby. Volitelné tělo přepíše pole uložené šablony platby, a to jen pro tuto jednu platbu.
**Parametry**
- `rec_id` (string; path; povinné) — Jedinečné ID dříve založené opakované platby
**Tělo požadavku** (nepovinné)
`application/json`: [Payment-Instance-Override](#schema-Payment-Instance-Override)
**Odpovědi**
- `201` Nová platba — [Payment-Details](#schema-Payment-Details)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Založení další platby opakování
`POST /recurrences/{rec_id}/next` · ID operace: `post-recurrences-rec_id-next`
Vyžaduje: `merchant_credentials` (scopes: `payment:write`)
Založí další platbu z opakování, které už je ve stavu `STARTED`. Dokud opakování není spuštěné a jeho první platba zaplacená, vrací `409`. Volitelné tělo přepíše pole uložené šablony platby, a to jen pro tuto jednu platbu.
**Parametry**
- `rec_id` (string; path; povinné) — Jedinečné ID dříve založené opakované platby
**Tělo požadavku** (nepovinné)
`application/json`: [Payment-Instance-Override](#schema-Payment-Instance-Override)
**Odpovědi**
- `201` Nová platba — [Payment-Details](#schema-Payment-Details)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
### Karty
Uložené tokeny karet, které zastupují kartu zákazníka při pozdějších strženích.
#### Vytvoření tokenu karty
`POST /cards/tokens` · ID operace: `post-cards-tokens`
Vyžaduje: `merchant_credentials` (scopes: `card:write`)
Vymění zašifrovaná data karty za trvalý token karty.
JWE vytvořené klientským SDK GoPay se posílá v poli `payload` a vymění se za objekt `Permanent Card Token Details`. Jeho `token` se při pozdějším stržení předává jako `card_token` ve vstupu `CARD_TOKEN`, zatímco `card_id` adresuje uloženou kartu v operacích pro čtení a smazání. JWE je jednorázové. Tokenizace je ve výchozím stavu vypnutá a je nutné ji obchodníkovi povolit; operace je pouze serverová.
**Tělo požadavku** (nepovinné)
`application/json`: [Token-Create-Request](#schema-Token-Create-Request)
**Odpovědi**
- `201` Nový token uložené karty — [Permanent-Card-Token-Details](#schema-Permanent-Card-Token-Details)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Detaily karty
`GET /cards/tokens/{card_id}` · ID operace: `get-cards-tokens-card_id`
Vyžaduje: `merchant_credentials` (scopes: `card:read`)
Vrátí aktuální údaje uložené karty.
Volá se po události `cards.updated`, aby se načetla pole, která vydavatel karty změnil na místě — nově vydaný PAN nebo nová expirace — zatímco `card_id` zůstává stejné. API neposkytuje výpis uložených karet; vazbu mezi `card_id` a zákazníkem si udržuje obchodník. Operace je pouze serverová.
**Parametry**
- `card_id` (string; path; povinné) — ID uložené platební karty
**Odpovědi**
- `200` Uložená karta — [Permanent-Card-Token-Details](#schema-Permanent-Card-Token-Details)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Smazání karty
`DELETE /cards/tokens/{card_id}` · ID operace: `delete-cards-tokens-card_id`
Vyžaduje: `merchant_credentials` (scopes: `card:write`)
Trvale smaže uloženou kartu.
Smazaný token nelze obnovit; opětovné uložení téže karty vyžaduje novou tokenizaci. Operace je pouze serverová.
**Parametry**
- `card_id` (string; path; povinné) — ID uložené platební karty
**Odpovědi**
- `204` Hotovo; odpověď nemá tělo
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
### Události
Log událostí e-shopu a veřejné klíče, kterými se ověřuje podpis webhooku.
#### Seznam událostí
`GET /eshops/{goid}/events` · ID operace: `get-eshops-goid-events`
Vyžaduje: `merchant_credentials` (scopes: `event:read`)
Vrátí jednu stránku událostí e-shopu, od nejnovější.
Každá stránka nese v `next_page_url` adresu té následující, včetně filtrů požadavku a
pozice, od které se pokračuje. Jakmile byla vrácena poslední odpovídající událost,
pole chybí.
**Parametry**
- `goid` (string; path; povinné) — Jedinečný identifikátor registrovaného webu obchodníka
- `max_items` (integer; query; nepovinné; výchozí `20`; minimum 1; maximum 100) — Nejvyšší počet událostí na jedné stránce
- `prev_item` (string; query; nepovinné) — `id` poslední události předchozí stránky. Stránka začíná událostí, která po ní
následuje. GoPay tuto hodnotu zapisuje do `next_page_url` a volající následuje tuto
adresu, místo aby parametr sestavoval sám. Hodnota, která vypadla z třicetidenního
okna, je odmítnuta.
- `type` (string; query; nepovinné) — Typy událostí, které se mají zahrnout, oddělené čárkou v jednom parametru, nejvýše 20
položek. Položkou je buď přesný typ (`payments.paid`), nebo celý jmenný prostor
(`payments.*`). Neznámý typ je odmítnut. Bez tohoto parametru odpovídá každý typ.
- `occurred_after` (string (date-time); query; nepovinné) — Zahrne události, které nastaly v tomto okamžiku nebo po něm. Je-li zadán i `occurred_before`, musí být dřívější
- `occurred_before` (string (date-time); query; nepovinné) — Zahrne události, které nastaly před tímto okamžikem
- `related_type` (string; query; nepovinné; hodnoty: `payments`, `links`, `refunds`, `recurrences`, `cards`) — Druh entity, na kterou `related_id` odkazuje. Vyžadováno společně s `related_id`
- `related_id` (string; query; nepovinné) — Zahrne pouze události, které tento identifikátor nesou, ať už je v `data` na kterékoli
pozici. Vyžadováno společně s `related_type`.
**Odpovědi**
- `200` Jedna stránka událostí e-shopu, od nejnovější — [Event-List](#schema-Event-List)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Detail události
`GET /eshops/{goid}/events/{event_id}` · ID operace: `get-eshops-goid-events-event_id`
Vyžaduje: `merchant_credentials` (scopes: `event:read`)
Vrátí jednu událost e-shopu podle jejího `id`.
**Parametry**
- `goid` (string; path; povinné) — Jedinečný identifikátor registrovaného webu obchodníka
- `event_id` (string; path; povinné) — Identifikátor události
**Odpovědi**
- `200` Událost — [Event](#schema-Event)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Podpisové klíče webhooků
`GET /webhooks/public-keys` · ID operace: `get-webhooks-public-keys`
Vyžaduje: `shareable_key` nebo `merchant_credentials` (scopes: `shared:read`)
Vrátí veřejné klíče, kterými se ověřuje podpis webhooku.
Klíče mají strukturu JWK Set popsanou v
[RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517). Během výměny klíče může být
zveřejněno několik klíčů naráz.
**Odpovědi**
- `200` Podpisové klíče webhooků, které se právě používají — [JWK-Set](#schema-JWK-Set)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
### Služby SDK
Operace, které klientská SDK GoPay volají z prohlížeče nebo aplikace zákazníka při sběru karetních údajů nebo údajů z peněženky pro stržení. Kód obchodníka je běžně nevolá. Pokud stržení provádí server obchodníka, potřebuje data prohlížeče, která pro něj shromáždí i klientské SDK GoPay. Operace jsou zdokumentovány pro plně vlastní integrace; vlastní integrace karetních údajů navíc vyžaduje PCI DSS SAQ.
#### Informace o platbě Google Pay
`GET /payments/{payment_id}/google-pay/info` · ID operace: `get-payments-payment_id-info-google-pay`
Vyžaduje: `payment_credentials` (scopes: `payment:read`) nebo `merchant_credentials` (scopes: `payment:read`)
Vrátí konfiguraci Google Pay payment requestu pro danou platbu.
Určeno pro klientská SDK GoPay; kód obchodníka tento endpoint běžně nevolá. Stejný endpoint slouží pro web i pro nativní aplikace — nastavené prostředí je v poli `environment`.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
**Odpovědi**
- `200` Konfigurace platebního požadavku Google Pay zpracovávaná tlačítkem Google Pay — object
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Informace o platbě Apple Pay
`GET /payments/{payment_id}/apple-pay/info` · ID operace: `get-payments-payment_id-info-apple-pay`
Vyžaduje: `payment_credentials` (scopes: `payment:read`) nebo `merchant_credentials` (scopes: `payment:read`)
Vrátí konfiguraci Apple Pay payment requestu pro danou platbu na webu.
Určeno pro klientská SDK GoPay; kód obchodníka tento endpoint běžně nevolá.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
**Odpovědi**
- `200` Objekt platebního požadavku Apple Pay zpracovávaný tlačítkem Apple Pay — object
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Informace o platbě Apple Pay pro aplikace
`GET /payments/{payment_id}/apple-pay/app-info` · ID operace: `get-payments-payment_id-apple-pay-app-info`
Vyžaduje: `payment_credentials` (scopes: `payment:read`) nebo `merchant_credentials` (scopes: `payment:read`)
Vrátí konfiguraci Apple Pay payment requestu pro danou platbu v nativní aplikaci. Nese `paymentSummaryItems` tam, kde webová varianta nese jediné `total`.
Určeno pro klientská SDK GoPay; kód obchodníka tento endpoint běžně nevolá.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
**Odpovědi**
- `200` Objekt platebního požadavku Apple Pay pro nativní aplikaci — object
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Ověření obchodníka
`POST /payments/{payment_id}/apple-pay/validate` · ID operace: `post-payments-payment_id-apple-pay-validate`
Vyžaduje: `payment_credentials` (scopes: `payment:read`) nebo `merchant_credentials` (scopes: `payment:read`)
Dokončí ověření obchodníka (merchant validation) pro relaci Apple Pay.
Adresa `validationUrl` vydaná Applem se předá GoPay, které vrátí merchant session, kterou očekává Apple Pay sheet. Určeno pro klientská SDK GoPay; kód obchodníka tento endpoint běžně nevolá.
**Parametry**
- `payment_id` (string; path; povinné) — Identifikátor platby, `Payment Details.id`
- `Origin` (string; header; povinné) — Původ stránky, na které je zobrazeno tlačítko Apple Pay. Prohlížeč ho přidá automaticky
**Tělo požadavku** (povinné)
`application/json`: [Validate-Merchant-Request](#schema-Validate-Merchant-Request)
**Odpovědi**
- `200` Merchant session pro platební okno Apple Pay — [Validate-Merchant-Response](#schema-Validate-Merchant-Response)
- `400` Chybný požadavek — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Nenalezeno — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Konflikt — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Získání veřejného klíče
`GET /cards/public-key` · ID operace: `get-encryption-public-key`
Vyžaduje: `shareable_key` nebo `merchant_credentials` (scopes: `shared:read`)
Vrátí veřejný šifrovací klíč pro šifrování dat platební karty.
Klíč je strukturován jako JWK dle [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).
Určeno pro klientská SDK GoPay; kód obchodníka tento endpoint běžně nevolá.
**Odpovědi**
- `200` Veřejný šifrovací klíč — [JWK](#schema-JWK)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### URL formuláře karty
`GET /cards/card-form-url` · ID operace: `get-card-form-url`
Vyžaduje: `shareable_key` nebo `merchant_credentials` (scopes: `shared:read`)
Vrátí URL hostovaného formuláře pro zadání údajů platební karty.
Určeno pro SDK GoPay pro prohlížeč, které formulář vkládá do stránky; kód obchodníka tento endpoint běžně nevolá.
**Odpovědi**
- `200` URL hostovaného formuláře karty — [Card-Form-URL](#schema-Card-Form-URL)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
#### Získání dat prohlížeče
`GET /cards/browser-data` · ID operace: `get-browser-data`
Vyžaduje: `shareable_key`
Vrátí pole `Browser Data`, která prohlížeč zákazníka nedokáže zjistit sám — zdrojovou IP adresu, hlavičku `User-Agent` a hlavičky `Accept` — odvozená z requestu, kterým byla vyžádána.
Klientské SDK GoPay ho volá z prohlížeče nebo zařízení zákazníka těsně před stržením. Volání ze serveru obchodníka vrátí hodnoty serveru, které vydavatel karty při 3-D Secure autentizaci odmítne.
**Odpovědi**
- `200` Data prohlížeče odvozená z requestu — [Browser-Data-Detected](#schema-Browser-Data-Detected)
- `401` Nepřihlášen — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Přístup odepřen — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Interní chyba serveru — [Error-Response-Body](#schema-Error-Response-Body)
## Schémata
### Client-Credentials-Request
**Přihlašovací údaje klienta**
Žádost o přístupový token obchodníka s grantem `client_credentials`
Type: `object`
- `grant_type` (string = `"client_credentials"`; povinné; příklad `"client_credentials"`) — Vždy `client_credentials` pro tento tok
- `scope` (string; povinné; příklad `"payment:write payment:read"`) — Seznam požadovaných token scopů oddělených mezerou.
- `payment:read` čte platby a zdroje, které na nich stojí — například stržení, vrácení, opakované platby a platební odkazy
- `payment:write` zakládá, strhává, ruší a upravuje platby a tytéž zdroje
- `card:read` čte uložené tokeny karet
- `card:write` ukládá a maže tokeny karet
- `event:read` čte události e-shopu
- `shared:read` čte veřejné zdroje, jako jsou veřejné klíče
### Payment-Credentials-Request
**Přihlašovací údaje platby**
Žádost o přístupový token omezený na platbu s grantem `payment_credentials`
Type: `object`
- `grant_type` (string = `"payment_credentials"`; povinné; příklad `"payment_credentials"`) — Vždy `payment_credentials` pro tento tok
- `scope` (string; povinné; příklad `"payment:charge payment:read"`) — Seznam požadovaných token scopů oddělených mezerou.
- `payment:read` čte platbu
- `payment:charge` strhává platbu
### Access-Token
**Přístupový token**
Přístupový token a jeho metainformace.
Type: `object`
- `token_type` (string = `"bearer"`; nepovinné; výchozí `"bearer"`; příklad `"bearer"`) — Vždy `bearer`
- `access_token` ([JWT](#schema-JWT); nepovinné) — Přístupový token, předává se jako Bearer token
- `scope` (string; nepovinné; příklad `"payment:write payment:read"`) — Mezerou oddělený seznam token scopů.
- `expires_in` (integer; nepovinné; minimum 0; příklad `900`) — Platnost přístupového JWT v sekundách
### JWT
JWT řetězec dle [RFC 7519: JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
JWT claims obsahují:
- `sub` -> Client ID, pro které byl token vydán
- `scope` -> scopy tokenu
- `iat` -> čas vydání tokenu
- `exp` -> čas expirace tokenu
- `domain` -> `merchant` pro tokeny vydané serveru obchodníka s grantem `client_credentials`, `payment` pro tokeny omezené na platbu vydané s grantem `payment_credentials` klientskému SDK GoPay
Type: `string`
### Payment-Create-Request
**Žádost o vytvoření platby**
Reprezentace požadavku na vytvoření nové platby
Type: `object`
- `amount` (integer; povinné; minimum 0; příklad `100`) — Celková částka v haléřích
- `currency` ([Currency](#schema-Currency); povinné) — Měna platby
- `order_number` (string; povinné; maximální délka 128; příklad `"2025010199"`) — Identifikace objednávky pro e-shop, alfanumerické znaky
- `order_description` (string; nepovinné; příklad `"Test order"`) — Popis objednávky, alfanumerické znaky
- `additional_params` (array of [Additional-Param](#schema-Additional-Param); nepovinné; maximální počet položek 4) — Dodatečné parametry platby
- `customer` ([Customer](#schema-Customer); povinné) — Informace o zákazníkovi
- `callback` ([Payment-Callback](#schema-Payment-Callback); povinné) — URL pro návratové přesměrování a pro notifikace
Příklad:
```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"
}
}
```
### Currency
Podporované měny platby ve formátu ISO 4217
Type: `string`
Hodnoty: `CZK`, `EUR`, `PLN`, `USD`, `GBP`, `HUF`, `RON`
### Additional-Param
**Doplňující parametr**
Dodatečné parametry platby
Type: `object`
- `name` (string; povinné; příklad `"Custom param"`) — Název parametru
- `value` (string; povinné; příklad `"Custom value"`) — Hodnota parametru
Příklad:
```json
{
"name": "Custom param",
"value": "Custom value"
}
```
### Payment-Details
**Detaily platby**
Reprezentace existující platby
Type: `object`
- `id` (string; povinné; příklad `"300000001"`) — Identifikátor platby
- `order_number` (string; povinné; příklad `"2025010199"`) — Číslo objednávky zadané při vytvoření platby
- `state` ([Payment-State](#schema-Payment-State); povinné) — Stav platby
- `amount` (integer; povinné; příklad `100`) — Celková částka v haléřích
- `currency` ([Currency](#schema-Currency); povinné) — Měna platby
- `customer` ([Customer](#schema-Customer); povinné) — Data zákazníka
- `gw_url` (string (uri); povinné; příklad `"https://gate.gopay.com/gw/123456789"`) — Adresa hostované platební brány GoPay pro tuto platbu, kterou používá integrace
Přesměrování. Nabídne zákazníkovi všechny platební metody povolené pro daný eshop
a po dobu, co je na ní zákazník, vede platbu GoPay. Je to cíl, kam se zákazník
odešle, a nejde ji zaintegrovat do vlastního checkoutu obchodníka.
`GET /payments/{payment_id}` hlásí výsledek platby zaplacené na bráně stejně
jako u kterékoli jiné platby.
- `charge` ([Payment-Charge-Status-Response](#schema-Payment-Charge-Status-Response); nepovinné) — Stržení platby, jakmile byl pokus o stržení proveden
- `payment_secret` (string; povinné; příklad `"ps_4d2f9a51b7e30c68a1c5e9f03b7d2e46"`) — Platební tajný klíč, který server obchodníka předá klientskému SDK GoPay, aby SDK mohlo s touto platbou pracovat. **Nezahrnujte do URL, nelogujte ani neukládejte!**
### Customer
**Zákazník**
Detaily zákazníka spojené s platbou. E-mailová adresa je povinná, protože slouží k autentizaci a zasílání notifikací.
Type: `object`
- `email` (string (email); povinné; maximální délka 128; příklad `"john.doe@example.com"`) — E-mail zákazníka
- `first_name` (string; nepovinné; maximální délka 256; příklad `"John"`) — Křestní jméno zákazníka
- `last_name` (string; nepovinné; maximální délka 256; příklad `"Doe"`) — Příjmení zákazníka
- `phone_number` (string; nepovinné; maximální délka 128; příklad `"+420123456789"`) — Telefonní číslo zákazníka (domácí nebo mobilní)
- `city` (string; nepovinné; maximální délka 128; příklad `"Testington"`) — Město adresy zákazníka
- `street` (string; nepovinné; maximální délka 128; příklad `"Example st. 10"`) — Ulice adresy zákazníka
- `postal_code` (string; nepovinné; maximální délka 128; příklad `"10000"`) — PSČ zákazníka
- `country_code` (string; nepovinné; maximální délka 128; příklad `"CZE"`) — Kód země zákazníka dle [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
- `customer_id` (string; nepovinné; maximální délka 128; příklad `"customer420"`) — Jedinečné ID zákazníka (slouží k přizpůsobení pokladního procesu)
Příklad:
```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"
}
```
### Payment-Callback
**Platební callback**
Objekt obsahující URL pro callbackové účely spojené s platbou
Type: `object`
- `notification_url` (string; nepovinné; příklad `"https://example.com/notify"`) — URL, na kterou přicházejí notifikace o platbě. Nepovinná: když chybí, notifikace se posílají na notifikační URL nastavenou u e-shopu, a e-shop, který žádnou nastavenou nemá, notifikaci nedostane. Pokud je uvedena, nesmí být prázdná
- `return_url` (string; povinné; příklad `"https://example.com/return"`) — URL, na kterou se prohlížeč zákazníka odešle na konci toku hostované brány a v checkout integraci po kroku 3-D Secure. Nesmí obsahovat fragment (`#…`)
Příklad:
```json
{
"notification_url": "https://example.com/notify",
"return_url": "https://example.com/return"
}
```
### Payment-State
**Stav platby**
Životní cyklus stavu platby.
- `CREATED` - Platba existuje a čeká na pokus o stržení
- `PAID` - Platba byla úspěšně stržena
- `CANCELED` - Zákazník platbu opustil, stržení bylo zamítnuto při autorizaci, nebo obchodník platbu zrušil dříve, než byla stržena
- `PAYMENT_METHOD_CHOSEN` - Probíhá pokus o stržení a jeho výsledek zatím není znám
- `TIMEOUTED` - Platba nedosáhla koncového stavu v rámci svého timeoutu
- `AUTHORIZED` - Platba byla autorizována, ale dosud nestržena; týká se jen toku s předautorizací
- `REFUNDED` - Platba byla plně refundována
- `PARTIALLY_REFUNDED` - Platba byla částečně refundována
Type: `string`
Hodnoty: `CREATED`, `PAID`, `CANCELED`, `PAYMENT_METHOD_CHOSEN`, `TIMEOUTED`, `AUTHORIZED`, `REFUNDED`, `PARTIALLY_REFUNDED`
### Charge-State
**Stav stržení**
Životní cyklus stavu stržení platby.
- `REQUESTED` - Stržení bylo zahájeno
- `PROCESSING` - Stržení je zpracováváno platebním poskytovatelem
- `ACTION_REQUIRED` - Zákazník musí dokončit krok, například 3-D Secure autentizaci, než stržení může pokračovat
- `SUCCEEDED` - Stržení bylo úspěšně dokončeno
- `FAILED` - Stržení selhalo
Type: `string`
Hodnoty: `REQUESTED`, `PROCESSING`, `ACTION_REQUIRED`, `SUCCEEDED`, `FAILED`
### Payment-Charge-Data
**Data stržení platby**
Platební prostředek použitý ke stržení. Variantu určuje pole `payment_instrument`, které nabývá hodnot z výčtu [Payment Instrument](#schema-Payment-Instrument).
Type: `oneOf`
Jedna z: [Payment-Card-Charge-Data](#schema-Payment-Card-Charge-Data)
Diskriminátor: `payment_instrument` (`PAYMENT_CARD` → [Payment-Card-Charge-Data](#schema-Payment-Card-Charge-Data))
### Payment-Charge-Input
**Vstup stržení platby**
Model obsahující všechna data potřebná pro provedení stržení platby
Type: `object`
- `payment_instrument` ([Payment-Charge-Data](#schema-Payment-Charge-Data); povinné) — Data platebního prostředku určující způsob stržení platby
### Payment-Instrument
**Platební nástroj**
Hodnoty pole, které určuje variantu [Payment Charge Data](#schema-Payment-Charge-Data)
Type: `string`
Hodnoty: `PAYMENT_CARD`
### Payment-Card-Charge-Data
**Data stržení platební karty**
Varianta `PAYMENT_CARD` unie [Payment Charge Data](#schema-Payment-Charge-Data). Nese karetní vstup, data prohlížeče a preferenci 3-D Secure.
Type: `object`
- `payment_instrument` (string = `"PAYMENT_CARD"`; povinné) — Vždy `PAYMENT_CARD`
- `input` ([Payment-Card-Input](#schema-Payment-Card-Input); povinné) — Jeden z možných vstupů pro karetní platbu
- `browser_data` ([Browser-Data](#schema-Browser-Data); povinné)
- `challenge_preference` ([Payment-Card-Challenge-Preference](#schema-Payment-Card-Challenge-Preference); nepovinné)
### Payment-Card-Input
**Vstup platební karty**
Karta, kterou se platba strhává. Variantu určuje pole `input_type`, které nabývá hodnot z výčtu [Payment Card Input Type](#schema-Payment-Card-Input-Type).
Type: `oneOf`
Jedna z: [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)
Diskriminátor: `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))
### Payment-Card-Input-Type
**Typ vstupu platební karty**
Hodnoty pole, které určuje variantu [Payment Card Input](#schema-Payment-Card-Input)
Type: `string`
Hodnoty: `CARD_TOKEN`, `APPLE_PAY`, `GOOGLE_PAY`, `ENCRYPTED_CARD`
### Card-Token-Input
**Vstup tokenu karty**
Varianta `CARD_TOKEN` unie [Payment Card Input](#schema-Payment-Card-Input). Nese token uložené karty.
Type: `object`
- `input_type` (string = `"CARD_TOKEN"`; povinné) — Vždy `CARD_TOKEN`
- `card_token` (string; povinné; příklad `"J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjG..."`) — Trvalý token karty získaný pomocí API volání [Vytvoření tokenu karty](#operation-post-cards-tokens)
### Payment-Card-Challenge-Preference
**Předvolba výzvy platební karty**
Preference obchodníka ohledně 3-D Secure autentizace karetní platby.
- `AUTO` - nechat rozhodnout GoPay
- `CHALLENGE_PREFERRED` - požádat o výzvu 3-D Secure pro silnější autentizaci; i tak ji lze přeskočit, například u Apple Pay
- `NO_CHALLENGE_PREFERRED` - požádat o přeskočení výzvy; vydavatel karty ji i tak může vyžadovat
Type: `string`
Hodnoty: `CHALLENGE_PREFERRED`, `NO_CHALLENGE_PREFERRED`, `AUTO`
### Google-Pay-Input
**Vstup Google Pay**
Varianta `GOOGLE_PAY` unie [Payment Card Input](#schema-Payment-Card-Input). Nese platební data vrácená z Google Pay.
Viz [Payment Data Cryptography](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography) v dokumentaci Google Pay.
Type: `object`
- `input_type` (string = `"GOOGLE_PAY"`; nepovinné; příklad `"GOOGLE_PAY"`) — Vždy `GOOGLE_PAY`
- `protocolVersion` (string; nepovinné; příklad `"ECv2"`) — Verze protokolu Google Pay API použitého k šifrování platebních dat
- `signature` (string; nepovinné; příklad `"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q=="`) — Digitální podpis platebních dat
- `intermediateSigningKey` (object; nepovinné) — Zprostředkující podpisový klíč od Googlu pro ověření podpisu
- `signedKey` (string; nepovinné; příklad `"{\"keyExpiration\":\"1542323393147\",\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw==\"}"`) — JSON řetězec obsahující hodnotu klíče a datum expirace
- `signatures` (array of string; nepovinné) — Podpisy zprostředkujícího podpisového klíče
- `signedMessage` (string; nepovinné; příklad `"{\"tag\":\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U=\",\"ephemeralPublicKey\":\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs=\",\"encryptedMessage\":\"mKOoXwi8OavZ\"}"`) — JSON řetězec obsahující zašifrovaná platební data
### Apple-Pay-Input
**Vstup Apple Pay**
Varianta `APPLE_PAY` unie [Payment Card Input](#schema-Payment-Card-Input). Nese platební token vrácený z Apple Pay.
Viz [Payment token format reference](https://developer.apple.com/documentation/passkit/payment-token-format-reference) v dokumentaci Apple Pay.
Type: `object`
- `input_type` (string = `"APPLE_PAY"`; povinné; příklad `"APPLE_PAY"`) — Vždy `APPLE_PAY`
- `data` (string; povinné; příklad `"V7OcjttPJnUJaQH7x7OjbIeZSINuc..."`) — Zašifrovaná platební data z tokenu Apple Pay
- `signature` (string; povinné; příklad `"MIAGCSqGSIb3DQEHAqCAM..."`) — Podpis platebních dat a hlavičky, podepsaný Applem
- `version` (string; povinné; příklad `"EC_v1"`) — Verze formátu platebního tokenu Apple Pay
- `header` (object; povinné) — Hlavička obsahující dodatečná data pro dešifrování a ověření platebního tokenu
- `applicationData` (string; nepovinné; příklad `"94ee059335e587e5f6b717fb172c5c3841659d892a84b7c6c47d0d13c58f7ea4"`) — Hash hodnoty `applicationData` nesené v platebním požadavku Apple Pay. Apple ho přidává jen u relací vytvořených s touto hodnotou, pole je tedy volitelné; pokud ho relace Apple Pay vrátí, přepošlete ho beze změny
- `ephemeralPublicKey` (string; povinné; příklad `"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwpd0HT6uOdE2pZTBZXsJF7IK7EvJQDq4LnQS5B5g8fiD9sEZNt4P9DhWRO44kEbbyiQ1FVgPcSsvJ2Z5I+qPTw=="`) — Dočasný veřejný klíč pro odvození sdíleného tajemství
- `publicKeyHash` (string; povinné; příklad `"L6vppo38t31Q/9npxRy/xbA1+cs13h1LV+pMO/FYwvo="`) — SHA-256 hash certifikátu veřejného klíče obchodníka
- `transactionId` (string; povinné; příklad `"4f4fac7a179ae30ce4c839e85efa4a34811a5ea2af88280c847a6a8ba2c0e8c5"`) — Jedinečný identifikátor transakce vygenerovaný Apple Pay
Příklad:
```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"
}
}
```
### Bank-Swift
**SWIFT kód banky**
SWIFT/BIC kód identifikující podporovanou banku. Pro banky neuvedené v seznamu použijte `OTHERS`.
- `GIBACZPX` - Česká spořitelna (Česká republika)
- `KOMBCZPP` - Komerční banka (Česká republika)
- `SUBASKBX` - VÚB banka (Slovensko)
- `GIBASKBX` - Slovenská sporiteľňa (Slovensko)
- `OTHERS` - Libovolná jiná podporovaná banka
Type: `string`
Hodnoty: `GIBACZPX`, `KOMBCZPP`, `SUBASKBX`, `GIBASKBX`, `OTHERS`
### Browser-Data
**Data prohlížeče**
Data prohlížeče zákazníka shromážděná pro účely 3-D Secure autentizace. Tato data jsou předávána vydavateli karty v průběhu autentizačního toku.
Type: `object`
- `language` (string; povinné; příklad `"cs-CZ"`) — Jazyk nebo locale prostředí zákazníka
- `timezone` (integer; povinné; příklad `-60`) — Posun časového pásma prostředí zákazníka v minutách (např. -60 pro SEČ)
- `screen_width` (integer; povinné; příklad `434`) — Šířka obrazovky zákazníka v pixelech
- `screen_height` (integer; povinné; příklad `965`) — Výška obrazovky zákazníka v pixelech
- `color_depth` (integer; povinné; příklad `24`) — Barevná hloubka obrazovky zákazníka v bitech
- `user_agent` (string; povinné; příklad `"Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Mobile Safari/537.36"`) — User-Agent řetězec prohlížeče zákazníka, vrácený endpointem pro data prohlížeče. Berte ho ze stejného zdroje jako `ip` — nesourodá dvojice neprojde 3-D Secure autentizací
- `accept_header` (string; povinné; příklad `"{\"accept-language\":\"cs;q=0.5\",\"accept-encoding\":\"gzip, deflate, br, zstd\",\"accept\":\"application/json, text/plain, */*\"}"`) — JSON zakódované Accept hlavičky z prohlížeče zákazníka, vrácené endpointem pro data prohlížeče. Berte je ze stejného zdroje jako `ip`
- `javascript_enabled` (boolean; povinné; příklad `true`) — Zda je v prohlížeči zákazníka povolený JavaScript
- `ip` (string; povinné; maximální délka 45; příklad `"192.0.2.42"`) — IP adresa prohlížeče zákazníka, vrácená endpointem pro data prohlížeče. Server obchodníka, který strhává platbu za zákazníka, musí přeposlat hodnotu získanou v prohlížeči, nikdy svou vlastní adresu
### Browser-Data-Detected
**Zjištěná data prohlížeče**
Pole `Browser Data`, která prohlížeč zákazníka nedokáže zjistit sám, odvozená z requestu, kterým byla vyžádána.
Při strhávání platby je vložte do `Browser Data`.
Type: `object`
- `ip` (string; povinné; maximální délka 45; příklad `"192.0.2.42"`) — IP adresa, ze které request přišel
- `user_agent` (string; povinné; příklad `"Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Mobile Safari/537.36"`) — Hlavička User-Agent odeslaná s requestem
- `accept_header` (string; povinné; příklad `"{\"accept-language\":\"cs;q=0.5\",\"accept-encoding\":\"gzip, deflate, br, zstd\",\"accept\":\"application/json, text/plain, */*\"}"`) — Accept hlavičky odeslané s requestem, zakódované do JSON
### Payment-Charge-Response
**Odpověď na stržení platby**
Stržení zahájené přes `POST /payments/{payment_id}/charge`: jeho stav, použitý platební prostředek a případný krok, který musí zákazník dokončit.
Type: `object`
- `id` (string; povinné; příklad `"9123456789"`) — Jedinečný identifikátor stržení
- `state` ([Charge-State](#schema-Charge-State); povinné) — Aktuální stav stržení
- `payment_instrument` ([Payment-Instrument-Data](#schema-Payment-Instrument-Data); povinné) — Detaily platebního prostředku použitého pro toto stržení
- `action` ([Payment-Charge-Action](#schema-Payment-Charge-Action); nepovinné) — Krok, který musí zákazník dokončit, například 3-D Secure autentizace. Přítomné, pokud je `state` `ACTION_REQUIRED`
### Payment-Charge-Status-Response
**Odpověď na stav stržení platby**
Aktuální stav stržení platby, použitý platební prostředek, případný krok, který musí zákazník dokončit, a u neúspěšného stržení i jeho důvod.
Type: `object`
- `id` (string; povinné; příklad `"9123456789"`) — Jedinečný identifikátor stržení
- `state` ([Charge-State](#schema-Charge-State); povinné) — Aktuální stav stržení
- `payment_instrument` ([Payment-Instrument-Data](#schema-Payment-Instrument-Data); nepovinné) — Detaily platebního prostředku použitého pro toto stržení
- `action` ([Payment-Charge-Action](#schema-Payment-Charge-Action); nepovinné) — Krok, který musí zákazník dokončit, například 3-D Secure autentizace. Přítomné, pokud je `state` `ACTION_REQUIRED`
- `fail_reason` (string; nepovinné; příklad `"Issuer declined the authorisation"`) — Důvod selhání stržení. Přítomno pouze pokud je stav `FAILED`
### Payment-Instrument-Data
**Data platebního nástroje**
Platební prostředek, který stržení použilo. Variantu určuje pole `payment_instrument`, které nabývá hodnot z výčtu [Payment Instrument](#schema-Payment-Instrument).
Type: `oneOf`
Jedna z: [Payment-Card-Instrument-Out](#schema-Payment-Card-Instrument-Out)
Diskriminátor: `payment_instrument` (`PAYMENT_CARD` → [Payment-Card-Instrument-Out](#schema-Payment-Card-Instrument-Out))
Příklad:
```json
{
"payment_instrument": "PAYMENT_CARD",
"details": {
"input_type": "CARD_TOKEN",
"masked_pan": "406821******1234",
"expiration_month": "01",
"expiration_year": "30",
"scheme": "VISA",
"fingerprint": "73c8d0a48d91def89761..."
}
}
```
### Payment-Card-Instrument-Out
**Výstup nástroje platební karty**
Varianta `PAYMENT_CARD` unie Payment Instrument Data. Obsahuje detaily specifické pro kartu použitou při stržení.
Type: `object`
- `payment_instrument` ([Payment-Instrument](#schema-Payment-Instrument); povinné) — Vždy `PAYMENT_CARD`
- `details` ([Payment-Card-Charge-Details](#schema-Payment-Card-Charge-Details); nepovinné) — Detaily platebního prostředku specifické pro kartu
Příklad:
```json
{
"payment_instrument": "PAYMENT_CARD",
"details": {
"input_type": "CARD_TOKEN",
"masked_pan": "406821******1234",
"expiration_month": "01",
"expiration_year": "30",
"scheme": "VISA",
"fingerprint": "73c8d0a48d91def89761..."
}
}
```
### Payment-Card-Charge-Details
**Detaily stržení platební karty**
Výstupní detaily platebního prostředku karty vrácené v odpovědi na stržení. Obsahuje maskovaná data karty identifikující použitou kartu.
Type: `object`
- `input_type` ([Payment-Card-Input-Type](#schema-Payment-Card-Input-Type); povinné) — Typ zadání karty použitý při stržení
- `masked_pan` (string; nepovinné; příklad `"406821******1234"`) — Maskované primární číslo účtu s viditelnými pouze prvními šesti a posledními čtyřmi číslicemi
- `expiration_month` (string; nepovinné; vzor `^(?:0[0-9]|1[0-2])$`; příklad `"01"`) — Měsíc expirace karty (01–12)
- `expiration_year` (string; nepovinné; vzor `^[0-9]{2}$`; příklad `"30"`) — Rok expirace karty (dvoumístný formát)
- `scheme` ([Card-scheme](#schema-Card-scheme); nepovinné) — Schéma karetní sítě
- `fingerprint` (string; nepovinné; příklad `"73c8d0a48d91def89761..."`) — Jedinečný hash identifikující fyzickou kartu
Příklad:
```json
{
"input_type": "CARD_TOKEN",
"masked_pan": "406821******1234",
"expiration_month": "01",
"expiration_year": "30",
"scheme": "VISA",
"fingerprint": "73c8d0a48d91def89761..."
}
```
### Card-scheme
**Karetní schéma**
Schéma karetní sítě (VISA nebo MASTERCARD)
Type: `string`
Hodnoty: `VISA`, `MASTERCARD`
### Payment-Charge-Action
**Akce stržení platby**
Krok, který musí zákazník dokončit, než stržení může pokračovat, například 3-D Secure autentizace na stránce vydavatele karty. Variantu určuje pole `action_type`.
Type: `oneOf`
Jedna z: [Emv-3DS-Action](#schema-Emv-3DS-Action)
Diskriminátor: `action_type` (`EMV3DS` → [Emv-3DS-Action](#schema-Emv-3DS-Action))
Příklad:
```json
{
"action_type": "EMV3DS",
"state": "CREATED",
"redirect_url": "https://gate.gopay.com/redirect"
}
```
### Payment-Charge-Action-Type
**Typ akce stržení platby**
Hodnoty pole, které určuje variantu Payment Charge Action.
- `EMV3DS` - EMV 3-D Secure autentizace pro platby kartou
Type: `string`
Hodnoty: `EMV3DS`
### Emv-3DS-Action
**Akce EMV 3DS**
Varianta `EMV3DS` unie Payment Charge Action. Představuje akci EMV 3-D Secure autentizace pro karetní platby.
Type: `object`
- `action_type` ([Payment-Charge-Action-Type](#schema-Payment-Charge-Action-Type); povinné) — Vždy `EMV3DS`
- `state` ([Emv-3DS-State](#schema-Emv-3DS-State); povinné) — Aktuální stav průběhu 3DS autentizace
- `redirect_url` (string (uri); nepovinné; příklad `"https://gate.gopay.com/redirect"`) — URL, na kterou se prohlížeč zákazníka odešle ke kroku 3-D Secure. Přítomné, dokud je stržení ve stavu `ACTION_REQUIRED`
Příklad:
```json
{
"action_type": "EMV3DS",
"state": "CREATED",
"redirect_url": "https://gate.gopay.com/redirect"
}
```
### Emv-3DS-State
**Stav EMV 3DS**
Stav životního cyklu EMV 3-D Secure autentizace.
- `CREATED` - Autentizace 3-D Secure byla zahájena
- `CHALLENGE_REQUIRED` - Zákazník musí dokončit výzvu 3-D Secure, například jednorázový kód nebo potvrzení v bankovní aplikaci
- `AUTHENTICATED_CHALLENGE` - Zákazník byl autentizován prostřednictvím výzvy
- `AUTHENTICATED_FRICTIONLESS` - Zákazník byl autentizován bez výzvy (bezproblémový průběh)
- `NOT_AUTHENTICATED` - Autentizace 3-D Secure nebyla dokončena
- `FAILED` - Autentizace 3-D Secure selhala
Type: `string`
Hodnoty: `CREATED`, `CHALLENGE_REQUIRED`, `AUTHENTICATED_CHALLENGE`, `AUTHENTICATED_FRICTIONLESS`, `NOT_AUTHENTICATED`, `FAILED`
### QR-Payment-Details
**Detaily QR platby**
Detaily QR platby včetně částky platby, informací o bankovním účtu příjemce a vygenerovaných QR kódů v různých formátech.
Type: `object`
- `amount` (integer; povinné; příklad `10000`) — Částka platby v haléřích
- `currency` ([Currency](#schema-Currency); povinné) — Měna platby
- `recipient` ([Bank-Transfer-Recipient](#schema-Bank-Transfer-Recipient); povinné) — Informace o příjemci
- `qr_code` ([QR-Code-List](#schema-QR-Code-List); povinné) — Vygenerované obrázky QR kódů v různých regionálních formátech
### Bank-Transfer-Recipient
**Příjemce bankovního převodu**
Informace o příjemci bankovního převodu, včetně jména, údajů o bankovním účtu a adresy.
Type: `object`
- `name` (string; nepovinné; příklad `"GoPay Czech"`) — Jméno příjemce platby
- `bank_account` ([Recipient-Bank-Account](#schema-Recipient-Bank-Account); nepovinné) — Bankovní údaje příjemce v lokálním i mezinárodním formátu
- `address` ([Recipient-Address](#schema-Recipient-Address); nepovinné) — Fyzická adresa příjemce
### Recipient-Bank-Account
**Bankovní účet příjemce**
Bankovní údaje příjemce v lokálním (dle země) i mezinárodním (IBAN/SWIFT) formátu.
Type: `object`
- `local` ([Bank-Account-Local-Details](#schema-Bank-Account-Local-Details); nepovinné) — Bankovní údaje v lokálním (dle země) formátu
- `international` ([Bank-Account-International-Details](#schema-Bank-Account-International-Details); nepovinné) — Bankovní údaje v mezinárodním formátu IBAN/BIC
### Bank-Account-Local-Details
**Lokální detaily bankovního účtu**
Bankovní údaje v lokálním českém/slovenském formátu, včetně předčíslí, bankovního kódu a variabilního symbolu pro identifikaci platby.
Type: `object`
- `prefix` (string; povinné; příklad `"000000"`) — Předčíslí čísla účtu (může být samé nuly)
- `account_number` (string; povinné; příklad `"9878039"`) — Lokální číslo bankovního účtu
- `bank_code` (string; povinné; příklad `"2010"`) — Numerický kód banky identifikující banku
- `variable_symbol` (string; povinné; příklad `"3123456789"`) — Variabilní symbol pro spárování platby s objednávkou
### Bank-Account-International-Details
**Mezinárodní detaily bankovního účtu**
Bankovní údaje v mezinárodním formátu IBAN/BIC, používaném pro přeshraniční a SEPA platby.
Type: `object`
- `bic` ([Bank-Swift](#schema-Bank-Swift); nepovinné) — BIC (kód banky) / SWIFT kód banky
- `iban` (string; nepovinné; příklad `"CZ5120100000000009878039"`) — Mezinárodní číslo bankovního účtu (IBAN)
- `reference` (string; nepovinné; příklad `"3123456789"`) — Referenční číslo platby pro spárování s objednávkou
### Recipient-Address
**Adresa příjemce**
Fyzická adresa příjemce platby.
Type: `object`
- `street` (string; nepovinné; příklad `"Senovazne nam. 1736"`) — Ulice a číslo popisné
- `city` (string; nepovinné; příklad `"Ceske Budejovice"`) — Název města
- `zip_code` (string; nepovinné; příklad `"37001"`) — PSČ
- `country` (string; nepovinné; příklad `"Czech Republic"`) — Název země
### QR-Code-List
**Seznam QR kódů**
Kolekce obrázků QR kódů v různých regionálních formátech, zakódovaných jako řetězec base64. Dostupné formáty závisí na měně platby a zemi příjemce.
Type: `object`
- `spayd` (string; nepovinné; příklad `"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 kód ve formátu SPAYD (Short Payment Descriptor), běžně používaný v České republice. Zakódován jako base64 obrázek v požadovaném formátu.
- `paybysquare` (string; nepovinné; příklad `"{QR code in base64}"`) — QR kód ve formátu Pay by Square, běžně používaný na Slovensku. Zakódován jako base64 obrázek v požadovaném formátu.
- `sepa` (string; nepovinné; příklad `"{QR code in base64}"`) — QR kód ve formátu SEPA (Single Euro Payments Area) pro EUR platby. Zakódován jako base64 obrázek v požadovaném formátu.
- `mnb_qr` (string; nepovinné; příklad `"{QR code in base64}"`) — QR kód ve formátu MNB (Magyar Nemzeti Bank), běžně používaný v Maďarsku. Zakódován jako base64 obrázek v požadovaném formátu.
### Token-Create-Request
**Žádost o vytvoření tokenu**
Tělo požadavku pro vytvoření tokenu karty. Obsahuje zašifrovaná data karty.
Type: `object`
- `payload` ([JWE](#schema-JWE); povinné) — Zašifrovaná data karty ve formátu JWE compact serialization
### Permanent-Card-Token-Details
**Detaily trvalého tokenu karty**
Detaily tokenu uložené karty. Token se používá při dalších strženích, dokud není smazán; změny od vydavatele, například nová expirace, se do něj promítají na místě.
Type: `object`
- `card_id` (string; povinné; příklad `"8007127320"`) — Jedinečný identifikátor uloženého tokenu karty
- `masked_pan` (string; povinné; příklad `"406821******1234"`) — Maskované primární číslo účtu s viditelnými pouze prvními šesti a posledními čtyřmi číslicemi
- `masked_virtual_pan` (string; povinné; příklad `"489537******6287"`) — Maskovaný virtuální PAN (síťový token) přidružený ke kartě
- `expiration_month` (string; povinné; vzor `^(?:0[0-9]|1[0-2])$`; příklad `"01"`) — Měsíc expirace karty (01–12)
- `expiration_year` (string; povinné; vzor `^[0-9]{2}$`; příklad `"30"`) — Rok expirace karty (dvoumístný formát)
- `scheme` ([Card-scheme](#schema-Card-scheme); povinné) — Schéma karetní sítě
- `corporate` (boolean; povinné; výchozí `false`; příklad `false`) — Zda se jedná o firemní (podnikovou) kartu
- `fingerprint` (string; povinné; příklad `"73c8d0a48d91def897612b54e630997745e1faad43045e732189cfe4acf4961b"`) — Jedinečný hash identifikující fyzickou kartu, stabilní napříč více tokenizacemi téže karty
- `token` (string; povinné; příklad `"J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv9DtCT3HLSlWHRYAbVTBLbouV77YtVSgavhi4uRZTwDy218Gog4MbZJ+umL/BkfFlNQ80PCdOjwYr8DtqZr71LHwkvg91ywirZp0="`) — Hodnota trvalého tokenu karty pro použití v požadavcích na stržení
- `card_art_url` (string (uri); povinné; příklad `"https://card.art/pic.png"`) — URL obrázku karty poskytnutého vydávající bankou
- `brand` (string; nepovinné; příklad `"GOLD"`) — Druh nebo úroveň karty (např. GOLD, PLATINUM, STANDARD)
- `service_type` ([Card-Service-Type](#schema-Card-Service-Type); nepovinné) — Zda se jedná o debetní nebo kreditní kartu
- `status` ([Card-Token-Status](#schema-Card-Token-Status); nepovinné) — Aktuální stav uloženého tokenu karty
Příklad:
```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"
}
```
### Card-Service-Type
**Typ karty**
Určuje, zda se jedná o debetní nebo kreditní kartu.
- `DEBIT` - Prostředky jsou strhávány přímo z bankovního účtu držitele karty
- `CREDIT` - Prostředky jsou čerpány z kreditního rámce držitele karty
Type: `string`
Hodnoty: `DEBIT`, `CREDIT`
### Card-Token-Status
**Stav tokenu karty**
Aktuální stav trvalého tokenu karty.
- `ACTIVE` - Token je platný a lze ho použít pro platby
- `SUSPENDED` - Token je dočasně pozastaven a nelze ho použít
- `DELETED` - Token byl trvale smazán
Type: `string`
Hodnoty: `ACTIVE`, `SUSPENDED`, `DELETED`
### JWK
Struktura veřejného šifrovacího klíče. Je formátována dle RFC 7517: JSON Web Key (JWK)
Type: `object`
- `kty` (string = `"RSA"`; povinné; příklad `"RSA"`) — Typ klíče. Vždy `RSA` pro šifrovací klíče používané GoPay.
- `use` (string = `"enc"`; povinné; příklad `"enc"`) — Použití klíče. Vždy `enc` (šifrování).
- `kid` (string; povinné; příklad `"key_20250406"`) — ID klíče
- `alg` (string; povinné; výchozí `"RSA-OAEP-256"`; příklad `"RSA-OAEP-256"`) — Algoritmus pro šifrování tímto klíčem.
- `n` (string; povinné; příklad `"oR79tj1xAaqr1TfmkGS03EfEZjU_5DMomKJXGK8cnmtGivG5XnFodcbztzSOrlrKmhoxrKRR0LiRRjYJIgTP3dGK9KOv7JRH4adnDClckQkxupwoz1dcm6cLDzjuVS1a4et8lQlwYKm5r52fG9VShckwNZgvmK0uYcE7717wLkX3JM2vA_F_-2oRCjG3l2E4cjhQzzstTFPkW35ZjuKut4If8LOnKH0h9tdblUOSB_VtZBNY6PCXeUTDfbCb85-eGrwWXEajq4uegPDbV2oSnTLxOXR8ctWURZ8XjS1PgsoDD4go9BQchv-9Q2m0NbS5s71WVJ9LOW7Xt-Napsoftw"`) — Modulus veřejného klíče `RSA`.
- `e` (string; povinné; výchozí `"AQAB"`; příklad `"AQAB"`) — Exponent veřejného klíče `RSA`.
Příklad:
```json
{
"kty": "RSA",
"kid": "key_20250406",
"use": "enc",
"alg": "RSA-OAEP-256",
"n": "oR79tj1xAaqr1TfmkGS03EfEZjU_5DMomKJXGK8cnmtGivG5XnFodcbztzSOrlrKmhoxrKRR0LiRRjYJIgTP3dGK9KOv7JRH4adnDClckQkxupwoz1dcm6cLDzjuVS1a4et8lQlwYKm5r52fG9VShckwNZgvmK0uYcE7717wLkX3JM2vA_F_-2oRCjG3l2E4cjhQzzstTFPkW35ZjuKut4If8LOnKH0h9tdblUOSB_VtZBNY6PCXeUTDfbCb85-eGrwWXEajq4uegPDbV2oSnTLxOXR8ctWURZ8XjS1PgsoDD4go9BQchv-9Q2m0NbS5s71WVJ9LOW7Xt-Napsoftw",
"e": "AQAB"
}
```
### JWE
Struktura obsahující zašifrovaný payload. Je popsána v [RFC 7516: JSON Web Encryption (JWE)](https://datatracker.ietf.org/doc/html/rfc7516)
Vytváří ho klientské SDK GoPay.
Type: `string`
### Card-Form-URL
**URL formuláře karty**
URL hostovaného formuláře pro zadání karty, který SDK GoPay pro prohlížeč vkládá do stránky obchodníka.
Type: `object`
- `card_form_url` (string; nepovinné; příklad `"https://secure.gopay.com/gp-card-comm/q/form"`) — URL hostovaného formuláře pro zadání údajů karty
### Error-Response-Body
**Tělo chybové odpovědi**
Standardní tělo chybové odpovědi vrácené pro všechny chybové odpovědi API. Obsahuje HTTP stavový kód, typ chyby, lidsky čitelnou zprávu a další diagnostické detaily.
Type: `object`
- `code` (integer; povinné; příklad `400`) — HTTP stavový kód
- `error` (string; povinné; příklad `"BAD_REQUEST"`) — Typ chyby
- `message` (string; povinné; příklad `"Invalid request parameter"`) — Chybová zpráva
- `detail` (string; povinné; příklad ``"The field `payment_instrument` is required"``) — Podrobný popis chyby
- `path` (string; povinné; příklad `"/payments/123/charge"`) — Cesta požadavku
- `timestamp` (string (date-time); povinné; příklad `"2025-12-10T10:30:00Z"`) — Časové razítko chyby
### Encrypted-Card-Input
**Šifrovaný vstup karty**
Varianta `ENCRYPTED_CARD` unie [Payment Card Input](#schema-Payment-Card-Input). Nese kartu zadanou zákazníkem, zašifrovanou klientským SDK GoPay. Je jednorázová a platí deset minut.
Type: `object`
- `input_type` (string = `"ENCRYPTED_CARD"`; povinné; příklad `"ENCRYPTED_CARD"`) — Vždy `ENCRYPTED_CARD`
- `payload` ([JWE](#schema-JWE); povinné) — Zašifrovaná karta
### Refund-Create-Request
**Žádost o vrácení platby**
Částka, která se má vrátit ze zaplacené platby
Type: `object`
- `amount` (integer; povinné; minimum 1; příklad `100`) — Částka k vrácení v haléřích. Pro plné vrácení nastavte na výši platby
### Refund-Details
**Detaily vrácení**
Vrácení provedené k platbě
Type: `object`
- `id` (string; povinné; příklad `"3050123456"`) — ID vrácení
- `state` ([Refund-State](#schema-Refund-State); povinné) — Stav vrácení
- `amount` (integer; povinné; příklad `100`) — Vrácená částka v haléřích
- `currency` ([Currency](#schema-Currency); povinné) — Měna vrácení
- `created_at` (string (date-time); povinné; příklad `"2025-12-10T10:30:00Z"`) — Kdy bylo vrácení vyžádáno
- `updated_at` (string | null (date-time); nepovinné; příklad `"2025-12-10T10:35:00Z"`) — Kdy se naposledy změnil stav vrácení. Null, dokud se stav poprvé nezmění
### Refund-State
**Stav vrácení**
Stav vrácení platby:
- `REQUESTED` - Vrácení bylo přijato a zpracovává se
- `SUCCESS` - Vrácení bylo vypořádáno
- `FAILED` - Vrácení se nepodařilo zpracovat
Type: `string`
Hodnoty: `REQUESTED`, `SUCCESS`, `FAILED`
### Recurrence-Schedule
**Rozvrh opakování**
Jak často opakování typu `AUTO` zakládá platbu
Type: `object`
- `period` (string; povinné; hodnoty: `DAY`, `WEEK`, `MONTH`; příklad `"MONTH"`) — Jednotka, ve které se počítá cyklus
- `cycle` (integer; povinné; minimum 1; příklad `1`) — Počet period mezi dvěma platbami
Příklad:
```json
{
"period": "MONTH",
"cycle": 1
}
```
### Recurrence-Create-Request
**Žádost o založení opakované platby**
Jeden ze dvou druhů opakované platby. Variantu určuje pole `type`, které nabývá hodnot z výčtu [Recurrence Type](#schema-Recurrence-Type). Opakování typu `AUTO` nese `schedule`, typ `ON_DEMAND` ho naopak mít nesmí, protože o každou další platbu si obchodník řekne sám.
Type: `oneOf`
Jedna z: [Recurrence-Create-Auto](#schema-Recurrence-Create-Auto), [Recurrence-Create-On-Demand](#schema-Recurrence-Create-On-Demand)
Diskriminátor: `type` (`AUTO` → [Recurrence-Create-Auto](#schema-Recurrence-Create-Auto), `ON_DEMAND` → [Recurrence-Create-On-Demand](#schema-Recurrence-Create-On-Demand))
### Recurrence-Create-Auto
**Založení opakované platby AUTO**
Varianta `AUTO` unie [Recurrence Create Request](#schema-Recurrence-Create-Request). Platby zakládá GoPay samo podle rozvrhu, takže `schedule` je tady povinné.
Type: `object`
- `type` (string = `"AUTO"`; povinné; příklad `"AUTO"`) — Vždy `AUTO`
- `schedule` ([Recurrence-Schedule](#schema-Recurrence-Schedule); povinné) — Jak často opakování zakládá platbu
- `recurrence_date_to` (string (date); povinné; příklad `"2027-09-04"`) — Poslední den, kdy smí opakování založit platbu, ve tvaru yyyy-MM-dd
- `payment` ([Payment-Create-Request](#schema-Payment-Create-Request); povinné) — Šablona platby, ze které vzniká každá platba tohoto opakování
Příklad:
```json
{
"type": "AUTO",
"schedule": {
"period": "MONTH",
"cycle": 1
},
"recurrence_date_to": "2027-09-04",
"payment": {
"amount": 1500,
"currency": "CZK",
"order_number": "2025010199",
"order_description": "Měsíční předplatné",
"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"
}
}
}
```
### Recurrence-Create-On-Demand
**Založení opakované platby ON_DEMAND**
Varianta `ON_DEMAND` unie [Recurrence Create Request](#schema-Recurrence-Create-Request). Žádný rozvrh neexistuje — o každou další platbu si obchodník řekne operací next — takže `schedule` se posílat nesmí.
Type: `object`
- `type` (string = `"ON_DEMAND"`; povinné; příklad `"ON_DEMAND"`) — Vždy `ON_DEMAND`
- `recurrence_date_to` (string (date); povinné; příklad `"2027-09-04"`) — Poslední den, kdy smí opakování založit platbu, ve tvaru yyyy-MM-dd
- `payment` ([Payment-Create-Request](#schema-Payment-Create-Request); povinné) — Šablona platby, ze které vzniká každá platba tohoto opakování
Příklad:
```json
{
"type": "ON_DEMAND",
"recurrence_date_to": "2027-09-04",
"payment": {
"amount": 1500,
"currency": "CZK",
"order_number": "2025010199",
"order_description": "Měsíční předplatné",
"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"
}
}
}
```
### Recurrence-Details
**Detail opakované platby**
Stav opakované platby a platba, kterou naposledy založila
Type: `object`
- `id` (string; povinné; příklad `"8008013370"`) — Jedinečné ID opakované platby
- `type` ([Recurrence-Type](#schema-Recurrence-Type); povinné) — Zda se platby zakládají podle rozvrhu nebo jen na vyžádání
- `state` ([Recurrence-State](#schema-Recurrence-State); povinné) — Aktuální stav opakované platby
- `schedule` ([Recurrence-Schedule](#schema-Recurrence-Schedule); nepovinné) — Přítomné jen u opakování typu `AUTO`
- `recurrence_date_to` (string (date); povinné; příklad `"2027-09-04"`) — Poslední den, kdy smí opakování založit platbu, ve tvaru yyyy-MM-dd
- `stop_reason` ([Recurrence-Stop-Reason](#schema-Recurrence-Stop-Reason); nepovinné) — Proč se opakování zastavilo — přítomné jen ve stavu `STOPPED`
- `payment` ([Recurrence-Payment](#schema-Recurrence-Payment); povinné) — Platba, kterou opakování nese — než nějaká vznikne, jde o uloženou šablonu
Příklad:
```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"
}
}
}
```
### Recurrence-Payment
**Platba opakování**
Platba, kterou opakování nese. Než se opakování spustí, jde jen o uloženou šablonu; jakmile platba vznikne, doplní se i `id`, `state`, `gw_url` a `payment_secret`.
Type: `object`
- `id` (string; nepovinné; příklad `"7310142951"`) — ID platby. Chybí, dokud opakování nezaložilo platbu
- `state` ([Payment-State](#schema-Payment-State); nepovinné) — Stav založené platby. Chybí, dokud opakování žádnou nezaložilo
- `amount` (integer; povinné; minimum 0; příklad `1500`) — Celková částka v haléřích
- `currency` ([Currency](#schema-Currency); povinné) — Měna platby
- `order_number` (string; povinné; maximální délka 128; příklad `"2025010199"`) — Identifikace objednávky v e-shopu, alfanumerické znaky
- `customer` ([Customer](#schema-Customer); povinné) — Informace o zákazníkovi
- `gw_url` (string; nepovinné; příklad `"https://gate.gopay.com/gw/123456789"`) — Adresa hostované platební brány GoPay, na které zákazník zaplatí založenou platbu. Nejde ji zaintegrovat do vlastního checkoutu obchodníka — viz `Payment Details.gw_url`. Chybí, dokud opakování žádnou nezaložilo
- `payment_secret` (string; nepovinné; příklad `"ps_6aa48c5fadd5ca9ccbc2a30bb13d7e8e"`) — Tajemství, které server obchodníka předá klientskému SDK GoPay, aby SDK mohlo s platbou pracovat. Chybí, dokud opakování nezaložilo platbu. **Nezahrnujte do URL, nelogujte ani neukládejte!**
Příklad:
```json
{
"amount": 1500,
"currency": "CZK",
"order_number": "2025010199",
"customer": {
"email": "john.doe@example.com"
}
}
```
### Recurrence-Type
**Typ opakování**
`AUTO` zakládá platby podle rozvrhu, `ON_DEMAND` jen tehdy, když si obchodník o další platbu řekne.
Type: `string`
Hodnoty: `AUTO`, `ON_DEMAND`
### Recurrence-State
**Stav opakování**
`NEW` po založení, `REQUESTED` jakmile vznikla první platba a čeká se na její zaplacení, `STARTED` po jejím zaplacení, kdy už lze žádat o další platby, a `STOPPED` po ukončení opakování.
Type: `string`
Hodnoty: `NEW`, `REQUESTED`, `STARTED`, `STOPPED`
### Recurrence-Stop-Reason
**Důvod zastavení opakování**
Proč skončilo opakování, které je ve stavu `STOPPED`.
- `RECURRENCE_EXPIRED` - Uplynulo `recurrence_date_to`
- `CARD_EXPIRED` - Autorizované kartě skončila platnost
- `CANCELLED_VIA_API` - Zastaveno přes `DELETE /recurrences/{rec_id}`
- `CANCELLED_VIA_BACKOFFICE` - Zastaveno operátorem GoPay jménem obchodníka
- `CANCELLED_BY_GOPAY` - Zastaveno společností GoPay
- `UNKNOWN` - Důvod není k dispozici
Type: `string`
Hodnoty: `RECURRENCE_EXPIRED`, `CARD_EXPIRED`, `CANCELLED_VIA_API`, `CANCELLED_VIA_BACKOFFICE`, `CANCELLED_BY_GOPAY`, `UNKNOWN`
### Customer-Override
**Přepis zákazníka**
Pole zákazníka, která se pro jednu platbu nahradí. Na rozdíl od `Customer` není povinné žádné — co se vynechá, doplní uložený zákazník opakování, slučuje se po jednotlivých polích. Neznámá pole se odmítají.
Type: `object`
- `email` (string (email); nepovinné; maximální délka 128; příklad `"john.doe@example.com"`) — E-mail zákazníka
- `first_name` (string; nepovinné; maximální délka 256; příklad `"John"`) — Jméno zákazníka
- `last_name` (string; nepovinné; maximální délka 256; příklad `"Doe"`) — Příjmení zákazníka
- `phone_number` (string; nepovinné; maximální délka 128; příklad `"+420123456789"`) — Telefonní číslo zákazníka (pevná linka nebo mobil)
- `city` (string; nepovinné; maximální délka 128; příklad `"Testington"`) — Město z adresy zákazníka
- `street` (string; nepovinné; maximální délka 128; příklad `"Example st. 10"`) — Ulice z adresy zákazníka
- `postal_code` (string; nepovinné; maximální délka 128; příklad `"10000"`) — PSČ z adresy zákazníka
- `country_code` (string; nepovinné; maximální délka 128; příklad `"CZE"`) — Kód země zákazníka podle [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
- `customer_id` (string; nepovinné; maximální délka 128; příklad `"customer420"`) — Jedinečné ID zákazníka (slouží k přizpůsobení checkoutu)
Příklad:
```json
{
"first_name": "John",
"last_name": "Doe"
}
```
### Payment-Instance-Override
**Přepis jedné platby**
Pole, která pro jednu platbu nahradí uloženou šablonu platby daného opakování. Vynechaná pole si ponechají uloženou hodnotu; `customer` se slučuje po jednotlivých polích, ne nahrazuje celý. Neznámá pole se odmítají.
Type: `object`
- `amount` (integer; nepovinné; minimum 0; příklad `9900`) — Celková částka v haléřích
- `order_number` (string; nepovinné; maximální délka 128; příklad `"2025010199"`) — Identifikace objednávky v e-shopu, alfanumerické znaky
- `order_description` (string; nepovinné; příklad `"Testovací objednávka"`) — Popis objednávky, alfanumerické znaky
- `additional_params` (array of [Additional-Param](#schema-Additional-Param); nepovinné; maximální počet položek 4) — Doplňkové parametry platby
- `customer` ([Customer-Override](#schema-Customer-Override); nepovinné) — Pole zákazníka, která se nahradí; vynechaná si ponechají uloženou hodnotu
- `callback` ([Payment-Callback](#schema-Payment-Callback); nepovinné) — URL pro návratové přesměrování a pro notifikace
Příklad:
```json
{
"amount": 9900,
"order_number": "2025010199",
"order_description": "Testovací objednávka",
"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"
}
}
```
### Link-Create-Request
**Žádost o vytvoření platebního odkazu**
Údaje platby, které nový platební odkaz nese, jeho platnost a to, zda ho lze použít víckrát
Type: `object`
- `payment` ([Payment-From-Link-Request](#schema-Payment-From-Link-Request); povinné) — Údaje platby použité pro každou platbu, kterou tento odkaz vytvoří
- `expires_in` (integer; nepovinné; minimum 1; příklad `3600`) — Životnost odkazu v sekundách od jeho vytvoření. Bez ní odkaz nevyprší. Horní hranice je sto let
- `reusable` (boolean; nepovinné; výchozí `true`; příklad `true`) — Zda odkaz smí založit více než jednu platbu. Jednorázový odkaz se spotřebuje první návštěvou, viz `Důvod zneplatnění odkazu`
### Link-Details
**Detail platebního odkazu**
Platební odkaz, jeho stav a údaje platby, které nese
Type: `object`
- `id` (string; povinné; příklad `"3405871122"`) — ID odkazu, které se používá při dotazu na stav a při zneplatnění. Není to kód z `url`
- `url` (string; povinné; příklad `"https://gate.gopay.com/gp-gw/l/Xk8mQ2pR7t"`) — Adresa ke sdílení se zákazníkem. Jejím otevřením vznikne platba a zákazník je přesměrován na platební bránu. Končí náhodným desetiznakovým kódem, který s `id` nesouvisí
- `active` (boolean; povinné; příklad `true`) — Zda odkazem stále lze založit platbu. Po expiraci se vrací false i dřív, než se to zapíše
- `reusable` (boolean; povinné; příklad `true`) — Zda odkaz smí založit více než jednu platbu
- `expires_at` (string (date-time); nepovinné; příklad `"2026-08-18T14:35:12Z"`) — Okamžik, kdy odkaz přestává být použitelný. Dopočítán při vytvoření z `expires_in`. U odkazu bez expirace chybí
- `stop_reason` ([Link-Stop-Reason](#schema-Link-Stop-Reason); nepovinné) — Důvod, proč odkaz už není aktivní. U aktivního odkazu se nevrací
- `payment` ([Payment-From-Link-Request](#schema-Payment-From-Link-Request); nepovinné) — Údaje platby, které odkaz nese
### Link-Stop-Reason
**Důvod zneplatnění odkazu**
Proč platební odkaz už není aktivní:
- `FROM_API` - Obchodník odkaz zneplatnil
- `USED` - Jednorázový odkaz byl otevřen a založil svoji platbu
- `EXPIRED` - Odkaz překročil své `expires_at`
Type: `string`
Hodnoty: `FROM_API`, `USED`, `EXPIRED`
### Payment-From-Link-Request
**Platba z platebního odkazu**
Popis platby zakládané z platebního odkazu. Stejné údaje se použijí pro každou platbu, kterou odkaz vytvoří — u opakovaně použitelného odkazu tak všechny platby sdílejí stejné `order_number` i stejnou `notification_url`.
Type: `object`
- `amount` (integer; povinné; minimum 0; příklad `15000`) — Celková částka v haléřích
- `currency` ([Currency](#schema-Currency); povinné) — Měna platby. Musí jít o měnu, pro kterou má eshop povolený platební kanál, jinak je odkaz odmítnut s `400`
- `order_number` (string; povinné; maximální délka 128; příklad `"2026-00042"`) — Identifikace objednávky v e-shopu, alfanumerické znaky
- `order_description` (string; nepovinné; maximální délka 256; příklad `"Faktura 2026-00042"`) — Popis objednávky, alfanumerické znaky
- `additional_params` (array of [Additional-Param](#schema-Additional-Param); nepovinné; maximální počet položek 4) — Doplňkové parametry platby. Žádné `name` nesmí obsahovat `=` a `name` s `value` dohromady nesmí přesáhnout 511 znaků
- `customer` ([Customer](#schema-Customer); povinné) — Údaje o zákazníkovi. E-mailová adresa je povinná
- `callback` ([Payment-Callback](#schema-Payment-Callback); povinné) — URL pro návratové přesměrování a pro notifikace. `return_url` je povinná, `notification_url` nepovinná. Každá musí být http nebo https a nejvýše 512 znaků dlouhá
Příklad:
```json
{
"amount": 15000,
"currency": "CZK",
"order_number": "2026-00042",
"order_description": "Faktura 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"
}
}
```
### Validate-Merchant-Request
**Žádost o ověření obchodníka**
Žádost o ověření obchodníka pro Apple Pay
Type: `object`
- `validationUrl` (string (uri); povinné; příklad `"https://apple-pay-gateway.apple.com/paymentservices/paymentSession"`) — Validační URL, kterou Apple Pay vydal pro relaci
### Validate-Merchant-Response
**Odpověď na ověření obchodníka**
Objekt merchant session, který Apple Pay očekává; předává se platebnímu oknu Apple Pay beze změny
Type: `object`
### Event
**Událost**
Jedna z událostí, které GoPay zaznamenává. Variantu určuje pole `type`, které nabývá hodnot z výčtu [Event Type](#schema-Event-Type). Typ, který kód obchodníka nezná, se ignoruje a nepovažuje za chybu, aby nový typ nerozbil funkční integraci.
Type: `oneOf`
Jedna z: [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)
Diskriminátor: `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))
Příklad:
```json
{
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"type": "payments.paid",
"occurred_at": "2026-07-08T12:04:39.123Z",
"data": {
"payment_id": "300000001",
"charge_id": "9123456789"
}
}
```
### Event-Type
**Typ události**
Hodnoty pole, které určuje variantu [Event](#schema-Event)
Type: `string`
Hodnoty: `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`
### Payment-Paid-Event
**Událost zaplacení platby**
Varianta `payments.paid` unie [Event](#schema-Event). Platba přešla do `PAID`.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `payments.paid`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Payment-Paid-Data](#schema-Payment-Paid-Data); povinné) — Identifikátory entit, kterých se událost týká
### Payment-Canceled-Event
**Událost zrušení platby**
Varianta `payments.canceled` unie [Event](#schema-Event). Platba přešla do `CANCELED`: zákazník ji opustil, stržení bylo zamítnuto při autorizaci, nebo ji obchodník zrušil dříve, než byla stržena.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `payments.canceled`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Payment-Event-Data](#schema-Payment-Event-Data); povinné) — Identifikátory entit, kterých se událost týká
### Payment-Timeouted-Event
**Událost vypršení platby**
Varianta `payments.timeouted` unie [Event](#schema-Event). Platba nedospěla do koncového stavu ve své lhůtě.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `payments.timeouted`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Payment-Event-Data](#schema-Payment-Event-Data); povinné) — Identifikátory entit, kterých se událost týká
### Link-Payment-Created-Event
**Událost vzniku platby z odkazu**
Varianta `links.payment_created` unie [Event](#schema-Event). Zákazník otevřel platební odkaz a vznikla z něj platba.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `links.payment_created`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Link-Payment-Created-Data](#schema-Link-Payment-Created-Data); povinné) — Identifikátory entit, kterých se událost týká
### Link-Disabled-Event
**Událost deaktivace odkazu**
Varianta `links.disabled` unie [Event](#schema-Event). Obchodník deaktivoval platební odkaz.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `links.disabled`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Link-Event-Data](#schema-Link-Event-Data); povinné) — Identifikátory entit, kterých se událost týká
### Refund-Succeeded-Event
**Událost úspěšného vrácení platby**
Varianta `refunds.succeeded` unie [Event](#schema-Event). Vrácení platby bylo vypořádáno.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `refunds.succeeded`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Refund-Event-Data](#schema-Refund-Event-Data); povinné) — Identifikátory entit, kterých se událost týká
### Refund-Failed-Event
**Událost neúspěšného vrácení platby**
Varianta `refunds.failed` unie [Event](#schema-Event). Vrácení platby se nepodařilo vypořádat.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `refunds.failed`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Refund-Event-Data](#schema-Refund-Event-Data); povinné) — Identifikátory entit, kterých se událost týká
### Recurrence-Started-Event
**Událost spuštění opakovaného předpisu**
Varianta `recurrences.started` unie [Event](#schema-Event). Opakovaný předpis byl aktivován platbou uvedenou v `data`.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `recurrences.started`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Recurrence-Payment-Data](#schema-Recurrence-Payment-Data); povinné) — Identifikátory entit, kterých se událost týká
### Recurrence-Payment-Created-Event
**Událost vzniku platby z opakovaného předpisu**
Varianta `recurrences.payment_created` unie [Event](#schema-Event). Z opakovaného předpisu vznikla naplánovaná platba.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `recurrences.payment_created`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Recurrence-Payment-Data](#schema-Recurrence-Payment-Data); povinné) — Identifikátory entit, kterých se událost týká
### Recurrence-Stopped-Event
**Událost zastavení opakovaného předpisu**
Varianta `recurrences.stopped` unie [Event](#schema-Event). Opakovaný předpis byl zastaven.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `recurrences.stopped`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Recurrence-Event-Data](#schema-Recurrence-Event-Data); povinné) — Identifikátory entit, kterých se událost týká
### Card-Updated-Event
**Událost změny uložené karty**
Varianta `cards.updated` unie [Event](#schema-Event). Uložený karetní token se změnil, například poté, co vydavatel kartu znovu vydal.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `cards.updated`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Card-Event-Data](#schema-Card-Event-Data); povinné) — Identifikátory entit, kterých se událost týká
### Card-Deleted-Event
**Událost smazání uložené karty**
Varianta `cards.deleted` unie [Event](#schema-Event). Uložený karetní token byl smazán.
Type: `object`
- `id` (string; povinné; příklad `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity
- `type` ([Event-Type](#schema-Event-Type); povinné) — Vždy `cards.deleted`
- `occurred_at` (string (date-time); povinné; příklad `"2026-07-08T12:04:39.123Z"`) — Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy
- `data` ([Card-Event-Data](#schema-Card-Event-Data); povinné) — Identifikátory entit, kterých se událost týká
### Payment-Paid-Data
**Data zaplacení platby**
Identifikuje platbu, a pokud ji zaplatilo stržení, i toto stržení.
Type: `object`
- `payment_id` (string; povinné; příklad `"300000001"`) — Identifikátor platby
- `charge_id` (string; nepovinné; příklad `"9123456789"`) — Identifikátor stržení, kterým byla platba zaplacena. Chybí, pokud platbu nezaplatilo stržení, například na hostované bráně na `gw_url`
### Payment-Event-Data
**Data události platby**
Identifikuje platbu, které se událost týká.
Type: `object`
- `payment_id` (string; povinné; příklad `"300000001"`) — Identifikátor platby
### Link-Payment-Created-Data
**Data vzniku platby z odkazu**
Identifikuje platební odkaz a platbu, která z něj vznikla.
Type: `object`
- `link_id` (string; povinné; příklad `"346346346"`) — Identifikátor platebního odkazu
- `payment_id` (string; povinné; příklad `"300000001"`) — Identifikátor platby
### Link-Event-Data
**Data události odkazu**
Identifikuje platební odkaz, kterého se událost týká.
Type: `object`
- `link_id` (string; povinné; příklad `"346346346"`) — Identifikátor platebního odkazu
### Refund-Event-Data
**Data události vrácení platby**
Identifikuje vrácení platby a platbu, ke které patří.
Type: `object`
- `payment_id` (string; povinné; příklad `"300000001"`) — Identifikátor platby
- `refund_id` (string; povinné; příklad `"3050123456"`) — Identifikátor vrácení platby
### Recurrence-Payment-Data
**Data platby z opakovaného předpisu**
Identifikuje opakovaný předpis a platbu, které se událost týká. U `recurrences.started` jde o platbu, která předpis spustila; u `recurrences.payment_created` o nově vzniklou platbu.
Type: `object`
- `recurrence_id` (string; povinné; příklad `"5521002"`) — Identifikátor opakovaného předpisu
- `payment_id` (string; povinné; příklad `"300000001"`) — Identifikátor platby
### Recurrence-Event-Data
**Data události opakovaného předpisu**
Identifikuje opakovaný předpis, kterého se událost týká.
Type: `object`
- `recurrence_id` (string; povinné; příklad `"5521002"`) — Identifikátor opakovaného předpisu
### Card-Event-Data
**Data události uložené karty**
Identifikuje uložený karetní token, kterého se událost týká. Karetní tokeny patří obchodníkovi a jsou sdílené mezi jeho e-shopy.
Type: `object`
- `card_id` (string; povinné; příklad `"8007127320"`) — Identifikátor uloženého karetního tokenu
### Event-List
**Seznam událostí**
Jedna stránka událostí e-shopu, od nejnovější
Type: `object`
- `items` (array of [Event](#schema-Event); povinné) — Události na této stránce
- `next_page_url` (string (uri); nepovinné; příklad `"https://gate.gopay.com/gp-gw/api/4.0/eshops/8123456789/events?type=refunds.*&max_items=20&prev_item=01H8ZQ7X9K4Q0M2V6T8B3C5D7E"`) — Úplná adresa následující stránky, nesoucí filtry požadavku a `id` poslední události
této stránky jako pozici, od které se pokračuje. Chybí, pokud další odpovídající
událost neexistuje.
### JWK-Set
**Sada JWK**
Sada veřejných klíčů obsahující aktuálně používané podpisové klíče webhooků. Je formátovaná podle RFC 7517: JSON Web Key Set (JWK Set)
Type: `object`
- `keys` (array of [Signing-JWK](#schema-Signing-JWK); povinné) — Aktuálně používané podpisové klíče webhooků
### Signing-JWK
**Podpisový JWK**
Struktura veřejného podpisového klíče webhooků. Je formátovaná podle RFC 7517: JSON Web Key (JWK)
Type: `object`
- `kty` (string = `"RSA"`; povinné; příklad `"RSA"`) — Typ klíče. U podpisových klíčů GoPay vždy `RSA`.
- `use` (string = `"sig"`; povinné; příklad `"sig"`) — Použití klíče. Vždy `sig` (podpis).
- `kid` (string; povinné; příklad `"sign-2026-02"`) — ID klíče. Odpovídá `kid` v chráněné hlavičce `X-GoPay-Signature`, kterou klíč ověřuje
- `alg` (string = `"RS256"`; povinné; příklad `"RS256"`) — Algoritmus, kterým byl podpis vytvořen. Vždy `RS256`.
- `n` (string; povinné; příklad `"4JHqz4QwbiVuVzLhjJwwgK_EC86qVTPhQIpmiQCoGNzLBQlsBdt13Y10AlzRSMMF65LyF5Y8doKR-gJlCR9J5P9YPr1IgU0wVyqJ349yL7O_lMWy5TfWdGz7KOrq9tyHVtjH0i5ztAIQHPvQ02LayjdNgUA4Z8RxFsSz03nCU-dJLJOg63BS23VfxEs4J_kmbITSACIxiIAerc-wUwIQkjlHyHQQtac7kcCQfSqDB3F2YqxFkWOC66drt2zcMutjxcK-ZcnjdBiQnTI_9izbJB9mX4CoErMWre7GNt_krHoi6OP6DoOvjEsABAS2Dyf13xLuNVH-QHpCUaYqR70OTQ"`) — Modul veřejného klíče `RSA`.
- `e` (string; povinné; výchozí `"AQAB"`; příklad `"AQAB"`) — Exponent veřejného klíče `RSA`.
Příklad:
```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"
}
```