Platobné rozhranie ČSOB - Zmluva o poskytnutí služby Platobné tlačidlo

Publikované 01.08.2009, autor Lubos Dzurik

ČSOB uzatvára s Virtulánym Obchodným Domom (VOD) Zmluvu o poskytnutí služby "Platobné tlačidlo", v rámci ktorej dohodne identifikačné parametre VOD. Zmluva zakotvuje povinnosť obchodníka:

  1. Použiť dodaný grafický element symbolizujúci implementovanú službu:
    ČSOB - Platobné tlačidlo
  2. Povinnú XML štruktúru parametrov odosielaných klientským prehliadačom na rozhranie serveru ČSOB banky:
  3. <zprava ofce="3100">
    <obchodnik>
    	<id></id>
    </obchodnik>
    <data>
    	<nProtiucet></nProtiucet>
    	<chKodBankaProti></chKodBankaProti>
    	<nCastka></nCastka>
    	<nKS></nKS>
    	<chVS></chVS>
    	<nSS></nSS>
    	<vchPoleAV1></vchPoleAV1>
    	<vchPoleAV2></vchPoleAV2>
    </data>
    </zprava>
    
  4. Povinnú XML štruktúru návratových parametrov odosielaných zo serveru ČSOB banky späť na klientský prehliadač:
    <?xml version="1.0" encoding="utf-8"?> 
    <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Body>
        <GetCSOBResponce xmlns="csob/webservices/OFResponce">
          <Status>string</Status>
          <VS>string</VS>
          <OF>string</OF>
        </GetCSOBResponce>
      </soap:Body>
    </soap:Envelope>
    

