Technický popis standardní platby
Standardní platba je využívána nejčastěji a je použita pro jednorázovou platbu za službu nebo zboží na prodejním místě obchodníka.
Založení platby je prováděno přes GoPay webovou službu, která se nachází na adrese:
-
https://gw.sandbox.gopay.com/axis/EPaymentServiceV2?wsdl v testovacím režimu, a na adrese
- https://gate.gopay.cz/axis/EPaymentServiceV2?wsdl pro provozní režim.
Založení standardní platby je provedeno voláním přes SOAP, je tedy nutné mít na serveru nainstalovaný SOAP client. Volání je realizováno pomocí metody z API platební brány GoPay a přijímá jako parametr platební příkaz (paymentCommand), který je podrobně popsán v tabulce.
| Název parametru | Popis parametru | Povinný |
|---|---|---|
| successURL | Návratové URL volané po úspěšném dokončení platebního procesu. Formát odpovídající RFC 2396. | ANO |
| failedURL | Návratové URL volané po zrušení platby. Formát odpovídající RFC 2396. | ANO |
| productName | Popis zboží/služby (max 256 znaků) | ANO |
| targetGoId | Identifikace příjemce platby. Unikátní označení prodejního místa/GoPay uživatele v rámci GoPay. Celočíselný identifikátor - definován během integrace prodejního místa. | ANO |
| orderNumber | Identifikace objednávky v rámci prodejního místa. Alfanumerické označení objednávky (max 128 znaků). | ANO |
| totalPrice | Cena zboží/služby v haléřích. Celočíselné vyjádření ceny. | ANO |
| currency | Měna, ve které je hrazena cena za zboží/službu. Formát měny se řídí mezinárodním měnovým standardem ISO 4217. | ANO |
| paymentChannels | Výčet platebních metod, které jsou zobrazeny na platební bráně. Kódy platebních metod najdete zde - CZK nebo EUR. Jednotlivé kódy jsou odděleny ",". Jde o volitelný parametr, pokud není uveden, zobrazí se všechny platební metody. Zobrazit lze pouze platební metody, které jsou pro dané prodejní místo aktivovány. | NE |
| defaultPaymentChannel | Textový řetězec označující předvybranou platební metodu, nabývá hodnot, viz zde - EUR a CZK. | NE |
| preAuthorization | Pro založení před-autorizované platby nastavte 1. Může nabývat hodnot 0 (NE) nebo 1 (ANO). Dokončení platby (zboží je na skladě) je nutné zavolat GoPay službu dokončení platby, viz zde. | NE |
| recurrencePayment | Pro založení opakované platby nastavte 1. Může nabývat hodnot 0 (NE) nebo 1 (ANO). Četnost opakování je popsána následujícími parametry. | NE |
| recurrenceCycle | Nabývá hodnot [DAY, WEEK, MONTH], které nastavují základní časovou jednotku opakování. Pro opakování od ČS a.s. lze použít pouze hodnotu DAY. | ANO - pokud je recurrent |
| recurrencePeriod | Společně s recurrenceCycle definuje periodu opakované platby. Např. při konfiguraci DAY 5, bude platba prováděna každý 5-tý den. | Payment=1 |
| recurrenceDateTo | Definuje datum, do něhož budou prováděny opakované platby. Jedná se o textový řetězec ve formátu yyyy-mm-dd. | Payment=1 |
| encryptedSignature | Podpis platebního příkazu. Sestavení řetězce pro podpis, viz níže. | ANO |
| customerData.firstName | Jméno zákazníka (max. 128 znaků). | NE |
| customerData.lastName | Příjmení zákazníka (max. 128 znaků). | NE |
| customerData.email | E-mailová adresa zákazníka (max. 128 znaků). | ANO |
| customerData.phoneNumber | Telefonní kontakt na zákazníka. | NE |
| customerData.street | Bydliště zákazníka - ulice (max. 256 znaků). | NE |
| customerData.city | Bydliště zákazníka - město (max. 128 znaků). | NE |
| customerData.postalCode | Bydliště zákazníka – poštovní směrovací číslo. | NE |
| customerData.countryCode | Bydliště zákazníka – kód země. | NE |
| p1 - p4 |
Volitelný parametr (max. 512 znaků). Parametry jsou vráceny v nezměněné podobě jako součást přesměrování zpět na prodejní místo a notifikace o změně stavu platby. |
NE |
| lang | Explicitní nastavení jazykové mutace platební brány. | NE |
Řetězec pro podpis
Šifrovaný podpis je sestaven z vlastností platebního příkazu. Podpis je šifrován tajným klíčem označeným jako secureKey, který je předáván v rámci integrace.
Řetězec pro sestavení podpisu
targetGoId+'|'+productName+'|'+totalPrice+'|'+currency+'|'+orderNumber+'|'+failedURL+'|'+successURL+'|'+preAuthorization+'|'+recurrentPayment+'|'+recurrenceDateTo+'|'+recurrenceCycle+'|'+recurrencePeriod+'|'+paymentChannels+'|'+secureKeyJako výsledek vytvoření platby je vrácen Stav platby (paymentStatus), který obsahuje parametry platby a identifikaci platby na straně GoPay (částka, název zboží, variabilní symbol, paymentSessionId, apod). Podrobnou tabulku popisující stav platby naleznete níže.
| Název parametru | Podpis parametru | Povinný |
|---|---|---|
| paymentSessionId | Identifikace platby v systému GoPay. Celé číslo. | ANO |
| parentPaymentSessionId | Identifikace rodičovské platby. Používáno pro opakované platby. | NE |
| targetGoId | Identifikace prodejního místa/GoPay uživatele v rámci GoPay. Celočíselný identifikátor – definován během integrace prodejního místa. | ANO |
| productName | Popis zboží/služby předaný při založení Platby. | ANO |
| orderNumber | Identifikace objednávky v rámci prodejního místa. Alfanumerické označení objednávky max. 128 znaků. | ANO |
| totalPrice |
Cena zboží/služby v haléřích. Celočíselné vyjádření ceny. Předaný při založení Platby. |
ANO |
| currency | Určuje měnu platby. Formát měny odpovídá ISO 4217. | ANO |
| sessionState | Stav platby | ANO |
| sessionSubState |
Doplňující stav platby – kódy reprezentují specifické situace:
Zákazník obdržel informační e-mail s instrukcemi pro provedení platby. |
NE |
| sessionSubStateDesc | Textový popis doplňující informace. | NE |
| result |
CALL_COMPLETED – volání WS proběhlo bezchybně, |
ANO |
| resultDescription | Popis chybové situace při CALL_FAILED. | NE |
| preAuthorization | Informuje, zda byla platba založena jako před-autorizovaná platba. | NE |
| recurrentPayment | Informuje, zda byla platba založena jako opakovaná platba. | NE |
| paymentChannel |
Určuje platební metodu, kterou zákazník vybral pro úhradu platby hodnot, viz CZK a EUR. |
ANO |
| encryptedSignature | Podpis platebního příkazu. Sestavení řetězce pro podpis, viz níže. | ANO |
| p1 - p4 | Volitelný parametr (max 512 znaků). | NE |
Řetězec pro podpis
Šifrovaný podpis je sestaven z vlastností platebního příkazu. Podpis je šifrován tajným klíčem označeným jako secureKey, který je předáván v rámci integrace.
Řetězec pro sestavení podpisu
targetGoId+'|'+productName+'|'+totalPrice+'|'+currency+'|'+orderNumber+'|'+failedURL+'|'+successURL+'|'+preAuthorization+'|'+recurrentPayment+'|'+recurrenceDateTo+'|'+recurrenceCycle+'|'+recurrencePeriod+'|'+paymentChannels+'|'+secureKeyNa straně prodejního místa je nutné vytvořit relaci mezi objednávkou a platbou paymentSessionId.
Vzorové implementace vytvoření platby naleznete přiložené ve složce example u jednotlivých API.
Poté, co je platba založena, je na ni nutné zákazníka přesměrovat. K tomu je využita URL platební brány. Tato URL je:
-
pro testovací režim - https://gw.sandbox.gopay.com/gw/pay-full-v2
- pro provozní režim - https://gate.gopay.cz/gw/pay-full-v2
Přesměrování obsahuje parametry paymentSession. Jednotlivé parametry (vyjma parametru paymentChannel) obsahují prefix sessionInfo.
| Název parametru | Popis parametru | Povinný |
|---|---|---|
| paymentSessionId | Identifikace platby v systému GoPay. Celé číslo. | ANO |
| targetGoId | Identifikace prodejního místa/GoPay uživatele v rámci GoPay. Celočíselný identifikátor - definován během integrace prodejního místa. | ANO |
| encryptedSignature | Podpis platebního příkazu. Sestavení řetězce pro podpis, viz níže | ANO |
Řetězec pro podpis
Šifrovaný podpis je sestaven z vlastností Platebního session. Podpis je šifrován tajným klíčem označeným jako secureKey, který je předáván v rámci integrace E-shopu.
Řetězec pro sestavení podpisu
targetGoId+'|'+paymentSessionId+'|'+secureKeyPřesměrování může vypadat například takto:
https://gate.gopay.cz/gw/pay-full-v2?sessionInfo.paymentSessionId=3803928540&sessionInfo.targetGoId=1803628540&sessionInfo.encryptedSignature=25ee53a1eccc253a8317bc9487174d09ba6b00a0f5267d2de6b483f58af9676d883e26600ce3316a
Vzorové implementace pro sestavení přesměrování naleznete ve shodných zdrojových kódech s vytvořením platby.
Zákazník po přesměrování provede, nebo neprovede platbu, a je poté přesměrován zpět na prodejní místo, na sucess nebo failed URL, které byly specifikovány při založení platby. Po přesměrování zpět na prodejní místo je ze strany prodejního místa provedeno volání na stav platby pomocí webové služby. Toto volání je blíže popsáno v článku Popis komunikace s platební bránou.
Při změně stavu platby je prodejnímu místu doručena notifikace. Její zpracování je popsáno v článku o Notifikacích.