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:
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:
{
"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 tohoorder_urlna 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
- Otvorte
payment_urlz odpovede vo svojom prehliadaci - Na platobnej stranke zadajte udaje testovacej karty:
| Pole | Hodnota |
|---|---|
| Cislo karty | 4111 1111 1111 1111 |
| Exspiracia | Akykolvek buduci datum (napr. 12/28) |
| CVC | Akekolvek 3 cislice (napr. 123) |
- Odosliete platbu
- 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:
curl -u YOUR_API_KEY: \
https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/Uspesna platba vyzera takto:
{
"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:
{
"event": "status_changed",
"order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}Ked ho prijmete:
- Zavolajte
GET /v1/orders/{order_id}/na overenie aktualneho stavu (nikdy neverite len payloadu webhooku) - Vratte HTTP
200na potvrdenie prijatia - 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.
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:
- Hostovana platobna stranka -- uplna referencia HPP so vsetkymi poliami a moznostami poziadavky
- Opakujuce sa platby -- nastavenie predplatnych a planovaneho fakturovanie
- Platby jednym klikom -- rychla pokladna pre vracajucich sa zakaznikov
- Autorizacia / Zachytenie / Zrusenie -- najprv autorizujte, zachytte neskor (napr. pri odosielani)
- Vratenie platieb -- spracovanie uplnych a ciastocnych vrateni
- SDK -- oficialne kniznice pre Node.js, Python, PHP, Java/Kotlin, C#/.NET a Ruby
- Pluginy -- pripravene integracie pre Shopify, WooCommerce, Magento a dalsie
Suvisiace endpointy
- Vytvorenie objednavky -- uplna API referencia pre vytvorenie objednavky
- Ziskanie objednavky -- ziskanie podrobnosti a stavu objednavky
- Vytvorenie platobneho odkazu -- vytvorenie opakovane pouzitelnych platobnych odkazov