Brzi početak
Prihvatite svoje prvo plaćanje u 5 minuta
Ovaj vodič vas vodi kroz stvaranje i dovršavanje testnog plaćanja koristeći Cost+ API. Na kraju ćete imati radnu integraciju na kojoj možete dalje graditi.
Preduvjeti
- Cost+ račun sa sandbox web stranicom — izradite jedan u portalu trgovca
- Vaš sandbox API ključ (nalazi se pod Websites → vaša sandbox web stranica → Integration)
Niste sigurni kako dobiti svoj API ključ? Pogledajte Testiranje integracije za detaljne upute za postavljanje.
Korak 1: Stvorite narudžbu
Pošaljite POST zahtjev za stvaranje narudžbe plaćanja. Zamijenite YOUR_API_KEY svojim sandbox API ključem:
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 cijeli broj u manjoj jedinici ISO 4217 valute. Za EUR, 1295 znači 12,95 EUR.
API vraća potpuni objekt narudžbe. Ključna polja su id, status i payment_url unutar 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"
}
]
}Oblik odgovora ovisi o tome što šaljete:
- S nizom
transactions(ovaj brzi početak): svaki objekt transakcije sadrži svojpayment_url. Preusmjerite kupca tamo. - Bez
transactions: narudžba umjesto toga imaorder_urlna najvišoj razini, a kupac bira način plaćanja na Cost+ hostiranoj stranici. Pogledajte vodič za Hosted Payment Page za taj tijek.
Spremite id — trebat će vam u koraku 3.
Korak 2: Dovršite testno plaćanje
- Otvorite
payment_urliz odgovora u pregledniku - Na stranici za plaćanje unesite podatke testne kartice:
| Polje | Vrijednost |
|---|---|
| Broj kartice | 4111 1111 1111 1111 |
| Istek | Bilo koji budući datum (npr. 12/28) |
| CVC | Bilo koje 3 znamenke (npr. 123) |
- Pošaljite plaćanje
- Bit ćete preusmjereni natrag na vaš
return_url
Ne oslanjajte se samo na preusmjeravanje za potvrdu plaćanja. Kupac može zatvoriti preglednik prije preusmjeravanja. Uvijek provjerite putem API-ja (korak 3) ili webhookova (korak 4).
Korak 3: Provjerite plaćanje
Dohvatite narudžbu kako biste potvrdili da je dovršena:
curl -u YOUR_API_KEY: \
https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/Uspješno plaćanje izgleda ovako:
{
"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 narudžbe je "completed" — plaćanje je uspjelo.
Korak 4: Obradite webhook (preporučeno)
Kada se status plaćanja promijeni, Cost+ šalje POST zahtjev na vaš webhook_url:
{
"event": "status_changed",
"order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}Kada ovo primite:
- Pozovite
GET /v1/orders/{order_id}/za provjeru trenutnog statusa (nikada ne vjerujte samo webhook podacima) - Vratite HTTP
200za potvrdu primitka - Ispunite narudžbu ako je status
"completed"
Za lokalni razvoj koristite tunel poput ngrok za izlaganje vašeg lokalnog poslužitelja i primanje webhookova.
Pogledajte vodič za webhookove za logiku ponovnih pokušaja, najbolje prakse i detalje o podacima.
Alternativa: Poveznice za plaćanje
Ako vam ne treba logika preusmjeravanja na strani poslužitelja, poveznice za plaćanje nude jednostavniji put. Stvorite poveznicu, podijelite URL s kupcem i provjerite status kasnije.
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 uključuje payment_url koji možete podijeliti putem e-pošte, SMS-a ili chata. Kupac može pokušati plaćanje više puta (do 25) dok poveznica ne istekne ili plaćanje ne uspije.
Pogledajte vodič za poveznice za plaćanje za potpuni tijek rada.
Što dalje?
Dovršili ste svoje prvo plaćanje. Evo kamo ići dalje:
- Hosted stranica za plaćanje — potpuna HPP referenca sa svim poljima zahtjeva i opcijama
- Ponavljajuća plaćanja — postavite pretplate i zakazanu naplatu
- Plaćanje jednim klikom — brza naplata za povratne kupce
- Autorizacija / Naplata / Poništenje — prvo autorizirajte, naplatite kasnije (npr. pri isporuci)
- Povrati — obradite potpune i djelomične povrate
- SDK-ovi — službene biblioteke za Node.js, Python, PHP, Java/Kotlin, C#/.NET i Ruby
- Dodaci — gotove integracije za Shopify, WooCommerce, Magento i druge
Povezane krajnje točke
- Stvori narudžbu — potpuna API referenca za stvaranje narudžbe
- Dohvati narudžbu — dohvati detalje i status narudžbe
- Stvori poveznicu za plaćanje — stvori poveznice za plaćanje za višestruku upotrebu