Rychlý start

Tento průvodce vás provede vytvořením a dokončením testovací platby pomocí API Cost+. Na konci budete mít fungující integraci, na které můžete dále stavět.

Předpoklady

Účet Cost+ se sandbox webem — vytvořte si ho v obchodním portálu
Váš sandbox API klíč (najdete v sekci Weby → váš sandbox web → Integrace)

Nevíte, jak získat API klíč? Podívejte se na stránku Testování integrace, kde najdete podrobné pokyny k nastavení.

Krok 1: Vytvoření objednávky

Odešlete POST požadavek pro vytvoření platební objednávky. Nahraďte YOUR_API_KEY vaším sandbox API klíčem:

Create an order

curl -X POST https://api.costplus.online/v1/orders/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 1295,
    "merchant_order_id": "my-first-order",
    "description": "Test order",
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook",
    "transactions": [
      {
        "payment_method": "credit-card"
      }
    ]
  }'

Hodnota amount je v nejmenší měnové jednotce (centy). 1295 znamená 12,95 EUR.

API vrátí kompletní objekt objednávky. Klíčová pole jsou id, status a payment_url uvnitř transakce:

Response

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "description": "Test order",
  "return_url": "https://example.com/return",
  "webhook_url": "https://example.com/webhook",
  "created": "2026-01-15T12:00:05.433502+00:00",
  "modified": "2026-01-15T12:00:05.553125+00:00",
  "expiration_period": "PT1H",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "amount": 1295,
      "currency": "EUR",
      "payment_url": "https://pay.costplus.online/4851e31c.../credit-card/d291f03f...",
      "is_capturable": false,
      "expiration_period": "PT30M"
    }
  ]
}

Uložte si id — budete ho potřebovat v kroku 3.

Krok 2: Dokončení testovací platby

Otevřete payment_url z odpovědi ve svém prohlížeči
Na platební stránce zadejte testovací údaje karty:

Pole	Hodnota
Číslo karty	`4111 1111 1111 1111`
Platnost	Jakékoli budoucí datum (např. `12/28`)
CVC	Jakékoli 3 číslice (např. `123`)

Odešlete platbu
Budete přesměrováni zpět na vaši return_url

Nespoléhejte pouze na přesměrování jako potvrzení platby. Zákazník může zavřít prohlížeč dříve, než dojde k přesměrování. Vždy ověřte stav prostřednictvím API (krok 3) nebo webhooků (krok 4).

Krok 3: Ověření platby

Načtěte objednávku pro potvrzení, že byla dokončena:

Check order status

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/

Úspěšná platba vypadá takto:

Response (completed)

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "completed": "2026-01-15T12:02:30.123456+00:00",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "completed",
      "amount": 1295,
      "currency": "EUR",
      "payment_method_details": {
        "truncated_pan": "1111",
        "card_expiry": "122028"
      }
    }
  ]
}

Stav objednávky status je "completed" — platba byla úspěšná.

Krok 4: Zpracování webhooku (doporučeno)

Když se změní stav platby, Cost+ odešle POST požadavek na vaši webhook_url:

Webhook payload

{
  "event": "status_changed",
  "order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}

Když obdržíte tuto notifikaci:

Zavolejte GET /v1/orders/{order_id}/ pro ověření aktuálního stavu (nikdy nevěřte samotné webhookové zprávě)
Vraťte HTTP 200 jako potvrzení přijetí
Vyřiďte objednávku, pokud je stav "completed"

Pro lokální vývoj použijte tunel jako ngrok k vystavení vašeho lokálního serveru pro příjem webhooků.

Podívejte se na průvodce Webhooky, kde najdete informace o logice opakování, osvědčených postupech a detailech payloadu.

Alternativa: Platební odkazy

Pokud nepotřebujete logiku přesměrování na straně serveru, platební odkazy nabízejí jednodušší cestu. Vytvořte odkaz, sdílejte URL se zákazníkem a stav zkontrolujte později.

Create a payment link

curl -X POST https://api.costplus.online/v1/paymentlinks/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "invoice-1234",
    "amount": 2500,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

Odpověď obsahuje payment_url, kterou můžete sdílet e-mailem, SMS nebo chatem. Zákazník může opakovat platbu až 25krát, dokud odkaz nevyprší nebo platba neproběhne úspěšně.

Podívejte se na průvodce Platební odkazy pro kompletní postup.

Co dál?

Dokončili jste svou první platbu. Zde jsou další kroky:

Hostovaná platební stránka — kompletní reference HPP se všemi poli požadavku a možnostmi
Opakované platby — nastavení předplatného a plánovaného fakturování
Platby jedním kliknutím — rychlý checkout pro vracející se zákazníky
Autorizace / Zachycení / Zrušení — nejprve autorizujte, zachyťte později (např. při odesílání)
Vrácení plateb — zpracování úplných a částečných refundací
SDK — oficiální knihovny pro Node.js, Python, PHP, Java/Kotlin, C#/.NET a Ruby
Pluginy — předpřipravené integrace pro Shopify, WooCommerce, Magento a další

Související endpointy

Vytvoření objednávky — kompletní API reference pro vytvoření objednávky
Získání objednávky — získání detailů a stavu objednávky
Vytvoření platebního odkazu — vytvoření znovupoužitelných platebních odkazů

On this page