Metody pro Apple Pay - csob/platebnibrana GitHub Wiki

Stručný přehled metod pro Apple Pay (applepay@shop)

Metoda	Popis
applepay/echo	Získání parametrů pro inicializaci Apple Pay.
applepay/init	Založení Apple Pay platby pro applepay@shop.
applepay/process	Spuštění zpracování Apple Pay platby.

Následující schéma zachycuje průběh Apple Pay platby:

img/cs_CZ/applepay-at-shop-highlevel-cz.png

Zákazník platí na e-shopu svou objednávku. Obchodník zobrazuje zákazníkovi možnost zaplatit pomocí Apple Pay platby, přičemž parametry pro inicializaci získává pomocí volání operace applepay/echo (0).

Poté, co zákazník zvolí Apple Pay platbu, nejprve se založí ApplePay session (obchodník v e-shopu komunikuje na servery Apple), následně e-shop incializuje na platební bráně platbu pomocí operace applepay/init. 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 Apple Pay platbě na e-shopu obchodníka, potřebné údaje pro platbu (číslo karty a expirace) si platební brána dešifruje z payloadu poslaného v rámci operace applepay/init.

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 applepay/process (3). Otisk zařízení je obchodník povinnen provést na straně e-shopu v rámci 1px iframe.

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.

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

Metoda `applepay/echo`

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

Tato operace umožňuje získat parametry pro inicializaci Apple Pay. Parametry může obchodník uložit do cache a použít opakovaně pro zobrazení stránky s možností zaplatit pomocí Apple Pay.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou.
dttm	String	Datum a čas odeslání požadavku ve formátu `YYYYMMDDHHMMSS`.
signature	String	Podpis požadavku, kódováno v BASE64.

Příklad požadavku:

{
  "merchantId":"M1MIPS0000",
  "dttm":"20220125131559",
  "signature":"base64-encoded-signature-of-payment-request"
}

Návratové hodnoty

Položka	Typ	Popis
dttm	String	Datum a čas odpovědi ve formátu `YYYYMMDDHHMMSS`.
resultCode	Number	Výsledek operace, viz výčet.
resultMessage	String	Textový popis výsledku operace.
initParams	Object	Parametry pro inicializaci javascriptu pro Apple Pay, vyplněno v případě, že `resultCode` je `0`.
signature	String	Podpis odpovědi, kódováno v BASE64.

Popis parametrů objektu initParams, obchodník dané hodnoty v nezměněné podobě vyplní do js (viz dále) pro inicializaci Apple Pay.

Položka	Typ	Popis
countryCode	Number	Kód země dle standardu ISO 3166-1 alpha-2, ve které je platba zpracovávána.
supportedNetworks	String	Seznam akceptovaných karetních brandů, které bude Apple Pay od zákazníka akceptovat, bude předvyplněno platební bránou, příklad: `[ "visa", "masterCard", "maestro" ]`.
merchantCapabilities	String	Seznam podporovaných způsobů ověření platby. Bude předvyplněno na základě nastavení platební brány, příklad: `[ "supports3DS" ]`.

Příklad návratových hodnot pro applepay/echo (applepay@shop má obchodník povolen):

