Přeskočit na hlavní obsah

Zpracování platby

Upozornění

⚠️⚠️⚠️⚠️
DRAFT - Tento článek je zatím ve vývoji a může obsahovat neúplné nebo nepřesné informace.

Zpracování platby pomocí Apple Pay nebo Google Pay v mobilní aplikaci pokračuje po získání platebního tokenu předáním dat na backend a jejich následným zpracováním prostřednictvím API Comgate. Součástí procesu je také autentizace držitele karty pomocí knihovny 3DS SDK, a to jak v režimu "frictionless", tak formou interaktivního "challenge".

Popisovaný postup zahrnuje celý scénář po přijetí tokenu od Apple Pay a Google Pay až po vyhodnocení výsledku platby. Vše je uspořádáno jako přehledný návod krok za krokem.

Sekvenční diagram​

Pro lepší orientaci v průběhu celého procesu zpracování platby je níže uveden sekvenční diagram. Znázorňuje komunikaci mezi jednotlivými komponentami – mobilní aplikací, Google Pay/Apple Pay, 3DS SDK a API platební brány Comgate – přehledně tak znázorňuje časovou posloupnost klíčových operací.

Diagram slouží jako přehledná vizuální pomůcka, která doplňuje textový popis jednotlivých kroků.

Upozornění

// TODO - diagram je draft

Celkový sekvenční diagram

// TODO - přidat diagram co je paltba a co je pokus o platbu

1. Vytvoření platby​

Prvním krokem po získání platebního tokenu od Apple Pay nebo Google Pay je vytvoření nové platby v systému Comgate. Platba se zakládá prostřednictvím volání API /create, které vrátí unikátní ID platby (transId). Toto ID je potřeba pro další zpracování platby.

Upozornění

Volání API /create musí být provedeno z vašeho serveru, nikoliv přímo z mobilního zařízení.

Více informací naleznete v článku popisující zabezpečení.

Tato zásada platí pouze pro endpointy začínající /1.0 a /2.0.

Parametry založení platby​

Založení platby probíhá standardním způsobem a není nutné nastavovat žádné specifické parametry. Konkrétní konfigurace platby a určení platební metody proběhne až v následujících krocích. Podrobnosti o endpointu /create naleznete v příslušné části dokumentace.

Základními parametry pro založení platby jsou: merchant, secret, price, curr, refId, method, email, country a prepareOnly. Ostatní parametry nejsou pro použití v mobilní aplikaci vyžadovány.

Tip

Hodnotu parametru method nastavte vždy na ALL.

Pro testovací účely lze využít parametr test=true.

Po úspěšném založení platby API vrátí JSON odpověď s identifikací platby. Pro další zpracování palatby je nutné zkontrolovat že návratový kód, parametr code je roven 0. Pro další zpracování je také nutné uložit si hodnotu ID platby transId.

Po úspěšném založení platby vrátí API odpověď ve formátu JSON obsahující identifikaci platby. Pro správné pokračování zpracování je nutné ověřit, že návratový kód v parametru code má hodnotu 0, což značí bezchybný průběh.

Zároveň je potřeba uložit si hodnotu transId, která představuje unikátní ID platby a bude použita v dalších krocích integrace.

Tip

Pro zpracování platby prostřednictvím mobilní aplikace není potřeba zpracovávat hodnotu redirect. Ta slouží pouze pro webové aplikace, kdy po přesměrování plátce na tuto adresu dojde k zobrazení platební brány.

Příklad - platba úspěšně založena:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "message": "OK",
  "transId": "XXXX-XXXX-XXXX",
  "redirect": "https://pay1.comgate.cz/init?id=XXXX-XXXX-XXXX"
}
ParametrTypPopis
codeStav založení platby
messageStringZpráva popisující návratový stav.
transIdStringId založené platby.
redirectStringURL pro přesměrování na platební bránu.
V rámci této implementace se nepoužívá.

2. 3DS SDK: Inicializace​

Jakmile je platba úspěšně založena a máme k dispozici hodnotu transId, můžeme přistoupit k inicializaci knihovny 3DS SDK. Tento krok slouží k získání parametrů potřebných pro vytvoření transakce na straně ACS (Access Control Server).

