Dokumentace

Práce s API službami

V rámci platební brány Zaplaceno.cz existují dvě prostředí:

1. Testovací prostředí (tzv. Sandbox) - Sandbox slouží k otestování napojení na platební bránu Zaplaceno.cz, a to bez jakékoli registrace. API je shodné s produkční verzí služby (má stejnou strukturu, stejné atributy i jejich popis). Jediným rozdílem je návrat testovacích (anonymizovaných) dat.

SANDBOX base URL: https://api.sandbox.zaplaceno.cz

2. Produkční prostředí - na základě podepsané Smlouvy o poskytování služby Zaplaceno.cz provedeme Vaší registraci v platební bráně. Po registraci obdržíte na sjednaný email zprávu k dokončení registrace (nastavení hesla do administrace platební brány). V administraci budete mít k dispozici Identifikátor (merchantID) a Tajný klíč (secureKey), které slouží k Vaší autentizaci.

PROD base URL: https://api.zaplaceno.cz/

Identifikátor - Merchant ID (Příklad)

d946b69b-dae1-43da-97ce-748260645fdb

Tajný klíč - SecureKey (Příklad tajného klíče. Slouží k podpisu vašich transakcí)

QDlj7pbFt9veNJuGHdFDuIM1tLNhuxFw57dfBRBwRbpHRjL6ebvbyYZcQZnDDS5UGjMWpEccUYTTwKfcJrl49G43ZMivbxjelA3NolOoXJv7FFI1Es7NYTJYTpFGuhL9vKz7NKsohoHwCM1ARKdGMrP7CmB0OSa0P4NjyIjekM5Eo3fKrm4WvklK7dVUXzDvwPY8mpptZNWFigx5jptkPsfVWFVlbSTrfdXqOTNkWRrL40mYZLwgHxVPDGpzZ5fhTMiONhaPcHWdWfEI3dyfDLn2XRYFCK5vY9372gXT7PXs3ZzFqIPFoSMeAgx8zsGsgx3zzUYsHyV3nEdUz7WGo0zo1xRy3gBkrlBIZzXEKAQ2GjOp2TRzpC4WWxZqKbTSPaZKbUWNmBodPBNpWip2sBJhAipQ3eNSuF7wPMdxUeDVSxxmcan75uoTC8Ls2TeCxdqRlFtunnbgbjLe8pcG12LHB1O2oE5EKtaHpWDaiQue8T9YHtcb7Hp3IE4ZUMs1MjHFr6cOXdt6T1eexZoZRM1uf37rpdbXENDrx28IwQkfNJ6SyRbWG51GudgwpiUJTuPLNrmJsrYOJVb3yKhebzESG58msWLOi6PKOrCJ9dh2GCoj3zrHIgxzbBt0K9sZXE5X17ETsfUofXmzpKPE3e1SjnozLVEvI89gtN6kvsY66dxX2UN81XgTdTn2z2YFFNVSKPgAUGyThgtKIDTHfj9iBe4kWhlhGNVRWLJAzcqid89hzq5swBxyPeeNoS6BwOZ8dON1f7uJSMOL4S0mR5XsIEAPlI2VcMBrq0XTwLeqFvCRRByQKLKQvd79uhXPkoMhFJlWmhbHPj9ikKqYYBRNZ82DsJPdle0sMUhKCSxG8LdcrAezdWpTrlrkMuTlZeTDuzf231LYoZIsrvh7QOCZJnQx9VryATE9qaN53iWNl0tuaduDPNRiauDzeUtRQZNtgqQvSOx3lTg5fmhwLMHKZ7N8C4qC7dW4jGKB

Přehled API služeb

Získání seznamu povolených poskytovatelů plateb

Služba slouží k ověření seznamu podporovaných bank platební bránou Zaplaceno.cz, prostřednictvím kterých může zákazník, jakožto plátce, provést platbu.

Iniciace platby

Integrace mezi e-shopem a platební bránou probíhá voláním služby POST /transaction/eshop/init. Request obsahuje údaje platebního příkazu a technické parametry popsané níže. V odpovědi je vrácena redirectUrl, na kterou má být uživatel přesměrován. Následuje autentizace uživatele vůči bance plátce a autorizace platby.

