GoPay technická dokumentace

GoPay technická dokumentace

Dokumentace

Tento dokument popisuje integraci platební brány GoPay pomocí našeho REST API a je určen pro vývojaře. Pokud vlastníte eshopovou platformu a hledáte GoPay pluginy, navštivte článek Obecný postup integrace.

GoPay REST API

Tato dokumentace obsahuje průvodce integrací platební brány GoPay a REST API referenci. K integraci můžete použít také jednu z námi nabízených knihoven.

PHP

Python

.NET (C#)

Java

git clone https://github.com/gopaycommunity/gopay-java-api.git
cd gopay-java-api
mvn package
API

API Endpoints

Sandbox enviroment - https://gw.sandbox.gopay.com/api
Production enviroment - https://gate.gopay.cz/api
Autentizace

Zabezpečení je zajištěno protokolem OAuth2.0. Základem komunikace s GoPay platební bránou je přístupový token. Token lze generovat ve dvou stupních oprávnění. payment-create umožní pomocí tokenu pouze zakládat platby, zatímco payment-all umožní pomocí tokenu provádět veškeré API operace.

Popis API volání pro získání tokenu a ukázky pro jednotlivé knihovny naleznete v sekci Získání přístupového tokenu v API Referenci.

Pro získání přístupového tokenu je nutno od GoPay obdržet údaje Client ID a Client Secret. Získání tokenu je provedeno API voláním, ve kterém jsou přístupové údaje předávány. Je použita HTTP Basic autentizace podle RFC 7617. Přístupové údaje jsou předány ve formě <ClientId>:<ClientSecret> zakódované v base64 a předané v hlavičce Authorization, např.:

Authorization: Basic PENsaWVudElkPjo8Q2xpZW50U2VjcmV0Pg==

Pro všechny ostatní API operace probíhá autorizace pomocí získaného tokenu. Token má životnost 30 minut a lze ho používat opakovaně na více operací, dokud mu životnost neskončí. Celý token je předáván v HTTP hlavičce Authorization za označením Bearer, např.:

Authorization: Bearer AAArt6RuTM69kX6UUGZ6p9hyMPrTUVXmMDdkC4BNnQvQcbNyUTvQtCv45R969
Vytvoření a průběh platby

Tato kapitola obsahuje obecný popis, jakým probíhá vytvoření platby, vyvolání platební brány, dále jakou má platba životnost a jakým způsobem se mění její stavy. Popisy jednotlivých kroků jsou popsány v samostatných částech dokumentace.

Přehled kroků

  • Získat prostřednictvím API přístupový token
  • Založit pomocí tokenu a dat z objednávky platbu
  • Pomocí získané gw_url (URL platby) vyvolat platební bránu
  • Při přesměrování zákazníka na návratovou URL získat ID platby a dotázat se s jeho pomocí na stav platby
  • Při přijetí asynchronní HTTP notifikace získat ID platby a dotázat se s jeho pomocí na stav platby

Vytvoření platby

Prvním krokem k vytvoření platby je získání tokenu. Toto je provedeno pomocí API volání v rámci REST API. U některých software knihoven je token získán automaticky při inicializaci.

Dalším krokem je samotné založení platby. Toto je provedeno pomocí API volání pro založení platby, v němž předáte parametry platby a údaje o zákazníkovi. Dále předáte return_url, na kterou bude zákazník přesměrován zpět z brány, a notification_url na kterou bude zaslána HTTP notifikace. K oběma bude v query parametru přidáno ID platby. Také zde určíte, jaké platební metody budou pro platbu k dispozici - viz sekce Nastavení platebních metod.

Na API volání je jako odpověď vrácen JSON, který obsahuje dvě důležité informace:

  • ID platby - v parametru id, což je jedinečný identifikátor platby v rámci systému GoPay. Pomocí něj lze provádět dotaz na stav platby.
  • URL platební brány - v parametru gw_url - pomocí této URL lze zákazníka přesměrovat na platební bránu nebo vyvolat inline bránu.

Dále v závislosti na typu platby může odpověď obsahovat další informace. Detailní popisy pro založení jednotlivých druhů plateb naleznete v samostatné sekci Platby.

Otevření platební brány

Pomocí získané gw_url je možné vyvolat platební bránu, která může být v jedné ze 3 verzí

  • Redirect varianta. Na získanou gw_url zákazníka přesměrujete (např. HTTP redirectem, HTML formulářem apod.) Zákazník opustí e-shop a přejde na zabezpečené prostředí GoPay platební brány pod doménou gate.gopay.cz.
  • Inline varianta. Je potřeba implementovat JavaScriptem na straně eshopu. Eshop se musí nacházet na doméně s HTTPS zabezpečením. Zákazník není přesměrován z eshopu, platební brána se otevře přes něj jako overlay. Pokud v některém kroku platby dojde k přesměrování na stránky třetí strany (online banking, 3DS), vrátí se zákazník na bránu ve variantě Redirect. Ukázky a detailnější popis platební brány naleznete v našem centru nápovědy v článku Co je inline platební brána?.
  • Mobilní varianta. Na mobilních zařízeních je vždy vyvolána mobilní verze redirect brány, i pokud máte v eshopu implementovanou inline variantu. Mobilní brána je optimalizována pro zobrazení a ovládání na mobilních zařízeních.

Detailní informace k vyvolání platební brány a návod, jak implementovat Inline variantu, naleznete v sekci Vyvolání platební brány

Vybrání platební metody

Na platební bráně má zákazník na výběr platební metody, které byly povoleny při Založení platby. Zákazníkovi se zobrazí buďto seznam platebních metod, nebo lze jednu předvybrat. Bližší informace jsou v sekci Nastavení platebních metod.

Dále má zákazník možnost platební bránu zavřít křížkem. Tím je přesměrován zpět na návratovou URL, aniž by proběhl pokus o uhrazení platby. Platba v tomto případě zůstává ve stavu CREATED.

V okamžiku, kdy se zákazník pokusí platbu uhradit tlačítkem pro potvrzení platby (může na něm být Zaplatit, či jiná textace), přiřadí se k platbě platební metoda a stav platby se změní na PAYMENT_METHOD_CHOSEN. Pokud se zákazník nachází např. na formuláři se zadáním čísla karty, ale ještě neklikl na tlačítko Zaplatit, není platební metoda vybrána.

Dokončení platby

Poté, co je platební metoda zvolena, dojde k autorizaci platby. Pro každou platební metodu se tento proces může lišit. Výsledkem může být jedna z těchto situací:

  • Platba je uhrazena. Autorizace dopadla úspěšně a částka platby je připsána na GoPay účet obchodníka. Platba je ve stavu PAID (popřípadě AUTHORIZED u předautorizací).
  • Platba je zamítnuta. V některém bodu došlo k zamítnutí platby ze strany partnera (např. banka nebo 3DS centrum zákazníka). Platba je ve stavu CANCELED.
  • Zatím neznáme výsledek platby. Nemáme od protistrany ještě výsledek o tom, jak platba dopadla. Toto může přetrvávat i poté, co se zákazník vrátí do eshopu. Jakmile bude výsledek znám, bude k platbě odeslána notifikace.

Pokud je platba v některém z těchto stavů, již není možné měnit platební metodu, ani se k ní vrátit.

Zákazník je přesměrován zpět na eshop poté, co dokončí platbu. Bránu může také zavřít sám a tím dojde k návratu na eshop. Přesměrován je na return_url, která byla předána při založení platby. K URL jsou připojeny query parametry:

  • id - obsahuje ID platby, podle kterého lze dotázat její stav
  • parent_id - pouze u opakované platby - obsahuje ID zakládající platby

Pomocí parametrů eshop provede dotaz na stav platby a zákazníka o výsledku informuje.

Odeslání notifikace

Pokud dojde ke změně stavu platby, je odeslána HTTP notifikace. Skládá se z notification_url, která byla předána při založení platby. K URL jsou připojeny query parametry:

  • id - obsahuje ID platby, podle kterého lze dotázat její stav
  • parent_id - pouze u opakované platby - obsahuje ID zakládající platby

Na tuto URL je odeslán HTTP GET request. Pouze u změny stavu platby z CREATED na PAYMENT_METHOD_CHOSEN k odeslání notifikace nedochází. Notifikace informace o stavu platby nenese, pouze id. Stav je potřeba ověřit pomocí API volání. Stav platby se může změnit vícekrát (např. jednou při zaplacení na PAID a později při refundaci na REFUNDED).

Stavy a životnost plateb

Platba může mít následující stavy:

  • CREATED - platba vytvořena
  • PAYMENT_METHOD_CHOSEN - čeká se na výsledek platby
  • TIMEOUTED - životnost platby vypršela
  • PAID - platba byla uhrazena
  • CANCELED - platba byla zamítnuta
  • AUTHORIZED - platba byla předautorizována
  • PARTIALLY_REFUNDED - část platby byla refundována
  • REFUNDED - celá platba byla refundována

Proces platby má 2 životnosti:

  • Životnost 1 - od vytvoření platby po potvrzení platební metody na bráně - vždy stejná pro každou platbu ve stavu CREATED
  • Životnost 2 - od potvrzení platební metody na bráně po výsledek / koncový stav platby - liší se pro jednotlivé platební metody

Pokud do vypršení první životnosti nedojde k pokusu platbu uhradit, nastane stav TIMEOUTED. Pokud do vypršení druhé životnosti není znám výsledek platby, také nastane stav TIMEOUTED.

Platby

Tato sekce popisuje jednotlivé typy plateb. Standardní platby jsou dostupné pro všechny platební metody. Ostatní typy plateb jsou dostupné pouze pro platby kartou (tedy Apple Pay a Google Pay).

Standardní platba

Standardní platba je jednorázová platba, kterou lze uhradit jakoukoliv platební metodou. Její průběh je popsán v sekci Popis vytvoření a průběhu platby.

Založení standardní platby

K založení standardní platby využijete API volání pro založení platby. Stačí předat pouze povinné parametry requestu. U standardní platby je vždy potřeba její autorizace ze strany zákazníka.

Všechny ostatní typy plateb jsou zakládány stejným API voláním, které je obohacené o dodatečné parametry.

Všechny typy plateb lze navzájem kombinovat. Platba tedy může být například opakovatelná na vyžádání a předautorizovaná současně.

Příklady pro všechna SDKs a podrobný popis API volání naleznete v sekci Založení platby.

HTTP

Založení minimální platby

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}
Opakovaná platba

Opakovaná platba slouží ke strhávání prostředků z karty zákazníka na pozadí. Zákazník tedy musí na platební bránu pouze jednou.

Opakovaná platba má dva druhy:

  • AUTO - platba je strhávána automaticky v předem daných intervalech. Nelze měnit částku, ani jiné parametry platby.
  • ON_DEMAND platba je strhávána požadavkem přes REST API. Strhávat lze v nepravidelných intervalech a lze měnit částku i jiné parametry.

Průběh opakovaných plateb je následující:

  • Zakládající platba - probíhá stejně jako standardní platba, zákazník je přesměrován na platební bránu, kde musí platbu dokončit, a tím vznikne zakládající platba.
  • Následné platby - probíhají buď automaticky, nebo jsou vytvořeny API voláním. V něm je reference na jejich zakládající platbu. Probíhají na pozadí, není nutná interakce zákazníka.

Opakovatelné platby jsou automaticky k dispozici pouze na testovacím prostředí. Pro jejich aktivaci na provozním prostředí kontaktujte naše oddělení zákaznické podpory a uveďte konkrétně, který typ opakovaných plateb si přejete aktivovat. Váš portál musí splňovat podmínky uvedené v článku Jaké informace musím prezentovat pro opakované platby? našeho centra nápovědy.

Automatická opakovaná platba

Automatická opakovaná platba je založena API voláním pro založení platby. V requestu je předán objekt recurrence.

U automatické platby je povinné předat tyto parametry:

  • recurrence_cycle určuje cyklus opakované platby, tedy zda opakovaná platba bude prováděna každý Xtý den, týden či měsíc. Nabývá hodnot uvedených v číselníku Recurrence cycle.
  • recurrence_period určuje periodu opakování platby (nikoliv frekvenci), tedy kolik dnů, týdnů či měsíců má uplynout mezi dvěma platbami.
  • recurrence_date_to určuje platnost opakované platby. Do tohoto data ji bude systém platební brány automaticky strhávat. Hodnota musí být vyšší než aktuální datum a vyšší než poslední den, kdy se má platba strhnout.

Ve objektu se určuje perioda, nikoliv frekvence. Příklad:

{
    "recurrence_cycle": "MONTH",
    "recurrence_period": 2,
    "recurrence_date_to": "2025-12-31"
}

S tímto voláním bude opakovaná platba provedena jednou za 2 měsíce, nikoliv 2x měsíčně.

Pokud si přejete platby opakovat ročně, nastavte recurrence_cycle na MONTH a recurrence_period na 12, pak bude opakování probíhat každých 12 měsíců, tedy jednou ročně

Následné opakované platby mají stejné parametry jako zakládající platba, nelze tedy měnit např. částku apod. Pokud je následná platba zamítnuta, další pokus o stržení platby proběhne až v následujícím termínu opakování.

Podrobný popis API volání a příklady pro jednotlivé knihovny naleznete v sekci založení standardní platby. U opakované platby je potřeba předat povinný objekt recurrence.

HTTP