Získané hodnoty budou následně využity v kroku 3 při založení nového pokusu o platbu.

V této části dokumentace si ukážeme, jak vytvořit instanci knihovny 3DS SDK a jak správně použít následující metody:

  • initialize(),
  • createTransaction(),
  • getAuthenticationRequestParameters().

Podrobný popis těchto metod je uveden v dokumentaci 3DS SDK.

Inicializace​

V části kódu, kde implementujete zpracování platby, je potřeba vytvořit instanci třídy ThreeDS2Service a nad ní zavolat metodu initialize(). Tím dojde k inicializaci knihovny 3DS SDK a nastavení všech parametrů potřebných pro následující proces autentizace platby.

Metoda initialize() přijímá 4 parametry:

  • context – Kontext aplikace, typicky získaný pomocí getApplicationContext().
  • configParameters – Konfigurační parametry pro SDK. Obvykle se předává prázdná instance třídy ConfigParameters.
  • locale – Vždy nastavte na null.
  • uiCustomization – Pokud není potřeba měnit vzhled 3DS stránky, použijte hodnotu null. V případě přizpůsobení vzhledu lze předat instanci třídy UICustomization s vlastní konfigurací podle specifikace SDK.

Vytvoření transakce​

Po úspěšné inicializaci knihovny 3DS SDK je potřeba vytvořit 3DS transakci. Tím vznikne instance třídy Transaction, která reprezentuje konkrétní autentizační pokus.

Transakce se vytváří voláním metody createTransaction() na instanci třídy ThreeDS2Service.

Metoda createTransaction() přijímá 2 parametry:

  • directoryServerID – Identifikátor directory serveru příslušné karetní asociace v závislosti na zvolené platební kartě.
  • messageVersion – Vždy použijte hodnotu "2.2.0".
Identifikátor directory serveru​

Apple Pay a Google Pay neposkytují přímý přístup k údajům o platební kartě. Informace o karetní asociaci autorizované karty je však součástí dat vrácených spolu s platebním tokenem a je k dispozici pro další zpracování platby.

ℹ️ Více informací naleznete v dokumentaci popisující implementaci Apple Pay a Google Pay do mobilní aplikace.

Hodnotu directoryServerID získáte podle následující tabulky:

AsociaceDirectory Server ID
VisaA000000003
MastercardA000000004

Získání autentizačních parametretrů​

Jakmile máte vytvořenou instanci Transaction, již nic nebrání získání potřebných autentizačních dat. Stačí zavolat metodu getAuthenticationRequestParameters() na objektu transakce.

Tato metoda vrací instanci třídy AuthenticationRequestParameters, která obsahuje všechny potřebné hodnoty vhodné pro odeslání na API Comgate. Tyto údaje se následně využijí k sestavení autentizačního požadavku v dalším kroku zpracování platby.

Tip

Instanci AuthenticationRequestParameters si uložte pro další použití v kroku 3.

Příklad implementace​

// java
import android.content.Context;
import com.visiona.threedsecure.sdk.android.ThreeDS2ServiceImpl;
import com.visiona.threedsecure.sdk.android.emvco.ConfigParameters;
import com.visiona.threedsecure.sdk.android.emvco.Transaction;
import com.visiona.threedsecure.sdk.android.emvco.AuthenticationRequestParameters;

Context applicationContext = getApplicationContext();
ConfigParameters configParameters = new ConfigParameters();

ThreeDS2Service threeDS2Service = new ThreeDS2ServiceImpl();
threeDS2Service.initialize(applicationContext, configParameters, null, null);

// Visa: A000000003 | Mastercard: A000000004
Transaction transaction = threeDS2Service.createTransaction("A000000003", "2.2.0");

AuthenticationRequestParameters aReq = transaction.getAuthenticationRequestParameters();

3. Zpracování pokusu o platbu​

Zpracování "platby" je v pozadí rozděleno do tří jednotlivých fází:

  • založení pokusu o platbu v systému Comgate,
  • založení transakce u procesora a karetní asociace,
  • a spuštění zpracování platby.