Notifikace o výsledku platby - callbackUrl

Jakmile je platba zpracována, platební brána zavolá callbackUrl a tím informuje e-shop, že si může zavolat službu pro získání stavu platby.

CallbackUrl je nastavené v administraci v rámci registrace e-shopu v platební bráně. Případnou změnu je možné provést zadáním požadavku na podporu platební brány nebo přetížit uloženou hodnotu vyplněním parametru callbackUrl v requestu POST /transaction/eshop/init.

Získání stavu platby

Služba GET /transaction/eshop/status slouží k opakovanému volání k získání aktuálního stavu iniciované platby.

Podpis

Každý request je vždy podepsán. Tento podpis je vyjádřen atributem signature. Detail výpočtu je uveden v samostatné kapitole „Výpočet kontrolního součtu (signature)“.

Base URL

SANDBOX base URL: https://api.sandbox.zaplaceno.cz

PROD base URL: https://api.zaplaceno.cz/

Rozhraní formalizované ve formátu OpenAPI získáte u kontaktní osoby Zaplaceno.cz.

Sandbox

Do testovacího prostředí není nutná žádná registrace v platební bráně Zaplaceno.cz. Sandbox neukládá žádná data. Slouží primárně k odladění technických validací zasílaných atributů. Návratové hodnoty z platební brány jsou vždy stejné bez ohledu na zaslané hodnoty v atributech requestu. Pro nasimulování různých stavů lze však změnit merchantTransactionId a tím ovlivnit, jak bude SANDBOX odpovídat.

ResultCode OPENED

Pro simulaci resultCode = OPENED použijte v merchantTransactionId libovolný validní UUID.

Request

https://api.sandbox.zaplaceno.cz/transaction/eshop/status?merchantId=21b9aa87-65c5-4cd0-bc6b-9ae2ac93ebf5&merchantTransactionId=7e8fede9-f9b1-4d98-8bfe-68c3ea5ed74c

Headers

Signature: eac6d3458d17b483ef4755b9cc35b3709dd2bf5ade13ba08da128217977f0b01

Response

{
    "merchantTransactionId": "7e8fede9-f9b1-4d98-8bfe-68c3ea5ed74c",
    "resultCode": "OPENED"
}

ResultCode AUTHORIZED

Pro simulaci resultCode = AUTHORIZED použijte merchantTransactionId začínající na 00000001 např. 00000001-f9b1-4d98-8bfe-68c3ea5ed74c.

ResultCode REJECTED

Pro simulaci resultCode = REJECTED použijte merchantTransactionId začínající na 00000000 např. 00000000-f9b1-4d98-8bfe-68c3ea5ed74c.

ResultCode COMPLETED

Pro simulaci resultCode = COMPLETED použijte merchantTransactionId začínající na 00000002 např. 00000002-f9b1-4d98-8bfe-68c3ea5ed74c

Získání seznamu povolených poskytovatelů plateb – GET /eshop/paymentProviders

Službu GET /eshop/paymentProviders volejte pro získání přehledu podporovaných bank, prostřednictvím kterých lze iniciovat platbu.

Atribut Povinnost Datový typ Popis Příklad

merchantId

(query)

[1..1]

UUID

Jedinečný identifikátor zákazníka (e-shopu) přidělený platební bránou

d946b69b-dae1-43da-97ce-748260645fdb

signature

(header)

[1..1]

String(64)

Podpis požadavku

Výpočet viz kapitola „Výpočet kontrolního součtu (signature)“

2f48c0900c1d568eefc4fff30a35977cbfeadfb082315d6783e31268d576d487

Příklad volání

Request

GET [base URL]/eshop/paymentProviders

Headers

Signature: 2f48c0900c1d568eefc4fff30a35977cbfeadfb082315d6783e31268d576d487

URL

[base URL]/eshop/paymentProviders?merchantId=d946b69b-dae1-43da-97ce-748260645fdb

Response

Výsledkem je seznam všech podporovaných poskytovatelů plateb pro zvolený e-shop.

Příklad hodnoty bankLogo je zkrácen kvůli větší přehlednosti, jedná se o SVG formát.

Body