Založení AUTO opakované platby

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "recurrence": {
        "recurrence_cycle": "DAY",
        "recurrence_period": 7,
        "recurrence_date_to": "2099-12-31"
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "recurrence": {
            "recurrence_cycle": "DAY",
            "recurrence_period": 7,
            "recurrence_date_to": "2099-12-31",
            "recurrence_state": "REQUESTED"
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}
Opakovaná platba na vyžádání

Opakovaná platba na vyžádání je zakládána stejným API voláním, jako automatická a je tedy rovněž potřeba předat povinný objekt recurrence.

V tomto objektu je potřeba předat tyto povinné parametry:

  • recurrence_cycle vždy ON_DEMAND
  • recurrence_date_to určuje platnost opakované platby. Do tohoto data ji bude systém platební brány strhávat na základě vašich API požadavků. Hodnota musí být vyšší než aktuální datum a vyšší než poslední den, kdy se má platba strhnout.

Parametr recurrence_period se u tohoto druhu opakované platby vůbec nepoužívá. Stržení následných plateb probíhá pomocí k tomu určeného API volání. V něm se zadává částka, ID objednávky a další parametry platby.

V době, kdy je vrácena odpověď na API volání, ještě platba zpravidla nebývá uhrazena. O výsledku platby je možné se informovat pomocí dotazu na stav platby na základě HTTP notifikace, kterou vám zašleme při změně stavu platby.

Příklady pro všechna SDKs a podrobný popis API volání naleznete v sekci Založení platby a Stržení opakované platby.

Zakládající platba
Následná platba

Založení ON_DEMAND opakované platby

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 100,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "recurrence": {
        "recurrence_cycle": "ON_DEMAND",
        "recurrence_date_to": "2099-12-31"
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notification-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 100,
    "currency": "CZK",
    "payer": {
        "contact": {
        "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "recurrence": {
        "recurrence_cycle": "ON_DEMAND",
        "recurrence_date_to": "2099-12-31",
        "recurrence_state": "REQUESTED"
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}

Stržení následné platby

POST /api/payments/payment/3123456789/create-recurrence HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456"
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456780,
    "parent_id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "lang": "cs",
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}
Zrušení opakované platby

Zrušení opakované platby je možné následujícími způsoby:

  • Ze strany obchodníka pomocí API volání pro zrušení opakované platby
  • Ze strany obchodníka prostřednictvím GoPay obchodního účtu
  • Ze strany zákazníka prostřednictvím e-mailu se stavem platby, který mu zasíláme
  • Ze strany GoPay (zpravidla na žádost zákazníka)
  • Automaticky v okamžiku, kdy dojde k vypršení platnosti karty zákazníka
  • Automaticky v okamžiku, kdy nastane datum předané jako date_to při založení platby

Pokud se přes API pokusíte zrušit opakování, které již v minulosti zrušené bylo, končí volání chybou s popisem, že opakování již je zrušeno.

Při zrušení opakování platby standardně nedochází k odeslání HTTP notifikace. Pokud si ji přejete v tomto případě dostávat, kontaktujte technickou podporu GoPay.

Příklady pro všechna SDKs a podrobný popis API volání naleznete v sekci Zrušení opakované platby.

HTTP

Zrušení opakované platby

POST /api/payments/payment/3123456789/void-recurrence HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "result": "FINISHED"
}
Stav opakované platby

V odpovědi na dotaz na stav platby je u mateřské opakovatelné platby vrácen navíc objekt recurrence, který popisuje opakování platby. Ten obsahuje i parametr recurrence_state, který popisuje stav opakování platby. Podle jeho hodnoty lze ověřit, zda k dané zakládající platbě lze provádět následné opakované platby, či nikoliv.

HTTP

Dotaz na stav opakované platby. Viz Dotaz na stav platby.

GET /api/payments/payment/3123456789 HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "PAID",
    "payment_instrument": "PAYMENT_CARD",
    "amount": 100,
    "currency": "CZK",
    "payer": {
        "payment_card": {
            "card_number": "440507******4448",
            "card_expiration": "9912",
            "card_brand": "Visa",
            "card_issuer_country": "CZE",
            "card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
        },
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "recurrence": {
        "recurrence_cycle": "ON_DEMAND",
        "recurrence_date_to": "2099-12-31",
        "recurrence_state": "STARTED"
    },
    "lang": "cs",
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/...",
}
Best practice

Standardně lze provádět nejvýše jednu následnou opakovanou platbu na vyžádání za kalendární den. Výjímkou je den, kdy je založena mateřská opakovatelná platba, ta se již do tohoto limitu počítá, takže ve stejný den nelze vytvořit následnou opakovanou platbu.

V případě, že opakování nebude úspěšné, budete pravděpodobně chtít provést další pokus platbu strhnout. Takovýto pokus je možné provést nejdříve následující kalendární den, nebo 24 hodin od posledního pokusu. Při pokusu strhnout platbu dříve dojde k zamítnutí pokusu kvůli limitu jednoho opakování denně.

Nedoporučujeme také opakování hned po první neúspěšné opakované platbě rušit. Doporučujeme provést celkem alespoň 3 pokusy v rozmezí nejméně 24h od sebe, než zrušíte opakovanou platbu a zákazníkovi předplacenou službu. Můžete také brát v potaz víkendy a pokusy o opakování provádět pouze v pracovní dny, kdy je větší pravděpodobnost, že zákazníkovi přibydou na účtě chybějící finance.

Před provedením dalšího pokusu o opakování platby vždy nejdříve vyčkejte na obdržení HTTP notifikace k předchozímu pokusu a zkontrolujte jeho stav. Tím se vyhnete možnému duplicitnímu stržení platby. Také doporučujeme rozlišovat mezi situacemi, kdy k vytvoření platby došlo, ale byla následně zamítnutá a situacemi, kdy k vytvoření vůbec nedošlo (vrátil se API error).

Předautorizovaná platba

Předautorizované platby umožňují vytvoření blokace (předautorizace) finančních prostředků na kartě zákazníka namísto stržení. Vytvořenou blokaci zaručujeme po dobu 4 dnů. Během této doby může obchodník platbu buď strhnout nebo uvolnit. Platbu je možné strhnout buďto v plné výši, anebo pouze část autorizované částky. Předautorizované platby se hodí například pro platby za zboží, u kterého v době nákupu není jisté, zda bude dostupné.

Předautorizované platby jsou automaticky k dispozici pouze na testovacím prostředí. Pro jejich aktivaci na provozním prostředí kontaktujte naše oddělení technické podpory. Uveďte také výslovně, zda chcete aktivovat i částečné strhávání plateb.

Založení předautorizované platby

Předautorizovaná platba je založena API voláním pro založení platby, ve kterém je potřeba předat parametr preauthorization s hodnotou true. Po založení platby je vrácen objekt popisující její stav a parametry. Průběh autorizace platby je stejný jako u standardní platby, jak je popsáno v sekci Popis vytvoření a průběhu platby.

Poté, co zákazník předautorizovanou platbu dokončí, platba přechází do stavu AUTHORIZED. O změně stavu platby informujeme prodejní místo pomocí automatické HTTP notifikace na notifikační URL adresu předanou při založení platby. V tomto okamžiku je na účtě klienta provedena blokace částky, která zatím není stržena (zaúčtována).

HTTP

Založení předautorizované platby

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "preauthorization": true,
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notification-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "preauthorization": {
        "requested": true,
        "state": "REQUESTED"
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}
Stržení předautorizované platby

Autorizovanou platbu je možno strhnout dvěma způsoby:

  • Stržení platby v plné výši. Využijete k tomu API volání, ve kterém není potřeba předávat žádné parametry. Volání strhne blokaci z účtu zákazníka a finanční prostředky připíše na GoPay obchodní účet obchodníka.
  • Částečné stržení. Lze jej provést pomocí API volání pro částečné stržení. V něm je potřeba v parametru amount specifikovat částku platby, která musí být nižší nebo rovna celkové autorizované částce. V případě stržení menší částky, než na kterou byla platba původně autorizována, dochází k aktualizaci údajů původní platby dle nového volání. Zbylá částka je zákazníkovi automaticky uvolněna zpět na platební kartu.

Platba následně přechází do stavu PAID.

Stržení
Částečné stržení

Stržení předautorizované platby

POST /api/payments/payment/3123456789/capture HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "result": "FINISHED"
}

Částečné stržení předautorizované platby

POST /api/payments/payment/3123456789/capture HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 5000
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "result": "FINISHED"
}
Zrušení předautorizované platby

Již autorizovanou platbu lze také zrušit prostřednictvím API volání pro zrušení předautorizace. Blokace finančních prostředků na účtu zákazníka je následně uvolněna a platba přechází do stavu CANCELED.

HTTP

Zrušení předautorizované platby

POST /api/payments/payment/3123456789/void-authorization HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "result": "FINISHED"
}
Platba s nulovou částkou

Předautorizovanou platbu lze také založit s nulovou částkou. Proběhne pouze ověření karty, ale nebude blokována žádná částka. To lze zkombinovat např. se zakládající opakovanou platbou (režim ON_DEMAND) pokud chcete nabídnout zkušební období zdarma. Dále lze s iniciační platbou pro vytvoření karetního tokenu, pokud chcete získat token bez toho, abyste zákazníkovi něco účtovali.

Takto založenou platbu nelze strhnout (volání skončí chybou), ale lze ji zrušit.

Kombinace platby s nulovou částkou a zakládající opakované platby není aktuálně podporována Raiffeisenbank! Takovéto platby nelze autorizovat kartami Raiffeisenbank a EQUA bank.

HTTP

Založení předautorizované platby s nulovou částkou

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 0,
    "currency": "CZK",
    "order_number": "123456",
    "preauthorization": true,
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notification-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 0,
    "currency": "CZK",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "preauthorization": {
        "requested": true,
        "state": "REQUESTED"
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}
Unikátní otisk karty

U plateb kartou je možné získávat unikátní otisk karty (tzv. card_fingerprint). Pomocí něj lze porovnat, zda dvě platby byly uhrazeny jednou a tou samou kartou. Pokud je karta použita prostřednictvím Apple Pay nebo Click To Pay, bude se otisk lišit od případu, kdy byla ručně zadána.

Při uložení karty s vyžádáním karetního tokenu (viz Platba karetním tokenem) je card_fingerprint vždy generován.

card_fingerprint bude součástí objektu payment card v dotazu na stav platby.

Funkce vytváření fingerprintu není automaticky aktivní. Pro její aktivaci kontaktuje technickou podporu GoPay.

Platba karetním tokenem

Při platbě kartou je možno vyžádat si uložení karty. V tom případě dojde i k přiřazení karetního tokenu, který můžete předat v následných platbách. U takových plateb nebude zákazník muset zadávat údaje z karty ručně.

Pro aktivaci vytváření karetních tokenů na testovacím i provozním prostředí kontaktujte naše oddělení technické podpory.

Přehled postupu pro získání tokenu:

  • Založit platby s parametrem request_card_token
  • Poté, co ji zákazník uhradí, provést dotaz na stav platby
  • Z odpovědi získat hodnotu card_id
  • Provést dotaz na detaily karty
  • Z odpovědi získat hodnotu card_token
Platba s vyžádáním karetního tokenu

Pro vytvoření karetního tokenu proveďte standardní založení platby pomocí API volání, kde je v objektu payer potřeba předat v poli request_card_token hodnotu true. V poli allowed_payment_instruments předejte jako jedinou hodnotu PAYMENT_CARD.

Poté, co je uhrazena, provedete dotaz na stav platby. V odpovědi nalezneme objekt payer, který obsahuje card_id. Díky tomuto identifikátoru můžete získat detaily karty včetně tokenu a jeho stavu.

Založení
Stav platby

Založení platby s vyžádáním tokenu

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "allowed_payment_instruments": ["PAYMENT_CARD"],
        "request_card_token": "true",
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": ["PAYMENT_CARD"],
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8179544857
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}

Dotaz na stav platby s vyžádáním tokenu

GET /api/payments/payment/3123456789 HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "PAID",
    "payment_instrument": "PAYMENT_CARD",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": ["PAYMENT_CARD"],
        "payment_card": {
            "card_number": "440507******4448",
            "card_expiration": "9912",
            "card_brand": "Visa",
            "card_issuer_country": "CZE",
            "card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
        },
        "contact": {
            "email": "john.doe@example.com"
        },
        "card_id": "9876543210"
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "lang": "en",
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/...",
}
Získání detailů karty

Pomocí k tomu určeného API volání můžete díky hodnotě card_id získat detaily uložené karty.

Detaily obsahují:

  • Údaje karty, jako vymaskovaný PAN a expiraci
  • card_fingerprint, díky kterému můžete ověřit, zda daná karta již je uložená
  • card_token, který můžete použít pro následné platby

Před čtením dalších údajů o kartě vždy nejprve kontrolujte, zda parametr card_status nabývá hodnoty active. Pokud ne, nebude objekt obsahovat další údaje.

Aktivní karta
Smazaná karta

Dotaz na stav aktivní karty

GET /api/payments/cards/9876543210 HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "card_id": 9876543210,
    "card_number": "440507******4448",
    "card_expiration": "9912",
    "card_brand": "Visa",
    "card_issuer_country": "CZE",
    "card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
    "card_fingerprint": "0c823534ec582c97fa85c0bf7b020ee25a0a5af13974709bb329a709a79c2b3e",
    "card_token": "YZ4E8f2jJA8cEDz1s0lO4BMXo6skkvItJddyrLhSyPa01T/cvrl+DwKsEqehFG7SQxJZUsBcgZ6sei4AKxrHHap7BofFr+SH3oHJyta0axiBB7MST3IWqrsq5ZtfukBrgwPBocNDPd/RnQs=",
    "status": "ACTIVE"
}

Dotaz na stav smazané karty

GET /api/payments/cards/9876543210 HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "card_id": 9876543210,
    "status": "DELETED"
}
Platba s použitím karetního tokenu

Pro použití tokenu založte platbu pomocí standardního API volání. V objektu payer předejte v parametru allowed_card_token dříve získaný card_token. Tím zákazník nebude muset zadávat údaje z karty. 3DS ověření může být stále vyžadováno. V objektu payer také předejte pole allowed_payment_instruments a v něm pouze hodnotu PAYMENT_CARD. To je u tohoto typu platby vyžadováno.

HTTP

Založení platby s použitím karetního tokenu

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "allowed_payment_instruments": ["PAYMENT_CARD"],
        "allowed_card_token": {{YOUR-CARD-TOKEN}},
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": ["PAYMENT_CARD"],
        "contact": {
        "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}
Smazání karty

Karta může být smazána ze strany obchodníka a to k tomu určeným API voláním, anebo ze strany GoPay (např. z důvodu nepoužívání). Pokud je karta smazána, změní se card_status na deleted a údaje o kartě již nebudou k dispozici. O změně stavu informujeme pomocí HTTP notifikace.

HTTP

Smazání karty

DELETE /api/payments/cards/987654321 HTTP/1.1

Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 204 No Content
Notifikace ke kartě

Pro použití funkce platby tokenem je nutno u GoPay zaregistrovat URL, na kterou budou zasílány HTTP notifikace.

Ty jsou odesílány ve chvíli, kdy:

  • Došlo k revokaci tokenu ze strany GoPay nebo obchodníka
  • Došlo k aktualizaci údajů o kartě (např. při vypršení platnosti staré karty)

HTTP notifikace je GET požadavek s query parametrem card_idnesoucí dříve získané ID karty.

Například: GET https://example.com/card-notify?card_id=123456

Pomocí ID je pak následně potřeba provést dotaz na detaily karty a ověřit card_status, případně aktualizovat údaje.

PSD2 platba tokenem účtu

V anonymním režimu PSD2 probíhá platba takto:

  • Zákazník je přesměrován na svojí banku, kde udělí souhlas s využíváním služeb AISP a PISP ze strany společnosti GoPay
  • Zákazník je přesměrován zpět na platební bránu, kde vybírá účet a potvrzuje platbu
  • Zákazník je přesměrován na svoji banku, kde autorizuje transakci
  • Zákazník je vrácen zpět na platební bránu, kde dojde k dokončení platby

V zapamatovaném režimu si GoPay uchovává souhlas z předchozí anonymní platby a obchodníkovi předává token. Ten je možné použít u následných plateb - zákazník tak nebude muset znova udělovat souhlas a přejde rovnou k autorizaci platby. Souhlas platí 90 dnů, poté musí zákazník udělit nový.

Zapamatovaný režim není automaticky aktivní. Pro jeho aktivaci kontaktujte naše oddělení technické podpory. Obchodník musí projít kontrolou ze strany GoPay.

Tato funkcionalita je podporována všemi bankami, pro které na produkci podporujeme PSD2 platby.

Platba s vyžádáním tokenu účtu

Bez předání bankovních údajů

Poté, co zákazník v rámci PSD2 platby udělí souhlas pro GoPay, dojde k vypsání jeho účtů. Zákazník vybere, který účet chce použít a pokračuje k autorizaci platby.

Je použito standardní API volání pro založení platby, kdy je potřeba předat objekt payer tímto způsobem:

  • allowed_payment_instruments musí být vždy nastaveno pouze na BANK_ACCOUNT
  • allowed_swifts musí vždy být nastaveno na konkrétní banku zákazníka
  • pro banku musíte mít zapnuté PSD2 platby

S předáním bankovních údajů

Pokud znáte bankovní údaje zákazníka a chcete získat token k jednomu konkrétnímu účtu, můžete v API předat bankovní údaje. Poté, co zákazník v rámci PSD2 platby udělí souhlas pro GoPay, dojde k načtení jeho účtů. Pokud se žádný účet neshoduje s předanými údaji, platba je zamítnuta. Pokud je nalezena shoda, pokračuje zákazník k autorizaci platby.

Je použito standardní API volání pro založení platby, kdy je potřeba předat objekt payer tímto způsobem:

  • allowed_payment_instruments musí být vždy nastaveno pouze na BANK_ACCOUNT
  • allowed_swifts musí vždy být nastaveno na konkrétní banku zákazníka
  • je potřeba předat objekt bank_account a v něm údaje o účtu zákazníka buďto v českém, nebo v mezinárodním formátu
  • pro banku musíte mít zapnuté PSD2 platby
Bez údajů
ČR formát
Mezinárodní formát

Založení platby bez předání bankovních údajů

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "allowed_payment_instruments": ["BANK_ACCOUNT"],
        "allowed_swifts": ["AIRACZPP"],
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": ["BANK_ACCOUNT"],
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}

Založení platby s předáním bankovních údajů v českém formátu

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "allowed_payment_instruments": ["BANK_ACCOUNT"],
        "allowed_swifts": ["AIRACZPP"],
        "bank_account": {
            "account_number": "1234562",
            "bank_code": "3030"
        },
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": ["BANK_ACCOUNT"],
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}

Založení platby s předáním bankovních údajů v mezinárodním formátu

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "allowed_payment_instruments": ["BANK_ACCOUNT"],
        "allowed_swifts": ["AIRACZPP"],
        "bank_account": {
            "iban": "CZ8930300000000001234562"
        },
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": ["BANK_ACCOUNT"],
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}
Získání tokenu účtu

V okamžiku, kdy je první platba uhrazena, dochází standardně k odeslání HTTP notifikace, viz Odeslání notifikace. Z ní získáte ID platby a s jeho pomocí provedete dotaz na stav platby. V odpovědi na tento dotaz je vrácen token účtu jako součást objektu bank_account v objektu payer.

HTTP

Dotaz na stav platby s PSD2 zapamatovaným režimem

GET /api/payments/payment/3123456789 HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "PAID",
    "payment_instrument": "BANK_ACCOUNT",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": ["BANK_ACCOUNT"],
        "bank_account": {
            "account_number": "1234562",
            "bank_code": "3030",
            "iban": "CZ8930300000000001234562",
            "account_name": "John Doe",
            "account_token": "3c8bdc18281a9d5f60ab9675d9b0953805050157bf60fb37e2060a04a58e79bf"
        },
        "contact": {
            "email": "john.doe@example.com",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "lang": "en",
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/...",
}
Platba s použitím tokenu účtu