Pro maximální zjednodušení celé integrace je tato logika sloučena do jediného API requestu. Veškerou následnou komunikaci obstará backend platební brány Comgate.

Ještě před detailním popisem tohoto kroku je vhodné stručně se seznámit s pojmy platba ⨯ pokus o platbu, které hrají klíčovou roli ve struktuře celé transakce, a dále se stavy platby a stavy pokusu o platbu – tedy s tím, jak jednotlivé stavy interpretovat a jak na jejich základě správně postupovat.

Struktura platby​

V rámci platebního systému Comgate je platba hlavním objektem, který nese základní informace – například částku, měnu a referenční identifikátor merchanta (refId). Nad jednou platbou může proběhnout více pokusů o platbu. Každý pokus o platbu má své vlastní unikátní ID a samostatný stav (např. úspěšný, neúspěšný, čekající).

ℹ️ Více informací o stavech plateb je dostupné níže.

Platba je v systému Comgate identifikována alfanumerickým kódem ve formátu XXXX-XXXX-XXXX (např. AQMF-NEES-9BAG), zatímco každý jednotlivý pokus o platbu má svůj vlastní číselný identifikátor, který je reprezentován jako typ , tedy celé číslo (např. 205483406).

Pokud jeden z pokusů o platbu selže, je možné provést další. Každý nový pokus o platbu je zaznamenán samostatně a nezávisle na předchozích. Jakmile je alespoň jeden z pokusů úspěšný, je celá platba považována za úspěšnou.

Naopak, pokud všechny založené pokusy o platbu selžou, neznamená to, že platba jako celek skončila neúspěšně. Platba přechází do stavu neúspěšná až ve chvíli, kdy uplyne časový limit stanovený pro její úhradu, nebo pokud je zrušena ze strany obchodníka či plátce.

Tip

V rámci mobilní aplikace nemá plátce standardní možnost platbu zrušit, pokud mu obchodník sám neposkytne odpovídající rozhraní – například implementací vlastního tlačítka, které volá endpoint /cancel.

Možnost zrušení platby ze strany plátce je za běžných okolností dostupná pouze v uživatelském rozhraní platební brány Comgate nebo prostřednictvím odkazu v e-mailu zaslaném systémem Comgate.

Pro lepší přehled uvádíme schéma znázorňující vztah mezi platbou a pokusy o platbu:

ER diagramER diagram

Vysvětlení: Jedna platba má žádný, jeden nebo více pokusů o platbu. Jeden pokus o platbu má právně jednu platbu.

Diagram je vytvořen v ER notaci Crow's Foot. Více informací o této notaci se můžete dočíst na portálu Medium nebo Vertabelo.

Správné použití platby a pokusu o platby​

Jak již bylo uvedeno výše, po nezdařené úhradě není nutné zakládat novou platbu. Díky navržené struktuře systému lze intuitivně provádět více pokusů o úhradu v rámci jedné platby, čímž se zachovává maximální přehlednost a kontinuita celého procesu.

Každému plátci lze vytvořit platbu s platností od 30 minut do 7 dnů. Doporučujeme udržet aktivní jednu platbu co nejdéle a nabízet pouze další pokusy o její úhradu. Novou platbu zakládejte pouze v případě, že žádná předchozí již není dostupná pro další pokus.

ℹ️ Více informací o expiraci platby se dozvítete v článku Expirace platby.

Stav platby a pokusu o platbu​

Důležitým aspektem při zpracování platby jsou jednotlivé stavy, které mohou během platby nastat. Tyto stavy slouží k vyhodnocení výsledku platby a určují, jaké další kroky je nutné podniknout.

Standardně API Comgate pracuje se stavem celé platby. V rámci nativní implementace však bylo zpřístupněno dosud interní chování platebního systému a funkcionalita byla rozšířena o zobrazení stavů i pro tzv. pokusy o platbu. Každý pokus má svůj vlastní stav, který je oddělený od stavu celé platby a umožňuje detailnější řízení a kontrolu nad průběhem celého procesu.

Tip

Je důležité si uvědomit, že některé stavy pokusu o platbu mají přímý vliv na výsledek celé platby, zatímco jiné ji neovlivňují a umožňují pokračování dalším pokusem.