[
    {
        "bankName": "Komerční banka",
        "bankCode": "KB",
        "bankLogo": "%3Csvg id='Vrstva_1' xmlns='http://www.w3.org/2000/svg' viewBox='0 0 159.3 56.6' style='enable-background:new..."
    },
{
        "bankName": "AirBank",
        "bankCode": "AIRBANK",
        "bankLogo": "%3Csvg id='Layer_1' xmlns='http://www.w3.org/2000/svg' viewBox='0 0 165 60'%3E%3Cstyle%3E.st0%7Bfill:%2302020..."
    },
]

Iniciace platby - POST /transaction/eshop/init

Notifikace o výsledku platby - příklad validního callbackUrl

Jakmile je na straně banky resp. následně platební brány platba zpracována, provede platební brána redirect na callbackUrl zadanou v init requestu.

https://eshop.cz/callback/merchantTransactionId=13acedde-4b7e-dab6-4149-7b2b60bc8a77

V tuto chvíli se e-shop může začít doptávat na stav platby pomocí metody status viz bod 5.2.

Získání stavu platby - GET /transaction/eshop/status

Pro získání informace o stavu platby volá e-shop službu GET /transaction/eshop/status.

Následující atributy jsou zaslány jako parametry v URL:

Tabulka 3

Atribut	Povinnost	Datový typ	Popis	Příklad
merchantId	[1..1]	UUID	Jedinečný identifikátor zákazníka (e-shopu) přidělený platební bránou	`d946b69b-dae1-43da-97ce-748260645fdb`
merchantTransactionId	[1..1]	UUID	Jedinečný identifikátor transakce generovaný na straně e-shopu	`13acedde-4b7e-dab6-4149-7b2b60bc8a77`
signature	[1..1]	String(64)	Podpis požadavku Výpočet viz kapitola „Výpočet kontrolního součtu (signature)“	`fe8bc6b149120b5c90561059749832f6d6e6b1759c29d314f0564aac36a4735c`

Za předpokladu happy flow brána provolá callbackUrl a tím dostane e-shop informaci, že může provolat službu pro získání stavu platby. Pokud však nastane situace, kdy dojde k chybě ať už na síťové úrovni, nebo uživatel zavře prohlížeč apod., e-shop by se nedozvěděl, zda se transakci podařilo dokončit.

Pokud nastane tento případ, doporučujeme, aby e-shop zkusil 30min po iniciaci platby provolat GET /transaction/eshop/status pro získání stavu platby. Ta může nabývat stavů viz kapitola Číselníky. Je-li stav OPENED, transakce ještě nebyla na straně platební brány nebo banky zpracována (např. z důvodu čekání na zpracování v nebankovní dny), je-li ve stavu COMPLETED nebo REJECETED, jde o finální stav a e-shop se dále již neptá. U stavu OPENED doporučujeme dotaz na stav platby opakovat v intervalu 30min až do konečného stavu.

Příklad volání

Request

GET [base URL]/transaction/eshop/status

Headers

Signature: fe8bc6b149120b5c90561059749832f6d6e6b1759c29d314f0564aac36a4735c

URL

[base URL]/transaction/eshop/status?merchantId=d946b69b-dae1-43da-97ce-748260645fdb&merchantTransactionId=13acedde-4b7e-dab6-4149-7b2b60bc8a77

Response body

{
    "merchantTransactionId": "13acedde-4b7e-dab6-4149-7b2b60bc8a77",
    "resultCode": "COMPLETED"
}

Výpočet kontrolního součtu (signature)

Pro zajištění integrity a nepopiratelnosti předávaného požadavku je k parametrům zprávy připojen parametr signature. Tento kontrolní mechanizmus je použit pro všechny zprávy od e-shopu směrem k platební bráně. Platební požadavek bez atributu signature, či s neodpovídající hodnotou, je automaticky zamítnut jako neoprávněný.

Hodnota atributu signature je vypočítána pomocí algoritmu HMAC-SHA256. Vstupem do tohoto algoritmu jsou všechny parametry požadavku z tabulek výše a neveřejný bezpečnostní klíč (secureKey), který zná jen e-shop a platební brána.

