Vývojáři

Tři volání a webhook.

Gateway je hostovaný checkout, takže integrace je záměrně malá: vytvoříte objednávku, pošlete zákazníka na stránku a ověříte podepsaný výsledek. Vše níže je celé rozhraní, se kterým přijdete do styku. Platební UI, logiku metod, 3-D Secure, peněženky i účtenky tvoříme a udržujeme my.

Požádat o přístup do sandboxu Vyzkoušejte checkout

Jak to vypadá

S čím se integrujete.

REST přes HTTPS
JSON na vstupu i výstupu
API klíče typu Bearer
Idempotency klíče
Podepsané webhooky
Ochrana proti replay útokům
Testovací a produkční režim
SDK pro iOS a Android
Pluginy pro e-shopy
Vestavěná pole

Rychlý start

Od nuly k zaplacené objednávce.

Celá úspěšná cesta. Částky jsou v nejmenších jednotkách měny, reference jsou vaše a na checkout URL přesměrujete zákazníka. Základní URL API dostanete spolu se sandbox klíči. Exportujte ji jako PROTOCORE_API_BASE a níže uvedená volání poběží přesně tak, jak jsou napsaná.

Vytvoření objednávky

Jedno volání s částkou, měnou a vaší vlastní referencí. Idempotency klíč si generujete sami. Opakovaný požadavek vrátí původní objednávku a nevytvoří druhou.

POST /v1/orders

curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
  -H "Authorization: Bearer $PROTOCORE_API_KEY" \
  -H "Idempotency-Key: 9F21-0716" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 4900,
        "currency": "EUR",
        "reference": "9F21-0716",
        "line_items": [
          { "name": "Brand identity sprint", "amount": 3850 },
          { "name": "Typeface licensing",   "amount": 600 },
          { "name": "Rush delivery",        "amount": 400 }
        ],
        "return_url": "https://arcstudio.ro/thanks"
      }'

Přesměrování zákazníka na checkout

Odpověď obsahuje checkout URL na vašem vlastním checkout hostu, tedy tom, který jste dostali se sandboxem, nebo na vaší doméně, jakmile ji na nás nasměrujete. Přesměrujte zákazníka na ni nebo ji otevřete v SDK. Na té stránce žijí platební metody, peněženky i 3-D Secure, takže na vaší straně není co stavět.

201 Created