ℹ️ Více informací o stavech platby a doporučeném postupu v jednotlivých situacích najdete v článku Stav platby.

Request na zpracování pokusu​

Jak již bylo zmíněno výše, platební brána Comgate v rámci jediného requestu automaticky provede celou sadu potřebných operací. Není tedy nutné jednotlivé kroky volat samostatně, jak tomu bývá u některých jiných řešení.

Comgate naváže komunikaci s Directory servery karetních asociací a ověří, zda je možné platbu provést. Pokud je vše v pořádku, dojde k registraci nové transakce a zároveň k zahájení autentizace držitele karty prostřednictvím procesu 3D Secure.

Při volání API jsou odesílány informace o platebním tokenu, detailech o transakci a iniciační parametry pro 3DS SDK.

Pro všechny requesty začínající /checkout/* je mimo parametru transId, také potřeba hodnotu checkoutId. Aktivace funkcionality Checkout a získání identifikátoru bylo popsáno v článku Checkout.

Upozornění

Pokud používáte více propojení obchodu, každé z nich má vlastní hodnotu checkoutId. Systém kontroluje a striktně vyžaduje, aby použité checkoutId odpovídalo propojení, přes které byla daná platba (transId) založena.

Request payment-prepare-init-process​

  • Metoda: POST
  • URL: https://payments.comgate.cz/checkout/provider/payment-prepare-init-process
  • Content-Type: application/json
  • Autentizace: pouze pomocí dvojice transId a checkoutId
JSON body
{
  "transId":"XXXX-XXXX-XXXX",
  "checkoutId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "service":"COMGATE_APPLEPAY",       // COMGATE_APPLEPAY ⨯ COMGATE_GOOGLEPAY
  "payload": "xxxxxxxxxxxxxxxxxxxxxx",
  "isNative": true,
  "isInEshop": true,
  "paymentDetails": {                 // hodnoty získané z Apple Pay nebo Google Pay
    "displayName": "Visa •••• 1234",  // Visa •••• 1234
    "network": "visa",                // visa / mastercard
    "cardType": 1                     // 0 - 5
  },
  "3dsData": {                        // hodnoty získané z 3DS SDK (krok 2)
    "SDKTransactionID": "...",
    "DeviceData": "...",
    "SDKEphemeralPublicKey": "...",
    "SDKAppID": "...",
    "SDKReferenceNumber": "...",
    "MessageVersion": "..."
  }
}
Popis parametrů​
ParametrTypPovinnýPopis
transIdStringAnoIdentifikátor platby získaný při jejím založení.
checkoutIdStringAnoIdentifikátor checkout modulu. Více informací v sekci Checkout.
serviceStringAnoUrčuje poskytovatele a metodu platby. Možné hodnoty:
  • "COMGATE_APPLEPAY"
  • "COMGATE_GOOGLEPAY"
payloadStringAnoPlatební token získaný z Apple Pay nebo Google Pay, zakódovaný pomocí Base64.
isNativeAnoHodnota jse vždy true. Slouží k identifikací správného chování.
isInEshopAnoHodnota jse vždy true. Slouží k identifikací správného chování.
paymentDetails - více informací v sekcích Apple Pay a Google Pay
  displayNameStringAnoPopis karty od AP nebo GP, např. "Visa •••• 1234".
  networkStringAnoCase-insensitive název asociace použité karty pro autorizaci platby (např. VISA, MASTERCARD).
  cardType NeTyp karty. U Apple Pay může být číselná hodnota, u Google Pay typicky "CARD".
3dsData - více informací v sekci Získání autentizačních parametrů
  SDKTransactionIDStringAnoHodnota z intance objektu AuthenticationRequestParameters.
  DeviceData
  SDKEphemeralPublicKey
  SDKAppID
  SDKReferenceNumber
  MessageVersion
Příklad pomocí curl
curl --request POST \
  --url https://payments.comgate.cz/checkout/provider/payment-prepare-init \
  --header 'Content-Type: application/json' \
  --data '{
  "transId":"XXXX-XXXX-XXXX",
  "checkoutId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "service":"COMGATE_APPLEPAY",
  "payload": "dG9rZW4gb2QgZ29vZ2xlIHBheSBuZWJvIGFwcGxlIHBheQ==",
  "isNative": true,
  "isInEshop": true,
  "paymentDetails": {
    "displayName": "Visa •••• 1234",
    "network": "visa",
    "cardType": 1
  },
  "3dsData": {
    "SDKTransactionID": "...",
    "DeviceData": "...",
    "SDKEphemeralPublicKey": "...",
    "SDKAppID": "...",
    "SDKReferenceNumber": "...",
    "MessageVersion": "..."
  }
}'

Po úspěšném vytvoření pokusu o platbu vrátí API odpověď ve formátu JSON, která obsahuje identifikaci pokusu. Úspěšnost požadavku je možné ověřit pomocí HTTP status kódu 200 a hodnoty klíče success, který musí být true.

Důležité je také uložit si hodnotu subpaymentId, která představuje unikátní identifikátor pokusu o platbu a bude potřeba v následujících krocích.

Tip

API může vracet i další parametry, které se vztahují k jiným typům integrace. Pokud nejsou v této dokumentaci popsány, považujte je za irelevantní.

Příklad - úspěšné založení pokusu o platbu:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "subpaymentId": 123456789,
  "status": "PENDING",
  "statusSubpayment": "PENDING",
  "3dsResponse": {
    "transStatus": "...",
    "acsTransactionID": "...",
    "acsReferenceNumber": "...",
    "acsSignedContent": "...",
    "authenticationValue": "...",
    "eci": "...",
  }
}
ParametrTypPopis
successIndikace jestli server považuje dotaz za úspěšný
subpaymentIdID pokusu o platbu
statusStringStav celé platby. Více viz stavy plateb.
statusSubpaymentStringStav pokusu o platbu. Více viz stavy pokusu.
3dsResponse - data potřebná pro 3DS SDK
   transStatusStringParametry budou popsány v sekci 4. TODO
   acsTransactionIDString
   acsReferenceNumberString
   acsSignedContentString
   authenticationValueString
   eciString

Důležité je uložit si hodnoty objektu 3dsResponse, které obsahují konfigurační data potřebná pro další zpracování pomocí 3DS SDK. Jejich použití bude popsáno v následujícím kroku 4.

Odpověď zároveň obsahuje aktuální stavy platby a pokusu o platbu, které již v této fázi mohou být rozhodující pro další zpracování a logiku vaší aplikace.

4. 3D secure: Zpracování challenge​

// TODO - textace - doplnit

Upozornění

TODO

5. Stav zpracování platby​

Po zahájení zpracování pokusu o platbu je třeba průběžně ověřovat jeho stav. Zpracování může trvat různě dlouho, zejména pokud je vyžadována interakce plátce prostřednictvím 3D Secure challenge.

Z tohoto důvodu je nutné implementovat tzv. short polling – pravidelné dotazování na API Comgate k získání aktuálního stavu zpracování pokusu o platbu.

Doba čekání na výsledek​

Doporučená celková doba čekání na výsledek platby závisí na výsledku předchozího kroku 3DS autentizace, konkrétně na hodnotě transStatus:

transStatusScénářDoporučený timeoutPoznámka
"Y"Frictionless flow (bez interakce plátce)3 minutyOdpověď bývá dostupná výrazně dříve.
3 minuty představují maximální dobu v extrémních případech.
"C"Challenge flow (s interakcí plátce)10 minutOdpověď závisí na rychlosti plátce, za jak dlouho se mu podaří vyřešit challenge.
"N"Transakce byla zamítnuta-Transakce byla na úrovni 3DS zamítnuta.
Další kontrola není nutná.
Tip

Mezinárodní standard EMVCo striktně doporučuje, aby byl pro scénáře s autentizační výzvou (challenge) nastaven timeout minimálně 5 minut. Tento časový rámec zohledňuje běžné chování uživatelů, například zpoždění způsobené přepínáním aplikací nebo prodlevy při potvrzování identity.

Interval opakování​

Při dotazování na stav pokusu o platbu vrací Comgate API v každé odpovědi objekt polling. Ten obsahuje dvě klíčové informace:

  • allowed – zda je vůbec vhodné pokračovat v opakovaném dotazování,
  • interval – jaký je doporučený časový odstup do dalšího dotazu (v milisekundách, např. 2000 = 2 sekundy).

Tyto hodnoty je nutné vždy zohlednit, protože se mohou dynamicky měnit v závislosti na stavu platby nebo aktuálním zatížení infrastruktury. Cílem je optimalizovat rychlost odezvy a současně minimalizovat zátěž systému.

Pokud se rozhodnete použít pevný interval, doporučujeme začít s hodnotou 5 sekund a po uplynutí jedné minuty prodloužit interval na 10 sekund.

Zároveň doporučujeme nastavit dolní bezpečnostní hranici: interval by nikdy neměl být kratší než 2 sekundy.

V případě mimořádné situace (např. výpadek připojení, neúplná nebo chybová odpověď) doporučujeme před opakováním požadavku vyčkat alespoň 2 sekundy. Tím se snižuje riziko opakovaných chyb a zahlcení komunikace.

Ukázka struktury objektu polling:

{
  "allowed": true, // je možné dotaz na stav opakovat
  "interval": 3000 // počet milisekund do dalšího dotazu
}
Upozornění

Vaše aplikace by měla při opakovaném dotazování vždy respektovat hodnoty vrácené v objektu polling. V opačném případě může Comgate detekovat nadměrnou zátěž a prostřednictvím mechanismu rate-limiting dočasně zablokovat další požadavky z daného zařízení nebo IP adresy.

Request na stav​

Při volání API pro získání stavu pokusu o platbu jsou odesílány pouze základní parametry.

Nebezpečí

Ačkoliv API pro dotazování na stav platby a pokusu o platbu vrací průběžné informace, nelze tyto údaje považovat za rozhodující. Pro bezpečné a finální ověření stavu platby je nezbytné provést ověřovací request, který je popsán v kroku 6.

Request payment-status​

  • Metoda: POST
  • URL: https://payments.comgate.cz/checkout/provider/payment-status
  • Content-Type: application/json
  • Autentizace: pouze pomocí trojice transId, checkoutId a subpaymentId
JSON body
{
  "transId": "XXXX-XXXX-XXXX",
  "checkoutId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "subpaymentId": 123456789,
  "service": "COMGATE_APPLEPAY"   // COMGATE_APPLEPAY ⨯ COMGATE_GOOGLEPAY
}
Popis parametrů​
ParametrTypPovinnýPopis
transIdStringAnoIdentifikátor platby získaný při jejím založení.
checkoutIdStringAnoIdentifikátor checkout modulu. Více informací v sekci Checkout.
subpaymentIdAnoID pokusu o platbu získané při zahájení zpracování.
serviceStringAnoUrčuje poskytovatele a metodu platby. Možné hodnoty:
  • "COMGATE_APPLEPAY"
  • "COMGATE_GOOGLEPAY"
Příklad pomocí curl
curl --request POST \
--url https://payments.comgate.cz/checkout/provider/payment-status \
--header 'Content-Type: application/json' \
--data '{
"transId":"XXXX-XXXX-XXXX",
"checkoutId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"service":"COMGATE_APPLEPAY",
"platbaPlatcePk":123456789
}'

Po úspěšném získání stavu pokusu o platbu vrátí API odpověď ve formátu JSON, která obsahuje veškeré potřebné údaje. Úspěšnost požadavku je možné ověřit pomocí HTTP status kódu 200 a hodnoty klíče success, který musí být true.

Tip

API může vracet i další parametry, které se vztahují k jiným typům integrace. Pokud nejsou v této dokumentaci popsány, považujte je za irelevantní.

Příklad - úspěšné získání stavu pokusu o platbu:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
    "subpaymentId": 207555807,
    "polling": {
        "allowed": true, // je možné dotaz na stav opakovat
        "interval": 3000 // počet milisekund do dalšího dotazu
    },
    "status": "PENDING", // stav platby
    "statusSubpayment": "CANCELLED", // stav pokusu o platbu
    "paymentErrorReason": "ACS_TIMEOUT"
}
ParametrTypPopis
successIndikace jestli server považuje dotaz za úspěšný
subpaymentIdID pokusu o platbu
polling.allowedInformace, zda je vhodné pokračovat v opakovaném dotazování.
polling.intervalDoporučený časový odstup do dalšího dotazu.
statusStringStav celé platby. Více viz stavy plateb.
statusSubpaymentStringStav pokusu o platbu. Více viz stavy pokusu.
paymentErrorReasonStringKód důvodu zamítnutí pokusu o platbu. paymentErrorReason slouží k identifikaci konkrétní příčiny neúspěchu — například nedostatek prostředků, zamítnutí 3DS autentizace nebo technická chyba při zpracování. Používá se primárně pro logování, analytiku a případné zobrazení chybového hlášení uživateli.

6. Ověření stavu platby​

Comgate poskytuje mechanismy, které umožňují bezpečně ověřit finální stav platby. Bez provedení tohoto ověření nelze ze strany Comgate garantovat, že je platba skutečně dokončena a prostředky byly úspěšně strženy. Důvodem pro tuto skutečnost jsou různé transakční mechanizmy.

Upozornění

Během zpracování platby dochází k řadě interních asynchronních operací a synchronizačních mechanismů. V okamžiku, kdy je stav platby dotazován prostřednictvím endpointu /payment-status, ještě nemusí být plně potvrzený.

Skutečný a zaručený výsledek platby lze získat pouze prostřednictvím referenčního Merchant API, které vrací finální stav po úplném dokončení veškerého zpracování.

Push notifikace​

Automatizované předání informace o změně stavu platby ze strany Comgate probíhá prostřednictvím webhooku, označovaného jako Push notifikace. Tato notifikace je odesílána na URL, kterou si obchodník předem nastaví, a slouží jako spolehlivý způsob, jak informovat o změně stavu platby v reálném čase a bez zbytečných prodlev.

Upozornění

Skutečný stav platby je doporučeno vždy ověřit prostřednictvím volání API metody /2.0/status. Toto dodatečné ověření slouží jako nadstandardní bezpečnostní opatření, které je klíčové zejména v případech, kdy by mohlo dojít k podvržení push notifikace — například v důsledku odcizení autentizačních údajů.

Pro zajištění integrity celého procesu je tedy vhodné stav platby nikdy nevyhodnocovat pouze na základě příchozí notifikace, ale vždy jej ověřit i na straně Comgate.

ℹ️ Více informací o push notifikaci naleznete ve specializovaném článku.

Ověření stavu​

Jak již bylo zmíněno výše v části popisující Push notifikaci, skutečný stav platby je doporučeno vždy ověřit prostřednictvím volání API metody /2.0/status.

Toto dodatečné ověření slouží jako nadstandardní bezpečnostní opatření, které je zásadní zejména v případech, kdy by mohlo dojít k podvržení push notifikace — například v důsledku kompromitace autentizačních údajů (merchant a secret).

ℹ️ Kompletní popis endpointu /2.0/status naleznete v REST dokumentaci.

Changelog​

Datum aktualizaceZměny
2025-05-27 9:10
  • Přejmenován parameter subpayment na subpaymentId
  • Přidán popis pro ověření stavu plathy
2025-05-25 23:00
  • Přidán popis pro EP /payment-status
  • Updaven popis stavů platby a pokusu o platbu
  • Rozšířena struktura API parametrů

Dobrý den, Jiří, naprosto vám rozumím. Naše brána se v tuto chvíli chová tak, že když nastane jakákoliv chyba v procesu zpracování (payment-prepare-init-process), tak placení považuje za neúspěšné. Když nastane chyba při dotazování na status, zkoušíme to Konstatovat mohu, že přes dodané API běží každý den desítky tisíc transakcí pro implementaci Google Pay a Apple Pay na naší platební bráně a chyb tento proces vykazuje naprosté minimum.

Předám dotaz na kolegy. O tomto API příliš nevím. Standardně identifikaci karty vracíme jako prvních 10 znaků čísla karty.