Dynamická částka

Funkce dynamická částka umožňuje změnit částku již založené platby bez nutnosti vytvářet platbu novou. Slouží především v situacích, kdy se po inicializaci platby ještě v košíku změní obsah objednávky (např. přidání položky, sleva, změna dopravy) a e-shop chce zabránit kompletnímu přenačtení stránky a opětovnému zakládání platby.

Po úspěšné změně částky na straně API je nutné v prohlížeči zavolat metodu changePayment(), která přenačte platbu v běžící instanci Core a aktualizuje zobrazené informace ve funkčních modulech (např. Apple Pay, Google Pay).

Upozornění

Funkce není ve výchozím stavu aktivní. Aby ji bylo možné použít, je nutné na straně Comgate povolit příznak dynamické částky pro konkrétní propojení obchodu. Aktivaci zajišťuje obchodní oddělení Comgate.

Poznámka

Dynamickou částku lze měnit pouze u plateb ve stavu REQUESTED (tedy dokud plátce neodeslal platbu ke zpracování).

Průběh změny částky

1. E-shop (backend) zavolá Comgate REST API endpoint /v1.0/changePrice se server-to-server requestem.
2. Comgate ověří oprávnění, stav platby a limity. Při úspěchu vrátí code=0.
3. E-shop (frontend) zavolá v běžící instanci Core metodu changePayment(transactionId), čímž se v Checkoutu projeví nová částka.

ℹ️ Volání /v1.0/changePrice musí být provedeno ze serveru e-shopu, nikoli z prohlížeče — obsahuje citlivý parametr secret.

API endpoint /v1.0/changePrice

Atribut	Hodnota
Metoda	POST
URL	https://payments.comgate.cz/v1.0/changePrice
Content-Type	application/x-www-form-urlencoded

Parametry požadavku

Parametr	Typ	Povinný	Popis
merchant	string	Ano	Identifikátor obchodníka v systému Comgate.
secret	string	Ano	Heslo k API přidělené při zřízení napojení.
transId	string	Ano	Identifikátor existující platby ve formátu XXXX-XXXX-XXXX.
newPrice	int	Ano	Nová částka v nejmenší jednotce měny (např. v haléřích pro CZK, centech pro EUR). Musí být kladná.

Omezení částky

• newPrice musí být kladné celé číslo.
• Pro měnu HUF musí částka vždy končit dvěma nulami (00) — HUF nepodporuje desetinná místa.

Odpověď

Tělo odpovědi je v application/x-www-form-urlencoded formátu.

Úspěch

code=0&message=OK

Chyba

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

Nejčastější chybové stavy

code	HTTP	Význam
0	200	Změna proběhla úspěšně.
1100	418	Neznámá 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á aktivace Comgate.
1400	403	Payment is not in REQUESTED state. — částku lze měnit jen u nezaplacené platby.
1400	403	The price is above the maximum limit! — částka překračuje limit.
1400	403	Amount X CUR is not supported by any available payment method.

Ukázka implementace

Volání API ze serveru e-shopu (jednoduchý cURL příklad v PHP) a následné přenačtení Checkoutu v prohlížeč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, // např. 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 prohlížeči pokyn k zavolání changePayment(transId)
}

JavaScript — frontend

// Po úspěšné odpovědi backendu zavoláme changePayment v běžící instanci Core.
instanceCore.changePayment('XXXX-XXXX-XXXX')
  .then(() => {
    console.log('Checkout přenačten s novou částkou.');
  })
  .catch((error) => {
    console.error('Nepodařilo se přenačíst Checkout:', error);
  });