Cost+Docs

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:

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

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:

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://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 svoj payment_url. Preusmjerite kupca tamo.
  • Bez transactions: narudžba umjesto toga ima order_url na 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

  1. Otvorite payment_url iz odgovora u pregledniku
  2. Na stranici za plaćanje unesite podatke testne kartice:
PoljeVrijednost
Broj kartice4111 1111 1111 1111
IstekBilo koji budući datum (npr. 12/28)
CVCBilo koje 3 znamenke (npr. 123)
  1. Pošaljite plaćanje
  2. 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:

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

Uspješno plaćanje izgleda ovako:

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"
      }
    }
  ]
}

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:

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

Kada ovo primite:

  1. Pozovite GET /v1/orders/{order_id}/ za provjeru trenutnog statusa (nikada ne vjerujte samo webhook podacima)
  2. Vratite HTTP 200 za potvrdu primitka
  3. 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.

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"
  }'

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:

Povezane krajnje točke

On this page