Metody pro OneClick platbu - csob/platebnibrana GitHub Wiki

Následující schéma zachycuje průběh OneClick platby v případě, že je platba prováděna za přítomnosti zákazníka:

Zákazník platí na e-shopu svou objednávku. Obchodník zobrazuje zákazníkovi možnost zaplatit pomocí Oneclick platby na základě dříve vytvořené Oneclick šablony, přičemž volitelně může ověřit platnost šablony pomocí operace oneclick/echo (0).

Poté, co zákazník zvolí OneClick platbu, e-shop incializuje na platební bráně platbu pomocí operace oneclick/init, pomocí parametru clientInitiated nastaveným na hodnotu true indikuje, že OneClick platba probíhá za přítomnosti zákazníka. V odpovědi získává identifikaci platby payId (1).

Na rozdíl od standardní platby kartou na bráně zůstává zákazník při OneClick platbě na e-shopu obchodníka, potřebné údaje pro platbu (číslo karty a expirace) se načítají z OneClick šablony v rámci zpracování platby na platební bráně.

Platební brána provádí u některých plateb tzv. otisk zařízení (2). Jedná se o odeslání údajů z prohlížeče zákazníka vydavateli karty, který tato data následně použije pro následné ověření platby. Obchodník spouští další zpracování voláním operace oneclick/process (3). Otisk zařízení je obchodník povinnen provést na straně e-shopu v rámci 1px iframe za pomocí parametrů, které dostal v odpovědi na volání oneclick/init.

U některých plateb je v rámci ověření vyžadováno od zákazníka potvrzení platby (5). Stejně jako u otisku zařízení i potvrzení platby je obchodník povinnen provést na straně e-shopu, otevírá iframe nebo provádí přesměrování do top.location na základě parametrů přijatých z platební brány.

Obchodník průběžně zjišťuje stav platby pomocí volání operace payment/status (4). V případě, že je vyžadováno potvrzení platby, je po dokončení ověření a autorizaci platby zákazník přesměrován pomocí returnMethod na returnUrl e-shopu. Po dokončení ověření a dokončení autorizace platby zobrazuje obchodník zákazníkovi výsledek platby.

V případě, že OneClick platba je prováděna bez přítomnosti zákazníka, provolá obchodník výše uvedené operace oneclick/echo, oneclick/init (s parametrem clientInitiated nastaveným na hodnotu false) a oneclick/process. V tomto případě se nevyžaduje provedení otisku ani provedení potvrzení platby. Obchodník zjišťuje stav platby pomocí volání operace payment/status.

Tučně uvedené parametry jsou pro volání povinné.

POST https://api.platebnibrana.csob.cz/api/v1.9/oneclick/echo

Operace ověří stav OneClick šablony. Zjištění stavu šablony doporučujeme použít před nabídnutím OneClick platby v košíku, případně při zobrazení uložených karet v zákaznickém účtu (více informací v obecném popisu OneClick platby). Pro ověření stavu šablony použijte tuto operaci, nevolejte stav úvodní OneClick platby.

Příklad požadavku:

{
  "merchantId":"M1MIPS0000",
  "origPayId":"0e92dd54b133@HA",
  "dttm":"20220125131559",
  "signature":"base64-encoded-request-signature"
}

Příklad návratových hodnot pro oneclick/echo - OneClick šablona je aktivní:

