Hitri začetek
Sprejmite prvo plačilo v 5 minutah
Ta vodnik vas vodi skozi ustvarjanje in dokončanje testnega plačila z uporabo Cost+ API. Na koncu boste imeli delujočo integracijo, na kateri lahko gradite.
Predpogoji
- Račun Cost+ s spletnim mestom peskovnika — ustvarite ga v portalu trgovca
- Vaš API ključ za peskovnik (najdete ga pod Spletna mesta → vaše spletno mesto peskovnika → Integracija)
Niste prepričani, kako pridobiti svoj API ključ? Glejte Testiranje integracije za podrobna navodila za nastavitev.
Korak 1: Ustvarite naročilo
Pošljite zahtevo POST za ustvarjanje plačilnega naročila. Zamenjajte YOUR_API_KEY s svojim API ključem za peskovnik:
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 celo število v pomožni enoti ISO 4217 valute. Za EUR 1295 pomeni 12,95 EUR.
API vrne celoten objekt naročila. Ključna polja so id, status in payment_url znotraj transakcije:
{
"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"
}
]
}Oblika odgovora je odvisna od tega, kaj pošljete:
- S poljem
transactions(ta hitri vodnik): vsak objekt transakcije vsebuje svojpayment_url. Tja preusmerite kupca. - Brez
transactions: naročilo ima namesto tegaorder_urlna zgornji ravni, kupec pa izbere način plačila na gostujoči strani Cost+. Za ta tok glejte vodnik Hosted Payment Page.
Shranite id — potrebovali ga boste v 3. koraku.
Korak 2: Dokončajte testno plačilo
- Odprite
payment_urliz odgovora v brskalniku - Na plačilni strani vnesite podatke testne kartice:
| Polje | Vrednost |
|---|---|
| Številka kartice | 4111 1111 1111 1111 |
| Veljavnost | Katerikoli prihodnji datum (npr. 12/28) |
| CVC | Katerekoli 3 številke (npr. 123) |
- Potrdite plačilo
- Preusmerjeni boste nazaj na vaš
return_url
Ne zanašajte se samo na preusmeritev za potrditev plačila. Stranka lahko zapre brskalnik, preden je preusmerjena. Vedno preverite prek API-ja (korak 3) ali webhook-ov (korak 4).
Korak 3: Preverite plačilo
Pridobite naročilo za potrditev dokončanja:
curl -u YOUR_API_KEY: \
https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/Uspešno plačilo izgleda takole:
{
"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"
}
}
]
}Status naročila je "completed" — plačilo je bilo uspešno.
Korak 4: Obdelajte webhook (priporočeno)
Ko se status plačila spremeni, Cost+ pošlje zahtevo POST na vaš webhook_url:
{
"event": "status_changed",
"order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}Ko to prejmete:
- Pokličite
GET /v1/orders/{order_id}/za preverjanje trenutnega statusa (nikoli ne zaupajte samo koristnim podatkom webhook-a) - Vrnite HTTP
200za potrditev prejema - Izpolnite naročilo, če je status
"completed"
Za lokalni razvoj uporabite tunel, kot je ngrok, za izpostavitev lokalnega strežnika in prejemanje webhook-ov.
Glejte vodnik za webhook-e za logiko ponovnih poskusov, najboljše prakse in podrobnosti o koristnih podatkih.
Alternativa: Plačilne povezave
Če ne potrebujete logike preusmeritev na strežniški strani, plačilne povezave ponujajo preprostejšo pot. Ustvarite povezavo, delite URL s stranko in preverite status pozneje.
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"
}'Odgovor vključuje payment_url, ki ga lahko delite prek e-pošte, SMS-a ali klepeta. Stranka lahko poskusi plačilo večkrat (do 25-krat), dokler povezava ne poteče ali plačilo ne uspe.
Glejte vodnik za plačilne povezave za celoten potek dela.
Kaj sledi?
Dokončali ste svoje prvo plačilo. Tukaj so nadaljnji koraki:
- Gostovana plačilna stran — celotna referenca HPP z vsemi polji zahteve in možnostmi
- Ponavljajoča se plačila — nastavite naročnine in načrtovane obračune
- Plačila z enim klikom — hiter zaključek nakupa za vračajoče se stranke
- Avtorizacija / zajem / razveljavitev — najprej avtorizirajte, zajemite pozneje (npr. ob pošiljanju)
- Vračila — obdelajte celotna in delna vračila
- SDK-ji — uradne knjižnice za Node.js, Python, PHP, Java/Kotlin, C#/.NET in Ruby
- Vtičniki — pripravljene integracije za Shopify, WooCommerce, Magento in več
Povezane končne točke
- Ustvari naročilo — celotna API referenca za ustvarjanje naročil
- Pridobi naročilo — pridobi podrobnosti naročila in status
- Ustvari plačilno povezavo — ustvari plačilne povezave za večkratno uporabo