Pro použití tokenu založte platbu pomocí standardního API volání. V objektu payer předejte objekt bank_account a v něm dříve získaný account_token. Zákazník nebude muset procházet udělením souhlasu ani vybírat účet, pouze autorizuje platbu. V objektu payer také předejte pole allowed_payment_instruments a v něm pouze hodnotu BANK_ACCOUNT. To je u tohoto typu platby vyžadováno.

HTTP

Založení platby s použitím tokenu účtu

POST /api/payments/payment HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 1000,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "allowed_payment_instruments": ["BANK_ACCOUNT"],
        "bank_account": {
            "account_token": "{{YOUR-ACCOUNT-TOKEN}}"
        },
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url"
    }
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 1000,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": ["BANK_ACCOUNT"],
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}
Platební brána
Nastavení platebních metod

Na platební bráně jsou k dispozici všechny platební metody, které jsou aktivní v eshopu (v případě Apple Pay pouze na zařízeních, která tuto metodu podporují). Nastavení platebních metod na úrovni eshopu je popsané v článku Jak nastavím, které platební metody chci mít aktivní?.

Při založení platby je možné dostupné platební metody dále upřesnit předáním následujících parametrů v objektu payer:

  • allowed_payment_instruments - pole platebních metod, které budou na bráně k dispozici
  • default_payment_instrument - kód platební metody, která bude předvybraná
  • allowed_swifts - swifty bank, ze kterých bude možno platbu uhradit
  • default_swift - předvybraná banka
Určení platebních metod

Povolené platební metody

Povolené platební metody lze ovládat pomocí pole allowed_payment_instruments

  • Případ 1: pole allowed_payment_instruments vůbec nepředáte, zákazníkovi se zobrazí rozcestník všech platebních metod, které má eshop povolené
  • Případ 2: předáte více metod, zákazníkovi se zobrazí rozcestník, kde si bude moct jednu z předaných metod vybrat
  • Případ 3: předáte přesně jednu hodnotu, po otevření platební brány se rovnou zobrazí zákazníkovi

Z tohoto pole jsou také odstraněny všechny metody, které nejsou aktivní na eshopu.

Předvybraná platební metoda

Předvybranou platební metodu lze určit předáním parametru default_payment_instrument. Ovlivňuje pouze případy 1 a 2 viz výše, na případ 3 nemá vliv. Pokud tento parametr nepředáte, zobrazí se zákazníkovi rozcestník s výběrem platebních metod. Tímto parametrem můžete po otevření brány zákazníkovi rovnou zobrazit konkrétní platební metodu. Ten však stále bude mít možnost si platební metodu změnit. Předvybraná metoda musí být prvkem množiny nabízených metod v závislosti na nastavení povolených metod viz výše.

Povolené metody 1
Povolené metody 2
Povolené metody 3
Předvybraná metoda 1
Předvybraná metoda 2

allowed_payments_instruments se v objektu payer vůbec nevyskytuje

"payer": {
    "contact": {
        "email": "john.doe@example.com"
    }
}

allowed_payment_instruments obsahuje několik hodnot

"payer": {
    "allowed_payment_instruments": ["PAYMENT_CARD", "BANK_ACCOUNT", "PAYPAL"]
    "contact": {
        "email": "john.doe@example.com"
    }
}

allowed_payment_instruments obsahuje přesně jednu hodnotu

"payer": {
    "allowed_payment_instruments": ["PAYMENT_CARD"]
    "contact": {
        "email": "john.doe@example.com"
    }
}

Pouze předvybraná metoda - musí být aktivní na eshopu

"payer": {
    "default_payment_instrument": "PAYMENT_CARD",
    "contact": {
        "email": "john.doe@example.com"
    }
}

Předvybraná metoda i povolené metody - předvybraná metoda musí bý v množině povolených

"payer": {
    "allowed_payment_instruments": ["PAYMENT_CARD", "BANK_ACCOUNT", "PAYPAL"],
    "default_payment_instrument": "PAYMENT_CARD",
    "contact": {
        "email": "john.doe@example.com"
    }
}
Určení bank

Pro využití těchto parametrů je potřeba v allowed_payment_instruments předávat hodnotu BANK_ACCOUNT.

Online vs Offline převod

Nabízíme dva typy bankovních převodů. Offline převod je zobrazení platebních údajů, zákazník následně musí sám zadat platební příkaz. Platbu lze uhradit z jakékoliv banky, pokud jsou dobře uvedné platební údaje (číslo účtu, částka, VS). U online převodu přesměrujeme zákazníka přímo do jeho bankovnictví, kde má příkaz předpřipravený. Platbu lze uhradit pouze z jeho banky pomocí předpřipraveného platebního příkazu.

Povolené SWIFTy

Banky, ze kterých je možné převodem platit, můžete určit pomocí pole allowed_swifts. Ovlivňuje pouze online převody.

  • Případ 1: pole allowed_swifts vůbec nepředáte. Zákazník platbu bankovním převodem bude moci uhradit z jakékoliv banky a to online i offline.
  • Případ 2: v allowed_swifts předáte jeden či více SWIFTů. Offline převody nebudou vůbec dostupné. K dispozici budou pouze ty banky, pro které je dostupný online převod a zároveň jejichž SWIFT jste předali v poli allowed_swifts.
  • Případ 3: v poli allowed_swifts předáte pouze jeden SWIFT a zároveň v poli allowed_payment_instruments předáte pouze hodnotu BANK_ACCOUNT. Pokud je pro tuto banku dostupný online převod, bude zákazník po otevření brány automaticky přesměrován přímo do bankovnictví banky.

Předvybraný SWIFT

Předvybrat banku lze předáním jejího SWIFTu v parametru default_swift. Lze použít jakýkoliv - online i offline. Banka s předvybraným SWIFTem bude v seznamu bank zobrazena jako první a bude zvýrazněna.

Integrace Apple Pay

Platební metoda Apple Pay je vázána na platební metodu Platební karta. Je tedy potřeba mít na vašem e-shopu povolené platby kartou.

Apple Pay je k dispozici pouze na zařízeních, které takovéto platby umožňují (typicky Apple zařízení disponující Touch ID nebo Face ID). Doporučujeme ji tedy zobrazovat v objednávce pouze klientům, kteří takto zaplatit mohou. K tomu slouží JavaScript, který ověří, zda klient tyto podmínky splňuje. Více se dozvíte na stránkách Apple pro vývojaře.

První kontrola je window.ApplePaySession, která ověřuje, zda je k dispozici Apple Pay JS API, což je pouze v prohlížeči Safari. Tuto kontrolu je možné volat i na nezabezpečeném připojení (HTTP). Tuto variantu doporučujeme v případě, že váš web nemá TLS zabezpečení.

Druhá kontrola window.ApplePaySession.canMakePayments() ověřuje, zda zařízení, přes které zákazník na web přistupuje, umožňuje platby přes Apple Pay. Tato kontrola vyžaduje, aby web podporoval HTTPS protokol, lze ji tedy použít pouze pokud máte TLS zabezpečení. Jedná se o spolehlivější kontrolu a pokud možno, doporučujeme používat obě.

Oficiální Apple developer portal také poskytuje informace ohledně:

Doporučené logo najdete ke stažení v článku Jaká používat loga a názvy platebních metod?

Dostupnost Apple Pay
Apple Pay tlačítko

Ověření dostupnosti Apple Pay

if (window.ApplePaySession) {
    // podmínka projde pokud je k dispozici Apple Pay JS API
}

if (window.ApplePaySession && window.ApplePaySession.canMakePayments()) {
    // podmínka projde pouze v případě, že používané zařízení podporuje Apple Pay 
}

Vytvoří skryté Apple Pay tlačítko pomocí stylů dostupných v Safari. Pomocí JavaScriptu se zobrazí pouze v prohlížeči Safari a na zařízeních, která Apple Pay podporují.

<form action="/create-apple-payment" method="post">
    <button type="submit" id="apple-pay-button" lang=en style="
              display: none;
              -webkit-appearance: -apple-pay-button;
              -apple-pay-button-type: plain;
              -apple-pay-button-style: black;"></button>
</form>
<script>
    if(window.ApplePaySession && window.ApplePaySession.canMakePayments()) {
        document.querySelector("#apple-pay-button").style.display = "inline-block";
    }
</script>
Vyvolání platební brány

K vyvolání platební brány potřebujete gw_url, kterou získáte v API odpovědi při úspěšném založení platby.

Redirect

Vyvolání redirect varianty brány je pouhé přesměrování zákazníka na gw_url. Zákazník je přesměrován na zabezpečené prostředí GoPay, kde se zobrazí platební brána a je možné dokončit platbu. V prvním kroku je nutné získat gw_url platby. Ta je vrácena v odpovědi požadavku na založení platby. Ve druhém kroku je potřeba zákazníka na získanou URL přesměrovat.

Toho lze dosáhnout několika způsoby:

  1. Odkazem
  2. HTTP Redirectem
  3. JavaScriptem

Způsoby 2. a 3. mají tu výhodu, že klient je na platební bránu přesměrován hned z první stránky checkoutu. U prvního způsobu je nejprve přesměrován na další stránku, kde musí znova kliknout na tlačítko či odkaz. Při popisu postupu předpokládáme, že v checkoutu zákazník vyplňuje formulář, jehož odesláním dochází k vytvoření platby.

Postup přesměrování odkazem:

  • formulář je odeslán metodou POST na server
  • server vytvoří platbu a získává gw_url
  • server vrací novou html stránku, kam je gw_url umístěna jako odkaz (pomocí např. PHP či template systému)
  • zákazník je na platební bránu přesměrován kliknutím na odkaz

Postup přesměrování HTTP Redirectem:

  • formulář je odeslán metodou POST na server
  • server vytvoří platbu a získává gw_url
  • server vrací HTTP Redirect (např. 302 Found) a v hlavičce Location předává gw_url
  • prohlížeč při přijetí odpovědi automaticky přesměrovává zákazníka na platební bránu

Postup přesměrování JavaScriptem:

  • k formuláři se připojí event listener, který čeká na odeslání (submit) formuláře. Po odeslání volá callback funkci, která:
    • zabrání výchozí akci, která by způsobila refresh stránky
    • serializuje data z formuláře do formátu JSON
    • pomocí AJAX volání odesílá data na server
  • server v rámci komunikace s GoPay systémem získává gw_url platby
  • server vrací gw_url platby v odpovědi na AJAX request
  • následně je zákazník JavaScriptem přesměrován na platební bránu (např. pomocí window.location)

V JavaScriptových příkladech se pro zjednodušení nezabýváme zpracováním výjimek, proto chybí ověření výsledku AJAX volání a try-catch blocky. V produkci by toto měl vývojař ošetřit.

Odkazem
HTTP Redirectem
JavaScriptem

V příkladu předpokládáme, že na endpointu /pay dojde ke zpracování formuláře a vytvoření platby. Vrácena je nová stránka, kde je gw_url serverem dosazena jako odkaz.

<!-- První stránka, např. /checkout -->

<form action="/pay" method="post">
<!-- Obsah checkout formuláře -->
    <button type="submit">Potvrdit</button>
</form>

<!-- Druhá stránka, /pay. gw_url je dosazena serverem -->
<a href="https://gw.sandbox.gopay.com/gw/v3/dfgvmwTKK5hrJx2aGG8ZnFyBJhAvF">
    <button>Zaplatit</button>
</a>

V příkladu předpokládáme, že na endpointu /pay dojde ke zpracování formuláře, vytvoření platby a následnému HTTP Redirectu na gw_url.

<!-- První stránka, např. /checkout -->

<form action="/pay" method="post">
<!-- Obsah checkout formuláře -->
    <button type="submit">Potvrdit</button>
</form>

<!-- Serverová HTTP odpověď -->
HTTP/1.1 302 Found
Location: https://gw.sandbox.gopay.com/gw/v3/dfgvmwTKK5hrJx2aGG8ZnFyBJhAvF

V příkladu předpokládáme, že endpoint /create-payment příjímá JSON s obsahem formuláře, vytváří platbu a následně vrací JSON, který obsahuje gw_url. Uvedený příklad je kompatibilní s moderními prohlížeči.

<form action="/create-payment" method="post" id="payment-form">
<!-- Obsah checkout formuláře -->
  <button type="submit">Zaplatit</button>
</form>
<script>
  document.addEventListener("DOMContentLoaded", () => {
    // přidání listeneru k checkout formuláři
    const paymentForm = document.querySelector("#payment-form");
    paymentForm.addEventListener("submit", async (event) => {
      // zabránění výchozí akci, která by způsobila refresh stránky
      event.preventDefault();
      // serializace dat z formuláře do formátu JSON
      const formData = new FormData(paymentForm);
      const formObject = Object.fromEntries(formData.entries());
      // asynchronní založení platby na serveru
      const response = await fetch(paymentForm.action, {
        method: paymentForm.method,
        headers: {
          "Content-Type": "application/json",
          Accept: "application/json"
        },
        body: JSON.stringify(formObject)
      });
      // zpracování odpovědi a přesměrování na gw_url, vrácenou serverem
      const result = await response.json();
      window.location.replace(result.gw_url);
    })
  })
</script>
Inline

Verze inline platební brány je vyvolána přímo nad eshopem. Zákazník není přesměrován na doménu GoPay, ale nachází se stále na adrese eshopu, který je v pozadí platební brány stále vidět. Další informace a ukázky vzhledu inline brány naleznete v centru nápovědy v článku Co je inline platební brána?. Pokud při procesu platby dojde k přesměrování (např. do 3DS, do online bankovnictví), vrací se zákazník na standardní redirect bránu.

Pro využití inline platební brány na prodejních místech je nutné mít TLS certifikát (podpora HTTPS). Pokud není HTTPS dostupné, dojde k vyvolání standardní redirect brány

K vyvolání inline je potřeba nejprve získat gw_url. Místo toho, aby na ní byl zákazník přesměrován, je platební brána vyvolána:

  1. Formulářem
  2. JavaScriptem

Podobně jako u redirect platební brány má vyvolání JavaScriptem tu výhodu, že se platební brána zvedá v jednom kroku a zákazníkovi tedy stačí odeslat jeden formulář. U vyvolání formulářem je proces dvoukrokový.

Postup vyvolání formulářem:

  • Formulář je odeslán metodou POST na server.
  • Server vytvoří platbu a získává gw_url.
  • Server vrací novou html stránku, s formulářem, kam je gw_url umístěna jako action (pomocí např. PHP či template systému). Formulář musí mít metodu POST, atribut id nastavený na gopay-payment-button a musí do něj být vložený script (viz příklad).
  • Zákazník odesláním formuláře vyvolává inline platební bránu.