{
  "origPayId":"0e92dd54b133@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro oneclick/echo - OneClick šablona nenalezena:

{
  "origPayId":"0e92dd54b133@HA",
  "dttm":"20220125131601",
  "resultCode": 700,
  "resultMessage":"Oneclick template not found",
  "signature":"base64-encoded-response-signature"
 }

Návratové hodnoty relevantní pro operaci oneclick/echo (kódy 700-750) jsou uvedeny v číselníku návratových hodnot.

V odpovědi operace oneclick/echo může platební brána vrátit rozšíření obsahující Data o kartě pro OneClick platbu.

POST https://api.platebnibrana.csob.cz/api/v1.9/oneclick/init

Operace založí OneClick platbu. Podmínkou je existence OneClick šablony, která byla dříve vytvořena na platební bráně.

Příklad požadavku:

{
  "merchantId":"M1MIPS0000",
  "origPayId":"0e92dd54b133@HA",
  "orderNo":"51966",
  "dttm":"20220125131559",
  "clientIp":"192.0.2.2",
  "returnUrl":"https://shop.example.com/return",
  "returnMethod":"POST",
  "customer": {
    "name":"Jan Novák",
    "email":"[email protected]",
    "mobilePhone":"+420.800300300"
  },
  "order": {
    "type":"purchase",
    "availability":"now",
    "delivery":"digital",
    "deliveryMode": "0",
    "deliveryEmail": "[email protected]"
  },
  "signature":"base64-encoded-request-signature"
}

Obecná struktura pro předání potřebných dat pro provedení otisku zařízení nebo pro provedení potvrzení v rámci ověření platby pro @shop platební metody.

Struktura pro předání dat pro provedení otisku zařízení. Pokud je otisk vyžadován, jsou tyto data v rámci oneclick@shop, applepay@shop nebo googlepay@shop vráceny v odpovědi na */init volání.

V případě, že je platba prováděna pomocí prohlížeče zákazníka (tzn. parametr sdkUsed je v init metodě nastaven na hodnotu false) a současně je vyžadován otisk zařízení (platební brána vrací v odpovědi vyplněnou strukturu actions.fingerprint.browserInit), je obchodník povinen na straně e-shopu vytvořit 1px iframe a otevřít v něm příslušnou url. V prohlížeči zákazníka se tak načte stránka platební brány, která obsahuje příslušný kód pro provedení otisku.

V případě, že je platba prováděna na mobilním zařízení pomocí SDK (tzn. parametr sdkUsed je v init metodě nastaven na hodnotu true), vrací platební brána v odpovědi na init volání parametry pro inicializaci SDK (viz parametry actions.fingerprint.sdkInit). Výsledek inicializace předává obchodník zpět na platební bránu voláním oneclick/process pomocí struktury fingerprint.sdk (viz dále). Pomocí SDK je v případě potřeby prováděno potvrzení platby v rámci jejího ověření, předané parametry slouží k zajištění zabezpečeného komunikačního kanálu mezi mobilní aplikací zákazníka a serverem vydavatele karty, který provádí vlastní ověření.

V případě, že je v rámci ověření platby vyžadováno potvrzení, obsahuje struktura actions.authenticate potřebné parametry spuštění potvrzení v prohlížeči nebo pomocí 3DS SDK. Tyto data jsou v rámci oneclick@shop, applepay@shop nebo googlepay@shop vráceny v odpovědi na */process volání, případně v odpovědi na volání payment/status.

V případě, že je platba prováděna pomocí prohlížeče zákazníka (tzn. parametr sdkUsed je v init metodě nastaven na hodnotu false) a současně je vyžadováno potvrzení platby (je vrácena vyplněná struktura actions.authenticate.browserChallenge), je obchodník povinen na straně e-shopu otevřít příslušnou url z browserChallenge (otevírá ji buď v iframe nebo v top.location). V prohlížeči zákazníka se tak načte stránka platební brány, která obsahuje příslušný kód pro provedení vlastního potvrzení platby. Zákazníkovi je (v rámci iframe nebo v rámci top.location) zobrazena stránka vydavatele karty, kde potvrzuje platbu. Poté, co je potvrzení platby dokončeno, je zákazníkovi zobrazen průběh dalšího zpracování platby (výsledek ověření a autorizace platby). Po dokončení zpracování je provedeno přesměrování na returnUrl e-shopu, (pokud je použit iframe, po přesměrování na returnUrl obchodník iframe zavírá), zobrazuje zákazníkovi v e-shopu výsledek platby.

V případě, že je platba prováděna na mobilním zařízení pomocí SDK (tzn. parametr sdkUsed je v init metodě nastaven na hodnotu true) a je vyžadováno potvrzení platby (je vrácena vyplněná struktura actions.authenticate.sdkChallenge), je obchodník povinen předat získané parametry a spustit ověření platby pomocí SDK.

Obecná struktura obsahující parametry pro otevření (zobrazení) daného endpointu, resp. pro provedení přesměrování na daný endpoint. Využívá se buď pro provedení otisku zařízení nebo pro spuštění potvrzení v rámci ověření platby.

Přestože jsou ve specifikaci endpointu uvedeny obě metody (GET i POST), platební brána aktuálně používá pro provedení otisku zařízení nebo pro spuštění potvrzení v rámci ověření platby pouze GET metodu (vrací se vždy jen vyplněná url bez parametrů vars).

Data pro provedení otisku zařízení v mobilní aplikaci zákazníka s integrovaným 3DS SDK. Obchodník tyto parametry použije pro inicializaci SDK.

Parametry pro spuštění potvrzení v rámci ověření platby pomocí 3DS SDK v mobilní aplikaci zákazníka.

Příklad návratových hodnot pro oneclick/init -- úspěšně založená platba:

{
  "payId":"7624c5e60252@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro oneclick/init -- úspěšně založená platba, včetně parametrů pro provedení otisku zařízení:

{
  "payId":"7624c5e60252@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "actions": {
    "fingerprint": {
      "browserInit": {
        "url":"https://example.com/3ds-method-endpoint"
      }
    }
  },
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro oneclick/init -- úspěšně založená platba, včetně parametrů pro inicializaci 3DS SDK pro ověření platby:

{
  "payId":"7624c5e60252@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "actions": {
    "fingerprint": {
      "sdkInit": {
        "directoryServerID":"A000000003",
        "schemeId":"Visa",
        "messageVersion":"2.2.0"
      }
    }
  },
  "signature":"base64-encoded-response-signature"
 }

V případě nevalidního požadavku vrací platební brána odpověď obsahující popis chyby. Detailní popis je uveden na stránce Volání rozhraní eAPI.

V případě, že se v response vrátí chyba "resultCode":900,"resultMessage":"Unable to load card for oneclick/init", zkuste prosím danou operaci po uplynutí několika sekund opakovat. Jedná se o dočasnou nedostupnost návazného systému.

POST https://api.platebnibrana.csob.cz/api/v1.9/oneclick/process

Operace spustí zpracování OneClick platby.

Dodatečná data pro ověření platby.

Struktura pro předání parametrů prohlížeče zákazníka, které budou použity pro ověření platby.

Struktura pro předání parametrů získaných po inicializaci 3DS SDK integrovaného do mobilní aplikace zákazníka, které budou použity pro ověření platby.

Příklad požadavku: (oneclick@shop, platba prováděná z prohlížeče zákazníka)

Obchodník předává v požadavku parametry prohlížeče zákazníka.

{
  "merchantId":"M1MIPS0000",
  "payId":"7624c5e60252@HA",
  "dttm":"20220125131615",
  "fingerprint": {
    "browser": {
      "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.99 Safari/537.36",
      "acceptHeader":"text/html,application/xhtml+xml,application/xml;",
      "language":"en",
      "javascriptEnabled":false
    }
  },
  "signature":"base64-encoded-request-signature"
}

Příklad požadavku: (oneclick@shop, platba prováděná z mobilní aplikace s integrovaným 3DS SDK)

Obchodník předává v požadavku parametry poté, co se provedla inicializace SDK.

{
  "merchantId":"M1MIPS0000",
  "payId":"7624c5e60252@HA",
  "dttm":"20220125131615",
  "fingerprint": {
    "sdk": {
      "appID":"198d0791-0025-4183-b9ae-900c88dd80e0",
      "encData":"encrypted-data",
      "ephemPubKey": "encoded-public-key",
      "maxTimeout": 5,
      "referenceNumber":"sdk-reference-number",
      "transID":"7f101033-df46-4f5c-9e96-9575c924e1e7"
    }
  },
  "signature":"base64-encoded-request-signature"
}

Příklad návratových hodnot pro oneclick/process (bez nutnosti provést potvrzení v rámci ověření platby)

{
  "payId":"7624c5e60252@HA",
  "dttm":"20220125131618",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 2,
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro oneclick/process (včetně parametrů pro provedení potvrzení v rámci ověření platby v prohlížeči zákazníka)

{
  "payId":"7624c5e60252@HA",
  "dttm":"20220125131618",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 2,
  "actions": {
    "authenticate": {
      "browserChallenge": {
        "url":"https://example.com/challenge-endpoint"
      }
    }
  },
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro oneclick/process (včetně parametrů pro provedení potvrzení v rámci ověření platby v mobilní aplikaci zákazníka pomocí 3DS SDK)

{
  "payId":"7624c5e60252@HA",
  "dttm":"20220125131618",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 2,
  "actions": {
    "authenticate": {
      "sdkChallenge": {
        "threeDSServerTransID":"eeddda80-6ca7-4b22-9d6a-eb8e84791ec9",
        "acsReferenceNumber":"3DS_LOA_ACS_201_13579",
        "acsTransID":"7f3296a8-08c4-4afb-a3e2-8ce31b2e9069",
        "acsSignedContent":"base64-encoded-acs-signed-content"
      }
    }
  },
  "signature":"base64-encoded-response-signature"
 }

Výsledek ověření a následné autorizace je potřeba zjistit následným voláním payment/status. Doba zpracování se může lišit v závislosti na tom, zda je vyžadováno potvrzení platby v rámci jejího ověření:

• pokud potvrzení není vyžadováno, je doporučená doba volání je 2-3 vteřiny po volání oneclick/process, pokud je stav platby stále 2 (platba probíhá), doporučujeme periodicky volat v intervalu 5 vteřin (celková doba autorizace závisí na zpracování požadavku v systémech VISA/MC a může být v nejhorším případě až 60 vteřin).
• pokud je potvrzení vyžadováno, může trvat řádově minuty, než je zákazníkem platba potvrzena a vydavatel karty dokončí ověření. V tomto případě doporučujeme volat payment/status periodicky v delším intervalu např. 30 vteřin.

V případě, že se v response vrátí chyba "resultCode":900,"resultMessage":"Unable to load card for oneclick/process", zkuste prosím danou operaci po uplynutí několika sekund opakovat. Jedná se o dočasnou nedostupnost návazného systému.