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 produkč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
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.
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.
https://api.sandbox.zaplaceno.cz/transaction/eshop/status?merchantId=21b9aa87-65c5-4cd0-bc6b-9ae2ac93ebf5&merchantTransactionId=7e8fede9-f9b1-4d98-8bfe-68c3ea5ed74c
Signature: eac6d3458d17b483ef4755b9cc35b3709dd2bf5ade13ba08da128217977f0b01
{
"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
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 |
|
signature (header) |
[1..1] |
String(64) |
Podpis požadavku Výpočet viz kapitola „Výpočet kontrolního součtu (signature)“ |
|
GET [base URL]/eshop/paymentProviders
Signature: 2f48c0900c1d568eefc4fff30a35977cbfeadfb082315d6783e31268d576d487
[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.
[
{
"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..."
},
]
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.
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 |
|
merchantTransactionId |
[1..1] | UUID |
Jedinečný identifikátor transakce generovaný na straně e-shopu |
|
signature |
[1..1] |
String(64) |
Podpis požadavku Výpočet viz kapitola „Výpočet kontrolního součtu (signature)“ |
|
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.
GET [base URL]/transaction/eshop/status
Signature: fe8bc6b149120b5c90561059749832f6d6e6b1759c29d314f0564aac36a4735c
[base URL]/transaction/eshop/status?merchantId=d946b69b-dae1-43da-97ce-748260645fdb&merchantTransactionId=13acedde-4b7e-dab6-4149-7b2b60bc8a77
{
"merchantTransactionId": "13acedde-4b7e-dab6-4149-7b2b60bc8a77",
"resultCode": "COMPLETED"
}
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.
merchantId + „|“ + merchantTransactionId
d946b69b-dae1-43da-97ce-748260645fdb|13acedde-4b7e-dab6-4149-7b2b60bc8a77
Hodnoty oddělené pipou jsou vloženy do atributu data. Klíč (secureKey) je vložen do atributu key.
fe8bc6b149120b5c90561059749832f6d6e6b1759c29d314f0564aac36a4735c
Čí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.
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ů
áäčďéěíĺľňöóôŕřšťüúůýž
ÄÁČĎÉĚÍĹĽŇÖÓÔŔŘŠŤÜÚŮÝŽ
âăąćçđęëîłńőśşţűźż
ÂĂĄĆÇĐĘËÎŁŃŐŚŞßŢŰŹŻ
'()+,-./:?
!"#$%&*;=@[\]_`{}
§<>|~^
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.
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 |
|
merchantTransactionId (body) |
[1..1] | UUID |
Jedinečný identifikátor platby generovaný e-shopem |
|
paymentMethod (body) |
[0..1] |
String, ENUM |
Pokud uživatel zvolil platební metodu již na e-shopu, je zde uvedena (viz Číselníky). |
|
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 |
|
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]“ |
|
variableSymbol (body) |
[1..1] |
String(10) |
Číslo objednávky |
|
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. |
|
signature (header) |
[1..1] |
String(64) |
Podpis požadavku. Výpočet viz „Výpočet kontrolního součtu (signature)“ |
|
POST [base URL]/transaction/eshop/init
Content-Type: application/json
Signature: 8e51f1ded00539302efb149647b85f3edce66ca6c6e400d1d8d410594354e318
{
"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"
}
Zaplaceno.cz je platební brána od Komerční banky | © Komerční banka 2022