Postup vyvolání JavaScriptem:

  • V hlavičce dokumentu vložit link na náš JavaScript (https://gw.sandbox.gopay.com/gp-gw/js/embed.js na testovacím prostředí a https://gate.gopay.cz/gp-gw/js/embed.js na produkčním prostředí).
  • K formuláři se připojí event listener, který čeká na odeslání (submit) formuláře. Po odeslání volá callback funkci, která:
    • zabrání výchozí akci, která by způsobila refresh stránky
    • serializuje data z formuláře do formátu JSON
    • pomocí AJAX volání odesílá data na server
  • Server v rámci komunikace s GoPay systémem získává gw_url platby.
  • Server vrací gw_url platby v odpovědi na AJAX request.
  • Následně se volá _gopay.checkout() metoda, která jako argument přijímá konfigurační objekt.
  • V konfiguračním objektu metody je gw_url předána jako gatewayUrl a inline je nastaveno na true (viz příklad).

V JavaScriptových příkladech se pro zjednodušení nezabýváme zpracováním výjimek, proto chybí ověření výsledku AJAX volání a try-catch blocky. V produkci by toto měl vývojař ošetřit.

Formulářem
JavaScriptem

V příkladu předpokládáme, že na endpointu /pay dojde ke zpracování formuláře a vytvoření platby. Vrácena je nová stránka, kde je gw_url serverem dosazena do formuláře.

<!-- První stránka, např. /checkout -->

<form action="/pay" method="post">
<!-- Obsah checkout formuláře -->
    <button type="submit">Potvrdit</button>
</form>

<!-- Druhá stránka, /pay. gw_url je dosazena serverem -->
<form action="https://gw.sandbox.gopay.com/gw/v3/dfgvmwTKK5hrJx2aGG8ZnFyBJhAvF" method="POST" id="gopay-payment-button">
    <button type="submit">Zaplatit</button>
    <script type="text/javascript" src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js"></script>
</form>

V příkladu předpokládáme, že endpoint /create-payment příjímá JSON s obsahem formuláře, vytváří platbu a následně vrací JSON, který obsahuje gw_url. Uvedený příklad je kompatibilní s moderními prohlížeči.

<!-- V hlavičce html dokumentu -->
<script src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js" defer></script>
<!-- V tělě html dokumentu -->
<form action="/create-payment" method="post" id="payment-form">
<!-- Obsah checkout formuláře -->
  <button type="submit">Zaplatit</button>
</form>
<script>
  document.addEventListener("DOMContentLoaded", () => {
    // přidání listeneru k checkout formuláři
    const paymentForm = document.querySelector("#payment-form");
    paymentForm.addEventListener("submit", async (event) => {
      // zabránění výchozí akci, která by způsobila refresh stránky
      event.preventDefault();
      // serializace dat z formuláře do formátu JSON
      const formData = new FormData(paymentForm);
      const formObject = Object.fromEntries(formData.entries());
      // asynchronní založení platby na serveru
      const response = await fetch(paymentForm.action, {
        method: paymentForm.method,
        headers: {
          "Content-Type": "application/json",
          Accept: "application/json"
        },
        body: JSON.stringify(formObject)
      });
      // zpracování odpovědi a vyvolání inline platební brány
      const result = await response.json();
      _gopay.checkout({gatewayUrl: result.gw_url, inline: true});
    })
  })
</script>
Android a iOS

Platební brána je aktuálně čistě webová aplikace. Pokud je tedy integrována do mobilní aplikace, je nutno s tím počítat. To se týká i všech jejích platebních metod - včetně Apple Pay a Google Pay. Aktuálně není možné tyto platební metody využít bez platební brány pouhým vyvoláním nativního dialogu přímo z aplikace, je nutná interakce zákazníka s platební bránou.

Nepoužívejte WebView. WebView nedisponuje plnou funkčností prohlížeče a platební brána a metody jako Apple Pay a Google Pay nebudou pomocí těchto technologií fungovat. Toto se týká např. technologií WebView pro Android a WKWebView pro Apple.

Používejte technologie, které mají funkčnost plnohodnotného prohlížeče - což znamená Chrome Custom Tabs pro Android a SFSafariViewController pro iOS.

Po provedení nebo zrušení platby je zákazník navrácen zpět na prodejní místo. Návrat je možné provést dvěma způsoby. První z nich je provedení přesměrování na return_url, která bylo definováno při založení platby. Kdykoliv v průběhu platby dojde k nějakému přesměrování (např. do 3DS či online bankovnictví), bude zákazník vrácen na return_url.

Pokud byla vyvolána inline brána JavaScriptem, je možno předat callback funkci jako druhý parametr metody _gopay.checkout. V takovém případě nedochází k žádnému přesměrování.

V API volání pro založení platby je předán parametr return_url v objektu callback. Na ni je zákazník z brány přesměrován metodou GET, jako query parametr id je předáno ID platby, ze které se zákazník vrací. Pomocí tohoto ID je následně potřeba provést dotaz na stav platby.

V odpovědi získáte parametr state, který popisuje stav platby. Následné zpracování stavu je popsané v sekci Zpracování stavu platby.

Pokud byla vyvolána inline brána JavaScriptem, je možno předat callback funkci jako druhý parametr metody _gopay.checkout. V takovém případě nedochází k přesměrování zákazníka na return_url, ale je volána callback funkce přímo na stránce, na které došlo k vyvolání platební brány. Callback funkci je jako argument předán objekt, který obsahuje return_url platby jako parametr url včetně query parametru id.

Ve funkci doporučujeme pomocí AJAX volání provést dotaz na stav platby. V tomto případě je nutno mít na vašem serveru endpoint, který přijme ID platby, provede dotaz na stav platby pomocí REST API a následně vrátí stav platby. Callback funkce jej může následně dále zpracovat.

ID platby můžete získat z url, která je předána jako argument callback funkci (první příklad), případně ho můžete mít uložené v proměnné již od asynchornního založení platby (druhý příklad - vychází z vyvolání inline brány JavaScriptem).

V JavaScriptových příkladech se pro zjednodušení nezabýváme zpracováním výjimek, proto chybí ověření výsledku AJAX volání a try-catch blocky. V produkci by toto měl vývojař ošetřit.

Pouze callback
Včetně založení platby

V příkladu předpokládáme, že jsme platbu již založili a v proměnné gwUrl máme uloženou gw_url platby. Dále předpokládáme, že endpoint /status přijme ID platby jako query paramter, provede dotaz na stav platby pomocí REST API a odpověď následně přepošle frontendu.

// Při vyvolání platební brány je předána callback funkce, které je jako argument automaticky předán objekt, obsahující return_url platby
_gopay.checkout({gatewayUrl: gwUrl, inline: true}, async (checkoutResult) => {
    // získání ID platby z return_url
    const returnUrl = new URL(checkoutResult.url);
    const paymentId = new URLSearchParams(returnUrl.search).get("id");
    // asynchronní dotaz na stav platby
    const statusResponse = await fetch(`/status?id=${paymentId}`);
    const statusResult = await statusResponse.json();
    // následuje zpracování stavu platby, zde je pouze vypsán do konzole
    console.log(`Stav platby: ${statusResult.state}`);
});

V příkladu předpokládáme, že endpoint /create-payment přijímá JSON s obsahem formuláře, vytváří platbu a následně vrací JSON, který obsahuje gw_url a ID platby. Dále předpokládáme, že endpoint /status přijme ID platby jako query paramter, provede dotaz na stav platby pomocí REST API a odpověď následně přepošle frontendu. Uvedený příklad je kompatibilní s moderními prohlížeči.

<!-- V hlavičce html dokumentu -->
<script src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js" defer></script>
<!-- V tělě html dokumentu -->
<form action="/create-payment" method="post" id="payment-form">
<!-- Obsah checkout formuláře -->
  <button type="submit">Zaplatit</button>
</form>
<script>
  document.addEventListener("DOMContentLoaded", () => {
    // přidání listeneru k checkout formuláři
    const paymentForm = document.querySelector("#payment-form");
    paymentForm.addEventListener("submit", async (event) => {
      // zabránění výchozí akci, která by způsobila refresh stránky
      event.preventDefault();
      // serializace dat z formuláře do formátu JSON
      const formData = new FormData(paymentForm);
      const formObject = Object.fromEntries(formData.entries());
      // asynchronní založení platby na serveru
      const response = await fetch(paymentForm.action, {
        method: paymentForm.method,
        headers: {
          "Content-Type": "application/json",
          Accept: "application/json"
        },
        body: JSON.stringify(formObject)
      });
      // zpracování odpovědi, ID platby, vrácené serverem, ukládáme do proměnné
      const result = await response.json();
      const paymentId = result.id;
      // Při vyvolání platební brány je předána callback funkce, argument nepotřebujeme, protože ID platby již máme
      _gopay.checkout({gatewayUrl: result.gw_url, inline: true}, async (checkoutResult) => {
        // asynchronní dotaz na stav platby
        const statusResponse = await fetch(`/status?id=${paymentId}`);
        const statusResult = await statusResponse.json();
        // následuje zpracování stavu platby, zde je pouze vypsán do konzole
        console.log(`Stav platby: ${statusResult.state}`);
      });
    });
  });
</script>
Zpracování stavu platby

Podle stavu platby při návratu může nastat jedna ze čtyř situací:

  1. Platba byla úspěšná (stavy PAID či AUTHORIZED)
  2. Platba byla zrušena (stavy CANCELED či TIMEOUTED)
  3. Neproběhl pokus platbu uhradit (stav CREATED)
  4. Čeká se na výsledek platby (stav PAYMENT_METHOD_CHOSEN)

Průběh stavů, kterých platba nabývá, je popsán v sekci Popis vytvoření a průběhu platby.

Stavem AUTHORIZED je označena předautorizovaná platba, autorizace tedy proběhla úspěšně a platbu bude možné následně strhnout pomocí API volání.

Pokud je platba při návratu ve stavu CREATED, zákazník neprovedl pokus platbu uhradit a platební bránu zavřel. Může nastat také, pokud bránu zavřel, protože chtěl zvolit jinou platební metodu. V takovém případě mu tedy lze nabídnout založení nové platby s jinou platební metodou.

Pokud je stav platby při návratu PAYMENT_METHOD_CHOSEN, znamená to, že se zákazník pokusil platbu uhradit, ale ještě nemáme výsledek platby. To může nastat například u bankovních převodů, kdy se čeká na připsání platby na účet GoPay. Tato platba ještě může být v budoucnu uhrazena, proto nedoporučujeme nabízet zákazníkovi provedení nové platby. O následné změně stavu platby budete informováni prostřednictvím HTTP notifikace.

API Reference
API Operace
Autentizace
POST /api/oauth2/token
Získání přístupového tokenu
POST /api/oauth2/token

Operace slouží k získání přístupového tokenu, který je používán ve všech dalších API operacích. Přístupové údaje jsou předávány v hlavičce Authorization zakódované v base64 ve formátu ClientID:ClientSecret podle RFC 7617.

Request headers

Accept
string required

Vždy application/json

Example:
application/json
Content-Type
string required

Vždy application/x-www-form-urlencoded

Example:
application/x-www-form-urlencoded
Authorization
string required
Example:
Basic MTA2MTM5OTE2MzpzdERUbVZYRg==

Request body

application/x-www-form-urlencoded
Object
scope

Rozsah práv tokenu

Example:
payment-create
grant_type
string

Vždy client_credentials

Example:
client_credentials

Responses

200 OK
Body
Object
token_type
string

Vždy bearer

Example:
bearer
access_token
string

Přístupový token

Example:
AAAnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p
refresh_token
string

Obnovovací token - nepoužívá se

Example:
xzZnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p
expires_in
integer

Životnost tokenu v sekundách

Example:
1800
HTTP
cURL
PHP
Python
.NET
Java

HTTP požadavek pro získání tokenu

POST /api/oauth2/token HTTP/1.1 

Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic PENsaWVudElkPjo8Q2xpZW50U2VjcmV0Pg==

scope=payment-all&grant_type=client_credentials

HTTP/1.1 200 OK

Content-Type: application/json

{
 "token_type":"bearer",
 "access_token":"AAAnu3YnAHRk298EsmyttFQMcbCcvmwTKK5hrJx2aGG8ZnFyBJhAvFWNmbWVSD7p",
 "expires_in":1800,
 "refresh_token": "ObrapXqkh3SaWifBQ4PS0kYRIbXGqUDr4t6PECZFE0lFox5uXtWNb/QzeDrk8wsWDVOn+vvCAPCPAnr+B8aon+JpW5hPVwlNj71eupst+k8="
}

Inicializace GoPay v cURLu

// příklad získání tokenu s rozsahem práv pro vytvoření platby a provedení dotazu na stav platby na testovacím prostředí

curl -v -N https://gw.sandbox.gopay.com/api/oauth2/token \
-X "POST" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "<ClientId>:<ClientSecret>" \
-d "grant_type=client_credentials&scope=payment-create"

Inicializace GoPay v PHP

// Předpokládáme, že v proměnných $goid, $clientId a $clientSecret máte uložené
// testovací přístupové údaje

$gopay = GoPay\payments([
    'goid' => $goid,
    'clientId' => $clientId,
    'clientSecret' => $clientSecret,
    'gatewayUrl' => 'https://gw.sandbox.gopay.com/api'
]);
// Token získá SDK interně, není třeba volat žádnou metodu pro získání tokenu
// V dalších příkladech bude použit objekt $gopay vytvořený v tomto příkladu

Inicializace GoPay v Pythonu

import gopay

# Předpokládáme, že v proměnných goid, client_id a client_secret máte uložené
# testovací přístupové údaje
api = gopay.payments({
    "goid": goid,
    "client_id": client_id,
    "client_secret": client_secret,
    "gateway_url": "https://gw.sandbox.gopay.com/api"
})
# token získá SDK interně, není třeba volat žádnou metodu pro získání tokenu
# v dalších příkladech bude použit objekt gopay vytvořený v tomto příkladu

Inicializace GoPay v .NET frameworku v C#

var gopay = new GPConnector("https://gw.sandbox.gopay.com/api", {{YOUR-CLIENT-ID}}, {{YOUR-CLIENT-SECRET}});
gopay.GetAppToken();

Inicializace GoPay v Javě

IGPConnector connector = HttpClientGPConnector.build("https://gw.sandbox.gopay.com/api");
connector.getAppToken({{YOUR-CLIENT-ID}},{{YOUR-CLIENT-SECRET}}); 
Platby
POST /api/payments/payment
POST /api/payments/payment/{id}/refund
GET /api/payments/payment/{id}
Založení platby
POST /api/payments/payment

Založení platby. Předáním parametrů preauthorization a recurrence je platba založena jako předautorizovaná, potažmo opakovaná.

Request headers

Authorization
string required

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}
Content-Type
string required

Vždy application/json

Example:
application/json
Accept
string required

Vždy application/json

Example:
application/json

Request body

Object
amount
integer required

Celková částka platby v háléřích/centech

Example:
1000
currency
Currency required

Měna platby

Example:
CZK
order_number
string required

Identifikace objednávky v rámci e-shopu, alfanumerické znaky

Max length: 128
Example:
123456
target
Target required

Popisuje příjemce platby

payer
Payer required

Předává nastavení platebních metod pro danou platbu a údaje o plátci

callback
Callback required

Návratová URL a notifikační URL pro oznámení změny stavu platby

order_description
string

Popis objednávky, alfanumerické znaky

Max length: 256
Example:
Test order
preauthorization
boolean

Pokud se jedná o předautorizovanou platbu, je předáván s hodnotou true

Example:
false
recurrence

Pokud se jedná o opakovanou platbu, je předáván objekt, popisující opakování platby

items
Array of Item

Detailně rozepsané jednotlivé položky objednávky

additional_params

Doplňkové parametry platby

Max items: 4
lang

Jazyk na platební bráně

Example:
CS

Responses

200 OK
Body
Object
id
integer

ID platby

Example:
3000006529
order_number
string

ID objednávky

Example:
OBJ20200825
state

Stav platby

Example:
CREATED
amount
integer

Celková částka platby v háléřích/centech

Example:
139950
currency

Měna platby

Example:
CZK
payer

Údaje o plátci a platebních metodách

target

Popisuje příjemce platby

additional_params

Doplňkové parametry platby

lang

Jazyk na platební bráně

Example:
CS
recurrence

Údaje o opakování platby, pokud je platba opakovaná

preauthorization

Údaje o předautorizaci, pokud je platba předautorizovaná

gw_url
string

URL pro vyvolání platební brány

Example:
https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF
HTTP - minimální
HTTP - úplná
cURL
PHP
Python
.NET

Založení platby s minimálními povinnými parametry

POST /api/payments/payment HTTP/1.1

Authorization: Bearer {{YOUR-TOKEN}}
Content-Type: application/json
Accept: application/json

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "gw_url": "https://gw.sandbox.gopay.com/gw/..."
}

Založení standardní platby v úplné podobě

POST /api/payments/payment HTTP/1.1

Authorization: Bearer {{YOUR-TOKEN}}
Content-Type: application/json
Accept: application/json

{
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "order_description": "Test order",
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD", "BANK_ACCOUNT", "GPAY", "APPLE_PAY"
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "allowed_swifts": [
            "GIBACZPX", "CEKOCZPP", "FIOBCZPP", "AGBACZPP", "AIRACZPP"
        ],
        "default_swift": "GIBACZPX",
        "contact": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "phone_number": "+420123456789",
            "city": "Test city",
            "street": "Test street 10",
            "postal_code": "10000",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url"
    },
    "items": [
        {"type": "ITEM", "name": "Test item", "amount": 10000}   
    ],
    "additional_params": [
        {"name": "Test name", "value": "Test value"}
    ],
    "lang": "CS"
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "allowed_payment_instruments": [
            "CLICK_TO_PAY",
            "APPLE_PAY",
            "PAYMENT_CARD",
            "GPAY",
            "BANK_ACCOUNT"
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "default_swift": "GIBACZPX",
        "contact": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "phone_number": "+420123456789",
            "city": "Test city",
            "street": "Test street 10",
            "postal_code": "10000",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "additional_params": [
        {"name": "Test name", "value": "Test value"}
    ],
    "lang": "cs",
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}

Založení standardní platby v cURLu (varianty minimální a úplná)

// založení standardní platby s minimálními povinnými parametry

Request:
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"  \
 -H "Content-Type: application/json"  \
 -H "Accept: application/json"  \
 -d '{
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "callback": {
        "return_url": "https://www.example.xy/return",
        "notification_url": "https://www.example.xy/notify"
    }
}'