{
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "initParams": {
    "countryCode": "CZ",
    "supportedNetworks": ["visa", "masterCard", "maestro"],
    "merchantCapabilities": ["supports3DS"]
  },
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro applepay/echo (applepay@shop má obchodník zakázán):

{
  "dttm":"20220125131601",
  "resultCode": 160,
  "resultMessage":"Payment method disabled",
  "signature":"base64-encoded-response-signature"
 }

Poté, co obchodník získá v odpovědi na volání applepay/echo parametry předané v initParams, provede na straně e-shopu vložení/vygenerování javascriptu pro inicializaci Apple Pay platby.

Viz také popis platební metody Apple Pay.

Metoda `applepay/init`

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

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou.
orderNo	String	Referenční číslo objednávky využívané pro párování plateb, které bude uvedeno také na výpisu z banky. Numerická hodnota, maximální délka je 10 číslic.
dttm	String	Datum a čas odeslání požadavku ve formátu `YYYYMMDDHHMMSS`.
clientIp	String	IP adresa zákazníka (jeho browseru) přistupující na e-shop obchodníka, formát ipv4 nebo ipv6.
totalAmount	Number	Celková cena v setinách základní měny. Tato hodnota bude zobrazena na platební bráně jako celková částka k zaplacení.
currency	String	Kód měny. Povolené hodnoty: `CZK`, `EUR`, `USD`, `GBP`, `HUF`, `PLN`, `RON`, `NOK`, `SEK`.
closePayment	Boolean	Indikuje, zda má být platba automaticky zahrnuta do uzávěrky a proplacena. Povolené hodnoty: `true` / `false`. Od verze 1.9 nepovinný parametr, defaultní hodnota: `true`.
payload	String	Data ve formátu JSON přijatá obchodníkem z Apple Pay (atribut `paymentData` v přijatých datech od Apple Pay). Obchodník kóduje jako BASE64 a následně předává v parametru `payload`.
returnUrl	String	URL adresa, na kterou bude klient přesměrován zpět do e-shopu po dokončení platby v případě, že u platby je vyžadováno potvrzení v rámci ověření platby. Maximální délka 300 znaků. Při přesměrování zpět na e-shop se předává stejná sada parametrů jako v případě návratu z platební brány při platbě kartou.
returnMethod	String	Metoda návratu na URL adresu e-shopu. Povolené hodnoty `POST`, `GET`. Doporučená metoda je `POST`.
customer	Object	Dodatečná data o nákupu týkající se zákazníka. Viz detailní popis struktury `customer`.
order	Object	Dodatečná data o nákupu týkající se objednávky. Viz detailní popis struktury `order`.
sdkUsed	Boolean	Indikuje, zda je ověření platby prováděno přes 3DS SDK (v případě mobilní aplikace) nebo ne (platba přes prohlížeč). Povolené hodnoty: `true` / `false`. Defaultní hodnota: `false`.
merchantData	String	Libovolná pomocná data, která předává obchodník na bránu, musí být kódována v BASE64. Maximální délka po zakódování je 255 znaků. V případě obchodního modelu "Marketplace" musí obchodník identifikovat svého retailera pomocí IČO. Tento identifikátor je třeba plnit do hranatých závorek [] a může být umístěn libovolně v rámci položky merchantData. V případě, že se nákupu účastní vícero retailerů, hodnoty IČO se oddělují čárkou - např. [12345678,87654321].
language	String	Preferovaná jazyková mutace, která se použije v případě, že se provádí potvrzení platby. Povolené hodnoty: `cs`,`en`,`de`,`fr`,`hu`,`it`,`ja`,`pl`,`pt`,`ro`,`ru`,`sk`,`es`,`tr`,`vi`,`hr`,`sl`,`sv`.
ttlSec	Number	Nastavení životnosti platby, v sekundách, min. povolená hodnota 300, max. povolená hodnota 1800 (5-30 min). Defaultní hodnota: 1800. Životnost platby je počítána od okamžiku provolání `applepay/init`.
signature	String	Podpis požadavku, kódováno v BASE64.

Příklad požadavku:

{
  "merchantId":"M1MIPS0000",
  "orderNo":"51966",
  "dttm":"20220125131559",
  "clientIp":"192.0.2.2",
  "totalAmount":12300,
  "currency":"CZK",
  "payload":"base64-encoded-payload-from-applepay",
  "returnUrl":"https://shop.example.com/return",
  "returnMethod":"POST",
  "signature":"base64-encoded-signature-of-payment-request"
}

Příklad požadavku:

{
  "merchantId":"M1MIPS0000",
  "orderNo":"51966",
  "dttm":"20220125131559",
  "clientIp":"192.0.2.2",
  "totalAmount":12300,
  "currency":"CZK",
  "closePayment":false,
  "payload":"base64-encoded-payload-from-applepay",
  "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-signature-of-payment-request"
}

Návratové hodnoty:

Položka	Typ	Popis
payId	String	Jednoznačné ID platby (přidělené platební bránou v operaci `applepay/init`, obsahuje 15-znakový řetězec).
dttm	String	Datum a čas odpovědi ve formátu `YYYYMMDDHHMMSS`.
resultCode	Number	Výsledek operace, viz výčet.
resultMessage	String	Textový popis výsledku operace.
paymentStatus	Number	Stav platby, viz životní cyklus transakce.
statusDetail	String	Detailní stav platby (tzv. mikrostav), obsahuje například důvod zamítnutí platby, viz popis.
actions	Object	Struktura pro předání potřebných dat pro provedení otisku zařízení. Viz struktura actions.
signature	String	Podpis odpovědi, kódováno v BASE64.

Příklad návratových hodnot pro applepay/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 applepay/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 applepay/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.

Metoda `applepay/process`

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

Operace spustí zpracování Apple Pay platby.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou.
payId	String	PayID získané při založení Apple Pay platby pomocí operace `applepay/init`.
dttm	String	Datum a čas odeslání požadavku ve formátu `YYYYMMDDHHMMSS`.
fingerprint	Object	Dodatečná data pro ověření platby. Viz struktura fingerprint.
signature	String	Podpis požadavku, kódováno v BASE64.

Příklad požadavku: (applepay@shop, platba prováděná z 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: (applepay@shop, platba prováděná z mobilní aplikace s integrovaným 3DS 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"
}

Návratové hodnoty

Položka	Typ	Popis
payId	String	Jednoznačné ID platby (přidělené platební bránou v operaci `applepay/init`, obsahuje 15-znakový řetězec)
dttm	String	Datum a čas odpovědi ve formátu `YYYYMMDDHHMMSS`.
resultCode	Number	Výsledek operace, viz výčet.
resultMessage	String	Textový popis výsledku operace.
paymentStatus	Number	Stav platby, viz životní cyklus transakce.
statusDetail	String	Detailní stav platby (tzv. mikrostav), obsahuje například důvod zamítnutí platby, viz popis.
actions	Object	Struktura pro předání potřebných dat pro provedení potvrzení v rámci ověření platby. Viz struktura actions.
signature	String	Podpis odpovědi, kódováno v BASE64.

Příklad návratových hodnot pro applepay/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 applepay/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 applepay/process (včetně parametrů pro provedení potvrzení v rámci ověření platby 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í applepay/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.

Metody pro Apple Pay - csob/platebnibrana GitHub Wiki

Stručný přehled metod pro Apple Pay (applepay@shop)

Metoda applepay/echo

Návratové hodnoty

Metoda applepay/init

Návratové hodnoty:

Metoda applepay/process

Návratové hodnoty

Metoda `applepay/echo`

Metoda `applepay/init`

Metoda `applepay/process`