openapi: 3.1.0
info:
  version: '4.0'
  title: Platby
  summary: Vytvářet a spravovat platby
  description: >-
    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í.
  contact:
    name: Technická podpora GoPay
    email: integration@gopay.com
servers:
  - url: 'https://gw.sandbox.gopay.com/gp-gw/api/4.0'
    description: Sandbox
  - url: 'https://gate.gopay.com/gp-gw/api/4.0'
    description: Produkce
tags:
  - name: Autentizace
    description: >-
      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í.
  - name: Platby
    description: >-
      Založení platby, její stržení platebním prostředkem a sledování až do koncového
      stavu.
  - name: Vrácení plateb
    description: >-
      Vrácení prostředků ze zaplacené platby zákazníkovi a přehled vrácení, která k dané
      platbě patří.
  - name: Platební odkazy
    description: >-
      Platební odkazy, které nesou údaje platby a zakládají ji teprve ve chvíli, kdy je
      zákazník otevře.
  - name: Opakované platby
    description: >-
      Opakované platby, které drží šablonu platby a zakládají z ní platby buď podle rozvrhu,
      nebo když si obchodník o další řekne.
  - name: Karty
    description: >-
      Uložené tokeny karet, které zastupují kartu zákazníka při pozdějších strženích.
  - name: Události
    description: >-
      Log událostí e-shopu a veřejné klíče, kterými se ověřuje podpis webhooku.
  - name: Služby SDK
    description: >-
      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.