Response:
{"id":1234567890,"order_number":"123456","state":"CREATED","amount":10000,"currency":"CZK","payer":{},"target":{"type":"ACCOUNT","goid":{{YOUR-GOID}}},"gw_url":"https://gw.sandbox.gopay.com/gw/v3/xxxxxxxxxxxxxxxxxxxxxxxxx"}

// založení standardní platby s rozšířenými objekty payer, items, additional_params

Request:
curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"  \
 -H "Content-Type: application/json"  \
 -H "Accept: application/json"  \
 -d '{
    "payer": {
        "allowed_payment_instruments": [
            "PAYMENT_CARD",
            "BANK_ACCOUNT"
        ],
        "default_payment_instrument": "PAYMENT_CARD",
        "allowed_swifts": [
            "FIOBCZPP",
            "BREXCZPP"
        ],
        "default_swift": "FIOBCZPP",
        "contact": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "phone_number": "+420777456123",
            "city": "Test city",
            "street": "Test street 10",
            "postal_code": "10000",
            "country_code": "CZE"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "items": [
        {
            "type": "DISCOUNT",
            "name": "Test item",
            "amount": 10000,
            "count": 1,
            "ean": 1234567890123,
            "product_url": "https://www.eshop.xy/kniha/fantasy"
        }
    ],
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "order_description": "Test order",
    "lang": "CS",
    "callback": {
        "return_url": "https://www.example.xy/return",
        "notification_url": "https://www.example.xy/notify"
    },
    "additional_params": [
        {
            "name": "Doplňující informace",
            "value": "123"
        }
    ]
}'

Response:
{"id":1234567890,"order_number":"1234","state":"CREATED","amount":10000,"currency":"CZK","payer":{"allowed_payment_instruments":["PAYMENT_CARD","BANK_ACCOUNT"],"default_payment_instrument":"PAYMENT_CARD","default_swift":"FIOBCZPP","contact":{"first_name":"John","last_name":"Doe","email":"john.doe@example.com","phone_number":"+420777456123","city":"Test city","street":"Test street 10","postal_code":"10000","country_code":"CZE"}},"target":{"type":"ACCOUNT","goid":{{YOUR-GOID}}},"additional_params":[{"name":"Doplňující informace","value":"123"}],"lang":"cs","gw_url":"https://gw.sandbox.gopay.com/gw/v3/xxxxxxxxxxxxxxxxxxxxxxxxx"}

Minimální a úplná platba v jazyce PHP

use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Payment\PaymentInstrument;
use GoPay\Definition\Payment\BankSwiftCode;

// Array s platbou s minimálními parametry
$payment = [
    'amount' => 10000,
    'currency' => Currency::CZECH_CROWNS,
    'order_number' => '123456',
    'payer' => [
        'contact' => [
            'email' => 'john.doe@example.com'
        ]
    ],
    'callback' =>  [
        'return_url' =>  'https://example.com/your-return-url',
        'notification_url' =>  'https://example.com/your-notify-url'
    ]
];

// Array s úplnou platbou
$fullPayment = [
    'amount' => 10000,
    'currency' => Currency::CZECH_CROWNS,
    'order_number' => '123456',
    'order_description' => 'Test order',
    'payer' => [
        'allowed_payment_instruments' => [
            PaymentInstrument::PAYMENT_CARD,
            PaymentInstrument::BANK_ACCOUNT,
            PaymentInstrument::GPAY,
            PaymentInstrument::APPLE_PAY
        ],
        'default_payment_instrument' => PaymentInstrument::PAYMENT_CARD,
        'allowed_swifts' => [
            BankSwiftCode::CESKA_SPORITELNA,
            BankSwiftCode::CSOB,
            BankSwiftCode::FIO_BANKA,
            BankSwiftCode::MONETA_MONEY_BANK,
            BankSwiftCode::AIRBANK
        ],
        'default_swift' => BankSwiftCode::CESKA_SPORITELNA,
        'contact' => [
            'first_name' => 'John',
            'last_name' => 'Doe',
            'email' => 'john.doe@example.com',
            'phone_number' => '+420123456789',
            'city' => 'Test city',
            'street' => 'Test street 10',
            'postal_code' => '10000',
            'country_code' => 'CZE'
        ]
    ],
    'callback' =>  [
        'return_url' =>  'https://example.com/your-return-url',
        'notification_url' =>  'https://example.com/your-notify-url'
    ],
    'items' => [
        ['type' => 'ITEM', 'name' => 'Test item', 'amount' => 10000]
    ],
    'additional_params' => [
        ['name' => 'Test name', 'value' => 'Test value']
    ]
];

// Není potřeba předávat objekt `target`, je doplněn automaticky

// Vlastní API call pro vytvoření platby
$response = $gopay->createPayment($payment);

// Kontrola, zda vytvoření platby bylo úspěšné a získání těla API odpovědi
if ($response->hasSucceed()) {
    $responseBody = $response->json;
    // k jednotlivým parametrům je pak možnost přistupovat podle jméma
    $gatewayUrl = $responseBody['gw_url'];
}

Minimální a úplná platba v jazyce Python

from gopay.enums import Currency, PaymentInstrument, BankSwiftCode, Language

# Dictionary s minimální platbou
payment = {
    "amount": 10000,
    "currency": "CZK",
    "order_number": "123456",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url",
    },
}

# Dictionary s úplnou platbou
full_payment = {
    "amount": 10000,
    "currency": Currency.CZECH_CROWNS,
    "order_number": "123456",
    "order_description": "Test order",
    "payer": {
        "allowed_payment_instruments": [
            PaymentInstrument.PAYMENT_CARD,
            PaymentInstrument.BANK_ACCOUNT,
            PaymentInstrument.GPAY,
            PaymentInstrument.APPLE_PAY,
        ],
        "default_payment_instrument": PaymentInstrument.PAYMENT_CARD,
        "allowed_swifts": [
            BankSwiftCode.CESKA_SPORITELNA,
            BankSwiftCode.CSOB,
            BankSwiftCode.FIO_BANKA,
            BankSwiftCode.MONETA_MONEY_BANK,
            BankSwiftCode.AIRBANK,
        ],
        "default_swift": BankSwiftCode.CESKA_SPORITELNA,
        "contact": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "phone_number": "+420123456789",
            "city": "Test city",
            "street": "Test street 10",
            "postal_code": "10000",
            "country_code": "CSE",
        },
    },
    "callback": {
        "return_url": "https://example.com/your-return-url",
        "notification_url": "https://example.com/your-notify-url",
    },
    "items": [
        {"type": "ITEM", "name": "Test item", "amount": 10000}
    ],
    "additional_params": [
        {"name": "Test name", "value": "Test value"}
    ],
    "lang": Language.CZECH,
}
# Není potřeba předávat objekt `target`, je doplněn automaticky

# Vlastní API call pro vytvoření platby
response = api.create_payment(payment)

# Kontrola, zda vytvoření platby bylo úspěšné a získání těla API odpovědi
if response.success:
    response_body = response.json
    # K jednotlivým parametrům odpovědi je možno přistupovat podle jména
    gateway_url = response_body["gw_url"]

Minimální platba ve frameworku .NET. Je možno rozšířit dalšími parametry.

using GoPay.Common;
using GoPay.Model.Payment;
using GoPay.Model.Payments;

// Objekt minimální platby
var payment = new BasePayment()
{
    Amount = 1000,
    Currency = Currency.CZK,
    OrderNumber = "123456",
    Payer = new Payer
    {
        Contact = new PayerContact
        {
            Email = "john.doe@example.com"
        }
    },
    Target = new Target
    {
        GoId = long.Parse(_configuration["GoPay:GoId"] ?? "0"),
        Type = Target.TargetType.ACCOUNT
    },
    Callback = new Callback
    {
        ReturnUrl = "https://example.com/your-return-url",
        NotificationUrl = "https://example.com/your-notify-url"
    }
};

// Objekt úplné platby
var fullPayment = new BasePayment()
{
    Amount = 1000,
    Currency = Currency.CZK,
    OrderNumber = "123456",
    OrderDescription = "Test order",
    Payer = new Payer
    {
        AllowedPaymentInstruments = new List<PaymentInstrument>
        {
            PaymentInstrument.PAYMENT_CARD,
            PaymentInstrument.BANK_ACCOUNT,
            PaymentInstrument.GPAY,
            PaymentInstrument.APPLE_PAY
        },
        DefaultPaymentInstrument = PaymentInstrument.PAYMENT_CARD,
        AllowedSwifts = new List<string>
        {
            "GIBACZPX",
            "CEKOCZPP",
            "FIOBCZPP",
            "AGBACZPP",
            "AIRACZPP"
        },
        DefaultSwift = "GIBACZPX",
        Contact = new PayerContact
        {
            FirstName = "John",
            LastName = "Doe",
            Email = "john.doe@example.com",
            PhoneNumber = "+420123456789",
            City = "Test city",
            Street = "Test street 10",
            PostalCode = "10000",
            CountryCode = Country.CZE
        }
    },
    Target = new Target
    {
        GoId = long.Parse(_configuration["GoPay:GoId"] ?? "0"),
        Type = Target.TargetType.ACCOUNT
    },
    Callback = new Callback
    {
        ReturnUrl = "https://example.com/your-return-url",
        NotificationUrl = "https://example.com/your-notify-url"
    },
    Items = new List<OrderItem>
    {
        new OrderItem {
            ItemType = ItemType.ITEM,
            Name = "Test item",
            Amount = 1000
        }
    },
    AdditionalParams = new List<AdditionalParam>
    {
        new AdditionalParam {
            Name = "Test name",
            Value = "Test value"
        }
    },
    Lang = "CZ"
};

// API Call pro vytvoření platby. Výsledkem bude objekt třídy Payment
try
{
    var result = connector.CreatePayment(payment);
}
catch (GPClientException e)
{
    System.Console.WriteLine(e);
}
Refundace platby
POST /api/payments/payment/{id}/refund

Refundace platby umožňuje navrácení finančních prostředků za již provedenou platbu zpět zákazníkovi. Refundaci je možno provést v plné výši, nebo částečnou.

Path variables

id
string required

ID platby k refundaci

Request headers

Accept
string required

Vždy application/json

Example:
application/json
Content-Type
string required

Vždy application/x-www-form-urlencoded

Example:
application/x-www-form-urlencoded
Authorization
string required

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Request body

application/x-www-form-urlencoded
Object
amount
integer

Částka k navrácení

Example:
10000

Responses

200 OK
Body
Object
id
integer

ID platby

Example:
3123456789
result

Výsledek operace

Example:
FINISHED
HTTP
cURL
PHP
Python

Refundace platby

POST /api/payments/payment/{id}/refund HTTP/1.1

Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {{YOUR-TOKEN}}

amount=10000

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "result": "FINISHED"
}

Refundace platby v cURLu

// příklad provedení vrácení (refundace) části či plné částky k platbě na testovacím prostředí

curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/refund"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/x-www-form-urlencoded"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"  \
 -d 'amount=10000'

Refundace platby v PHP

// Předpokládáme, že v proměnné $paymentId máte uložené ID platby

// API call pro refundaci. Druhý parametr je částka k refundaci
$response = $gopay->refundPayment($paymentId, 10000);

// Kontrola, zda refundace byla úspěšná a získání těla API odpovědi
if ($response->hasSucceed()) {
    $responseBody = $response->json;
}

Refundace platby v Pythonu

# Předpokládáme, že v proměnné payment_id máte uložené ID platby

# API call pro refundaci. Druhý parametr je částka k refundaci
response = api.refund_payment(payment_id, 10000)

# Kontrola, zda byla refundace úspěšná a záskání těla API odpovědi
if response.success:
    response_body = response.json
Dotaz na stav platby
GET /api/payments/payment/{id}

Funkcionalita stav platby umožní prodejnímu místu zjistit, jaký je aktuální stav dříve vytvořené platby. V případě předautorizované a opakované platby obsahuje také odpověď informace o opakování platby či předautorizaci. Objekt payer může obsahovat údaje o platební kartě či bankovním účtu, pokud klient uhradil platbu tímto způsobem.

Path variables

id
string required

ID dotazované platby

Request headers

Accept
string required

Vždy application/json

Example:
application/json
Authorization
string required

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
id
integer

ID platby

Example:
3123456789
order_number
string

ID objednávky

Example:
123456
state

Stav platby

Example:
PAID
sub_state

Podstav platby

Example:
_3001
amount
integer

Celková částka platby v háléřích/centech

Example:
1000
currency

Měna platby

Example:
CZK
payment_instrument

Zvolená platební metoda

Example:
PAYMENT_CARD
payer

Údaje o plátci a platebních metodách

target

Popisuje příjemce platby

additional_params

Doplňkové parametry platby

lang

Jazyk na platební bráně

Example:
CS
recurrence

Údaje o opakování platby, pokud je platba opakovaná

preauthorization

Údaje o předautorizaci, pokud je platba předautorizovaná

gw_url
string

URL platební brány

Example:
https://gw.sandbox.gopay.com/gw/v3/...
HTTP
cURL
PHP
Python

Dotaz na stav platby

GET /api/payments/payment/3123456789 HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "order_number": "123456",
    "state": "PAID",
    "payment_instrument": "PAYMENT_CARD",
    "amount": 10000,
    "currency": "CZK",
    "payer": {
        "payment_card": {
            "card_number": "440507******4448",
            "card_expiration": "9912",
            "card_brand": "Visa",
            "card_issuer_country": "CZE",
            "card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)",
            "card_fingerprint": "0c823534ec582c97fa85c0bf7b020ee25a0a5af13974709bb329a709a79c2b3e"
        },
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": {{YOUR-GOID}}
    },
    "lang": "en",
    "gw_url": "https://gw.sandbox.gopay.com/gw/v3/..."
}

Dotaz na stav platby v cURLu

// příklad dotazu na stav platby na testovacím prostředí

curl -X GET "https://gw.sandbox.gopay.com/api/payments/payment/3123456789"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/x-www-form-urlencoded"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"

Dotaz na stav platby v PHP

// Předpokládáme, že v proměnné $paymentId máte uložené ID platby

// API call pro dotaz na stav platby
$response = $gopay->getStatus($paymentId);

// Kontrola, zda bylo volání úspěšné a získání těla API odpovědi
if ($response->hasSucceed()) {
    $responseBody = $response->json;
    // K jednotlivým parametrům je pak možnost přistupovat podle jména
    $paymentStatus = $responseBody['state'];
}

Dotaz na stav platby v Pythonu

# Předpokládáme, že v proměnné payment_id máte uložené ID platby

# API call dotazu na stav platby
response = api.get_status(payment_id)

# Kontrola, zda bylo volání úspěšné a získání těla API odpovědi
if response.success:
    response_body = response.json
    # K jednotlivým parametrům odpovědi je možno přistupovat podle jména
    payment_status = response_body["state"]
Opakované platby
POST /api/payments/payment/{id}/create-recurrence
POST /api/payments/payment/{id}/void-recurrence
Stržení opakované platby
POST /api/payments/payment/{id}/create-recurrence

Pomocí požadavku je možné strhnout novou platbu na základě dříve založené opakované platby v režimu ON_DEMAND (na vyžádání).

Path variables

id
string required

ID zakládající platby

Request headers

Accept
string required

Vždy application/json

Example:
application/json
Content-Type
string required

Vždy application/json

Example:
application/json
Authorization
string required

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Request body

Object
amount
integer required

Částka platby v haléřích/centech

Example:
1000
currency
Currency required

Měna platby

Example:
CZK
order_number
string required

Identifikace objednávky v rámci e-shopu, alfanumerické znaky

Max length: 128
Example:
123456
order_description
string

Popis objednávky

Max length: 256
Example:
Test recurrence
items
Array of Item

Detailně rozepsané jednotlivé položky objednávky

additional_params

Doplňkové parametry platby

Responses

200 OK
Body
Object
id
integer

ID platby

Example:
3123456790
parent_id
integer

ID zakládající platby

Example:
3123456789
order_number
string

ID objednávky

Example:
123456
state

Stav platby

Example:
CREATED
amount
integer

Částka platby v haléřích/centech

Example:
1000
currency

Měna platby

Example:
CZK
payment_instrument

Platební metoda

Example:
PAYMENT_CARD
payer

Údaje o plátci a platebních metodách

target

Popisuje příjemce platby

additional_params

Doplňkové parametry platby

lang

Jazyk na platební bráně

Example:
CS
HTTP
cURL
PHP
Python

Vytvoření následné opakované platby