{
  "id": "ord_2h4Kq9wRz",
  "reference": "9F21-0716",
  "amount": 4900,
  "currency": "EUR",
  "status": "pending",
  "checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}

Ověření podepsaného výsledku

Po dokončení platby dorazí na váš endpoint podepsaná událost. Než čemukoli uvěříte, ověřte podpis pomocí webhook secretu a teprve pak objednávku vyřiďte podle reference, kterou už znáte.

POST /your/webhook — order.paid

{
  "type": "order.paid",
  "id": "evt_7Ka2Lm",
  "created": "2026-07-23T09:41:02Z",
  "data": {
    "id": "ord_2h4Kq9wRz",
    "reference": "9F21-0716",
    "amount": 4900,
    "currency": "EUR",
    "method": "usdc",
    "settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
  }
}

Reference

Endpointy, které opravdu použijete.

V dokumentaci toho najdete víc, ale tohle je sada, kterou většina integrací nikdy nepřeroste.

POST /v1/orders

Vytvoří objednávku a vrátí její checkout URL. Přijímá idempotency klíč.

GET /v1/orders/:id

Aktuální stav objednávky: status, metoda, vypořádání a refundace.

POST /v1/orders/:id/refunds

Refundace k objednávce, plná nebo částečná, s povinným důvodem.

POST /v1/orders/:id/void

Uvolní autorizaci před vypořádáním, takže se nepohnou žádné peníze.

POST /v1/links

Vytvoří platební odkaz, jednorázový nebo sběrný, s volitelnou expirací.

GET /v1/payouts/:id

Dávka vypořádání a objednávky, které ji financovaly, s rozpisem poplatků.

POST /v1/customers/:id/cards

Uloží kartu do vaultu pro platby jedním kliknutím a opakované platby. Vrátí referenci tokenu.

POST /v1/subscriptions

Strhává uloženou kartu podle plánu. Každý cyklus vytvoří vlastní objednávku.

Webhooky

O čem se dozví váš backend.

Každá událost nese referenci objednávky, kterou jste vytvořili, takže váš handler může být jen switch podle typu a vyhledání na vaší straně.

order.paid

Autorizace i capture proběhly. Vyřiďte objednávku podle reference.

order.failed

Platba se nedokončila, a to s důvodem, na který může operátor reagovat.

order.refunded

Byla vystavena refundace, plná nebo částečná, s důvodem a poznámkou.

order.disputed

Byl otevřen chargeback, důkazy jsou už přiložené k objednávce.

payout.settled

Dávka vypořádání odešla na váš účet, včetně seznamu objednávek, které za ní stojí.

subscription.charged

Opakovaný cyklus vytvořil vlastní objednávku a účtenku.

Ověření

Zkontrolujte podpis dřív, než uvěříte tělu.

Každé doručení nese časové razítko a HMAC podpis surového těla. Porovnávejte v konstantním čase, odmítejte vše starší, než je vaše tolerance, a duplicitní id události berte jako již zpracované. Při odpovědi jiné než 2xx zkoušíme znovu, takže i váš handler by měl být idempotentní.

Node — ověření podpisu

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
  const expected = createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(sig, "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false;

  // Reject replays outside a five-minute window.
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}

Záruky

Vlastnosti, na kterých můžete stavět.

Idempotentní vytváření

Každé vytvoření objednávky přijímá idempotency klíč. Opakovaný požadavek, ať po timeoutu, deployi nebo opětovném doručení z fronty, vrátí původní objednávku, místo aby strhl platbu dvakrát.

Podepsané události chráněné proti replay útokům

Webhooky nesou HMAC podpis s časovým razítkem a stabilní id události. Doručení se opakuje s backoffem, dokud váš endpoint neodpoví 2xx, takže okno deploye vás o platbu nepřipraví.

Jedna reference od začátku do konce

Reference, kterou zadáte při vytvoření, se objeví na checkoutu, účtence, webhooku, výplatě i u každé pozdější refundace. Nemusíte mapovat žádný druhý identifikátor mezi systémy.

Testovací režim běží stejným kódem

Testovací klíče spouští totožné toky nad testovacími relacemi. Co projde v testu, to půjde do ostrého provozu. Liší se jen klíče, které posíláte, ne endpointy, které voláte.

Vyzkoušejte checkout

Testovací data

Jak vyzkoušet cesty, na kterých záleží.

Ke každé cestě níže patří testovací karta. Najdete ji spolu s klíči, jakmile vám vystavíme sandbox. Čísla jsou pro každý sandbox jiná a nezveřejňujeme je zde, aby zůstala správná i při změnách testovacích rozsahů karetních schémat. Chování je v obou případech deterministické: test si stejně snadno ověří zamítnutí jako úspěch.

Schváleno rovnou

Autorizuje a zaúčtuje bez ověření 3-D Secure — ideální průchod bez komplikací.

Ověření 3-D Secure

Vynutí ověření, kterým můžete projít, a otestujete tak i návrat zpět do aplikace.

Měkké zamítnutí

Zamítne platbu pro nedostatek prostředků a poté ji zopakuje jinou cestou.

Tvrdé zamítnutí

Zamítne platbu natrvalo pro propadlou platnost karty, bez opakování.

Testovací sítě USDC

Testnet USDC na Ethereu, Base a Solaně za pevný kurz.

Simulace převodu

Označte testovací převod na vIBAN jako přijatý a objednávka přejde do stavu zaplaceno.

Získejte klíče a začněte.

Sandbox obchodník s API klíči, webhook secrety a všemi zapnutými metodami — plus kompletní reference, aby váš tým mohl integrovat dřív, než se cokoli podepíše.

Požádat o přístup do sandboxu contact@protocore.io