Metody pro platební tlačítko

Stručný přehled

Metoda	Popis
button/init	Založení platby pro platební tlačítko (pt@shop).

Tučně uvedené parametry jsou pro volání povinné.

---

Metoda button/init  

POST https://api.platebnibrana.csob.cz/api/v1.9/button/init

Založí platbu platebním tlačítkem (pt@shop) a připraví parametry pro přesměrování uživatele z e-shopu na elektronické bankovnictví. Z elektronického bankovnictví je uživatel přesměrován zpět do e-shopu obchodníka přes platební bránu, která zobrazuje výsledek autorizace.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou.
orderNo	String	Referenční číslo objednávky využívané pro párování plateb, které bude uvedeno také na výpisu z banky. Numerická hodnota, maximální délka je 10 číslic.
dttm	String	Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
clientIp	String	IP adresa zákazníka (jeho prohlížeče) přistupujícího na e-shop obchodníka, formát ipv4 nebo ipv6.
totalAmount	Number	Celková cena v setinách základní měny. Tato hodnota bude zobrazena na platební bráně jako celková částka k zaplacení.
currency	String	Kód měny. Povolené hodnoty: CZK.
returnUrl	String	URL adresa, na kterou bude klient přesměrován zpět do e-shopu. Maximální délka je 300 znaků. Při přesměrování zpět na e-shop se předává stejná sada parametrů jako v případě návratu z platební brány při platbě kartou.
returnMethod	String	Metoda návratu na URL adresu e-shopu. Povolené hodnoty POST, GET. Doporučená metoda je POST.
brand	String	Platební tlačítko, které zákazník zvolil, povolená hodnota je csob. Od verze 1.9 je tato položka nepovinná, defaultní hodnota csob.
merchantData	String	Libovolná pomocná data, která předává obchodník na bránu, musí být kódována v BASE64. Maximální délka po zakódování je 255 znaků. V případě obchodního modelu "Marketplace" musí obchodník identifikovat svého retailera pomocí IČO. Tento identifikátor je třeba plnit do hranatých závorek [] a může být umístěn libovolně v rámci položky merchantData. V případě, že se nákupu účastní vícero retailerů, hodnoty IČO se oddělují čárkou - např. [12345678,87654321].
language	String	Preferovaná jazyková mutace, která se zobrazí zákazníkovi na platební bráně (platební brána je zobrazena při přechodu z elektronického bankovnictví zpět na e-shop, zobrazuje výsledek autorizace). Povolené hodnoty: cs,en,de,fr,hu,it,ja,pl,pt,ro,ru,sk,es,tr,vi,hr,sl,sv.
signature	String	Podpis požadavku, kódováno v BASE64.

---

Příklad požadavku

{
  "merchantId":"M1MIPS0000",
  "orderNo":"11345325",
  "dttm":"20220125131559",
  "clientIp":"193.1.2.3",
  "totalAmount":12300,
  "currency":"CZK",
  "returnUrl":"https://shop.example.com/return",
  "returnMethod":"POST",
  "merchantData":"some-base64-encoded-merchant-data",
  "language":"cs",
  "signature":"base64-encoded-signature-of-payment-request"
}

Návratové hodnoty  

Položka	Typ	Popis
payId	String	Jednoznačné ID platby (přidělené platební bránou v operaci init, obsahuje 15-znakový řetězec).
dttm	String	Datum a čas odpovědi ve formátu YYYYMMDDHHMMSS.
resultCode	Number	Výsledek operace, viz výčet.
resultMessage	String	Textový popis výsledku operace.
paymentStatus	Number	Stav platby, viz životní cyklus transakce.
redirect	Object	Struktura obsahující potřebné parametry pro přesměrování na elektronické bankovnictví.
signature	String	Podpis odpovědi, kódováno v BASE64.

---

redirect - parametry pro přesměrování

Položka	Typ	Popis
method	String	Typ HTTP metody, povolené hodnoty jsou GET, POST.
url	String	URL pro přesměrování.
params	Map	Vyplněno pouze v případě přesměrování pomocí POST, mapa obsahující key-value hodnoty, do řetězce pro ověření podpisu odpovědi se vkládají pouze "value" hodnoty (bez klíčů) v pořadí, v jakém přijdou v odpovědi.

Příklad návratových hodnot

{
  "payId":"54de9577040c@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus":1,
  "redirect": {
    "method":"GET",
    "url":"https://platebnibrana.csob.cz/pay/example.com/2c72d818-9788-45a1-878a-9db2a706edc5/pt-detect/csob"
  },
  "signature":"base64-encoded-response-signature"
 }

Příklad řetězce pro ověření podpisu odpovědi:

54de9577040c@HA|20220125131601|0|OK|1|GET|https://platebnibrana.csob.cz/pay/example.com/2c72d818-9788-45a1-878a-9db2a706edc5/pt-detect/csob