Cost+Docs

Rychly start

Prijmite svoju prvu platbu za 5 minut

Tento navod vas prevedie vytvorenim a dokoncenim testovacej platby pomocou Cost+ API. Na konci budete mat funkcnu integraciu, na ktorej mozete dalej stavat.

Predpoklady

  • Cost+ ucet so sandbox webovou strankou -- vytvorte si ho v obchodnom portali
  • Vas sandbox API kluc (najdete ho v casti Webove stranky -> vasa sandbox webova stranka -> Integracia)

Neviete, ako ziskat svoj API kluc? Pozrite si Testovanie integracie, kde najdete podrobne pokyny na nastavenie.

Krok 1: Vytvorenie objednavky

Posliete POST poziadavku na vytvorenie platobnej objednavky. Nahradte YOUR_API_KEY svojím sandbox API klucom:

Vytvorenie objednavky
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"
      }
    ]
  }'

amount je celé číslo v menovej jednotke ISO 4217. Pre EUR znamená 1295 12,95 EUR.

API vrati uplny objekt objednavky. Klucove polia su id, status a payment_url v transakcii:

Odpoved
{
  "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://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f...",
      "is_capturable": false,
      "expiration_period": "PT30M"
    }
  ]
}

Tvar odpovede závisí od toho, čo odošlete:

  • S poľom transactions (tento rýchly štart): každý objekt transakcie obsahuje vlastný payment_url. Presmerujte tam zákazníka.
  • Bez transactions: objednávka má namiesto toho order_url na najvyššej úrovni a zákazník si vyberá spôsob platby na hostovanej stránke Cost+. Tento postup pozrite v príručke Hosted Payment Page.

Ulozte si id -- budete ho potrebovat v kroku 3.

Krok 2: Dokoncenie testovacej platby

  1. Otvorte payment_url z odpovede vo svojom prehliadaci
  2. Na platobnej stranke zadajte udaje testovacej karty:
PoleHodnota
Cislo karty4111 1111 1111 1111
ExspiraciaAkykolvek buduci datum (napr. 12/28)
CVCAkekolvek 3 cislice (napr. 123)
  1. Odosliete platbu
  2. Budete presmerovany spat na vasu return_url

Nespoliehajte sa len na presmerovanie na potvrdenie platby. Zakaznik moze zavriet prehliadac pred presmerovanim. Vzdy overte stav cez API (krok 3) alebo webhooky (krok 4).

Krok 3: Overenie platby

Ziskajte objednavku na potvrdenie jej dokoncenia:

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

Uspesna platba vyzera takto:

Odpoved (dokoncena)
{
  "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 objednavky status je "completed" -- platba bola uspesna.

Krok 4: Spracovanie webhooku (odporucane)

Ked sa zmeni stav platby, Cost+ posle POST poziadavku na vasu webhook_url:

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

Ked ho prijmete:

  1. Zavolajte GET /v1/orders/{order_id}/ na overenie aktualneho stavu (nikdy neverite len payloadu webhooku)
  2. Vratte HTTP 200 na potvrdenie prijatia
  3. Vybavte objednavku, ak je stav "completed"

Pre lokalny vyvoj pouzite tunel ako ngrok na sprístupnenie vasho lokalneho servera a prijimanie webhookov.

Pozrite si navod pre webhooky, kde najdete logiku opakovanych pokusov, osvedcene postupy a podrobnosti o payloade.

Alternativa: Platobne odkazy

Ak nepotrebujete logiku presmerovania na strane servera, platobne odkazy ponukaju jednoduchsiu cestu. Vytvorte odkaz, zdielate URL so zakaznikom a skontrolujete stav neskor.

Vytvorenie platobneho odkazu
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"
  }'

Odpoved obsahuje payment_url, ktoru mozete zdielat e-mailom, SMS alebo chatom. Zakaznik moze skusit platbu viackrat (az 25-krat), kym odkaz nevyprsi alebo platba neuspeje.

Pozrite si navod pre platobne odkazy, kde najdete uplny postup.

Co dalej?

Dokoncili ste svoju prvu platbu. Tu su dalsie kroky:

Suvisiace endpointy

On this page