Štruktúra dat odosielaných na platobný server ČSOB

  • <id>
    • povinné pole s jednoznačným identifikátorom VOD prideleným podľa zmluvného dojednania.
    • Formát poľa: maximálne 4 miestne číslo.
  • <nProtiucet>
    • povinné pole, obsahuje číslo účtu VOD v prospech ktorého bude zrealizovaná dispozícia klienta. Toto číslo účtu musí súhlasiť s číslom účtu, ktoré je priradené vo vnútornom systéme banky pre daný VOD podľa zmluvnéhodojednania.
    • Predvyplnené pole vo formulári tuzemského platobného príkazu nie je možné v rámcidispozície klientom editovať.
    • Formát poľa: buď 16 miestne číslo(predčíslie a číslo účtu doplnené nulami (nuly na začiatku je možné i vynechať)alebo maximálne 17 znakov dlhý string (formát s pomlčkou). Číslo účtu musí vyhovovať bankovej kontrole naplatnosť čísla účtu.
      Príklad: 0000190000000123, 190000000123, 19-123, 123
  • <chKodBankaProti>
    • povinné pole, obsahuje kód banky VOD v ktorého prospech bude zrealizovaná dispozícia klienta. Tento kód banky musí súhlasiť s kódom banky, ktorý je priradený vo vnútornom systéme banky pre daný VOD podľa zmluvného dojednania.
    • Predvyplnenépole vo formulári tuzemského platobného styku nie je možné v rámci dispozície klientom editovať.
    • Formát poľa: 4 miestne číslo.
      Príklad: 7500
  • <nCiastka>
    • povinné pole, obsahuje čiastku, ktorá bude zaslaná v prospech účtu VOD podľa zmluvného dojednania.
    • Predvyplnené pole vo formulári tuzemského platobného styku nie je možné v rámci dispozície klientom editovať.
    • Formát poľa: číslo, maximálne 12 miestny základ + prípadne maximálne 2 desatinné miesta. Oddeľovač desatinných miest je povolený vo formáte čiarky alebo bodky.
      Príklad: 19,50 alebo 19,5 alebo 19.50 alebo 19.5 alebo 19
  • <nKS>
    • povinné pole,obsahuje povinné konštantné symboly.
    • Pokiaľ sa zašle nevyplnené pole, pole formulára zostává editovateľné, nepredvyplnené, ale aplikácia ČSOB Elektronického bankovníctva bude tento KS požadovať pre dokončenie dispozície klienta.
    • Formát poľa: 4 miestne číslo
      Príklad: 0308
  • <chVS>
    • povinné pole,obsahuje číselnú hodnotu podľa VOD, pre spárovanie platby v systéme obchodníka.
    • Predvyplnené pole vo formulári tuzemského platobného príkazu nie je možné klientomv rámci dispozície editovať.
    • Formát poľa: maximálne 10 miestnečíslo.
  • <nSS>
    • nepovinné pole, obsahuje prípadne ďalšiu číselnú hodnotu pre identifikáciu transakcie VOD pre spárovanie platby v systéme obchodníka
    • Predvyplnené pole vo formulári tuzemského platobného príkazu nie je možné klientom v rámci dispozície editovať.
    • Pokiaľ bude zaslané nevyplnené pole SS, pole formulára zostáva editovateľné a nepredvyplnené pre dispozíciu klienta.
    • Formát poľa: maximálne 10 miestne číslo.
  • <vchPoleAV1>
    • povinné pole, obsahuje reťazec “#” doplnený hodnotou ID VOD podľa zmluvného dojednania. Toto pole musí byť totožné s parametrom <id>.
    • Formát poľa: string, maximálne 35 znakov.
  • <vchPoleAV2>
    • nepovinné pole, obsahuje správu pre príjemcu a môže obsahovať text podľa požiadavky VOD.
    • Predvyplnenépole vo formulári tuzemského platobného príkazu nie je možné klientom v rámci dispozície editovať.
    • Pokiaľ bude zaslané nevyplnené pole AV2, pole formulára zostáva editovateľné a nepredvyplnené pre dispozíciu klienta.
    • Formát poľa: string, maximálne 35 znakov.

Všetky uvedené parametre musia byť vyplnené buď štandardnými hodnotami (default values) alebo parametrami pre konkrétnu transakciu. Keď sú všetky parametre naplnené, vytvorí sa z nich XML reťazec v štruktúre zodpovedajúcej popisu v bode 2 vyššie. Takto vytvorený reťazec sa uloží do skrytého elementu nazvaného povinne ZPRAVA v formulári (HTML form) a celý formulár sa odošle na pridelenú URL adresu platobného rozhrania ČSOB banky. Výsledná štruktúra parametrov má teda v prehliadači nasledovný tvar:

<form action="https://pridelenaUrlLinka.sk" method="post">
	<input name="ZPRAVA" id="ZPRAVA" value="<zprava ofce="3100"><obchodnik><id>123456789</id></obchodnik> <data>........</data></zprava>" />
</form>

Odoslanie formulára môže vykonať buď samotný zákazník kliknutím na SUBMIT button, alebo JAVASCRIPT po úspešnej validácii vstupných XML parametrov. Po prijatí platobnej dispozície (transakčnej požiadavky) vykonáva server ČSOB validáciu (kontrolu) zasielaných parametrov a prístup do platobného systému umožní jedine v prípade nezistenia chyby.

Štruktúra návratových dát z platobného servera ČSOB

Platobné rozhranie ČSOB vracia reťazec vo formáte SOAP protokolu. Najzaujímavejším parametrom je parameter <Status> <Status>, ktorý obsahuje výsledok transakcie.

Popis parametrov:

  • Status = pole vracia OK (ak bol prijatý transakčným systémom) nebo NOK  (príkaz nebol prijatý transakčným systémom)
  • VS = variabilný symbol identifikujúci platbu
  • OF = kód obchodnej funkcie

Zhrnutie

Bezpečnosť:

Platobné rozhranie ČSOB nevyužíva podpisovanie transakcie žiadnym šifrovacím algoritmom (SIGN parameter). Jediným bezpečnostným prvkom je zabezpečenie platobného rozhrania cez HTTPS (secure protocol). V prípade neodbornej implementácie môže tak klient riskovať odchytenie napr. čísla účtu obchodníka, VS, alebo ID svojho obchodu. Vyspelejšie platobné rozhrania dnes už štandardne podpisujú online transakcie hashovacími algoritmami, v ktorej zakotvia všetky rozhodujúce a jedinečné parametre prevádzanej transakcie.

Pred spustením VOD online banka prekontroluje korektnosť implementácie.

Štruktúra odosielaných parametrov:

Štruktúra odosielaných dat obsahuje tak redundantné (resp. nejasne dokumentované) ako aj duplikované parametre (napr. vchPoleAV1). Parameter <PROTIUCET> by v žiadnom prípade nemal byť odosielaný cez internet, nakoľko ho banka môže špecifikovať pri podpise zmluvy o poskytnutí služby. Súčasne sa jedná o značne nepružnú XML štruktúru parametrov, nakoľko neumožňuje pružne upraviť návratovú URL adresu. Návratová URL adresa z platobného servera ČSOB je zakotvené pri podpise zmluvy a (bohužiaľ) v čase jej podpisu nie sú väčšinou známe technické detaily implementácie. Žiadať dodatočne o úpravu návratovej URL adresy prináša množstvo byrokratických problémov.

Štruktúra návratových parametrov:

Štruktúra návratových parametrov sa zdá byť taktiež neúplná - server síce vracia variabilný symbol <VS> transakcie, ale už nie špecifický symbol. Záhadným je taktiež parameter <OF>, ktorý nie je v implementačnej príručke zdokumentovaný. A parameter <OFResponce> snáď vyvolá úsmev alebo pochybnosť, či sa jedná o úmyselnú gramatickú poslovenčenú nuanciu alebo nedostatky v angličtine tvorcu systému. Proste <OFResponse> by úsmev ani pochybnosť nevyvolal:-)

Náročnosť impelmentácie:

Vďaka nekryptovaniu prenášaných údajov je implementácia platobného rozhrania ČSOB technicky nenáročná - nepožaduje inštaláciu de facto žiadnych kryptovacích knižníc ani XML parserov.

Implementačná príručka - na stiahnutie:



Váš komentár..
Email bude prepísaný napr. na [michal AT gmail DOT com]
Pozn.: Urážlivé alebo nesúvisiace komentáre budú odstránené.
Zadajte prosím výsledok z vyššie uvedeného obrázku.