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+'|'+secureKey

Jako 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:

  • 101 K úhradě vybrána online platební metoda.
  • 102 K úhradě vybrána offline platební metoda.

​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ě,
CALL_FAILED – volání WS proběhlo s chybou (např. neodpovídající podpis).

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+'|'+secureKey

Na 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+'|'+secureKey

Př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.

Pomohl Vám tento článek?:

Nenašli jste, co hledáte?

Kontaktujte pracovníka podpory