paths:
  /oauth2/token:
    post:
      tags:
        - Autentizace
      summary: Přihlášení
      description: |-
        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í.
      operationId: post-oauth2-token
      requestBody:
        required: true
        $ref: '#/components/requestBodies/Access-Token-Request'
      responses:
        '200':
          description: Přístupový token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Access-Token'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - basic: []
  '/eshops/{goid}/payments':
    post:
      tags:
        - Platby
      summary: Vytvoření platby
      description: |-
        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`.
      operationId: post-eshops-goid-payments
      responses:
        '201':
          description: Nová platba
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment-Details'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment-Create-Request'
      security:
        - merchant_credentials:
            - 'payment:write'
    parameters:
      - schema:
          type: string
        name: goid
        in: path
        required: true
        description: Jedinečný identifikátor registrovaného webu obchodníka
  '/payments/{payment_id}':
    get:
      tags:
        - Platby
      summary: Stav platby
      description: |-
        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.
      operationId: get-payments-payment_id
      responses:
        '200':
          description: Platba
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment-Details'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:read'
        - payment_credentials:
            - 'payment:read'
    delete:
      tags:
        - Platby
      summary: Zrušení platby
      description: |-
        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á.
      operationId: delete-payments-payment_id
      responses:
        '204':
          description: Hotovo; odpověď nemá tělo
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:write'
    parameters:
      - schema:
          type: string
        name: payment_id
        in: path
        required: true
        description: Identifikátor platby, `Payment Details.id`
  '/payments/{payment_id}/charge':
    post:
      tags:
        - Platby
      summary: Stržení platby
      description: |-
        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čí.
      operationId: post-payments-payment_id-charge
      responses:
        '201':
          description: Zahájené stržení
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment-Charge-Response'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment-Charge-Input'
      security:
        - merchant_credentials:
            - 'payment:write'
        - payment_credentials:
            - 'payment:charge'
    get:
      tags:
        - Platby
      summary: Stav stržení platby
      description: |-
        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`.
      operationId: get-payments-payment_id-charge
      responses:
        '200':
          description: Aktuální stav stržení platby
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment-Charge-Status-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:read'
        - payment_credentials:
            - 'payment:read'
    parameters:
      - schema:
          type: string
        name: payment_id
        in: path
        required: true
        description: Identifikátor platby, `Payment Details.id`
  '/payments/{payment_id}/qr-payment/info':
    get:
      tags:
        - Platby
      summary: Informace o QR platbě
      description: |-
        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í.
      operationId: get-payments-payment_id-qr-payment-info
      parameters:
        - name: format
          in: query
          description: Obrazový formát generovaného QR kódu
          schema:
            type: string
            enum:
              - png
              - svg
            default: png
            examples:
              - png
      responses:
        '200':
          description: Údaje QR platby pro tuto platbu
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QR-Payment-Details'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:read'
        - payment_credentials:
            - 'payment:read'
    parameters:
      - schema:
          type: string
        name: payment_id
        in: path
        required: true
        description: Identifikátor platby, `Payment Details.id`
  '/payments/{payment_id}/google-pay/info':
    get:
      tags:
        - Služby SDK
      summary: Informace o platbě Google Pay
      description: |-
        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`.
      operationId: get-payments-payment_id-info-google-pay
      responses:
        '200':
          $ref: '#/components/responses/Google-Pay-Info-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - payment_credentials:
            - 'payment:read'
        - merchant_credentials:
            - 'payment:read'
    parameters:
      - schema:
          type: string
        name: payment_id
        in: path
        required: true
        description: Identifikátor platby, `Payment Details.id`
  '/payments/{payment_id}/apple-pay/info':
    get:
      tags:
        - Služby SDK
      summary: Informace o platbě Apple Pay
      description: |-
        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á.
      operationId: get-payments-payment_id-info-apple-pay
      responses:
        '200':
          $ref: '#/components/responses/Apple-Pay-Info-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - payment_credentials:
            - 'payment:read'
        - merchant_credentials:
            - 'payment:read'
    parameters:
      - schema:
          type: string
        name: payment_id
        in: path
        required: true
        description: Identifikátor platby, `Payment Details.id`
  '/payments/{payment_id}/apple-pay/app-info':
    get:
      tags:
        - Služby SDK
      summary: Informace o platbě Apple Pay pro aplikace
      description: |-
        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á.
      operationId: get-payments-payment_id-apple-pay-app-info
      responses:
        '200':
          $ref: '#/components/responses/Apple-Pay-App-Info-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - payment_credentials:
            - 'payment:read'
        - merchant_credentials:
            - 'payment:read'
    parameters:
      - schema:
          type: string
        name: payment_id
        in: path
        required: true
        description: Identifikátor platby, `Payment Details.id`
  '/payments/{payment_id}/apple-pay/validate':
    post:
      tags:
        - Služby SDK
      summary: Ověření obchodníka
      description: |-
        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á.
      operationId: post-payments-payment_id-apple-pay-validate
      parameters:
        - name: Origin
          in: header
          description: Původ stránky, na které je zobrazeno tlačítko Apple Pay. Prohlížeč ho přidá automaticky
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Merchant session pro platební okno Apple Pay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Validate-Merchant-Response'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - payment_credentials:
            - 'payment:read'
        - merchant_credentials:
            - 'payment:read'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Validate-Merchant-Request'
    parameters:
      - schema:
          type: string
        name: payment_id
        in: path
        required: true
        description: Identifikátor platby, `Payment Details.id`
  '/payments/{payment_id}/refunds':
    post:
      tags:
        - Vrácení plateb
      summary: Vrácení platby
      description: |
        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.
      operationId: post-payments-payment_id-refunds
      responses:
        '201':
          description: Nové vrácení
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund-Details'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Refund-Create-Request'
      security:
        - merchant_credentials:
            - 'payment:write'
    get:
      tags:
        - Vrácení plateb
      summary: Seznam vrácení platby
      description: Vrátí všechna vrácení provedená k dané platbě.
      operationId: get-payments-payment_id-refunds
      responses:
        '200':
          description: Vrácení platby
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Refund-Details'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:read'
        - payment_credentials:
            - 'payment:read'
    parameters:
      - schema:
          type: string
        name: payment_id
        in: path
        required: true
        description: Identifikátor platby, `Payment Details.id`
  '/refunds/{refund_id}':
    get:
      tags:
        - Vrácení plateb
      summary: Detail vrácení
      description: Vrátí aktuální stav a částku jednoho vrácení.
      operationId: get-refunds-refund_id
      responses:
        '200':
          description: Vrácení
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund-Details'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:read'
    parameters:
      - schema:
          type: string
        name: refund_id
        in: path
        required: true
        description: Identifikátor vrácení
  '/eshops/{goid}/recurrences':
    post:
      tags:
        - Opakované platby
      summary: Založení opakované platby
      description: >-
        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.
      operationId: post-eshops-goid-recurrences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Recurrence-Create-Request'
      responses:
        '201':
          description: Nová opakovaná platba
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recurrence-Details'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:write'
    parameters:
      - schema:
          type: string
        name: goid
        in: path
        required: true
        description: Jedinečný identifikátor registrovaného webu obchodníka
  '/recurrences/{rec_id}':
    get:
      tags:
        - Opakované platby
      summary: Stav opakované platby
      description: Vrátí aktuální stav opakované platby a platbu, kterou naposledy založila.
      operationId: get-recurrences-rec_id
      responses:
        '200':
          description: Opakovaná platba
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recurrence-Details'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:read'
    delete:
      tags:
        - Opakované platby
      summary: Zastavení opakované platby
      description: >-
        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.
      operationId: delete-recurrences-rec_id
      responses:
        '204':
          description: Hotovo; odpověď nemá tělo
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:write'
    parameters:
      - schema:
          type: string
        name: rec_id
        in: path
        required: true
        description: Jedinečné ID dříve založené opakované platby
  '/recurrences/{rec_id}/start':
    post:
      tags:
        - Opakované platby
      summary: Spuštění opakované platby
      description: >-
        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.
      operationId: post-recurrences-rec_id-start
      requestBody:
        description: Pole, která se pro tuto jednu platbu přepíšou
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment-Instance-Override'
      responses:
        '201':
          description: Nová platba
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment-Details'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:write'
    parameters:
      - schema:
          type: string
        name: rec_id
        in: path
        required: true
        description: Jedinečné ID dříve založené opakované platby
  '/recurrences/{rec_id}/next':
    post:
      tags:
        - Opakované platby
      summary: Založení další platby opakování
      description: >-
        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.
      operationId: post-recurrences-rec_id-next
      requestBody:
        description: Pole, která se pro tuto jednu platbu přepíšou
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment-Instance-Override'
      responses:
        '201':
          description: Nová platba
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment-Details'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:write'
    parameters:
      - schema:
          type: string
        name: rec_id
        in: path
        required: true
        description: Jedinečné ID dříve založené opakované platby
  '/eshops/{goid}/links':
    post:
      tags:
        - Platební odkazy
      summary: Vytvoření platebního odkazu
      description: |-
        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.
      operationId: post-eshops-goid-links
      responses:
        '201':
          description: Nový platební odkaz
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link-Details'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Link-Create-Request'
      security:
        - merchant_credentials:
            - 'payment:write'
    parameters:
      - schema:
          type: string
        name: goid
        in: path
        required: true
        description: Jedinečný identifikátor registrovaného webu obchodníka
  '/eshops/{goid}/links/{link_id}':
    get:
      tags:
        - Platební odkazy
      summary: Stav platebního odkazu
      description: |-
        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.
      operationId: get-eshops-goid-links-link_id
      responses:
        '200':
          description: Platební odkaz
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link-Details'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:read'
    delete:
      tags:
        - Platební odkazy
      summary: Zneplatnění odkazu
      description: |-
        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ě.
      operationId: delete-eshops-goid-links-link_id
      responses:
        '204':
          description: Hotovo; odpověď nemá tělo
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'payment:write'
    parameters:
      - schema:
          type: string
        name: goid
        in: path
        required: true
        description: Jedinečný identifikátor registrovaného webu obchodníka
      - schema:
          type: string
          pattern: '^[0-9]+$'
        name: link_id
        in: path
        required: true
        description: 'ID odkazu vrácené při jeho vytvoření. Nečíselná nebo záporná hodnota je odmítnuta s `400`'
  /cards/tokens:
    post:
      tags:
        - Karty
      summary: Vytvoření tokenu karty
      description: |-
        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á.
      operationId: post-cards-tokens
      responses:
        '201':
          description: Nový token uložené karty
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Permanent-Card-Token-Details'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '409':
          $ref: '#/components/responses/Conflict-409-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Token-Create-Request'
      security:
        - merchant_credentials:
            - 'card:write'
  '/cards/tokens/{card_id}':
    get:
      tags:
        - Karty
      summary: Detaily karty
      description: |-
        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á.
      operationId: get-cards-tokens-card_id
      parameters:
        - name: card_id
          in: path
          required: true
          description: ID uložené platební karty
          schema:
            type: string
      responses:
        '200':
          description: Uložená karta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Permanent-Card-Token-Details'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'card:read'
    delete:
      tags:
        - Karty
      summary: Smazání karty
      description: |-
        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á.
      operationId: delete-cards-tokens-card_id
      parameters:
        - name: card_id
          in: path
          required: true
          description: ID uložené platební karty
          schema:
            type: string
      responses:
        '204':
          description: Hotovo; odpověď nemá tělo
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'card:write'
    parameters:
      - schema:
          type: string
        name: card_id
        in: path
        required: true
        description: ID uložené platební karty
  /cards/public-key:
    get:
      tags:
        - Služby SDK
      summary: Získání veřejného klíče
      description: |-
        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á.
      operationId: get-encryption-public-key
      responses:
        '200':
          description: Veřejný šifrovací klíč
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWK'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - shareable_key: []
        - merchant_credentials:
            - 'shared:read'
  /cards/card-form-url:
    get:
      tags:
        - Služby SDK
      summary: URL formuláře karty
      description: |-
        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á.
      operationId: get-card-form-url
      responses:
        '200':
          description: URL hostovaného formuláře karty
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card-Form-URL'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - shareable_key: []
        - merchant_credentials:
            - 'shared:read'
  /cards/browser-data:
    get:
      tags:
        - Služby SDK
      summary: Získání dat prohlížeče
      description: |-
        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.
      operationId: get-browser-data
      responses:
        '200':
          description: Data prohlížeče odvozená z requestu
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Browser-Data-Detected'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - shareable_key: []
  '/eshops/{goid}/events':
    get:
      tags:
        - Události
      summary: Seznam událostí
      description: |-
        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í.
      operationId: get-eshops-goid-events
      parameters:
        - name: max_items
          in: query
          description: Nejvyšší počet událostí na jedné stránce
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            examples:
              - 20
        - name: prev_item
          in: query
          description: |-
            `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.
          schema:
            type: string
            examples:
              - 01H8ZQ7X9K4Q0M2V6T8B3C5D7E
        - name: type
          in: query
          description: |-
            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.
          schema:
            type: string
            examples:
              - 'refunds.succeeded,refunds.failed,payments.*'
        - name: occurred_after
          in: query
          description: '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ší'
          schema:
            type: string
            format: date-time
            examples:
              - '2026-07-01T00:00:00Z'
        - name: occurred_before
          in: query
          description: Zahrne události, které nastaly před tímto okamžikem
          schema:
            type: string
            format: date-time
            examples:
              - '2026-08-01T00:00:00Z'
        - name: related_type
          in: query
          description: 'Druh entity, na kterou `related_id` odkazuje. Vyžadováno společně s `related_id`'
          schema:
            type: string
            enum:
              - payments
              - links
              - refunds
              - recurrences
              - cards
            examples:
              - payments
        - name: related_id
          in: query
          description: |-
            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`.
          schema:
            type: string
            examples:
              - '300000001'
      responses:
        '200':
          description: Jedna stránka událostí e-shopu, od nejnovější
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event-List'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'event:read'
    parameters:
      - schema:
          type: string
          examples:
            - '8123456789'
        name: goid
        in: path
        required: true
        description: Jedinečný identifikátor registrovaného webu obchodníka
  '/eshops/{goid}/events/{event_id}':
    get:
      tags:
        - Události
      summary: Detail události
      description: Vrátí jednu událost e-shopu podle jejího `id`.
      operationId: get-eshops-goid-events-event_id
      responses:
        '200':
          description: Událost
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '400':
          $ref: '#/components/responses/Bad-Request-400-Response'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '404':
          $ref: '#/components/responses/Not-Found-404-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - merchant_credentials:
            - 'event:read'
    parameters:
      - schema:
          type: string
          examples:
            - '8123456789'
        name: goid
        in: path
        required: true
        description: Jedinečný identifikátor registrovaného webu obchodníka
      - schema:
          type: string
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        name: event_id
        in: path
        required: true
        description: Identifikátor události
  /webhooks/public-keys:
    get:
      tags:
        - Události
      summary: Podpisové klíče webhooků
      description: |-
        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.
      operationId: get-webhooks-public-keys
      responses:
        '200':
          description: Podpisové klíče webhooků, které se právě používají
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWK-Set'
        '401':
          $ref: '#/components/responses/Unauthorized-401-Response'
        '403':
          $ref: '#/components/responses/Forbidden-403-Response'
        '500':
          $ref: '#/components/responses/Internal-Server-Error-500-Response'
      security:
        - shareable_key: []
        - merchant_credentials:
            - 'shared:read'
components:
  requestBodies:
    Access-Token-Request:
      required: true
      content:
        application/x-www-form-urlencoded:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Client-Credentials-Request'
              - $ref: '#/components/schemas/Payment-Credentials-Request'
          examples:
            Client Credentials:
              value:
                grant_type: client_credentials
                scope: 'payment:write payment:read'
  securitySchemes:
    basic:
      type: http
      description: |-
        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).
      scheme: basic
    merchant_credentials:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            'card:write': Ukládání a mazání tokenů karet
            'card:read': Čtení uložených tokenů karet
            'payment:write': 'Zakládání, strhávání, rušení a úpravy plateb a zdrojů, které na nich stojí'
            'payment:read': 'Čtení plateb a zdrojů, které na nich stojí'
            'event:read': Čtení událostí e-shopu
            'shared:read': 'Čtení veřejných zdrojů, jako jsou veřejné klíče, URL a hodnoty odvozené z requestu'
          tokenUrl: /oauth2/token
      description: |-
        Autorizuje server obchodníka pomocí `client_id:client_secret`.
        Tajný klíč ani JWT nesmí nikdy opustit server obchodníka.
    payment_credentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes:
            'payment:read': Čtení platby
            'payment:charge': Stržení platby
      description: |-
        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:
      type: http
      scheme: basic
      description: |-
        `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).
  responses:
    Google-Pay-Info-Response:
      description: Konfigurace platebního požadavku Google Pay zpracovávaná tlačítkem Google Pay
      content:
        application/json:
          schema:
            type: object
            properties:
              environment:
                description: 'Prostředí Google Pay, ve kterém platba probíhá: `TEST` v sandboxu, `PRODUCTION` v produkci'
                type: string
                enum:
                  - TEST
                  - PRODUCTION
                examples:
                  - TEST
              paymentDataRequest:
                description: 'Objekt Google Pay `PaymentDataRequest` předávaný do Google Pay API'
                type: object
                properties:
                  apiVersion:
                    description: Hlavní verze Google Pay API
                    type: integer
                    examples:
                      - 2
                  apiVersionMinor:
                    description: Vedlejší verze Google Pay API
                    type: integer
                    examples:
                      - 0
                  allowedPaymentMethods:
                    description: Platební metody, které platební okno Google Pay nabízí
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          description: Typ platební metody
                          type: string
                          examples:
                            - CARD
                        parameters:
                          description: Přijímané způsoby ověření karty a karetní sítě
                          type: object
                          properties:
                            allowedAuthMethods:
                              description: Přijímané způsoby ověření karty
                              examples:
                                - - PAN_ONLY
                                  - CRYPTOGRAM_3DS
                              type: array
                              items:
                                type: string
                                enum:
                                  - PAN_ONLY
                                  - CRYPTOGRAM_3DS
                            allowedCardNetworks:
                              description: Přijímané karetní sítě
                              examples:
                                - - MASTERCARD
                                  - VISA
                              type: array
                              items:
                                type: string
                                enum:
                                  - VISA
                                  - MASTERCARD
                        tokenizationSpecification:
                          description: Jak Google Pay šifruje platební data pro GoPay
                          type: object
                          properties:
                            type:
                              description: Typ tokenizace
                              type: string
                              examples:
                                - PAYMENT_GATEWAY
                            parameters:
                              description: Parametry brány
                              type: object
                              properties:
                                gateway:
                                  description: Identifikátor brány registrovaný u Google Pay
                                  type: string
                                  examples:
                                    - gopay
                                gatewayMerchantId:
                                  description: Identifikátor obchodníka u brány
                                  type: string
                                  examples:
                                    - '26046768005768011132'
                  transactionInfo:
                    description: Částka a měna zobrazené v platebním okně Google Pay
                    type: object
                    properties:
                      currencyCode:
                        description: Měna platby
                        $ref: '#/components/schemas/Currency'
                      countryCode:
                        description: Kód země obchodníka dle ISO 3166-1 alpha-2
                        type: string
                        examples:
                          - CZ
                      totalPriceStatus:
                        description: Zda je celková částka konečná
                        type: string
                        examples:
                          - FINAL
                      totalPrice:
                        description: Celková částka jako desetinný řetězec
                        type: string
                        examples:
                          - '5.00'
                  merchantInfo:
                    description: Název obchodníka a jeho identifikátor u Google
                    type: object
                    properties:
                      merchantName:
                        description: Název obchodníka zobrazený v platebním okně Google Pay
                        type: string
                        examples:
                          - GoPay Czech
                      merchantId:
                        description: Identifikátor obchodníka u Google
                        type: string
                        examples:
                          - '14846034534970557458'
                  emailRequired:
                    description: Zda Google Pay žádá zákazníka o e-mailovou adresu
                    examples:
                      - true
                    type: boolean
            x-examples:
              Example 1:
                enabled: true
                environment: PRODUCTION
                paymentDataRequest:
                  apiVersion: 2
                  apiVersionMinor: 0
                  allowedPaymentMethods:
                    - type: CARD
                      parameters:
                        allowedAuthMethods:
                          - PAN_ONLY
                          - CRYPTOGRAM_3DS
                        allowedCardNetworks:
                          - MASTERCARD
                          - VISA
                      tokenizationSpecification:
                        type: PAYMENT_GATEWAY
                        parameters:
                          gateway: gopay
                          gatewayMerchantId: '26046768005768011132'
                  transactionInfo:
                    currencyCode: CZK
                    countryCode: CZ
                    totalPriceStatus: FINAL
                    totalPrice: '5.00'
                  merchantInfo:
                    merchantName: GoPay Czech
                    merchantId: '14846034534970557458'
                  emailRequired: true
          examples: {}
    Apple-Pay-Info-Response:
      description: Objekt platebního požadavku Apple Pay zpracovávaný tlačítkem Apple Pay
      content:
        application/json:
          schema:
            type: object
            x-examples:
              Example 1:
                enabled: true
                applePayPaymentRequest:
                  merchantCapabilities:
                    - supports3DS
                    - supportsCredit
                    - supportsDebit
                  supportedNetworks:
                    - maestro
                    - masterCard
                    - electron
                    - visa
                    - vPay
                  countryCode: CZ
                  currencyCode: CZK
                  requiredBillingContactFields: []
                  requiredShippingContactFields: []
                  applicationData: OTIyMzg3MzA0Ng==
                  total:
                    label: GoPay Czech
                    amount: '5.00'
                    type: final
                merchantDisplayName: GoPay Czech
                merchantIdentifier: '8398119642'
                applepayVersion: 6
            properties:
              applepayVersion:
                description: Verze Apple Pay JS API, pro kterou je požadavek sestaven
                type: integer
                examples:
                  - 6
              merchantIdentifier:
                description: Identifikátor obchodníka u Apple
                type: string
                examples:
                  - '8398119642'
              applePayPaymentRequest:
                description: Platební požadavek Apple Pay předávaný do Apple Pay
                type: object
                properties:
                  merchantCapabilities:
                    description: Platební schopnosti, které obchodník podporuje
                    examples:
                      - - supports3DS
                    type: array
                    items:
                      type: string
                  supportedNetworks:
                    description: Přijímané karetní sítě
                    examples:
                      - - masterCard
                        - visa
                    type: array
                    items:
                      type: string
                      enum:
                        - maestro
                        - masterCard
                        - electron
                        - visa
                        - vPay
                  countryCode:
                    description: Kód země obchodníka dle ISO 3166-1 alpha-2
                    type: string
                    examples:
                      - CZ
                  currencyCode:
                    description: Měna platby
                    $ref: '#/components/schemas/Currency'
                  requiredBillingContactFields:
                    description: Fakturační kontaktní údaje, které Apple Pay vyžaduje
                    examples:
                      - []
                    type: array
                    items:
                      type: string
                  requiredShippingContactFields:
                    description: Doručovací kontaktní údaje, které Apple Pay vyžaduje
                    examples:
                      - []
                    type: array
                    items:
                      type: string
                  applicationData:
                    description: Data, která Apple Pay vrací zahashovaná v platebním tokenu
                    examples:
                      - OTIyMzg3MzA0Ng==
                    type: string
                  total:
                    description: Celková částka zobrazená v platebním okně Apple Pay
                    type: object
                    properties:
                      label:
                        description: Popisek zobrazený u částky
                        type: string
                        examples:
                          - GoPay Czech Branch
                      amount:
                        description: Částka jako desetinný řetězec
                        type: string
                        examples:
                          - '5.00'
                      type:
                        description: Zda je částka konečná
                        type: string
                        examples:
                          - final
          examples: {}
    Bad-Request-400-Response:
      description: Chybný požadavek
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response-Body'
            x-examples:
              Example 1:
                code: 400
                error: BAD_REQUEST
                message: Invalid request parameter
                detail: 'The field `payment_instrument` is required'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
          examples:
            Example 1:
              value:
                code: 400
                error: BAD_REQUEST
                message: Invalid request parameter
                detail: 'The field `payment_instrument` is required'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
    Unauthorized-401-Response:
      description: Nepřihlášen
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response-Body'
            x-examples:
              Example 1:
                code: 401
                error: UNAUTHORIZED
                message: Wrong credentials
                detail: 'The access token is missing or has expired'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
          examples:
            Example 1:
              value:
                code: 401
                error: UNAUTHORIZED
                message: Wrong credentials
                detail: 'The access token is missing or has expired'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
    Forbidden-403-Response:
      description: Přístup odepřen
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response-Body'
            x-examples:
              Example 1:
                code: 403
                error: FORBIDDEN
                message: Missing token scope
                detail: 'The token does not include the scope `payment:charge`'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
          examples:
            Example 1:
              value:
                code: 403
                error: FORBIDDEN
                message: Missing token scope
                detail: 'The token does not include the scope `payment:charge`'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
    Not-Found-404-Response:
      description: Nenalezeno
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response-Body'
            x-examples:
              Example 1:
                code: 404
                error: NOT_FOUND
                message: Resource not found
                detail: 'Payment 123 does not exist'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
          examples:
            Example 1:
              value:
                code: 404
                error: NOT_FOUND
                message: Resource not found
                detail: 'Payment 123 does not exist'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
    Conflict-409-Response:
      description: Konflikt
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response-Body'
          examples:
            Example 1:
              value:
                code: 409
                error: CONFLICT
                message: Wrong resource state
                detail: 'The payment is in the state `PAID` and cannot be charged'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
    Internal-Server-Error-500-Response:
      description: Interní chyba serveru
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response-Body'
            x-examples:
              Example 1:
                code: 500
                error: INTERNAL_SERVER_ERROR
                message: Unexpected error occurred
                detail: 'The request could not be completed'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
          examples:
            Example 1:
              value:
                code: 500
                error: INTERNAL_SERVER_ERROR
                message: Unexpected error occurred
                detail: 'The request could not be completed'
                path: /payments/123/charge
                timestamp: '2025-12-10T10:30:00Z'
    Apple-Pay-App-Info-Response:
      description: Objekt platebního požadavku Apple Pay pro nativní aplikaci
      content:
        application/json:
          schema:
            type: object
            x-examples:
              Example 1:
                applepayVersion: 6
                merchantIdentifier: merchant.com.gopay.demo
                applePayPaymentRequest:
                  merchantCapabilities:
                    - supports3DS
                    - supportsCredit
                    - supportsDebit
                  supportedNetworks:
                    - maestro
                    - masterCard
                    - electron
                    - visa
                    - vPay
                  countryCode: CZ
                  currencyCode: CZK
                  requiredBillingContactFields: []
                  requiredShippingContactFields: []
                  applicationData: OTIyMzg3MzA0Ng==
                  paymentSummaryItems:
                    - label: GoPay Czech Branch
                      amount: '5.00'
                      type: final
            properties:
              applepayVersion:
                description: Verze Apple Pay JS API, pro kterou je požadavek sestaven
                type: integer
                examples:
                  - 6
              merchantIdentifier:
                description: Identifikátor obchodníka u Apple
                type: string
                examples:
                  - merchant.com.gopay.demo
              applePayPaymentRequest:
                description: Platební požadavek Apple Pay předávaný do Apple Pay
                type: object
                properties:
                  merchantCapabilities:
                    description: Platební schopnosti, které obchodník podporuje
                    examples:
                      - - supports3DS
                    type: array
                    items:
                      type: string
                  supportedNetworks:
                    description: Přijímané karetní sítě
                    examples:
                      - - masterCard
                        - visa
                    type: array
                    items:
                      type: string
                  countryCode:
                    description: Kód země obchodníka dle ISO 3166-1 alpha-2
                    type: string
                    examples:
                      - CZ
                  currencyCode:
                    description: Měna platby
                    type: string
                    examples:
                      - CZK
                  requiredBillingContactFields:
                    description: Fakturační kontaktní údaje, které Apple Pay vyžaduje
                    examples:
                      - []
                    type: array
                    items:
                      type: object
                  requiredShippingContactFields:
                    description: Doručovací kontaktní údaje, které Apple Pay vyžaduje
                    examples:
                      - []
                    type: array
                    items:
                      type: object
                  applicationData:
                    description: Data, která Apple Pay vrací zahashovaná v platebním tokenu
                    type: string
                    examples:
                      - OTIyMzg3MzA0Ng==
                  paymentSummaryItems:
                    description: Položky zobrazené v platebním okně Apple Pay
                    type: array
                    items:
                      type: object
                      properties:
                        label:
                          description: Popisek zobrazený u částky
                          type: string
                          examples:
                            - GoPay Demo Merchant
                        amount:
                          description: Částka jako desetinný řetězec
                          type: string
                          examples:
                            - '5.00'
                        type:
                          description: Zda je částka konečná
                          type: string
                          examples:
                            - final
  schemas:
    Client-Credentials-Request:
      type: object
      title: Přihlašovací údaje klienta
      description: Žádost o přístupový token obchodníka s grantem `client_credentials`
      required:
        - grant_type
        - scope
      properties:
        grant_type:
          type: string
          const: client_credentials
          description: Vždy `client_credentials` pro tento tok
          examples:
            - client_credentials
        scope:
          type: string
          description: |-
            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
          examples:
            - 'payment:write payment:read'
    Payment-Credentials-Request:
      type: object
      title: Přihlašovací údaje platby
      description: Žádost o přístupový token omezený na platbu s grantem `payment_credentials`
      required:
        - grant_type
        - scope
      properties:
        grant_type:
          type: string
          const: payment_credentials
          description: Vždy `payment_credentials` pro tento tok
          examples:
            - payment_credentials
        scope:
          type: string
          description: |-
            Seznam požadovaných token scopů oddělených mezerou.
            - `payment:read` čte platbu
            - `payment:charge` strhává platbu
          examples:
            - 'payment:charge payment:read'
    Access-Token:
      type: object
      title: Přístupový token
      description: Přístupový token a jeho metainformace.
      properties:
        token_type:
          type: string
          const: bearer
          description: Vždy `bearer`
          default: bearer
          examples:
            - bearer
        access_token:
          $ref: '#/components/schemas/JWT'
          description: Přístupový token, předává se jako Bearer token
        scope:
          type: string
          description: |
            Mezerou oddělený seznam token scopů.
          examples:
            - 'payment:write payment:read'
        expires_in:
          type: integer
          description: Platnost přístupového JWT v sekundách
          minimum: 0
          examples:
            - 900
    JWT:
      type: string
      title: JWT
      description: |-
        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
      examples:
        - eyJraWQiOiJzaWduLTIwMjYtMDIiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwic2NvcGUiOiJwYXltZW50OndyaXRlIHBheW1lbnQ6cmVhZCIsImRvbWFpbiI6Im1lcmNoYW50IiwiaWF0IjoxNzczMzE5NTkzLCJleHAiOjE3NzMzMjA0OTN9.WlrmAZT9FLeuaHz9Gp79HeAZh8S0AtYEXbu4pOghXt4f3qv6xNHa8XX3AlvcnN3dKHD8VYWtVhLiUY2DFpGnKZQN97DY91lrStimpRSX9AY5xtOB1sZzNayEpu6MjspVv6IlNrcl2YHYFgqIN1GdFUCKCFetW9Vrm3IjSQCxWA7abo5XqxJyTP_ue7ybSz7y4xiUFNH8cIKpX0PEV3svyoXnbE58UEVktzIWsLA1PnjhtFcxsWT5y1Y_bR8OVxUVTiS0TfMoA1ETQ9ybI7IbX3sttzXnRfnwsn0iS5g96NrrJh2wDvSFQ2fwO_xO-VYl6dHI8tkGDV7JYvFOZ_i7uw
    Payment-Create-Request:
      type: object
      title: Žádost o vytvoření platby
      description: Reprezentace požadavku na vytvoření nové platby
      properties:
        amount:
          type: integer
          description: Celková částka v haléřích
          minimum: 0
          examples:
            - 100
        currency:
          $ref: '#/components/schemas/Currency'
          description: Měna platby
        order_number:
          type: string
          description: 'Identifikace objednávky pro e-shop, alfanumerické znaky'
          maxLength: 128
          examples:
            - '2025010199'
        order_description:
          type: string
          description: 'Popis objednávky, alfanumerické znaky'
          examples:
            - Test order
        additional_params:
          type: array
          description: Dodatečné parametry platby
          maxItems: 4
          items:
            $ref: '#/components/schemas/Additional-Param'
          examples:
            - - name: Custom param
                value: Custom value
        customer:
          $ref: '#/components/schemas/Customer'
          description: Informace o zákazníkovi
        callback:
          $ref: '#/components/schemas/Payment-Callback'
          description: URL pro návratové přesměrování a pro notifikace
      required:
        - amount
        - currency
        - order_number
        - customer
        - callback
      examples:
        - 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:
      type: string
      enum:
        - CZK
        - EUR
        - PLN
        - USD
        - GBP
        - HUF
        - RON
      description: Podporované měny platby ve formátu ISO 4217
      examples:
        - CZK
    Additional-Param:
      type: object
      title: Doplňující parametr
      description: Dodatečné parametry platby
      properties:
        name:
          type: string
          description: Název parametru
          examples:
            - Custom param
        value:
          type: string
          description: Hodnota parametru
          examples:
            - Custom value
      required:
        - name
        - value
      examples:
        - name: Custom param
          value: Custom value
    Payment-Details:
      type: object
      title: Detaily platby
      description: Reprezentace existující platby
      required:
        - id
        - order_number
        - state
        - amount
        - currency
        - customer
        - gw_url
        - payment_secret
      properties:
        id:
          type: string
          description: Identifikátor platby
          examples:
            - '300000001'
        order_number:
          type: string
          description: Číslo objednávky zadané při vytvoření platby
          examples:
            - '2025010199'
        state:
          $ref: '#/components/schemas/Payment-State'
          description: Stav platby
        amount:
          type: integer
          description: |
            Celková částka v haléřích
          examples:
            - 100
        currency:
          $ref: '#/components/schemas/Currency'
          description: |
            Měna platby
        customer:
          $ref: '#/components/schemas/Customer'
          description: Data zákazníka
        gw_url:
          type: string
          description: |
            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.
          format: uri
          examples:
            - 'https://gate.gopay.com/gw/123456789'
        charge:
          $ref: '#/components/schemas/Payment-Charge-Status-Response'
          description: Stržení platby, jakmile byl pokus o stržení proveden
        payment_secret:
          type: string
          description: '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!**'
          examples:
            - ps_4d2f9a51b7e30c68a1c5e9f03b7d2e46
    Customer:
      type: object
      description: Detaily zákazníka spojené s platbou. E-mailová adresa je povinná, protože slouží k autentizaci a zasílání notifikací.
      properties:
        email:
          type: string
          description: E-mail zákazníka
          format: email
          maxLength: 128
          examples:
            - john.doe@example.com
        first_name:
          type: string
          description: Křestní jméno zákazníka
          maxLength: 256
          examples:
            - John
        last_name:
          type: string
          description: Příjmení zákazníka
          maxLength: 256
          examples:
            - Doe
        phone_number:
          type: string
          description: Telefonní číslo zákazníka (domácí nebo mobilní)
          maxLength: 128
          examples:
            - '+420123456789'
        city:
          type: string
          description: Město adresy zákazníka
          maxLength: 128
          examples:
            - Testington
        street:
          type: string
          description: Ulice adresy zákazníka
          maxLength: 128
          examples:
            - Example st. 10
        postal_code:
          type: string
          description: PSČ zákazníka
          maxLength: 128
          examples:
            - '10000'
        country_code:
          type: string
          description: 'Kód země zákazníka dle [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)'
          maxLength: 128
          examples:
            - CZE
        customer_id:
          type: string
          description: Jedinečné ID zákazníka (slouží k přizpůsobení pokladního procesu)
          maxLength: 128
          examples:
            - customer420
      required:
        - email
      examples:
        - 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
      x-examples:
        Example 1:
          first_name: John
          last_name: Doe
          email: john.doe@example.com
          phone_number: '+420123456789'
          city: Testington
          street: Example st. 10
          postal_code: '10000'
          country_code: CZE
          customer_id: customer420
      title: Zákazník
    Payment-Callback:
      type: object
      title: Platební callback
      description: Objekt obsahující URL pro callbackové účely spojené s platbou
      properties:
        notification_url:
          type: string
          description: >-
            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á
          examples:
            - 'https://example.com/notify'
        return_url:
          type: string
          description: '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 (`#…`)'
          examples:
            - 'https://example.com/return'
      required:
        - return_url
      examples:
        - notification_url: 'https://example.com/notify'
          return_url: 'https://example.com/return'
    Payment-State:
      type: string
      enum:
        - CREATED
        - PAID
        - CANCELED
        - PAYMENT_METHOD_CHOSEN
        - TIMEOUTED
        - AUTHORIZED
        - REFUNDED
        - PARTIALLY_REFUNDED
      description: |-
        Ž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
      examples:
        - CREATED
      title: Stav platby
    Charge-State:
      type: string
      enum:
        - REQUESTED
        - PROCESSING
        - ACTION_REQUIRED
        - SUCCEEDED
        - FAILED
      title: Stav stržení
      description: |-
        Ž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
      examples:
        - REQUESTED
    Payment-Charge-Data:
      title: Data stržení platby
      description: 'Platební prostředek použitý ke stržení. Variantu určuje pole `payment_instrument`, které nabývá hodnot z výčtu [Payment Instrument](#/schemas/Payment-Instrument).'
      oneOf:
        - $ref: '#/components/schemas/Payment-Card-Charge-Data'
      discriminator:
        propertyName: payment_instrument
        mapping:
          PAYMENT_CARD: '#/components/schemas/Payment-Card-Charge-Data'
    Payment-Charge-Input:
      type: object
      title: Vstup stržení platby
      description: Model obsahující všechna data potřebná pro provedení stržení platby
      required:
        - payment_instrument
      properties:
        payment_instrument:
          $ref: '#/components/schemas/Payment-Charge-Data'
          description: Data platebního prostředku určující způsob stržení platby
    Payment-Instrument:
      type: string
      enum:
        - PAYMENT_CARD
      title: Platební nástroj
      description: 'Hodnoty pole, které určuje variantu [Payment Charge Data](#/schemas/Payment-Charge-Data)'
    Payment-Card-Charge-Data:
      type: object
      title: Data stržení platební karty
      description: 'Varianta `PAYMENT_CARD` unie [Payment Charge Data](#/schemas/Payment-Charge-Data). Nese karetní vstup, data prohlížeče a preferenci 3-D Secure.'
      required:
        - payment_instrument
        - input
        - browser_data
      properties:
        payment_instrument:
          const: PAYMENT_CARD
          type: string
          description: Vždy `PAYMENT_CARD`
        input:
          $ref: '#/components/schemas/Payment-Card-Input'
          description: Jeden z možných vstupů pro karetní platbu
        browser_data:
          $ref: '#/components/schemas/Browser-Data'
        challenge_preference:
          $ref: '#/components/schemas/Payment-Card-Challenge-Preference'
    Payment-Card-Input:
      title: Vstup platební karty
      description: 'Karta, kterou se platba strhává. Variantu určuje pole `input_type`, které nabývá hodnot z výčtu [Payment Card Input Type](#/schemas/Payment-Card-Input-Type).'
      oneOf:
        - $ref: '#/components/schemas/Card-Token-Input'
        - $ref: '#/components/schemas/Google-Pay-Input'
        - $ref: '#/components/schemas/Apple-Pay-Input'
        - $ref: '#/components/schemas/Encrypted-Card-Input'
      discriminator:
        propertyName: input_type
        mapping:
          CARD_TOKEN: '#/components/schemas/Card-Token-Input'
          GOOGLE_PAY: '#/components/schemas/Google-Pay-Input'
          APPLE_PAY: '#/components/schemas/Apple-Pay-Input'
          ENCRYPTED_CARD: '#/components/schemas/Encrypted-Card-Input'
    Payment-Card-Input-Type:
      type: string
      enum:
        - CARD_TOKEN
        - APPLE_PAY
        - GOOGLE_PAY
        - ENCRYPTED_CARD
      title: Typ vstupu platební karty
      description: 'Hodnoty pole, které určuje variantu [Payment Card Input](#/schemas/Payment-Card-Input)'
    Card-Token-Input:
      type: object
      title: Vstup tokenu karty
      description: 'Varianta `CARD_TOKEN` unie [Payment Card Input](#/schemas/Payment-Card-Input). Nese token uložené karty.'
      required:
        - input_type
        - card_token
      properties:
        input_type:
          const: CARD_TOKEN
          type: string
          description: Vždy `CARD_TOKEN`
        card_token:
          type: string
          description: 'Trvalý token karty získaný pomocí API volání [Vytvoření tokenu karty](#/operations/post-cards-tokens)'
          examples:
            - J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjG...
    Payment-Card-Challenge-Preference:
      type: string
      enum:
        - CHALLENGE_PREFERRED
        - NO_CHALLENGE_PREFERRED
        - AUTO
      title: Předvolba výzvy platební karty
      description: |-
        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
      examples:
        - AUTO
    Google-Pay-Input:
      type: object
      additionalProperties: true
      title: Vstup Google Pay
      description: |-
        Varianta `GOOGLE_PAY` unie [Payment Card Input](#/schemas/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.
      properties:
        input_type:
          const: GOOGLE_PAY
          type: string
          description: Vždy `GOOGLE_PAY`
          examples:
            - GOOGLE_PAY
        protocolVersion:
          type: string
          description: Verze protokolu Google Pay API použitého k šifrování platebních dat
          examples:
            - ECv2
        signature:
          type: string
          description: Digitální podpis platebních dat
          examples:
            - MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q==
        intermediateSigningKey:
          type: object
          description: Zprostředkující podpisový klíč od Googlu pro ověření podpisu
          properties:
            signedKey:
              type: string
              description: JSON řetězec obsahující hodnotu klíče a datum expirace
              examples:
                - '{"keyExpiration":"1542323393147","keyValue":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw=="}'
            signatures:
              type: array
              description: Podpisy zprostředkujícího podpisového klíče
              examples:
                - - MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v
              items:
                type: string
                examples:
                  - MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v
          examples:
            - signedKey: '{"keyExpiration":"1542323393147","keyValue":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw=="}'
              signatures:
                - MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v
        signedMessage:
          type: string
          description: JSON řetězec obsahující zašifrovaná platební data
          examples:
            - '{"tag":"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U=","ephemeralPublicKey":"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs=","encryptedMessage":"mKOoXwi8OavZ"}'
    Apple-Pay-Input:
      type: object
      additionalProperties: true
      title: Vstup Apple Pay
      description: |-
        Varianta `APPLE_PAY` unie [Payment Card Input](#/schemas/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.
      properties:
        input_type:
          const: APPLE_PAY
          type: string
          description: Vždy `APPLE_PAY`
          examples:
            - APPLE_PAY
        data:
          type: string
          description: Zašifrovaná platební data z tokenu Apple Pay
          examples:
            - V7OcjttPJnUJaQH7x7OjbIeZSINuc...
        signature:
          type: string
          description: 'Podpis platebních dat a hlavičky, podepsaný Applem'
          examples:
            - MIAGCSqGSIb3DQEHAqCAM...
        version:
          type: string
          description: Verze formátu platebního tokenu Apple Pay
          examples:
            - EC_v1
        header:
          type: object
          additionalProperties: true
          description: Hlavička obsahující dodatečná data pro dešifrování a ověření platebního tokenu
          properties:
            applicationData:
              type: string
              description: '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'
              examples:
                - 94ee059335e587e5f6b717fb172c5c3841659d892a84b7c6c47d0d13c58f7ea4
            ephemeralPublicKey:
              type: string
              description: Dočasný veřejný klíč pro odvození sdíleného tajemství
              examples:
                - MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwpd0HT6uOdE2pZTBZXsJF7IK7EvJQDq4LnQS5B5g8fiD9sEZNt4P9DhWRO44kEbbyiQ1FVgPcSsvJ2Z5I+qPTw==
            publicKeyHash:
              type: string
              description: SHA-256 hash certifikátu veřejného klíče obchodníka
              examples:
                - L6vppo38t31Q/9npxRy/xbA1+cs13h1LV+pMO/FYwvo=
            transactionId:
              type: string
              description: Jedinečný identifikátor transakce vygenerovaný Apple Pay
              examples:
                - 4f4fac7a179ae30ce4c839e85efa4a34811a5ea2af88280c847a6a8ba2c0e8c5
          required:
            - ephemeralPublicKey
            - publicKeyHash
            - transactionId
          examples:
            - applicationData: 94ee059335e587e5f6b717fb172c5c3841659d892a84b7c6c47d0d13c58f7ea4
              ephemeralPublicKey: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwpd0HT6uOdE2pZTBZXsJF7IK7EvJQDq4LnQS5B5g8fiD9sEZNt4P9DhWRO44kEbbyiQ1FVgPcSsvJ2Z5I+qPTw==
              publicKeyHash: L6vppo38t31Q/9npxRy/xbA1+cs13h1LV+pMO/FYwvo=
              transactionId: 4f4fac7a179ae30ce4c839e85efa4a34811a5ea2af88280c847a6a8ba2c0e8c5
      required:
        - input_type
        - data
        - signature
        - version
        - header
      examples:
        - 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:
      type: string
      enum:
        - GIBACZPX
        - KOMBCZPP
        - SUBASKBX
        - GIBASKBX
        - OTHERS
      title: SWIFT kód banky
      description: |-
        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
      examples:
        - GIBACZPX
    Browser-Data:
      type: object
      title: Data prohlížeče
      description: 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.
      required:
        - language
        - timezone
        - screen_width
        - screen_height
        - color_depth
        - user_agent
        - accept_header
        - javascript_enabled
        - ip
      properties:
        language:
          type: string
          description: Jazyk nebo locale prostředí zákazníka
          examples:
            - cs-CZ
        timezone:
          type: integer
          description: Posun časového pásma prostředí zákazníka v minutách (např. -60 pro SEČ)
          examples:
            - -60
        screen_width:
          type: integer
          description: Šířka obrazovky zákazníka v pixelech
          examples:
            - 434
        screen_height:
          type: integer
          description: Výška obrazovky zákazníka v pixelech
          examples:
            - 965
        color_depth:
          type: integer
          description: Barevná hloubka obrazovky zákazníka v bitech
          examples:
            - 24
        user_agent:
          type: string
          description: 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í
          examples:
            - 'Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Mobile Safari/537.36'
        accept_header:
          type: string
          description: 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`
          examples:
            - '{"accept-language":"cs;q=0.5","accept-encoding":"gzip, deflate, br, zstd","accept":"application/json, text/plain, */*"}'
        javascript_enabled:
          type: boolean
          description: Zda je v prohlížeči zákazníka povolený JavaScript
          examples:
            - true
        ip:
          type: string
          maxLength: 45
          description: 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
          examples:
            - 192.0.2.42
    Browser-Data-Detected:
      type: object
      title: Zjištěná data prohlížeče
      description: |-
        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`.
      required:
        - ip
        - user_agent
        - accept_header
      properties:
        ip:
          type: string
          maxLength: 45
          description: IP adresa, ze které request přišel
          examples:
            - 192.0.2.42
        user_agent:
          type: string
          description: Hlavička User-Agent odeslaná s requestem
          examples:
            - 'Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Mobile Safari/537.36'
        accept_header:
          type: string
          description: Accept hlavičky odeslané s requestem, zakódované do JSON
          examples:
            - '{"accept-language":"cs;q=0.5","accept-encoding":"gzip, deflate, br, zstd","accept":"application/json, text/plain, */*"}'
    Payment-Charge-Response:
      type: object
      title: Odpověď na stržení platby
      description: '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.'
      required:
        - id
        - state
        - payment_instrument
      properties:
        id:
          type: string
          description: Jedinečný identifikátor stržení
          examples:
            - '9123456789'
        state:
          $ref: '#/components/schemas/Charge-State'
          description: Aktuální stav stržení
        payment_instrument:
          $ref: '#/components/schemas/Payment-Instrument-Data'
          description: Detaily platebního prostředku použitého pro toto stržení
        action:
          $ref: '#/components/schemas/Payment-Charge-Action'
          description: '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:
      type: object
      title: Odpověď na stav stržení platby
      description: '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.'
      required:
        - id
        - state
      properties:
        id:
          type: string
          description: Jedinečný identifikátor stržení
          examples:
            - '9123456789'
        state:
          $ref: '#/components/schemas/Charge-State'
          description: Aktuální stav stržení
        payment_instrument:
          $ref: '#/components/schemas/Payment-Instrument-Data'
          description: Detaily platebního prostředku použitého pro toto stržení
        action:
          $ref: '#/components/schemas/Payment-Charge-Action'
          description: 'Krok, který musí zákazník dokončit, například 3-D Secure autentizace. Přítomné, pokud je `state` `ACTION_REQUIRED`'
        fail_reason:
          type: string
          description: Důvod selhání stržení. Přítomno pouze pokud je stav `FAILED`
          examples:
            - Issuer declined the authorisation
    Payment-Instrument-Data:
      title: Data platebního nástroje
      description: 'Platební prostředek, který stržení použilo. Variantu určuje pole `payment_instrument`, které nabývá hodnot z výčtu [Payment Instrument](#/schemas/Payment-Instrument).'
      examples:
        - payment_instrument: PAYMENT_CARD
          details:
            input_type: CARD_TOKEN
            masked_pan: 406821******1234
            expiration_month: '01'
            expiration_year: '30'
            scheme: VISA
            fingerprint: 73c8d0a48d91def89761...
      oneOf:
        - $ref: '#/components/schemas/Payment-Card-Instrument-Out'
      discriminator:
        propertyName: payment_instrument
        mapping:
          PAYMENT_CARD: '#/components/schemas/Payment-Card-Instrument-Out'
    Payment-Card-Instrument-Out:
      type: object
      title: Výstup nástroje platební karty
      description: Varianta `PAYMENT_CARD` unie Payment Instrument Data. Obsahuje detaily specifické pro kartu použitou při stržení.
      examples:
        - payment_instrument: PAYMENT_CARD
          details:
            input_type: CARD_TOKEN
            masked_pan: 406821******1234
            expiration_month: '01'
            expiration_year: '30'
            scheme: VISA
            fingerprint: 73c8d0a48d91def89761...
      required:
        - payment_instrument
      properties:
        payment_instrument:
          $ref: '#/components/schemas/Payment-Instrument'
          description: Vždy `PAYMENT_CARD`
        details:
          $ref: '#/components/schemas/Payment-Card-Charge-Details'
          description: Detaily platebního prostředku specifické pro kartu
    Payment-Card-Charge-Details:
      type: object
      title: Detaily stržení platební karty
      description: 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.
      examples:
        - input_type: CARD_TOKEN
          masked_pan: 406821******1234
          expiration_month: '01'
          expiration_year: '30'
          scheme: VISA
          fingerprint: 73c8d0a48d91def89761...
      required:
        - input_type
      properties:
        input_type:
          $ref: '#/components/schemas/Payment-Card-Input-Type'
          description: Typ zadání karty použitý při stržení
        masked_pan:
          type: string
          description: Maskované primární číslo účtu s viditelnými pouze prvními šesti a posledními čtyřmi číslicemi
          examples:
            - 406821******1234
        expiration_month:
          type: string
          description: Měsíc expirace karty (01–12)
          pattern: '^(?:0[0-9]|1[0-2])$'
          examples:
            - '01'
        expiration_year:
          type: string
          description: Rok expirace karty (dvoumístný formát)
          pattern: '^[0-9]{2}$'
          examples:
            - '30'
        scheme:
          $ref: '#/components/schemas/Card-scheme'
          description: Schéma karetní sítě
        fingerprint:
          type: string
          description: Jedinečný hash identifikující fyzickou kartu
          examples:
            - 73c8d0a48d91def89761...
    Card-scheme:
      type: string
      enum:
        - VISA
        - MASTERCARD
      title: Karetní schéma
      description: Schéma karetní sítě (VISA nebo MASTERCARD)
      examples:
        - VISA
    Payment-Charge-Action:
      title: Akce stržení platby
      description: '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`.'
      examples:
        - action_type: EMV3DS
          state: CREATED
          redirect_url: 'https://gate.gopay.com/redirect'
      oneOf:
        - $ref: '#/components/schemas/Emv-3DS-Action'
      discriminator:
        propertyName: action_type
        mapping:
          EMV3DS: '#/components/schemas/Emv-3DS-Action'
      type: object
    Payment-Charge-Action-Type:
      type: string
      enum:
        - EMV3DS
      title: Typ akce stržení platby
      description: |-
        Hodnoty pole, které určuje variantu Payment Charge Action.
        - `EMV3DS` - EMV 3-D Secure autentizace pro platby kartou
      examples:
        - EMV3DS
    Emv-3DS-Action:
      type: object
      title: Akce EMV 3DS
      description: Varianta `EMV3DS` unie Payment Charge Action. Představuje akci EMV 3-D Secure autentizace pro karetní platby.
      examples:
        - action_type: EMV3DS
          state: CREATED
          redirect_url: 'https://gate.gopay.com/redirect'
      required:
        - action_type
        - state
      properties:
        action_type:
          $ref: '#/components/schemas/Payment-Charge-Action-Type'
          description: Vždy `EMV3DS`
        state:
          $ref: '#/components/schemas/Emv-3DS-State'
          description: Aktuální stav průběhu 3DS autentizace
        redirect_url:
          type: string
          description: '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`'
          examples:
            - 'https://gate.gopay.com/redirect'
          format: uri
    Emv-3DS-State:
      type: string
      enum:
        - CREATED
        - CHALLENGE_REQUIRED
        - AUTHENTICATED_CHALLENGE
        - AUTHENTICATED_FRICTIONLESS
        - NOT_AUTHENTICATED
        - FAILED
      title: Stav EMV 3DS
      description: |-
        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
      examples:
        - CREATED
    QR-Payment-Details:
      type: object
      title: Detaily QR platby
      description: '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.'
      properties:
        amount:
          type: integer
          description: Částka platby v haléřích
          examples:
            - 10000
        currency:
          $ref: '#/components/schemas/Currency'
          description: Měna platby
        recipient:
          $ref: '#/components/schemas/Bank-Transfer-Recipient'
          description: Informace o příjemci
        qr_code:
          $ref: '#/components/schemas/QR-Code-List'
          description: Vygenerované obrázky QR kódů v různých regionálních formátech
      required:
        - amount
        - currency
        - recipient
        - qr_code
    Bank-Transfer-Recipient:
      type: object
      title: Příjemce bankovního převodu
      description: 'Informace o příjemci bankovního převodu, včetně jména, údajů o bankovním účtu a adresy.'
      properties:
        name:
          type: string
          description: Jméno příjemce platby
          examples:
            - GoPay Czech
        bank_account:
          $ref: '#/components/schemas/Recipient-Bank-Account'
          description: Bankovní údaje příjemce v lokálním i mezinárodním formátu
        address:
          $ref: '#/components/schemas/Recipient-Address'
          description: Fyzická adresa příjemce
    Recipient-Bank-Account:
      type: object
      title: Bankovní účet příjemce
      description: Bankovní údaje příjemce v lokálním (dle země) i mezinárodním (IBAN/SWIFT) formátu.
      properties:
        local:
          $ref: '#/components/schemas/Bank-Account-Local-Details'
          description: Bankovní údaje v lokálním (dle země) formátu
        international:
          $ref: '#/components/schemas/Bank-Account-International-Details'
          description: Bankovní údaje v mezinárodním formátu IBAN/BIC
    Bank-Account-Local-Details:
      type: object
      title: Lokální detaily bankovního účtu
      description: '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.'
      properties:
        prefix:
          type: string
          description: Předčíslí čísla účtu (může být samé nuly)
          examples:
            - '000000'
        account_number:
          type: string
          description: Lokální číslo bankovního účtu
          examples:
            - '9878039'
        bank_code:
          type: string
          description: Numerický kód banky identifikující banku
          examples:
            - '2010'
        variable_symbol:
          type: string
          description: Variabilní symbol pro spárování platby s objednávkou
          examples:
            - '3123456789'
      required:
        - prefix
        - account_number
        - bank_code
        - variable_symbol
      x-examples:
        Example 1:
          prefix: '000000'
          account_number: '9878039'
          bank_code: '2010'
          variable_symbol: '3123456789'
    Bank-Account-International-Details:
      type: object
      title: Mezinárodní detaily bankovního účtu
      description: 'Bankovní údaje v mezinárodním formátu IBAN/BIC, používaném pro přeshraniční a SEPA platby.'
      x-examples:
        Example 1:
          bic: FIOBCZPP
          iban: CZ5120100000000009878039
          reference: '3123456789'
      properties:
        bic:
          $ref: '#/components/schemas/Bank-Swift'
          description: BIC (kód banky) / SWIFT kód banky
        iban:
          type: string
          description: Mezinárodní číslo bankovního účtu (IBAN)
          examples:
            - CZ5120100000000009878039
        reference:
          type: string
          description: Referenční číslo platby pro spárování s objednávkou
          examples:
            - '3123456789'
    Recipient-Address:
      type: object
      title: Adresa příjemce
      description: Fyzická adresa příjemce platby.
      properties:
        street:
          type: string
          description: Ulice a číslo popisné
          examples:
            - Senovazne nam. 1736
        city:
          type: string
          description: Název města
          examples:
            - Ceske Budejovice
        zip_code:
          type: string
          description: PSČ
          examples:
            - '37001'
        country:
          type: string
          description: Název země
          examples:
            - Czech Republic
      x-examples:
        Example 1:
          street: Senovazne nam. 1736
          city: Ceske Budejovice
          zip_code: '37001'
          country: Czech Republic
    QR-Code-List:
      type: object
      title: Seznam QR kódů
      description: '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.'
      properties:
        spayd:
          type: string
          description: '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.'
          examples:
            - 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=
        paybysquare:
          type: string
          description: '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.'
          examples:
            - '{QR code in base64}'
        sepa:
          type: string
          description: 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.
          examples:
            - '{QR code in base64}'
        mnb_qr:
          type: string
          description: '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.'
          examples:
            - '{QR code in base64}'
    Token-Create-Request:
      type: object
      title: Žádost o vytvoření tokenu
      description: Tělo požadavku pro vytvoření tokenu karty. Obsahuje zašifrovaná data karty.
      required:
        - payload
      properties:
        payload:
          $ref: '#/components/schemas/JWE'
          description: Zašifrovaná data karty ve formátu JWE compact serialization
    Permanent-Card-Token-Details:
      type: object
      title: Detaily trvalého tokenu karty
      description: 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ě.
      properties:
        card_id:
          type: string
          description: Jedinečný identifikátor uloženého tokenu karty
          examples:
            - '8007127320'
        masked_pan:
          type: string
          description: Maskované primární číslo účtu s viditelnými pouze prvními šesti a posledními čtyřmi číslicemi
          examples:
            - 406821******1234
        masked_virtual_pan:
          type: string
          description: Maskovaný virtuální PAN (síťový token) přidružený ke kartě
          examples:
            - 489537******6287
        expiration_month:
          type: string
          description: Měsíc expirace karty (01–12)
          pattern: '^(?:0[0-9]|1[0-2])$'
          examples:
            - '01'
        expiration_year:
          type: string
          description: Rok expirace karty (dvoumístný formát)
          pattern: '^[0-9]{2}$'
          examples:
            - '30'
        scheme:
          $ref: '#/components/schemas/Card-scheme'
          description: Schéma karetní sítě
        corporate:
          type: boolean
          description: Zda se jedná o firemní (podnikovou) kartu
          default: false
          examples:
            - false
        fingerprint:
          type: string
          description: 'Jedinečný hash identifikující fyzickou kartu, stabilní napříč více tokenizacemi téže karty'
          examples:
            - 73c8d0a48d91def897612b54e630997745e1faad43045e732189cfe4acf4961b
        token:
          type: string
          description: Hodnota trvalého tokenu karty pro použití v požadavcích na stržení
          examples:
            - J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv9DtCT3HLSlWHRYAbVTBLbouV77YtVSgavhi4uRZTwDy218Gog4MbZJ+umL/BkfFlNQ80PCdOjwYr8DtqZr71LHwkvg91ywirZp0=
        card_art_url:
          type: string
          description: URL obrázku karty poskytnutého vydávající bankou
          format: uri
          examples:
            - 'https://card.art/pic.png'
        brand:
          type: string
          description: 'Druh nebo úroveň karty (např. GOLD, PLATINUM, STANDARD)'
          examples:
            - GOLD
        service_type:
          $ref: '#/components/schemas/Card-Service-Type'
          description: Zda se jedná o debetní nebo kreditní kartu
        status:
          $ref: '#/components/schemas/Card-Token-Status'
          description: Aktuální stav uloženého tokenu karty
      required:
        - card_id
        - masked_pan
        - masked_virtual_pan
        - expiration_month
        - expiration_year
        - scheme
        - corporate
        - fingerprint
        - token
        - card_art_url
      examples:
        - 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:
      type: string
      enum:
        - DEBIT
        - CREDIT
      title: Typ karty
      description: |-
        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
      examples:
        - DEBIT
    Card-Token-Status:
      type: string
      enum:
        - ACTIVE
        - SUSPENDED
        - DELETED
      title: Stav tokenu karty
      description: |-
        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
      examples:
        - ACTIVE
    JWK:
      type: object
      title: JWK
      description: 'Struktura veřejného šifrovacího klíče. Je formátována dle RFC 7517: JSON Web Key (JWK)'
      properties:
        kty:
          const: RSA
          description: Typ klíče. Vždy `RSA` pro šifrovací klíče používané GoPay.
          examples:
            - RSA
        use:
          const: enc
          description: Použití klíče. Vždy `enc` (šifrování).
          examples:
            - enc
        kid:
          type: string
          description: ID klíče
          examples:
            - key_20250406
        alg:
          type: string
          description: Algoritmus pro šifrování tímto klíčem.
          default: RSA-OAEP-256
          examples:
            - RSA-OAEP-256
        'n':
          type: string
          description: Modulus veřejného klíče `RSA`.
          examples:
            - oR79tj1xAaqr1TfmkGS03EfEZjU_5DMomKJXGK8cnmtGivG5XnFodcbztzSOrlrKmhoxrKRR0LiRRjYJIgTP3dGK9KOv7JRH4adnDClckQkxupwoz1dcm6cLDzjuVS1a4et8lQlwYKm5r52fG9VShckwNZgvmK0uYcE7717wLkX3JM2vA_F_-2oRCjG3l2E4cjhQzzstTFPkW35ZjuKut4If8LOnKH0h9tdblUOSB_VtZBNY6PCXeUTDfbCb85-eGrwWXEajq4uegPDbV2oSnTLxOXR8ctWURZ8XjS1PgsoDD4go9BQchv-9Q2m0NbS5s71WVJ9LOW7Xt-Napsoftw
        e:
          type: string
          description: Exponent veřejného klíče `RSA`.
          default: AQAB
          examples:
            - AQAB
      required:
        - kty
        - use
        - kid
        - alg
        - 'n'
        - e
      examples:
        - kty: RSA
          kid: key_20250406
          use: enc
          alg: RSA-OAEP-256
          'n': oR79tj1xAaqr1TfmkGS03EfEZjU_5DMomKJXGK8cnmtGivG5XnFodcbztzSOrlrKmhoxrKRR0LiRRjYJIgTP3dGK9KOv7JRH4adnDClckQkxupwoz1dcm6cLDzjuVS1a4et8lQlwYKm5r52fG9VShckwNZgvmK0uYcE7717wLkX3JM2vA_F_-2oRCjG3l2E4cjhQzzstTFPkW35ZjuKut4If8LOnKH0h9tdblUOSB_VtZBNY6PCXeUTDfbCb85-eGrwWXEajq4uegPDbV2oSnTLxOXR8ctWURZ8XjS1PgsoDD4go9BQchv-9Q2m0NbS5s71WVJ9LOW7Xt-Napsoftw
          e: AQAB
    JWE:
      type: string
      title: JWE
      description: |-
        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.
      examples:
        - eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoia2V5XzIwMjUwNDA2In0.aG93ZGlkYmFzZTY0.dGhpc2lzdGhlaXY.ZW5jcnlwdGVkY2FyZGhvbGRlcmRhdGE.YXV0aHRhZw
    Card-Form-URL:
      type: object
      title: URL formuláře karty
      description: URL hostovaného formuláře pro zadání karty, který SDK GoPay pro prohlížeč vkládá do stránky obchodníka.
      properties:
        card_form_url:
          type: string
          description: URL hostovaného formuláře pro zadání údajů karty
          examples:
            - 'https://secure.gopay.com/gp-card-comm/q/form'
      x-examples:
        Example 1:
          card_form_url: 'https://secure.gopay.com/gp-card-comm/q/form'
    Error-Response-Body:
      type: object
      title: Tělo chybové odpovědi
      description: '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.'
      required:
        - code
        - error
        - message
        - detail
        - path
        - timestamp
      properties:
        code:
          description: HTTP stavový kód
          examples:
            - 400
          type: integer
        error:
          description: Typ chyby
          examples:
            - BAD_REQUEST
          type: string
        message:
          type: string
          description: Chybová zpráva
          examples:
            - Invalid request parameter
        detail:
          type: string
          description: Podrobný popis chyby
          examples:
            - 'The field `payment_instrument` is required'
        path:
          type: string
          description: Cesta požadavku
          examples:
            - /payments/123/charge
        timestamp:
          type: string
          description: Časové razítko chyby
          format: date-time
          examples:
            - '2025-12-10T10:30:00Z'
    Encrypted-Card-Input:
      title: Šifrovaný vstup karty
      description: 'Varianta `ENCRYPTED_CARD` unie [Payment Card Input](#/schemas/Payment-Card-Input). Nese kartu zadanou zákazníkem, zašifrovanou klientským SDK GoPay. Je jednorázová a platí deset minut.'
      type: object
      required:
        - input_type
        - payload
      properties:
        input_type:
          const: ENCRYPTED_CARD
          type: string
          description: Vždy `ENCRYPTED_CARD`
          examples:
            - ENCRYPTED_CARD
        payload:
          $ref: '#/components/schemas/JWE'
          description: Zašifrovaná karta
    Refund-Create-Request:
      title: Žádost o vrácení platby
      description: Částka, která se má vrátit ze zaplacené platby
      type: object
      required:
        - amount
      properties:
        amount:
          type: integer
          description: 'Částka k vrácení v haléřích. Pro plné vrácení nastavte na výši platby'
          minimum: 1
          examples:
            - 100
    Refund-Details:
      title: Detaily vrácení
      description: Vrácení provedené k platbě
      type: object
      required:
        - id
        - state
        - amount
        - currency
        - created_at
      properties:
        id:
          type: string
          description: ID vrácení
          examples:
            - '3050123456'
        state:
          $ref: '#/components/schemas/Refund-State'
          description: Stav vrácení
        amount:
          type: integer
          description: Vrácená částka v haléřích
          examples:
            - 100
        currency:
          $ref: '#/components/schemas/Currency'
          description: Měna vrácení
        created_at:
          type: string
          format: date-time
          description: Kdy bylo vrácení vyžádáno
          examples:
            - '2025-12-10T10:30:00Z'
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Kdy se naposledy změnil stav vrácení. Null, dokud se stav poprvé nezmění
          examples:
            - '2025-12-10T10:35:00Z'
    Refund-State:
      type: string
      title: Stav vrácení
      enum:
        - REQUESTED
        - SUCCESS
        - FAILED
      description: |
        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
      examples:
        - SUCCESS
    Recurrence-Schedule:
      title: Rozvrh opakování
      type: object
      description: Jak často opakování typu `AUTO` zakládá platbu
      required:
        - period
        - cycle
      properties:
        period:
          type: string
          description: Jednotka, ve které se počítá cyklus
          enum:
            - DAY
            - WEEK
            - MONTH
          examples:
            - MONTH
        cycle:
          type: integer
          description: Počet period mezi dvěma platbami
          minimum: 1
          examples:
            - 1
      examples:
        - period: MONTH
          cycle: 1
    Recurrence-Create-Request:
      type: object
      title: Žádost o založení opakované platby
      description: 'Jeden ze dvou druhů opakované platby. Variantu určuje pole `type`, které nabývá hodnot z výčtu [Recurrence Type](#/schemas/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.'
      oneOf:
        - $ref: '#/components/schemas/Recurrence-Create-Auto'
        - $ref: '#/components/schemas/Recurrence-Create-On-Demand'
      discriminator:
        propertyName: type
        mapping:
          AUTO: '#/components/schemas/Recurrence-Create-Auto'
          ON_DEMAND: '#/components/schemas/Recurrence-Create-On-Demand'
    Recurrence-Create-Auto:
      type: object
      title: Založení opakované platby AUTO
      description: 'Varianta `AUTO` unie [Recurrence Create Request](#/schemas/Recurrence-Create-Request). Platby zakládá GoPay samo podle rozvrhu, takže `schedule` je tady povinné.'
      additionalProperties: false
      required:
        - type
        - schedule
        - recurrence_date_to
        - payment
      properties:
        type:
          const: AUTO
          type: string
          description: Vždy `AUTO`
          examples:
            - AUTO
        schedule:
          $ref: '#/components/schemas/Recurrence-Schedule'
          description: Jak často opakování zakládá platbu
        recurrence_date_to:
          type: string
          format: date
          description: 'Poslední den, kdy smí opakování založit platbu, ve tvaru yyyy-MM-dd'
          examples:
            - '2027-09-04'
        payment:
          $ref: '#/components/schemas/Payment-Create-Request'
          description: Šablona platby, ze které vzniká každá platba tohoto opakování
      examples:
        - 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:
      type: object
      title: Založení opakované platby ON_DEMAND
      description: 'Varianta `ON_DEMAND` unie [Recurrence Create Request](#/schemas/Recurrence-Create-Request). Žádný rozvrh neexistuje — o každou další platbu si obchodník řekne operací next — takže `schedule` se posílat nesmí.'
      additionalProperties: false
      required:
        - type
        - recurrence_date_to
        - payment
      properties:
        type:
          const: ON_DEMAND
          type: string
          description: Vždy `ON_DEMAND`
          examples:
            - ON_DEMAND
        recurrence_date_to:
          type: string
          format: date
          description: 'Poslední den, kdy smí opakování založit platbu, ve tvaru yyyy-MM-dd'
          examples:
            - '2027-09-04'
        payment:
          $ref: '#/components/schemas/Payment-Create-Request'
          description: Šablona platby, ze které vzniká každá platba tohoto opakování
      examples:
        - 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:
      title: Detail opakované platby
      type: object
      description: Stav opakované platby a platba, kterou naposledy založila
      required:
        - id
        - type
        - state
        - recurrence_date_to
        - payment
      properties:
        id:
          type: string
          description: Jedinečné ID opakované platby
          examples:
            - '8008013370'
        type:
          $ref: '#/components/schemas/Recurrence-Type'
          description: Zda se platby zakládají podle rozvrhu nebo jen na vyžádání
        state:
          $ref: '#/components/schemas/Recurrence-State'
          description: Aktuální stav opakované platby
        schedule:
          $ref: '#/components/schemas/Recurrence-Schedule'
          description: Přítomné jen u opakování typu `AUTO`
        recurrence_date_to:
          type: string
          format: date
          description: 'Poslední den, kdy smí opakování založit platbu, ve tvaru yyyy-MM-dd'
          examples:
            - '2027-09-04'
        stop_reason:
          $ref: '#/components/schemas/Recurrence-Stop-Reason'
          description: Proč se opakování zastavilo — přítomné jen ve stavu `STOPPED`
        payment:
          $ref: '#/components/schemas/Recurrence-Payment'
          description: 'Platba, kterou opakování nese — než nějaká vznikne, jde o uloženou šablonu'
      examples:
        - 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:
      title: Platba opakování
      type: object
      description: >-
        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`.
      required:
        - amount
        - currency
        - order_number
        - customer
      properties:
        id:
          type: string
          description: 'ID platby. Chybí, dokud opakování nezaložilo platbu'
          examples:
            - '7310142951'
        state:
          $ref: '#/components/schemas/Payment-State'
          description: 'Stav založené platby. Chybí, dokud opakování žádnou nezaložilo'
        amount:
          type: integer
          description: Celková částka v haléřích
          minimum: 0
          examples:
            - 1500
        currency:
          $ref: '#/components/schemas/Currency'
          description: Měna platby
        order_number:
          type: string
          description: 'Identifikace objednávky v e-shopu, alfanumerické znaky'
          maxLength: 128
          examples:
            - '2025010199'
        customer:
          $ref: '#/components/schemas/Customer'
          description: Informace o zákazníkovi
        gw_url:
          type: string
          description: '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'
          examples:
            - 'https://gate.gopay.com/gw/123456789'
        payment_secret:
          type: string
          description: '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!**'
          examples:
            - ps_6aa48c5fadd5ca9ccbc2a30bb13d7e8e
      examples:
        - amount: 1500
          currency: CZK
          order_number: '2025010199'
          customer:
            email: john.doe@example.com
    Recurrence-Type:
      title: Typ opakování
      type: string
      description: >-
        `AUTO` zakládá platby podle rozvrhu, `ON_DEMAND` jen tehdy, když si obchodník o další
        platbu řekne.
      enum:
        - AUTO
        - ON_DEMAND
      examples:
        - ON_DEMAND
    Recurrence-State:
      title: Stav opakování
      type: string
      description: >-
        `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í.
      enum:
        - NEW
        - REQUESTED
        - STARTED
        - STOPPED
      examples:
        - NEW
    Recurrence-Stop-Reason:
      title: Důvod zastavení opakování
      type: string
      description: |-
        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
      enum:
        - RECURRENCE_EXPIRED
        - CARD_EXPIRED
        - CANCELLED_VIA_API
        - CANCELLED_VIA_BACKOFFICE
        - CANCELLED_BY_GOPAY
        - UNKNOWN
      examples:
        - CANCELLED_VIA_API
    Customer-Override:
      title: Přepis zákazníka
      type: object
      description: >-
        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í.
      additionalProperties: false
      properties:
        email:
          type: string
          description: E-mail zákazníka
          format: email
          maxLength: 128
          examples:
            - john.doe@example.com
        first_name:
          type: string
          description: Jméno zákazníka
          maxLength: 256
          examples:
            - John
        last_name:
          type: string
          description: Příjmení zákazníka
          maxLength: 256
          examples:
            - Doe
        phone_number:
          type: string
          description: Telefonní číslo zákazníka (pevná linka nebo mobil)
          maxLength: 128
          examples:
            - '+420123456789'
        city:
          type: string
          description: Město z adresy zákazníka
          maxLength: 128
          examples:
            - Testington
        street:
          type: string
          description: Ulice z adresy zákazníka
          maxLength: 128
          examples:
            - Example st. 10
        postal_code:
          type: string
          description: PSČ z adresy zákazníka
          maxLength: 128
          examples:
            - '10000'
        country_code:
          type: string
          description: 'Kód země zákazníka podle [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)'
          maxLength: 128
          examples:
            - CZE
        customer_id:
          type: string
          description: Jedinečné ID zákazníka (slouží k přizpůsobení checkoutu)
          maxLength: 128
          examples:
            - customer420
      examples:
        - first_name: John
          last_name: Doe
    Payment-Instance-Override:
      title: Přepis jedné platby
      type: object
      description: >-
        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í.
      additionalProperties: false
      properties:
        amount:
          type: integer
          description: Celková částka v haléřích
          minimum: 0
          examples:
            - 9900
        order_number:
          type: string
          description: 'Identifikace objednávky v e-shopu, alfanumerické znaky'
          maxLength: 128
          examples:
            - '2025010199'
        order_description:
          type: string
          description: 'Popis objednávky, alfanumerické znaky'
          examples:
            - Testovací objednávka
        additional_params:
          type: array
          description: Doplňkové parametry platby
          maxItems: 4
          items:
            $ref: '#/components/schemas/Additional-Param'
          examples:
            - - name: Custom param
                value: Custom value
        customer:
          $ref: '#/components/schemas/Customer-Override'
          description: 'Pole zákazníka, která se nahradí; vynechaná si ponechají uloženou hodnotu'
        callback:
          $ref: '#/components/schemas/Payment-Callback'
          description: URL pro návratové přesměrování a pro notifikace
      examples:
        - 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:
      title: Žádost o vytvoření platebního odkazu
      description: Údaje platby, které nový platební odkaz nese, jeho platnost a to, zda ho lze použít víckrát
      type: object
      required:
        - payment
      properties:
        payment:
          $ref: '#/components/schemas/Payment-From-Link-Request'
          description: Údaje platby použité pro každou platbu, kterou tento odkaz vytvoří
        expires_in:
          type: integer
          description: 'Životnost odkazu v sekundách od jeho vytvoření. Bez ní odkaz nevyprší. Horní hranice je sto let'
          minimum: 1
          examples:
            - 3600
        reusable:
          type: boolean
          default: true
          description: '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`'
          examples:
            - true
    Link-Details:
      title: Detail platebního odkazu
      description: Platební odkaz, jeho stav a údaje platby, které nese
      type: object
      required:
        - id
        - url
        - active
        - reusable
      properties:
        id:
          type: string
          description: 'ID odkazu, které se používá při dotazu na stav a při zneplatnění. Není to kód z `url`'
          examples:
            - '3405871122'
        url:
          type: string
          description: '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í'
          examples:
            - 'https://gate.gopay.com/gp-gw/l/Xk8mQ2pR7t'
        active:
          type: boolean
          description: 'Zda odkazem stále lze založit platbu. Po expiraci se vrací false i dřív, než se to zapíše'
          examples:
            - true
        reusable:
          type: boolean
          description: Zda odkaz smí založit více než jednu platbu
          examples:
            - true
        expires_at:
          type: string
          format: date-time
          description: '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í'
          examples:
            - '2026-08-18T14:35:12Z'
        stop_reason:
          $ref: '#/components/schemas/Link-Stop-Reason'
          description: Důvod, proč odkaz už není aktivní. U aktivního odkazu se nevrací
        payment:
          $ref: '#/components/schemas/Payment-From-Link-Request'
          description: Údaje platby, které odkaz nese
    Link-Stop-Reason:
      type: string
      title: Důvod zneplatnění odkazu
      enum:
        - FROM_API
        - USED
        - EXPIRED
      description: |
        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`
      examples:
        - USED
    Payment-From-Link-Request:
      type: object
      title: Platba z platebního odkazu
      description: >-
        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`.
      required:
        - amount
        - currency
        - order_number
        - customer
        - callback
      properties:
        amount:
          type: integer
          description: Celková částka v haléřích
          minimum: 0
          examples:
            - 15000
        currency:
          $ref: '#/components/schemas/Currency'
          description: '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:
          type: string
          description: 'Identifikace objednávky v e-shopu, alfanumerické znaky'
          maxLength: 128
          examples:
            - '2026-00042'
        order_description:
          type: string
          description: 'Popis objednávky, alfanumerické znaky'
          maxLength: 256
          examples:
            - Faktura 2026-00042
        additional_params:
          type: array
          description: 'Doplňkové parametry platby. Žádné `name` nesmí obsahovat `=` a `name` s `value` dohromady nesmí přesáhnout 511 znaků'
          maxItems: 4
          items:
            $ref: '#/components/schemas/Additional-Param'
          examples:
            - - name: Custom param
                value: Custom value
        customer:
          $ref: '#/components/schemas/Customer'
          description: Údaje o zákazníkovi. E-mailová adresa je povinná
        callback:
          $ref: '#/components/schemas/Payment-Callback'
          description: '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á'
      examples:
        - 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:
      title: Žádost o ověření obchodníka
      description: Žádost o ověření obchodníka pro Apple Pay
      type: object
      required:
        - validationUrl
      properties:
        validationUrl:
          type: string
          format: uri
          description: Validační URL, kterou Apple Pay vydal pro relaci
          examples:
            - https://apple-pay-gateway.apple.com/paymentservices/paymentSession
    Validate-Merchant-Response:
      title: Odpověď na ověření obchodníka
      description: Objekt merchant session, který Apple Pay očekává; předává se platebnímu oknu Apple Pay beze změny
      type: object
      additionalProperties: true
    Event:
      title: Událost
      description: 'Jedna z událostí, které GoPay zaznamenává. Variantu určuje pole `type`, které nabývá hodnot z výčtu [Event Type](#/schemas/Event-Type). Typ, který kód obchodníka nezná, se ignoruje a nepovažuje za chybu, aby nový typ nerozbil funkční integraci.'
      examples:
        - id: 01ARZ3NDEKTSV4RRFFQ69G5FAV
          type: payments.paid
          occurred_at: '2026-07-08T12:04:39.123Z'
          data:
            payment_id: '300000001'
            charge_id: '9123456789'
      oneOf:
        - $ref: '#/components/schemas/Payment-Paid-Event'
        - $ref: '#/components/schemas/Payment-Canceled-Event'
        - $ref: '#/components/schemas/Payment-Timeouted-Event'
        - $ref: '#/components/schemas/Link-Payment-Created-Event'
        - $ref: '#/components/schemas/Link-Disabled-Event'
        - $ref: '#/components/schemas/Refund-Succeeded-Event'
        - $ref: '#/components/schemas/Refund-Failed-Event'
        - $ref: '#/components/schemas/Recurrence-Started-Event'
        - $ref: '#/components/schemas/Recurrence-Payment-Created-Event'
        - $ref: '#/components/schemas/Recurrence-Stopped-Event'
        - $ref: '#/components/schemas/Card-Updated-Event'
        - $ref: '#/components/schemas/Card-Deleted-Event'
      discriminator:
        propertyName: type
        mapping:
          payments.paid: '#/components/schemas/Payment-Paid-Event'
          payments.canceled: '#/components/schemas/Payment-Canceled-Event'
          payments.timeouted: '#/components/schemas/Payment-Timeouted-Event'
          links.payment_created: '#/components/schemas/Link-Payment-Created-Event'
          links.disabled: '#/components/schemas/Link-Disabled-Event'
          refunds.succeeded: '#/components/schemas/Refund-Succeeded-Event'
          refunds.failed: '#/components/schemas/Refund-Failed-Event'
          recurrences.started: '#/components/schemas/Recurrence-Started-Event'
          recurrences.payment_created: '#/components/schemas/Recurrence-Payment-Created-Event'
          recurrences.stopped: '#/components/schemas/Recurrence-Stopped-Event'
          cards.updated: '#/components/schemas/Card-Updated-Event'
          cards.deleted: '#/components/schemas/Card-Deleted-Event'
    Event-Type:
      type: string
      enum:
        - 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
      title: Typ události
      description: 'Hodnoty pole, které určuje variantu [Event](#/schemas/Event)'
      examples:
        - payments.paid
    Payment-Paid-Event:
      type: object
      title: Událost zaplacení platby
      description: 'Varianta `payments.paid` unie [Event](#/schemas/Event). Platba přešla do `PAID`.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `payments.paid`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Payment-Paid-Data'
          description: Identifikátory entit, kterých se událost týká
    Payment-Canceled-Event:
      type: object
      title: Událost zrušení platby
      description: 'Varianta `payments.canceled` unie [Event](#/schemas/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.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `payments.canceled`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Payment-Event-Data'
          description: Identifikátory entit, kterých se událost týká
    Payment-Timeouted-Event:
      type: object
      title: Událost vypršení platby
      description: 'Varianta `payments.timeouted` unie [Event](#/schemas/Event). Platba nedospěla do koncového stavu ve své lhůtě.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `payments.timeouted`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Payment-Event-Data'
          description: Identifikátory entit, kterých se událost týká
    Link-Payment-Created-Event:
      type: object
      title: Událost vzniku platby z odkazu
      description: 'Varianta `links.payment_created` unie [Event](#/schemas/Event). Zákazník otevřel platební odkaz a vznikla z něj platba.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `links.payment_created`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Link-Payment-Created-Data'
          description: Identifikátory entit, kterých se událost týká
    Link-Disabled-Event:
      type: object
      title: Událost deaktivace odkazu
      description: 'Varianta `links.disabled` unie [Event](#/schemas/Event). Obchodník deaktivoval platební odkaz.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `links.disabled`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Link-Event-Data'
          description: Identifikátory entit, kterých se událost týká
    Refund-Succeeded-Event:
      type: object
      title: Událost úspěšného vrácení platby
      description: 'Varianta `refunds.succeeded` unie [Event](#/schemas/Event). Vrácení platby bylo vypořádáno.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `refunds.succeeded`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Refund-Event-Data'
          description: Identifikátory entit, kterých se událost týká
    Refund-Failed-Event:
      type: object
      title: Událost neúspěšného vrácení platby
      description: 'Varianta `refunds.failed` unie [Event](#/schemas/Event). Vrácení platby se nepodařilo vypořádat.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `refunds.failed`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Refund-Event-Data'
          description: Identifikátory entit, kterých se událost týká
    Recurrence-Started-Event:
      type: object
      title: Událost spuštění opakovaného předpisu
      description: 'Varianta `recurrences.started` unie [Event](#/schemas/Event). Opakovaný předpis byl aktivován platbou uvedenou v `data`.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `recurrences.started`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Recurrence-Payment-Data'
          description: Identifikátory entit, kterých se událost týká
    Recurrence-Payment-Created-Event:
      type: object
      title: Událost vzniku platby z opakovaného předpisu
      description: 'Varianta `recurrences.payment_created` unie [Event](#/schemas/Event). Z opakovaného předpisu vznikla naplánovaná platba.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `recurrences.payment_created`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Recurrence-Payment-Data'
          description: Identifikátory entit, kterých se událost týká
    Recurrence-Stopped-Event:
      type: object
      title: Událost zastavení opakovaného předpisu
      description: 'Varianta `recurrences.stopped` unie [Event](#/schemas/Event). Opakovaný předpis byl zastaven.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `recurrences.stopped`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Recurrence-Event-Data'
          description: Identifikátory entit, kterých se událost týká
    Card-Updated-Event:
      type: object
      title: Událost změny uložené karty
      description: 'Varianta `cards.updated` unie [Event](#/schemas/Event). Uložený karetní token se změnil, například poté, co vydavatel kartu znovu vydal.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `cards.updated`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Card-Event-Data'
          description: Identifikátory entit, kterých se událost týká
    Card-Deleted-Event:
      type: object
      title: Událost smazání uložené karty
      description: 'Varianta `cards.deleted` unie [Event](#/schemas/Event). Uložený karetní token byl smazán.'
      required:
        - id
        - type
        - occurred_at
        - data
      properties:
        id:
          type: string
          description: 'Jedinečný identifikátor události. Na této hodnotě server obchodníka odstraňuje duplicity'
          examples:
            - 01ARZ3NDEKTSV4RRFFQ69G5FAV
        type:
          $ref: '#/components/schemas/Event-Type'
          description: Vždy `cards.deleted`
        occurred_at:
          type: string
          format: date-time
          description: 'Kdy se skutečnost stala, v UTC. Může obsahovat zlomky sekundy'
          examples:
            - '2026-07-08T12:04:39.123Z'
        data:
          $ref: '#/components/schemas/Card-Event-Data'
          description: Identifikátory entit, kterých se událost týká
    Payment-Paid-Data:
      type: object
      title: Data zaplacení platby
      description: 'Identifikuje platbu, a pokud ji zaplatilo stržení, i toto stržení.'
      required:
        - payment_id
      properties:
        payment_id:
          type: string
          description: Identifikátor platby
          examples:
            - '300000001'
        charge_id:
          type: string
          description: 'Identifikátor stržení, kterým byla platba zaplacena. Chybí, pokud platbu nezaplatilo stržení, například na hostované bráně na `gw_url`'
          examples:
            - '9123456789'
    Payment-Event-Data:
      type: object
      title: Data události platby
      description: Identifikuje platbu, které se událost týká.
      required:
        - payment_id
      properties:
        payment_id:
          type: string
          description: Identifikátor platby
          examples:
            - '300000001'
    Link-Payment-Created-Data:
      type: object
      title: Data vzniku platby z odkazu
      description: Identifikuje platební odkaz a platbu, která z něj vznikla.
      required:
        - link_id
        - payment_id
      properties:
        link_id:
          type: string
          description: Identifikátor platebního odkazu
          examples:
            - '346346346'
        payment_id:
          type: string
          description: Identifikátor platby
          examples:
            - '300000001'
    Link-Event-Data:
      type: object
      title: Data události odkazu
      description: Identifikuje platební odkaz, kterého se událost týká.
      required:
        - link_id
      properties:
        link_id:
          type: string
          description: Identifikátor platebního odkazu
          examples:
            - '346346346'
    Refund-Event-Data:
      type: object
      title: Data události vrácení platby
      description: Identifikuje vrácení platby a platbu, ke které patří.
      required:
        - payment_id
        - refund_id
      properties:
        payment_id:
          type: string
          description: Identifikátor platby
          examples:
            - '300000001'
        refund_id:
          type: string
          description: Identifikátor vrácení platby
          examples:
            - '3050123456'
    Recurrence-Payment-Data:
      type: object
      title: Data platby z opakovaného předpisu
      description: 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.
      required:
        - recurrence_id
        - payment_id
      properties:
        recurrence_id:
          type: string
          description: Identifikátor opakovaného předpisu
          examples:
            - '5521002'
        payment_id:
          type: string
          description: Identifikátor platby
          examples:
            - '300000001'
    Recurrence-Event-Data:
      type: object
      title: Data události opakovaného předpisu
      description: Identifikuje opakovaný předpis, kterého se událost týká.
      required:
        - recurrence_id
      properties:
        recurrence_id:
          type: string
          description: Identifikátor opakovaného předpisu
          examples:
            - '5521002'
    Card-Event-Data:
      type: object
      title: Data události uložené karty
      description: 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.
      required:
        - card_id
      properties:
        card_id:
          type: string
          description: Identifikátor uloženého karetního tokenu
          examples:
            - '8007127320'
    Event-List:
      type: object
      title: Seznam událostí
      description: Jedna stránka událostí e-shopu, od nejnovější
      required:
        - items
      properties:
        items:
          type: array
          description: Události na této stránce
          items:
            $ref: '#/components/schemas/Event'
          examples:
            - - id: 01ARZ3NDEKTSV4RRFFQ69G5FAV
                type: payments.paid
                occurred_at: '2026-07-08T12:04:39.123Z'
                data:
                  payment_id: '300000001'
                  charge_id: '9123456789'
        next_page_url:
          type: string
          format: uri
          description: |-
            Ú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.
          examples:
            - 'https://gate.gopay.com/gp-gw/api/4.0/eshops/8123456789/events?type=refunds.*&max_items=20&prev_item=01H8ZQ7X9K4Q0M2V6T8B3C5D7E'
    JWK-Set:
      type: object
      title: Sada JWK
      description: '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)'
      required:
        - keys
      properties:
        keys:
          type: array
          description: Aktuálně používané podpisové klíče webhooků
          items:
            $ref: '#/components/schemas/Signing-JWK'
          examples:
            - - kty: RSA
                use: sig
                kid: sign-2026-02
                alg: RS256
                'n': 4JHqz4QwbiVuVzLhjJwwgK_EC86qVTPhQIpmiQCoGNzLBQlsBdt13Y10AlzRSMMF65LyF5Y8doKR-gJlCR9J5P9YPr1IgU0wVyqJ349yL7O_lMWy5TfWdGz7KOrq9tyHVtjH0i5ztAIQHPvQ02LayjdNgUA4Z8RxFsSz03nCU-dJLJOg63BS23VfxEs4J_kmbITSACIxiIAerc-wUwIQkjlHyHQQtac7kcCQfSqDB3F2YqxFkWOC66drt2zcMutjxcK-ZcnjdBiQnTI_9izbJB9mX4CoErMWre7GNt_krHoi6OP6DoOvjEsABAS2Dyf13xLuNVH-QHpCUaYqR70OTQ
                e: AQAB
    Signing-JWK:
      type: object
      title: Podpisový JWK
      description: 'Struktura veřejného podpisového klíče webhooků. Je formátovaná podle RFC 7517: JSON Web Key (JWK)'
      properties:
        kty:
          const: RSA
          description: Typ klíče. U podpisových klíčů GoPay vždy `RSA`.
          examples:
            - RSA
        use:
          const: sig
          description: Použití klíče. Vždy `sig` (podpis).
          examples:
            - sig
        kid:
          type: string
          description: 'ID klíče. Odpovídá `kid` v chráněné hlavičce `X-GoPay-Signature`, kterou klíč ověřuje'
          examples:
            - sign-2026-02
        alg:
          const: RS256
          description: Algoritmus, kterým byl podpis vytvořen. Vždy `RS256`.
          examples:
            - RS256
        'n':
          type: string
          description: Modul veřejného klíče `RSA`.
          examples:
            - 4JHqz4QwbiVuVzLhjJwwgK_EC86qVTPhQIpmiQCoGNzLBQlsBdt13Y10AlzRSMMF65LyF5Y8doKR-gJlCR9J5P9YPr1IgU0wVyqJ349yL7O_lMWy5TfWdGz7KOrq9tyHVtjH0i5ztAIQHPvQ02LayjdNgUA4Z8RxFsSz03nCU-dJLJOg63BS23VfxEs4J_kmbITSACIxiIAerc-wUwIQkjlHyHQQtac7kcCQfSqDB3F2YqxFkWOC66drt2zcMutjxcK-ZcnjdBiQnTI_9izbJB9mX4CoErMWre7GNt_krHoi6OP6DoOvjEsABAS2Dyf13xLuNVH-QHpCUaYqR70OTQ
        e:
          type: string
          description: Exponent veřejného klíče `RSA`.
          default: AQAB
          examples:
            - AQAB
      required:
        - kty
        - use
        - kid
        - alg
        - 'n'
        - e
      examples:
        - kty: RSA
          use: sig
          kid: sign-2026-02
          alg: RS256
          'n': 4JHqz4QwbiVuVzLhjJwwgK_EC86qVTPhQIpmiQCoGNzLBQlsBdt13Y10AlzRSMMF65LyF5Y8doKR-gJlCR9J5P9YPr1IgU0wVyqJ349yL7O_lMWy5TfWdGz7KOrq9tyHVtjH0i5ztAIQHPvQ02LayjdNgUA4Z8RxFsSz03nCU-dJLJOg63BS23VfxEs4J_kmbITSACIxiIAerc-wUwIQkjlHyHQQtac7kcCQfSqDB3F2YqxFkWOC66drt2zcMutjxcK-ZcnjdBiQnTI_9izbJB9mX4CoErMWre7GNt_krHoi6OP6DoOvjEsABAS2Dyf13xLuNVH-QHpCUaYqR70OTQ
          e: AQAB
x-internal: false