Platební brána kontroluje správnost atributu signature oproti zaslaným atributům. Díky tomu lze bezpečně ověřit, že požadavek nebyl ručně změněn.

Pořadí parametrů pro výpočet odpovídá pořadí ve výše uvedených tabulkách, které je nutné dodržet. Pokud je některý z parametrů nepovinný a v requestu není zaslán, pak ani nevstupuje do výpočtu a je vynechán. Pokud je některý z nepovinných parametrů v requestu zaslán, je nutné jej zahrnout i do výpočtu signature.

Příklad výpočtu

Zde je uveden příklad výpočtu signature pro /transaction/eshop/status, který lze analogicky použít i pro všechny další metody.

Příklad zřetězení parametrů

merchantId + „|“ + merchantTransactionId

Příklad zřetězení hodnot parametrů

d946b69b-dae1-43da-97ce-748260645fdb|13acedde-4b7e-dab6-4149-7b2b60bc8a77

Výpočet HMAC-SHA256

Hodnoty oddělené pipou jsou vloženy do atributu data. Klíč (secureKey) je vložen do atributu key.

Hodnota parametru signature pro výše uvedené zřetězené hodnoty parametrů

fe8bc6b149120b5c90561059749832f6d6e6b1759c29d314f0564aac36a4735c

Číselníky

Číselník resultCode

Návratový kód z platební brány informující o výsledku platby.

Návratový kód platební brány	Popis
`OPENED`	Transakce ve zpracování
`AUTHORIZED`	Transakce autorizována na straně banky
`COMPLETED`	Transakce dokončena (finální stav)
`REJECTED`	Transakce zamítnuta (finální stav)

Číselník PaymentMethod

Kód platební metody v případě, že je daná metoda vybraná již v e-shopu nikoli až v platební bráně Zaplaceno.cz.

Atribut zasílaný e-shopem	Popis
`PSD2`	Výběr platební metody je bezhotovostní PSD2 převod
`CARD`	Výběr platební metody je platba kartou

Číselník PaymentProviders

Kód poskytovatele platby v případě, že je poskytovatel platby vybraný již v e-shopu nikoli až v platební bráně Zaplaceno.cz.

Dostupné kódy vychází ze služby paymentProviders viz kapitola „Získání seznamu povolených poskytovatelů plateb – GET /eshop/paymentProviders“. E-shop použije hodnotu z atributu bankCode.

Validační pravidla

Jedná se o validační pravidla platební brány Zaplaceno.cz. Validační pravidla jednotlivých bank plátce se mohou lišit.

AV pole – zpráva pro příjemce (description)

Text maximální délky 100 alfanumerických znaků podporovaných CERTIS (clearing ČNB), a to včetně podporovaných speciálních znaků

Povolené znaky s diakritikou

áäčďéěíĺľňöóôŕřšťüúůýž
ÄÁČĎÉĚÍĹĽŇÖÓÔŔŘŠŤÜÚŮÝŽ

Vyloučené znaky s diakritikou

âăąćçđęëîłńőśşţűźż
ÂĂĄĆÇĐĘËÎŁŃŐŚŞßŢŰŹŻ

Povolené speciální znaky CERTIS

'()+,-./:?
!"#$%&*;=@[\]_`{}

Vyloučené speciální znaky CERTIS

§<>|~^

Úplný výčet znaků:

mezera (ASCII: 32)
!"#$%&'()*+,-./ (ASCII: 33-47)
0-9 (ASCII: 48-57)
:;=?@ (ASCII: 58,59,61,63,64)
A-Z (ASCII: 65-90)
[\]_` (ASCII: 91,92,93,95,96)
a-z (ASCII: 97-122)
{} (ASCII: 123,125)
áäčďéěíĺľňöóôŕřšťüúůýž
ÄÁČĎÉĚÍĹĽŇÖÓÔŔŘŠŤÜÚŮÝŽ

Částka převodu (totalPrice)

Částka se zadává jako desetinné číslo. Desetinným oddělovačem je tečka.

Maximální hodnota převáděné částky může být na straně platební brány shora omezena. Pro více informací se informujte u platební brány.

Variabilní symbol (variableSymbol)

Text maximální délky 10 číslic 0-9, nepovinné pole. Vodící nuly na začátku jsou povoleny.

Iniciace platby - POST /transaction/eshop/init

Pro odeslání platebního příkazu e-shop sestaví POST request s níže uvedenými parametry:

Tabulka 2

Atribut	Povinnost	Datový typ	Popis	Příklad
merchantId (body)	[1..1]	UUID	Jedinečný identifikátor obchodníka přidělený platební bránou	`d946b69b-dae1-43da-97ce-748260645fdb`
merchantTransactionId (body)	[1..1]	UUID	Jedinečný identifikátor platby generovaný e-shopem	`13acedde-4b7e-dab6-4149-7b2b60bc8a77`
paymentMethod (body)	[0..1]	String, ENUM	Pokud uživatel zvolil platební metodu již na e-shopu, je zde uvedena (viz Číselníky).	`PSD2`
paymentProvider (body)	[0..1]	String, ENUM	Pokud uživatel zvolil banku již na e-shopu, je zde uvedena	`KB`
language (body)	[0..1]	String(4)	Jazyk platební brány. Aktuálně je podporován pouze CZ.	`CZ`
totalPrice (body)	[1..1]	Number(19,2)	Částka převodu	`10.10`
currency (body)	[0..1]	String, ENUM	Kód měny dle ISO 4217. Aktuálně podporovaná měna je pouze CZK.	`CZK`
description (body)	[0..1]	String(60)	Zpráva pro příjemce. Platební brána doplňuje dalších 80 znaků ve formátu „Zaplaceno.cz - platba pro [merchantId] obj.č. [variableSymbol]“	`Poplatek za služby`
variableSymbol (body)	[1..1]	String(10)	Číslo objednávky	`0123456789`
callbackUrl (body)	[0..1]	String(255)	URL pro odpověď obchodníkovi po dokončení platby. Tato URL je registrována u e-shopu v platební bráně. Je-li zaslána v požadavku, přetíží nastavenou hodnotu.	`https://mujobchod.cz/callback`
signature (header)	[1..1]	String(64)	Podpis požadavku. Výpočet viz „Výpočet kontrolního součtu (signature)“	`18d8a2a5e9375b45d3ec509943b7682aac63f7e19e2b84a28da3ab8dc886eb5e`

Příklad volání

Request

POST [base URL]/transaction/eshop/init

Headers

Content-Type: application/json
Signature: 8e51f1ded00539302efb149647b85f3edce66ca6c6e400d1d8d410594354e318

Body

{
    "merchantId": "d946b69b-dae1-43da-97ce-748260645fdb",
    "merchantTransactionId": "13acedde-4b7e-dab6-4149-7b2b60bc8a77",
    "paymentMethod": "PSD2",
    "paymentProvider": "KB",
    "language": "CZ",
    "totalPrice": "0.01",
    "currency": "CZK",
    "description": "zprava pro prijemnce",
    "variableSymbol": "0123456789",
    "callbackUrl": " https://eshop.cz/callback"
}

Response body

Zákazník je následně přesměrován na adresu podobnou:

{
    "redirectUrl": "[base URL]/init?transactionId=13acedde-4b7e-dab6-4149-7b2b60bc8a77&merchantCallbackUrl= https://eshop.cz/callback"
}

Práce s API službami

Práce s API službami

Přehled API služeb

Sandbox

Request

Headers

Response

Získání seznamu povolených poskytovatelů plateb – GET ​/eshop​/paymentProviders

Příklad volání

Request

Headers

URL

Body

Iniciace platby - POST /transaction/eshop/init

Notifikace o výsledku platby - příklad validního callbackUrl

Získání stavu platby - GET /transaction/eshop/status

Příklad volání

Request

Headers

URL

Response body

Výpočet kontrolního součtu (signature)

Příklad zřetězení parametrů

Příklad zřetězení hodnot parametrů

Výpočet HMAC-SHA256

Hodnota parametru signature pro výše uvedené zřetězené hodnoty parametrů

Číselníky

Validační pravidla

Úplný výčet znaků:

Iniciace platby - POST /transaction/eshop/init

Příklad volání

Request

Headers

Body

Získání seznamu povolených poskytovatelů plateb – GET /eshop/paymentProviders