Dynamická suma

Funkcia dynamická suma umožňuje zmeniť sumu už založenej platby bez nutnosti vytvárať platbu novú. Slúži predovšetkým v situáciách, keď sa po inicializácii platby ešte v košíku zmení obsah objednávky (napr. pridanie položky, zľava, zmena dopravy) a e-shop chce zabrániť kompletnému opätovnému načítaniu stránky a opätovnému zakladaniu platby.

Po úspešnej zmene sumy na strane API je potrebné v prehliadači zavolať metódu changePayment(), ktorá prenačíta platbu v bežiacej inštancii Core a aktualizuje zobrazené informácie vo funkčných moduloch (napr. Apple Pay, Google Pay).

Upozornenie

Funkcia nie je vo predvolenom stave aktívna. Aby ju bolo možné použiť, je potrebné na strane Comgate povoliť príznak dynamickej sumy pre konkrétne prepojenie obchodu. Aktiváciu zaisťuje obchodné oddelenie Comgate.

Poznámka

Dynamickú sumu možno meniť iba u platieb v stave REQUESTED (teda dokým platiteľ neodoslal platbu na spracovanie).

Priebeh zmeny sumy

1. E-shop (backend) zavolá Comgate REST API endpoint /v1.0/changePrice so server-to-server requestom.
2. Comgate overí oprávnenie, stav platby a limity. Pri úspechu vráti code=0.
3. E-shop (frontend) zavolá v bežiacej inštancii Core metódu changePayment(transactionId), čím sa v Checkoute prejaví nová suma.

ℹ️ Volanie /v1.0/changePrice musí byť vykonané zo servera e-shopu, nie z prehliadača — obsahuje citlivý parameter secret.

API endpoint /v1.0/changePrice

Atribút	Hodnota
Metóda	POST
URL	https://payments.comgate.cz/v1.0/changePrice
Content-Type	application/x-www-form-urlencoded

Parametre požiadavky

Parameter	Typ	Povinný	Popis
merchant	string	Áno	Identifikátor obchodníka v systéme Comgate.
secret	string	Áno	Heslo k API pridelené pri zriadení napojenia.
transId	string	Áno	Identifikátor existujúcej platby vo formáte XXXX-XXXX-XXXX.
newPrice	int	Áno	Nová suma v najmenšej jednotke meny (napr. v halieroch pre CZK, centoch pre EUR). Musí byť kladná.

Obmedzenie sumy

• newPrice musí byť kladné celé číslo.
• Pre menu HUF musí suma vždy končiť dvomi nulami (00) — HUF nepodporuje desatinné miesta.

Odpoveď

Telo odpovede je v application/x-www-form-urlencoded formáte.

Úspech

code=0&message=OK

Chyba

code=1400&message=Payment+is+not+in+REQUESTED+state.+Price+can+only+be+changed+for+REQUESTED+payments.

Najčastejšie chybové stavy

code	HTTP	Význam
0	200	Zmena prebehla úspešne.
1100	418	Neznáma chyba.
1400	400	Transaction not found — transId neexistuje.
1400	403	Web Checkout SDK is not enabled for this shop connection.
1400	403	Dynamic price change is not enabled for this shop connection. — nutná aktivácia Comgate.
1400	403	Payment is not in REQUESTED state. — sumu možno meniť iba u nezaplatenej platby.
1400	403	The price is above the maximum limit! — suma prekračuje limit.
1400	403	Amount X CUR is not supported by any available payment method.

Ukážka implementácie

Volanie API zo servera e-shopu (jednoduchý cURL príklad v PHP) a následné opätovné načítanie Checkoutu v prehliadači:

PHP — backend

<?php
$ch = curl_init('https://payments.comgate.cz/v1.0/changePrice');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'merchant' => $merchantId,
    'secret'   => $secret,
    'transId'  => $transId,
    'newPrice' => $newPriceInHellers, // napr. 12500 = 125,00 Kč
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$body = curl_exec($ch);
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

parse_str($body, $response);
if (($response['code'] ?? null) === '0') {
    // OK — pošli prehliadaču pokyn na zavolanie changePayment(transId)
}

JavaScript — frontend

// Po úspešnej odpovedi backendu zavoláme changePayment v bežiacej inštancii Core.
instanceCore.changePayment('XXXX-XXXX-XXXX')
  .then(() => {
    console.log('Checkout prenačítaný s novou sumou.');
  })
  .catch((error) => {
    console.error('Nepodarilo sa prenačítať Checkout:', error);
  });