POST /api/payments/payment/3123456789/create-recurrence HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 1000,
    "currency": "CZK",
    "order_number": "123456",
    "order_description": "Test recurrence"
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456790,
    "parent_id": 3123456789,
    "order_number": "123456",
    "state": "CREATED",
    "amount": 1000,
    "currency": "CZK",
    "payment_instrument": "PAYMENT_CARD",
    "payer": {
        "contact": {
            "email": "john.doe@example.com"
        }
    },
    "target": {
        "type": "ACCOUNT",
        "goid": 8123456789
    },
    "lang": "CS"
}

Vytvoření následné opakované platby v cURLu

// příklad vytvoření následné opakované platby na vyžádání na testovacím prostředí

curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/create-recurrence"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/json"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"  \
 -d '{
    "amount": 1000,
    "currency": "CZK",
    "order_number": "123456",
    "order_description": "Test recurrence"
}'

Vytvoření následné opakované platby v PHP

// Předpokládáme, že v proměnné $parentId máte uložené ID zakládající platby

use GoPay\Definition\Payment\Currency;

// Array s následnou platbou
$payment = [
    'amount' => 1000,
    'currency' => Currency::CZECH_CROWNS,
    'order_number' => '123456',
    'order_description' => 'Test recurrence'
];

// Vlastní API call pro vytvoření následné platby
$response = $gopay->createRecurrence($parentId, $payment);

// Kontrola, zda vytvoření platby bylo úspěšné a získání těla API odpovědi
if ($response->hasSucceed()) {
    $responseBody = $response->json;
}

Vytvoření následné opakované platby v Pythonu

# Předpokládáme, že v proměnné parent_id máte uložené ID zakládající platby

from gopay.enums import Currency

# Dictionary s následnou platbou
payment = {
    "amount": 1000,
    "currency": Currency.CZECH_CROWNS,
    "order_number": "123456",
    "order_description": "Test recurrence",
}

# API call pro založení následné platby
response = api.create_recurrence(parent_id, payment)

# Kontrola, zda bylo volání úspěšné a získání těla API odpovědi
if response.success:
    response_body = response.json
Zrušení opakované platby
POST /api/payments/payment/{id}/void-recurrence

Umožňuje zrušit opakování dříve vytvořené platby.

Path variables

id
string required

ID zakládající opakované platby

Request headers

Accept
string required

Vždy application/json

Example:
application/json
Authorization
string required

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
id
integer

ID platby

Example:
3123456789
result

Výsledek operace

Example:
FINISHED
HTTP
cURL
PHP
Python

Zrušení opakování

POST /api/payments/payment/3123456789/void-recurrence HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "result": "FINISHED"
}

Zrušení opakování v cURLu

// příklad zrušení opakování na testovacím prostředí

curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/void-recurrence"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/x-www-form-urlencoded"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"

Zrušení opakování v PHP

// Předpokládáme, že v proměnné $parentId máte uložené ID zakládající platby

// API call pro zrušení opakování platby
$response = $gopay->voidRecurrence($parentId);

// Kontrola, zda bylo volání úspěšné a získání těla API odpovědi
if ($response->hasSucceed()) {
    $responseBody = $response->json;
}

Zrušení opakování v Pythonu

# Předpokládáme, že v proměnné parent_id máte uložené ID zakládající platby

# API call pro zrušení opakované platby
response = api.void_recurrence(parent_id)

# Kontrola, zda bylo volání úspěšné a záskání těla API odpovědi
if response.success:
    response_body = response.json
Předautorizované platby
POST /api/payments/payment/{id}/capture
POST /api/payments/payment/{id}/capture
POST /api/payments/payment/{id}/void-authorization
Stržení předautorizace
POST /api/payments/payment/{id}/capture

Pomocí volání je možné strhnout plnou částku autorizace na základě dříve vytvořené předautorizované platby.

Path variables

id
string required

ID platby předautorizace

Request headers

Accept
string required

Vždy application/json

Example:
application/json
Authorization
string required

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
id
integer

ID platby

Example:
3123456789
result

Výsledek operace

Example:
FINISHED
HTTP
cURL
PHP
Python

Stržení předautorizace

POST /api/payments/payment/3123456789/capture HTTP/1.1 

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "result": "ACCEPTED"
}

Stržení předautorizace v cURLu

// příklad stržení předautorizace na testovacím prostředí

curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/capture"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/json"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"  \
 -d '{
    "amount": 10000,
    "items": [
        {
            "type": "ITEM",
            "name": "Test item",
            "amount": 10000,
            "count": 1
        }
    ]
}'

Stržení předautorizace v PHP

// Předpokládáme, že v proměnné $paymentId máte uložené ID předautorizované platby

// API call pro stržení předautorizace
$response = $gopay->captureAuthorization($paymentId);

// Kontrola, zda bylo volání úspěšné a získání těla API odpovědi
if ($response->hasSucceed()) {
    $responseBody = $response->json;
}

Stržení předautorizace v Pythonu

# Předpokládáme, že v proměnné payment_id máte uložené ID předautorizované platby

# API call pro stržení předautorizace
response = api.capture_authorization(payment_id)

# Kontrola, zda bylo volání úspěšné a záskání těla API odpovědi
if response.success:
    response_body = response.json
Částečné stržení předautorizace
POST /api/payments/payment/{id}/capture

Pomocí volání je možné strhnout určitou výši částky autorizace na základě dříve vytvořené předautorizované platby. Požadovaná částka stržení nemůže být vyšší než původní částka předautorizované platby. Je zásadní předat hlavičku Content-Type: application/json.

Path variables

id
string required

ID platby předautorizace

Request headers

Accept
string required

Vždy application/json

Example:
application/json
Content-Type
string required

Vždy application/json

Example:
application/json
Authorization
string required

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Request body

Object
amount
integer

Celková částka v haléřích/centech

Example:
30000
items
Array of Item

Detailně rozepsané jednotlivé položky platby

Responses

200 OK
Body
Object
id
integer

ID platby

Example:
3000006542
result

Výsledek operace

Example:
FINISHED
HTTP
cURL
PHP
Python

Částečné stržení předautorizace

POST /api/payments/payment/3123456789/capture HTTP/1.1 

Accept: application/json
Content-Type: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "amount": 5000,
    "items": [
        {"type": "ITEM", "name": "Test item", "amount": 5000}
    ]
}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "result": "FINISHED"
}

Částečné stržení předautorizace v cURLu

// příklad částečného stržení předautorizace na testovacím prostředí

curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/capture"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/json"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"  \
 -d '{
    "amount": 49900,
    "items": [
        {
            "type": "ITEM",
            "name": "Test item",
            "amount": 49900,
            "count": 1
        }
    ]
}'

Částečné stržení předautorizace v PHP

// Předpokládáme, že v proměnné $paymentId máte uložené ID předautorizované platby

// Array s detaily strhávané částky
$payment = [
    'amount' => 5000,
    'items' => [
        ['type' => 'ITEM', 'name' => 'Test item', 'amount' => 5000]
    ]
];

// API call pro stržení předautorizace
$response = $gopay->captureAuthorizationPartial($paymentId, $payment);

// Kontrola, zda bylo volání úspěšné a získání těla API odpovědi
if ($response->hasSucceed()) {
    $responseBody = $response->json;
}

Částečné stržení předautorizace v Pythonu

# Předpokládáme, že v proměnné payment_id máte uložené ID předautorizované platby

# Dictionary s detaily strhávané částky
payment = {
    "amount": 5000,
    "items": [
        {"type": "ITEM", "name": "Test item", "amount": 5000}
    ]
}

# API call pro částečné stržení předautorizace
response = api.capture_authorization_partial(payment_id, payment)

# Kontrola, zda bylo volání úspěšné a záskání těla API odpovědi
if response.success:
    response_body = response.json
Zrušení předautorizace
POST /api/payments/payment/{id}/void-authorization

Provede uvolnění prostředků předautorizace dříve vytvořené platby.

Path variables

id
string required

ID platby předautorizace

Request headers

Accept
string required

Vždy application/json

Example:
application/json
Authorization
string required

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
id
integer

ID platby

Example:
3000006542
result

Výsledek operace

Example:
FINISHED
HTTP
cURL
PHP
Python

Zrušení předautorizace

POST /api/payments/payment/3123456789/void-authorization HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "id": 3123456789,
    "result": "FINISHED"
}

Zrušení předautorizace v cURLu

// příklad zrušení předautorizace na testovacím prostředí

curl -X POST "https://gw.sandbox.gopay.com/api/payments/payment/3123456789/void-authorization"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/x-www-form-urlencoded"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"

Zrušení předautorizace v PHP

// Předpokládáme, že v proměnné $paymentId máte uložené ID předautorizované platby

// API call pro zrušení předautorizace
$response = $gopay->voidAuthorization($paymentId);

// Kontrola, zda bylo volání úspěšné a získání těla API odpovědi
if ($response->hasSucceed()) {
    $responseBody = $response->json;
}

Zrušení předautorizace v Pythonu

# Předpokládáme, že v proměnné payment_id máte uložené ID předautorizované platby

# API call pro zrušení předautorizace
response = api.void_authorization(payment_id)

# Kontrola, zda bylo volání úspěšné a záskání těla API odpovědi
if response.success:
    response_body = response.json
Platební karty
GET /api/payments/cards/{card_id}
DELETE /api/payments/cards/{card_id}
Získání detailů karty
GET /api/payments/cards/{card_id}

Slouží k získání detailů uložené platební karty.

Path variables

card_id
number required

ID karty

Request headers

Accept
string optional

Vždy application/json

Example:
application/json
Authorization
string optional

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
card_id
integer

ID uložené karty

Example:
8039094151
card_number
string

Vymaskované číslo karty

Example:
444444******4448
card_expiration
string

Expirace karty

Example:
1909
card_brand
string

Schéma platební karty

Example:
VISA
card_issuer_country
string

Země vydavatele karty

Example:
CZE
card_issuer_bank
string

Vydavatel karty

Example:
AIR BANK, A.S.
card_fingerprint
string

Unikátní identifikátor konkrétní platební karty

Example:
0c823534ec582c97fa85c0bf7b020ee25a0a5af13974709bb329a709a79c2b3e
card_token
string

Token pro použití v následných platbách

Example:
{{YOUR-CARD-TOKEN}}
status

Stav záznamu

Example:
active
HTTP - aktivní karta
HTTP - smazaná karta
cURL
PHP
Python

Dotaz na detaily aktivní karty

GET /api/payments/cards/9876543210 HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "card_id": 9876543210,
    "card_number": "440507******4448",
    "card_expiration": "9912",
    "card_brand": "Visa",
    "card_issuer_country": "CZE",
    "card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
    "card_fingerprint": "0c823534ec582c97fa85c0bf7b020ee25a0a5af13974709bb329a709a79c2b3e",
    "card_token": "YZ4E8f2jJA8cEDz1s0lO4BMXo6skkvItJddyrLhSyPa01T/cvrl+DwKsEqehFG7SQxJZUsBcgZ6sei4AKxrHHap7BofFr+SH3oHJyta0axiBB7MST3IWqrsq5ZtfukBrgwPBocNDPd/RnQs=",
    "status": "ACTIVE"
}

Dotaz na detaily smazané karty

GET /api/payments/cards/9876543210 HTTP/1.1

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "card_id": 9876543210,
    "status": "DELETED"
}

Dotaz na detaily karty v cURLu

// ukázka dotazu na detaily karty na testovacím prostředí

curl -X GET "https://gw.sandbox.gopay.com/api/payments/cards/9876543210"  \
 -H "Accept: application/json"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"

Dotaz na detaily karty v PHP

// Předpokládáme, že v proměnné $cardId máte uložené ID karty

// API call pro dotaz na stav platby
$response = $gopay->getCardDetails($cardId);

// Kontrola, zda bylo volání úspěšné a získání těla API odpovědi
if ($response->hasSucceed()) {
    $responseBody = $response->json;
    // K jednotlivým parametrům je pak možnost přistupovat podle jména
    $cardStatus = $responseBody['status'];
}

Dotaz na detaily karty v Pythonu

# Předpokládáme, že v proměnné card_id máte uložené ID karty

# API call pro získání detailů karty
response = api.get_card_details(card_id)

# Kontrola, zda bylo volání úspěšné a získání těla API odpovědi
if response.success:
    response_body = response.json
    # K jednotlivým parametrům odpovědi je možno přistupovat podle jména
    card_status = response_body["status"]
Smazání uložené karty
DELETE /api/payments/cards/{card_id}

Slouží ke smazání dříve uložené karty.

Path variables

card_id
string required

ID karty

Request headers

Authorization
string optional

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Responses

204 No Content
HTTP
cURL
PHP
Python

Smazání karty

DELETE /api/payments/cards/9876543210 HTTP/1.1 

Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 204 No Content

Smazání karty v cURLu

// ukázka smazání karty na testovacím prostředí

curl -X DELETE "https://gw.sandbox.gopay.com/api/payments/cards/987654321"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"

// potvrzení se nevrátí, stav si můžete zkontrolovat novým získáním detailů karty - viz příklad response:

{"card_id":987654321,"status":"DELETED"}

Smazání karty v PHP

// Předpokládáme, že v proměnné $cardId máte uložené ID karty

// API call pro dotaz na stav platby
$response = $gopay->deleteCard($cardId);

Smazání karty v Pythonu

# Předpokládáme, že v proměnné card_id máte uložené ID karty

# API call pro smazání karty
response = api.delete_card(card_id)
Platební metody
GET /api/eshops/eshop/{goid}/payment-instruments/{currency}
GET /api/eshops/eshop/{goid}/payment-instruments
Povolené platební metody pro měnu
GET /api/eshops/eshop/{goid}/payment-instruments/{currency}

Vrací seznam povolených platebních metod pro danou měnu, jejich českých popisků a log platebních metod. U bankovních převodů jsou předávány popisky a loga pro jednotlivé banky.

Path variables

goid
string required
currency
Currency required

Request parameters

lang
Lang optional

Jazyk platebních metod. Můžete také předat all pro vypsání všech jazyků.

Request headers

Accept
string required

Vždy application/json

Example:
application/json
Authorization
string required

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
groups

Popisy skupin platebních metod

enabledPaymentInstruments

Seznam povolených platebních metod pro danou měnu na e-shopu, jejich popisky a loga

HTTP
cURL
PHP
Python

Dotaz na povolené platební metody pro měnu

GET /api/eshops/eshop/{{YOUR-GOID}}/payment-instruments/CZK HTTP/1.1 

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "groups": {
        "card-payment": {
            "label": {
                "cs": "Platební karta"
            }
        },
        "bank-transfer": {
            "label": {
                "cs": "Rychlý bankovní převod"
            }
        },
        "wallet": {
            "label": {
                "cs": "Elektronické peněženky"
            }
        },
        "others": {
            "label": {
                "cs": "Ostatní"
            }
        }
    },
    "enabledPaymentInstruments": [
        {
            "paymentInstrument": "PAYMENT_CARD",
            "label": {
                "cs": "Platební karta"
            },
            "image": {
                "normal": "https://static1.gopay.com/images/payment-method/miniature/PAYMENT_CARD.svg",
                "large": "https://static1.gopay.com/images/payment-method/default/PAYMENT_CARD.svg"
            },
            "group": "card-payment",
            "enabledSwifts": null
        },
        {
            "paymentInstrument": "BANK_ACCOUNT",
            "label": {
                "cs": "Bankovní převod"
            },
            "image": {
                "normal": "https://static1.gopay.com/images/payment-method/miniature/BANK_ACCOUNT.svg",
                "large": "https://static1.gopay.com/images/payment-method/default/BANK_ACCOUNT.svg"
            },
            "group": "bank-transfer",
            "enabledSwifts": [
                {
                    "swift": "GIBACZPX",
                    "label": {
                        "cs": "Platba 24"
                    },
                    "image": {
                        "normal": "https://static1.gopay.com/images/bank/miniature/GIBACZPX.svg",
                        "large": "https://static1.gopay.com/images/bank/default/GIBACZPX.svg"
                    },
                    "isOnline": true
                },
                {
                    "swift": "CEKOCZPP",
                    "label": {
                        "cs": "ČSOB"
                    },
                    "image": {
                        "normal": "https://static1.gopay.com/images/bank/miniature/CEKOCZPP.svg",
                        "large": "https://static1.gopay.com/images/bank/default/CEKOCZPP.svg"
                    },
                    "isOnline": true
                }, 
                {
                    "swift": "OTHERS",
                    "label": {
                        "cs": "Jiná banka"
                    },
                    "image": {
                        "normal": "https://static1.gopay.com/images/bank/miniature/OTHERS.svg",
                        "large": "https://static1.gopay.com/images/bank/default/OTHERS.svg"
                    },
                    "isOnline": false
                }
            ]
        },
        {
            "paymentInstrument": "PAYPAL",
            "label": {
                "cs": "PayPal"
            },
            "image": {
                "normal": "https://static1.gopay.com/images/payment-method/miniature/PAYPAL.svg",
                "large": "https://static1.gopay.com/images/payment-method/default/PAYPAL.svg"
            },
            "group": "wallet",
            "enabledSwifts": null
        }
    ]
}

