Skip to content

Metody pro Apple Pay

Jump to bottom
David Matějček edited this page Nov 9, 2023 · 4 revisions

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:

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@example.com",
    "mobilePhone":"+420.800300300"
  },
  "order": {
    "type":"purchase",
    "availability":"now",
    "delivery":"digital",
    "deliveryMode": "0",
    "deliveryEmail": "delivery@example.com"
  },
  "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.

💳 Platební brána

  1. Průběh platby
  2. API integrace a zabezpečení
  3. Návod na přechod do produkčního prostředí
  4. Testovací karty
  5. API Sunset

💰 Platby

  1. Ověření karetních plateb
  2. Platba na bráně
  3. OneClick platba
  4. Platba na míru
  5. Apple Pay
  6. Google Pay
  7. Zaúčtování platby kartou na menší částku
  8. Platební tlačítko ČSOB
  9. Platba Skip Pay

🔬 eAPI 1.9

  1. Volání rozhraní eAPI
  2. Podpis požadavku a ověření podpisu odpovědi
  3. Přehled eAPI metod
  4. Základní metody
  5. Metody pro OneClick platbu
  6. Metody pro Apple Pay
  7. Metody pro Google Pay
  8. Metody pro platební tlačítko
  9. Metody pro platbu Skip Pay
  10. Dodatečná data o nákupu

📐 Návody a podklady

  1. Loga a prezentace platebních metod
  2. Logo obchodníka
  3. Barevné schéma

📟 API rozšíření

  1. Koncept API rozšíření
  2. Detailní datum a čas zpracování a vypořádání transakce
  3. Data o kartě pro OneClick platbu
  4. Data o kartě pro platbu na bráně
  5. Tokenizace
  6. Ověřovací kód na výpis

🔧 Časté dotazy (FAQ)

  1. Funkční a komerční dotazy
  2. Technické dotazy

📡 Archiv starších verzí eAPI

  1. eAPI 1.8
  2. eAPI 1.7
  3. eAPI 1.6
  4. eAPI 1.5
  5. eAPI 1.0
Clone this wiki locally