Dotaz na povolené platební metody v cURLu

// příklad dotazu na seznam povolených metod pro CZK účet ke GoID pro testovací prostředí

curl -X GET "https://gw.sandbox.gopay.com/api/eshops/eshop/{{YOUR-GOID}}/payment-instruments/CZK"  \
 -H "Accept: application/json"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"

Dotaz na povolené platební metody v PHP

// Předpokládáme, že v proměnné $goid máte uložené vaše GoID

use GoPay\Definition\Payment\Currency;

// API call pro získání platebních metod, druhý parametr je zvolená měna
$response = $gopay->getPaymentInstruments($goid, Currency::CZECH_CROWNS);

// Kontrola, zda bylo API volání úspěšné a získání těla API odpovědi
if ($response->hasSucceed()) {
    $responseBody = $response->json;
    // získání array s kódy platebních metod
    $instruments = array_map(
        fn ($el) => $el['paymentInstrument'],
        $responseBody['enabledPaymentInstruments']
    );
}

Dotaz na povolené platební metody v Pythonu

# Předpokládáme, že v proměnné goid máte uložené vaše GoID

from gopay.enums import Currency

# API call pro získání platebních metod, druhý parametr je zvolená měna
response = api.get_payment_instruments(goid, Currency.CZECH_CROWNS)

# Kontrola, zda bylo API volání úspěšné a získání těla API odpovědi
if response.success:
    response_body = response.json
    # Získání listu s kódy platebních metod
    payment_instruments = [
        el["paymentInstrument"]
        for el in response_body["enabledPaymentInstruments"]
    ]
Všechny povolené platební metody
GET /api/eshops/eshop/{goid}/payment-instruments

Vrací seznam všech povolených platebních metod na eshopu, jejich českých popisků a log platebních metod. U bankovních převodů jsou předávány popisky a loga pro jednotlivé banky.

Path variables

goid
string required

Request parameters

lang
Lang optional

Jazyk platebních metod. Můžete také předat all pro vypsání všech jazyků.

Request headers

Accept
string optional

Vždy application/json

Example:
application/json
Authorization
string optional

Bearer autentizace pomocí dříve získaného tokenu

Example:
Bearer {{YOUR-TOKEN}}

Responses

200 OK
Body
Object
groups

Popisy skupin platebních metod

enabledPaymentInstruments
Any of

Objekt, obsahující všechny povolené platební metody na e-shopu, jejich popisky a loga

Object
<Payment Instrument>

Povolená platební metoda na eshopu. Názvy parametrů nabývají hodnot z číselníku Payment instrument

HTTP
cURL
PHP

Dotaz na všechny povolené platební metody

GET /api/eshops/eshop/{{YOUR-GOID}}/payment-instruments?lang=cs HTTP/1.1 

Accept: application/json
Authorization: Bearer {{YOUR-TOKEN}}

HTTP/1.1 200 OK

Content-Type: application/json

{
    "groups": {
        "card-payment": {
            "label": {
                "cs": "Platební karta"
            }
        },
        "bank-transfer": {
            "label": {
                "cs": "Rychlý bankovní převod"
            }
        },
        "wallet": {
            "label": {
                "cs": "Elektronické peněženky"
            }
        },
        "others": {
            "label": {
                "cs": "Ostatní"
            }
        }
    },
    "enabledPaymentInstruments": {
        "PAYMENT_CARD": {
            "label": {
                "cs": "Platební karta"
            },
            "image": {
                "normal": "https://static1.gopay.com/images/payment-method/miniature/PAYMENT_CARD.svg",
                "large": "https://static1.gopay.com/images/payment-method/default/PAYMENT_CARD.svg"
            },
            "currencies": [
                "CZK",
                "EUR"
            ],
            "group": "card-payment",
            "enabledSwifts": null
        },
        "BANK_ACCOUNT": {
            "label": {
                "cs": "Bankovní převod"
            },
            "image": {
                "normal": "https://static1.gopay.com/images/payment-method/miniature/BANK_ACCOUNT.svg",
                "large": "https://static1.gopay.com/images/payment-method/default/BANK_ACCOUNT.svg"
            },
            "currencies": [
                "CZK",
                "EUR"
            ],
            "group": "bank-transfer",
            "enabledSwifts": {
                "GIBACZPX": {
                    "label": {
                        "cs": "Česká spořitelna"
                    },
                    "image": {
                        "normal": "https://static1.gopay.com/images/bank/miniature/GIBACZPX.svg",
                        "large": "https://static1.gopay.com/images/bank/default/GIBACZPX.svg"
                    },
                    "currencies": {
                        "CZK": {
                            "isOnline": true
                        }
                    }
                },
                "SUBASKBX": {
                    "label": {
                        "cs": "VÚB banka"
                    },
                    "image": {
                        "normal": "https://static1.gopay.com/images/bank/miniature/SUBASKBX.svg",
                        "large": "https://static1.gopay.com/images/bank/default/SUBASKBX.svg"
                    },
                    "currencies": {
                        "EUR": {
                            "isOnline": true
                        }
                    }
                },
                "OTHERS": {
                    "label": {
                        "cs": "Jiná banka"
                    },
                    "image": {
                        "normal": "https://static1.gopay.com/images/bank/miniature/OTHERS.svg",
                        "large": "https://static1.gopay.com/images/bank/default/OTHERS.svg"
                    },
                    "currencies": {
                        "CZK": {
                            "isOnline": false
                        },
                        "EUR": {
                            "isOnline": false
                        }
                    }
                }
            }
        },
        "PAYPAL": {
            "label": {
                "cs": "PayPal"
            },
            "image": {
                "normal": "https://static1.gopay.com/images/payment-method/miniature/PAYPAL.svg",
                "large": "https://static1.gopay.com/images/payment-method/default/PAYPAL.svg"
            },
            "currencies": [
                "CZK"
            ],
            "group": "wallet",
            "enabledSwifts": null
        }
    }
}

Dotaz na všechny povolené platební metody v cURLu

// příklad dotazu na seznam všech povolených platebních metod ke zvolenému GoID pro testovací prostředí

curl -X GET "https://gw.sandbox.gopay.com/api/eshops/eshop/{{YOUR-GOID}}/payment-instruments"  \
 -H "Accept: application/json"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"

Dotaz na všechny povolené platební metody v PHP

// příklad dotazu na seznam všech povolených platebních metod ke zvolenému GoID pro testovací prostředí

$response = $gopay->getPaymentInstrumentsALL('8123456789');

// Kontrola, zda bylo API volání úspěšné a získání těla API odpovědi

if ($response->hasSucceed()) {
    $responseBody = $response->json;
    echo json_encode($responseBody);
    }
Obchodní účet
POST /api/accounts/account-statement
Výpis pohybů
POST /api/accounts/account-statement

Funkcionalita umožňuje generovat výpisy z GoPay obchodního účtu. Metoda vrací obsah souboru ve zvoleném formátu výpisu.

Request headers

Accept
string required

Vždy application/json

Example:
application/json
Content-Type
string required

Vždy application/json

Example:
application/json
Authorization
string required

Předává se string Bearer, za kterým následuje vytvořený přístupový token

Example:
Bearer {{YOUR-TOKEN}}

Request body

Object
date_from
string date

Počáteční datum výpisu

Example:
2016-07-08
date_to
string date

Koncové datum výpisu

Example:
2016-08-08
goid
integer

Jedinečný identifikátor e-shopu v systému platební brány

Example:
8123456789
currency

Měna účtu, ze kterého má být výpis vygenerován

Example:
CZK
format

Určuje formát souboru generovaného výpisu

Example:
CSV_A

Responses

200 OK

Jako tělo odpovědi se vrací obsah výpisu v požadovaném formátu

application/octet-stream
HTTP
cURL
PHP
Python

Výpis pohybů účtu

POST /api/accounts/account-statement HTTP/1.1 

Accept: application/octet-stream
Content-Type: application/json
Authorization: Bearer {{YOUR-TOKEN}}

{
    "date_from": "2022-12-01",
    "date_to": "2022-12-02",
    "goid": {{YOUR-GOID}},
    "currency": "CZK",
    "format": "CSV_A"
}

HTTP/1.1 200 OK

Content-Type: application/octet-stream

"ID pohybu";"Datum";"Typ";"Protistrana";"ID objednávky/VS";"Částka";"Počáteční stav";"Koncový stav";"Měna";"ID Referenčního pohybu"
...

Výpis pohybů účtu v cURLu

// příklad výpisu ve formátu CSV_A k CZK účtu na testovacím prostředí

curl -X POST "https://gw.sandbox.gopay.com/api/accounts/account-statement"  \
 -H "Accept: application/json"  \
 -H "Content-Type: application/json"  \
 -H "Authorization: Bearer {{YOUR-TOKEN}}"  \
 -d '{
    "date_from": "2022-12-01",
    "date_to": "2022-12-02",
    "goid": {{YOUR-GOID}},
    "currency": "CZK",
    "format": "CSV_A"
}'

Výpis pohybů účtu v PHP

// předpokládáme, že v proměnné $goid máte uložené vaše GoID

use GoPay\Definition\Payment\Currency;
use GoPay\Definition\Account\StatementGeneratingFormat;

// Array s tělem požadavku
$body = [
    'date_from' => '2022-12-01',
    'date_to' => '2022-12-02',
    'currency' => Currency::CZECH_CROWNS,
    'format' => StatementGeneratingFormat::CSV_A,
    'goid' => $goid
];

// API call pro získání výpisu
$response = $gopay->getAccountStatement($body);

// Kontrola, zda vytvoření platby bylo úspěšné
if ($response->hasSucceed()) {

    // Extrakce obsahu odpovědi
    $data = $response->__toString();
    $file = 'statement.csv';

    // Vytvoření souboru
    file_put_contents($file, $data);
    }

Výpis pohybů účtu v Pythonu

# Předpokládáme, že v proměnné goid máte uložené vaše GoID

from gopay.enums import Currency, StatementGeneratingFormat

# Dictionary s tělem požadavku
request_body = {
    "date_from": "2022-12-01",
    "date_to": "2022-12-02",
    "currency": Currency.CZECH_CROWNS,
    "format": StatementGeneratingFormat.CSV_A,
    "goid": goid,
}

# API call pro vygenerování výpisu
response = api.get_account_statement(request_body)
if response.success:
    statement = response.raw_body.decode("utf-8")
Objekty
Target

Popisuje příjemce platby/e-shop.

Object
type
string

Vždy ACCOUNT

Example:
ACCOUNT
goid
integer

Jedinečný identifikátor eshopu v systému platební brány

Example:
8123456789
Target
{
    "type": "ACCOUNT",
    "goid": 8123456789
}
Item

Položka platby

Object
type
Type required

Typ položky

Example:
ITEM
name
string required

Název položky, alfanumerické znaky

Max length: 256
Example:
Test item
amount
integer required

Celková částka položek v haléřích/centech

Example:
1000
count
integer

Počet položek

Min: 1
Example:
1
vat_rate
integer

DPH sazba, pouze pro Českou Republiku

Min: 0
Max: 100
Example:
21
ean
integer

EAN kód produktu

Example:
4006381333931
product_url
string

URL adresa produktu

Max length: 512
Example:
https://example.com/product
Item - min
Item - full

Minimální podoba položky

{
    "type": "ITEM",
    "name": "Test item",
    "amount": 1000
}

Úplná podoba položky

{
    "type": "ITEM",
    "name": "Test item",
    "amount": 1000,
    "count": 1,
    "vat_rate": 21,
    "ean": 4006381333931,
    "product_url": "https://example.com/product"
}
Contact

Informace o zákazníkovi

Object
first_name
string

Jméno zákazníka

Max length: 256
Example:
John
last_name
string

Příjmení zákazníka

Max length: 256
Example:
Doe
email
string required

Validní e-mail zákazníka

Max length: 128
Example:
john.doe@example.com
phone_number
string

Telefonní číslo zákazníka s předvolbou

Max length: 128
Example:
+420123456789
city
string

Město zákazníka

Max length: 128
Example:
Test city
street
string

Ulice zákazníka

Max length: 128
Example:
Test street 10
postal_code
string

Poštovní směrovací číslo zákazníka

Max length: 16
Example:
10000
country_code
string

Třípísmenný kód státu zákazníka podle standardu ISO 3166-1 alpha-3

Example:
CZE
Types: Payer
Contact - min
Contact - full

Minimální podoba objektu contact

{
    "email": "john.doe@example.com"
}

Úplná podoba objektu contact

{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+420123456789",
    "city": "Test city",
    "street": "Test street 10",
    "postal_code": "10000",
    "country_code": "CZE"
}
Payer

Objekt popisující údaje o zákazníkovi a nastavení platebních metod pro danou platbu. Nastavuje také různé typy plateb, např. vyžádání karetního tokenu a tokenu účtu.

Object
allowed_payment_instruments

Seznam povolených platebních metod

Example:
["PAYMENT_CARD", "BANK_ACCOUNT", "GPAY", "APPLE_PAY"]
default_payment_instrument

Předzvolená platební metoda

Example:
PAYMENT_CARD
allowed_swifts
Array of Swift

Seznam povolených SWIFTů pro online bankovní převody

Example:
["GIBACZPX", "CEKOCZPP", "FIOBCZPP", "AGBACZPP", "AIRACZPP"]
default_swift

Předzvolený SWIFT

Example:
GIBACZPX
contact
Contact required

Kontaktní údaje zákazníka

bank_account

Údaje o bankovním účtu zákazníka

payment_card
Payment card read-only

Údaje o platební kartě klienta

request_card_token
boolean

Vyžádá uložení karty a vytvoření tokenu pro další platby

Example:
false
card_id
integer read-only

ID uložené platební karty pro účely platby tokenem

allowed_card_token
string

Token uložené platební karty

Example:
{{YOUR-TOKEN}}
email
string

Email použité GoPay peněženky (pouze u platební metody GOPAY)

Example:
john.doe@example.com
Minimal - request
Standard - request
Payment card - response
Bank account - response

Minimální objekt payer, který je nutno předat při založení platby

{
    "contact": {
        "email": "john.doe@example.com"
    }
}

Úplný objekt payer, který je možno předat při založení standardní platby

{
    "allowed_payment_instruments": ["PAYMENT_CARD", "BANK_ACCOUNT", "GPAY", "APPLE_PAY"],
    "default_payment_instrument": "PAYMENT_CARD",
    "allowed_swifts": ["GIBACZPX", "CEKOCZPP", "FIOBCZPP", "AGBACZPP", "AIRACZPP"]],
    "default_swift": "GIBACZPX",
    "contact": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone_number": "+420123456789",
        "city": "Test city",
        "street": "Test street 10",
        "postal_code": "10000",
        "country_code": "CZE"
    }
}

Objekt payer ze stavu platby, která byla uhrazena platební kartou

{
    "contact": {
        "email": "john.doe@example.com"
    },
    "payment_card": {
    "card_number": "440507******4448",
    "card_expiration": "9912",
    "card_brand": "Visa",
    "card_issuer_country": "CZE",
    "card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
    }
}

Objekt payer ze stavu platby, která byla uhrazena bankovním převodem

{
    "contact": {
        "email": "john.doe@example.com"
    },
    "bank_account": {
        "prefix": "000000",
        "account_number": "9878039",
        "bank_code": "2010",
        "iban": "CZ5120100000000009878039",
        "bic": "FIOBCZPP",
        "account_name": "John Doe"
    }
}
Callback

Popisuje adresy, na které bude předáváno ID vytvořené platby - adresu, na kterou bude zákazník přesměrován a adresu, kam budou zasílány HTTP push notifikace.

Object
return_url
string required

URL pro návrat klienta z platební brány do e-shopu (včetně protokolu)

Max length: 512
Example:
https://example.com/your-return-url
notification_url
string required

URL pro zasílání asynchronních HTTP notifikací

Max length: 512
Example:
https://example.com/your-notify-url
Callback
{
    "return_url": "https://example.com/your-return-url",
    "notification_url": "https://example.com/your-notify-url"
}
Payment card

Objekt popisující údaje o platební kartě. Pouze pro čtení vracen v dotazu na stav platby, pokud zákazník platil kartou. Parametr card_fingerprint je předáván pouze pokud je tato funkce aktivována.

Object
card_number
string

Vymaskované číslo karty

Example:
444444******4448
card_expiration
string

Datum expirace

Example:
1230
card_brand
string

Asociace platební karty

Example:
VISA
card_issuer_country
string

Země vydání platební karty

Example:
CZE
card_issuer_bank
string

Vydavatelská banka

Example:
AIR BANK, A.S.
3ds_result

Výsledek 3D Secure autorizace, pouze u identifikační platby

Example:
Y/Y
card_fingerprint
string

Unikátní identifikátor konkrétní platební karty

Example:
7fa592f3e4b1af1945730b1c0e014d83b5102184fa6b3be15ef57c83d44c94c5
Types: Payer
Payment card

Objekt platební karty

{
    "card_number": "440507******4448",
    "card_expiration": "9912",
    "card_brand": "Visa",
    "card_issuer_country": "CZE",
    "card_issuer_bank": "CESKA SPORITELNA, A.S (CZECH SAVINGS BANK)"
}
Bank account

Údaje o bankovním účtu plátce. Pouze pro čtení vracen v dotazu na stav platby, pokud klient platil účtem. IBAN a SWIFT jsou předávány pouze u zahraničních účtů.

Object
prefix
string

Předčíslí účtu

Example:
000000
account_number
string

Číslo účtu v domestic formátu

Example:
9878039
bank_code
string

Kód banky v domestic formátu

Example:
2010
iban
string

IBAN

Example:
CZ5120100000000009878039
bic
string read-only

SWIFT/BIC

Example:
FIOBCZPP
account_name
string read-only

Jméno majitele účtu

Example:
John Doe
account_token
string

Uložený token pro PSD2 zapamatovaný režim

Example:
{{YOUR-ACCOUNT-TOKEN}}
Types: Payer
Bank account
{
    "prefix": "000000",
    "account_number": "9878039",
    "bank_code": "2010",
    "account_name": "John Doe",
    "iban": "CZ5120100000000009878039"
}
Additional param

Dodatečné parametry platby

Object
name
string

Název parametru

Example:
Test name
value
string

Hodnota parametru

Example:
Test value
Additional param
{
    "name": "Test name",
    "value": "Test value"
}
Recurrence

Objekt popisující opakování platby. U opakované platby ON_DEMAND se nepředává parametr recurrence_period. Parametr recurrence_state je vracen v dotazu na stav platby.

Object
recurrence_cycle

Časový úsek opakování

Example:
MONTH
recurrence_period
integer

Perioda opakování platby

Example:
12
recurrence_date_to
string date

Doba platnosti opakované platby (výlučně do) ve formátu YYYY-MM-DD

Example:
2025-12-31
recurrence_state
Recurrence state read-only

Stav opakování platby

Example:
STARTED
AUTO - request
ON_DEMAND - request
Response

Objekt recurrence předaný při založení AUTO opakované platby

{
    "recurrence_cycle": "MONTH",
    "recurrence_period": 1,
    "recurrence_date_to": "2025-12-31",
}

Objekt recurrence předaný při založení ON_DEMAND opakované platby

{
    "recurrence_cycle": "ON_DEMAND",
    "recurrence_period": 12,
    "recurrence_date_to": "2025-12-31"
}

Objekt recurrence, který se vrací ve stavu platby

{
    "recurrence_cycle": "WEEK",
    "recurrence_period": 1,
    "recurrence_date_to": "2025-12-31",
    "recurrence_state": "STOPPED"
}
Preauthorization

Objekt popisující předautorizaci platby. Vrací se pouze ve stavu platby.

Object
requested
boolean

Zda byla předautorizace založena

Example:
true

Stav předautorizace platby

Example:
REQUESTED
Preauthorization
{
    "requested": true,
    "state": "REQUESTED"
}
Error

Objekt popisující chybu

Object

Rozsah chyby

Example:
F
field
string

Kterého parametru se chyba týká, pokud se nejedná o globální chybu

Example:
goid
message
string

Lokalizovaná message. Lokalizace založená na Accept-Language v hlavičce. Defaultně je nastaveno na en-US, dále je možné použít českou lokalizaci pomocí hlavičky Accept-Language: cs.

Example:
Payee not found
description
string

Technický popis chyby

error_code
integer

Číselné označení typu chyby

Example:
320
error_name
string

Kódové označení typu chyby

Example:
PAYEE_NOT_FOUND
Field error
Global error

Chyba v konkrétním parametru

{
    "scope": "F",
    "field": "goid",
    "message": "Payee not found",
    "error_code": "320",
    "error_name": "PAYEE_NOT_FOUND"
}

Obecná chyba

{
    "scope": "G",
    "description": "System error",
    "error_code": "100",
    "error_name": "SYSTEM_ERROR"
}
Group Code

Obsahuje popisky skupiny platebních metod.

Object
label
Object

Popis platební metody

cs
string

Název platební metody v češtině

Example:
Platební karta
Types: Groups
Example 1
{
  "label": {
    "cs": "Platební karta"
  }
}
Groups

Seznam všech skupin povolených platebních metod.

Any of
Object
<Group>

Popisuje skupinu platebních metod. Názvy parametrů nabývají hodnot z číselníku Group

Example 1
{
  "card-payment": {
    "label": {
      "cs": "Platební karta"
    }
  }
}
Enabled swift

Popisuje povolené swifty pro bankovní převody.

Object
image
Object

Ikony banky

large
string

URL velké ikony

Example:
https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png
normal
string

URL menší ikony

Example:
https://gate.gopay.cz/images/checkout/GIBACZPX.png
isOnline
boolean

Zda je pro tento SWIFT možný online bankovní převod

Example:
true
label
Object

Popisek platební metody

cs
string

Český popisek

Example:
Platba 24
swift
string

SWIFT banky

Example:
GIBACZPX
Example 1
{
  "image": {
    "large": "https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png",
    "normal": "https://gate.gopay.cz/images/checkout/GIBACZPX.png"
  },
  "isOnline": true,
  "label": {
    "cs": "Platba 24"
  },
  "swift": "GIBACZPX"
}
Enabled payment instrument

Popisuje povolené platební metody.

Object
enabledSwifts
Array of Enabled swift nullable

Řada objektů popisující jednotlivé povolené SWIFTY (pouze pro bankovní převody)

group

Do které skupiny se platební metoda řadí

Example:
card-payment
image
Object

Ikony platební metody

large
string

URL velké ikony

Example:
https://gate.gopay.cz/images/checkout/payment_card@2x.png
normal
string

URL malé ikony

Example:
https://gate.gopay.cz/images/checkout/payment_card.png
label
Object

Popisky platební metody

cs
string

Český popisek

Example:
Platební karta
paymentInstrument

Označení platební metody v rámci API

Example:
PAYMENT_CARD
Example 1
{
  "enabledSwifts": [{
    "image": {
      "large": "https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png",
      "normal": "https://gate.gopay.cz/images/checkout/GIBACZPX.png"
    },
    "isOnline": true,
    "label": {
      "cs": "Platba 24"
    },
    "swift": "GIBACZPX"
  }],
  "group": "bank-transfer",
  "image": {
    "large": "https://gate.gopay.cz/images/checkout/payment_card@2x.png",
    "normal": "https://gate.gopay.cz/images/checkout/payment_card.png"
  },
  "label": {
    "cs": "Bankovní převod"
  },
  "paymentInstrument": "BANK_ACCOUNT"
}
Enabled swift (all)

Popisuje povolené swifty pro bankovní převody.

Object
image
Object

Ikony banky

large
string

URL velké ikony

Example:
https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png
normal
string

URL menší ikony

Example:
https://gate.gopay.cz/images/checkout/GIBACZPX.png
isOnline
boolean

Zda je pro tento SWIFT možný online bankovní převod

Example:
true
label
Object

Popisek platební metody

cs
string

Český popisek

Example:
Platba 24
swift
string

SWIFT banky

Example:
GIBACZPX
currencies
Any of
Object
<Currency>
Object

Měna, pro kterou je SWIFT dostupný. Název parametru nabývá hodnot z číselníku Currency.

isOnline
boolean

Značí, zda je SWIFT spojený s online převodem.

Example:
true
Example 1
{
  "image": {
    "large": "https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png",
    "normal": "https://gate.gopay.cz/images/checkout/GIBACZPX.png"
  },
  "isOnline": true,
  "label": {
    "cs": "Platba 24"
  },
  "swift": "GIBACZPX",
  "currencies": {
    "CZK": {
      "isOnline": "true"
    }
  }
}
Enabled payment instrument (all)

Popisuje povolené platební metody pro všechny měny.

Object
enabledSwifts
Any of nullable

Objekt popisující povolené SWIFTy pro bankovní převod. Názvy parametrů nabývají hodnot z číselníku Swift.

Object

Objekt popisující každý jednotlivý SWIFT.

group

Do které skupiny se platební metoda řadí

Example:
bank-transfer
image
Object

Ikony platební metody

large
string

URL velké ikony

Example:
https://gate.gopay.cz/images/checkout/bank_account@2x.png
normal
string

URL malé ikony

Example:
https://gate.gopay.cz/images/checkout/bank_account.png
label
Object

Popisky platební metody

cs
string

Český popisek

Example:
Bankovní platba
currencies
Array of Currency

Měny, pro které je daná platební metoda dosupná

Example 1
{
  "enabledSwifts": {
    "GIBACZPX": {
      "image": {
        "large": "https://gate.gopay.cz/images/checkout/GIBACZPX@2x.png",
        "normal": "https://gate.gopay.cz/images/checkout/GIBACZPX.png"
      },
      "isOnline": true,
      "label": {
        "cs": "Platba 24"
      },
      "swift": "GIBACZPX",
      "currencies": {
        "CZK": {
          "isOnline": "true"
        }
      }
    }
  },
  "group": "bank-transfer",
  "image": {
    "large": "https://gate.gopay.cz/images/checkout/bank_account@2x.png",
    "normal": "https://gate.gopay.cz/images/checkout/bank_account.png"
  },
  "label": {
    "cs": "Bankovní platba"
  },
  "currencies": [
    "CZK"
  ]
}
Číselníky

Seznam číselníků (enums) používaných v API

Currency

Seznam dostupných měn

string
Enumeration:
CZK

Česká koruna

EUR

Euro

PLN

Polský złoty

USD

Americký dolar

GBP

Britská libra

HUF

Maďarský forint

RON

Rumunský nový lei

BGN

Bulharský lev

HRK

Chorvatská kuna

Payment instrument

Seznam dostupných platebních metod

string
Enumeration:
PAYMENT_CARD

Platební karta

BANK_ACCOUNT

Bankovní převod

GPAY

Google Pay

APPLE_PAY

Apple Pay

GOPAY

GoPay účet

PAYPAL

PayPal účet

MPAYMENT

mPlatba (mobilní platba)

PRSMS

Premium SMS

PAYSAFECARD

PaySafeCard kupón

BITCOIN

Bitcoin peněženka

CLICK_TO_PAY

Click To Pay VISA/MasterCard

Swift

Seznam dostupných SWIFT/BIC kódů pro účely určení platebních metod.

string
Enumeration:
GIBACZPX

Česká Spořitelna

KOMBCZPP

Komerční Banka

CEKOCZPP

ČSOB

RZBCCZPP

Raiffeisenbank

BACXCZPP

UniCredit Bank

AGBACZPP

Moneta Money Bank

FIOBCZPP

FIO Banka

BREXCZPP

mBank

AIRACZPP

AirBank

INGBCZPP

ING Bank

OBKLCZ2X

Oberbank

SUBACZPP

VÚB Praha

BPPFCZP1

Hello bank!

CTASCZ22

CREDITAS

EXPNCZPP

Max banka

JTBPCZPP

J&T Banka

TATRSKBX

Tatra Banka

SUBASKBX

VÚB

UNCRSKBX

UniCredit Bank SK

GIBASKBX

Slovenská Sporiteľňa

CEKOSKBX

ČSOB SK

POBNSKBA

Poštová Banka

OTPVSKBX

OTP Banka Slovensko

KOMASK2X

Prima Banka Slovensko

CITISKBA

Citibank Europe

FIOZSKBA

Fio banka SK

BREXSKBX

mBank SK

INGBSKBX

ING Bank SK

JTBPSKBA

J&T Banka SK

OBKLSKBA

Oberbank SK

BSLOSK22

Privatbanka

BFKKSKBB

BKS Bank

TATRSKBXXXX

Raiffeisenbank SK

KOMBSKBA

Komerční banka SK

Types: Payer
State

Seznam možných stavů plateb

string
Enumeration:
CREATED

Platba vytvořena

PAID

Platba uhrazena

CANCELED

Platba zamítnuta

PAYMENT_METHOD_CHOSEN

Platební metoda potvrzena

TIMEOUTED

Platbě vypršela životnost

AUTHORIZED

Platba předautorizována

REFUNDED

Platba vrácena

PARTIALLY_REFUNDED

Platba částečně vrácena

Substate

Seznam podstavů plateb

string
Enumeration:
_101

Čekáme na provedení online platby.

_102

Čekáme na provedení offline platby.

_3001

Bankovní platba potvrzena avízem.

_3002

Bankovní platba potvrzena výpisem.

_3003

Bankovní platba nebyla potvrzena.

_5001

Schváleno s nulovou částkou

_5002

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu dosažení limitů na platební kartě.

_5003

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu problémů na straně vydavatele platební karty.

_5004

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu problému na straně vydavatele platební karty.

_5005

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu zablokované platební karty.

_5006

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu nedostatku peněžních prostředků na platební kartě.

_5007

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu expirované platební karty.

_5008

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu zamítnutí CVV/CVC kódu.

_5009

Zamítnutí platby v systému 3D Secure banky zákazníka.

_5015

Zamítnutí platby v systému 3D Secure banky zákazníka.

_5017

Zamítnutí platby v systému 3D Secure banky zákazníka.

_5018

Zamítnutí platby v systému 3D Secure banky zákazníka.

_5019

Zamítnutí platby v systému 3D Secure banky zákazníka.

_6502

Zamítnutí platby v systému 3D Secure banky zákazníka.

_6504

Zamítnutí platby v systému 3D Secure banky zákazníka.

_5010

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu problémů na platební kartě.

_5014

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu problémů na platební kartě.

_5011

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu problémů na účtu platební karty.

_5036

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu problémů na účtu platební karty.

_5012

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu technických problémů v autorizačním centru banky zákazníka.

_5013

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu chybného zadání čísla platební karty.

_5016

Zamítnutí platby v autorizačním centru banky zákazníka, platba nebyla povolena na platební kartě zákazníka.

_5020

Neznámá konfigurace

_5021

Zamítnutí platby v autorizačním centru banky zákazníka z důvodu dosažení nastavených limitů na platební kartě.

_5022

Nastal technický problém spojený s autorizačním centrem banky zákazníka.

_5023

Platba nebyla provedena.

_5038

Platba nebyla provedena.

_5024

Platba nebyla provedena. Platební údaje nebyly zadány v časovém limitu na platební bráně.

_5025

Platba nebyla provedena. Konkrétní důvod zamítnutí je sdělen přímo zákazníkovi.

_5026

Platba nebyla provedena. Součet kreditovaných částek překročil uhrazenou částku.

_5027

Platba nebyla provedena. Uživatel není oprávněn k provedení operace.

_5028

Platba nebyla provedena. Částka k úhradě překročila autorizovanou částku.

_5029

Platba zatím nebyla provedena.

_5030

Platba nebyla provedena z důvodu opakovaného zadání platby.

_5031

Při platbě nastal technický problém na straně banky.

_5033

SMS se nepodařilo doručit.

_5035

Platební karta je vydaná v regionu, ve kterém nejsou podporovány platby kartou.

_5037

Držitel platební karty zrušil platbu.

_5039

Platba byla zamítnuta v autorizačním centru banky zákazníka z důvodu zablokované platební karty.

_5040

Duplicitni reversal transakce

_5041

Duplicitní transakce

_5042

Bankovní platba byla zamítnuta.

_5043

Platba zrušena uživatelem.

_5044

SMS byla odeslána. Zatím se ji nepodařilo doručit.

_5045

Platba byla přijata. Platba bude připsána po zpracování v síti Bitcoin.

_5046

Platba nebyla uhrazena v plné výši.

_5047

Platba byla provedena po splatnosti.

_5048

Zákazník neudělil souhlas s provedením PSD2 platby

_5049

PSD2 platba zamítnuta

_5050

PSD2 požadovaný účet nenalezen

Card status

Stav uložené platební karty.

string
Enumeration:
active

Uložená karta je aktivní

deleted

Uložená karta byla smazána

Type