Cost+Docs

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:

Ustvarjanje naročila
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:

Odgovor
{
  "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 svoj payment_url. Tja preusmerite kupca.
  • Brez transactions: naročilo ima namesto tega order_url na 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

  1. Odprite payment_url iz odgovora v brskalniku
  2. Na plačilni strani vnesite podatke testne kartice:
PoljeVrednost
Številka kartice4111 1111 1111 1111
VeljavnostKaterikoli prihodnji datum (npr. 12/28)
CVCKaterekoli 3 številke (npr. 123)
  1. Potrdite plačilo
  2. 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:

Preverjanje statusa naročila
curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/

Uspešno plačilo izgleda takole:

Odgovor (dokončano)
{
  "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:

Koristni podatki webhook-a
{
  "event": "status_changed",
  "order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}

Ko to prejmete:

  1. Pokličite GET /v1/orders/{order_id}/ za preverjanje trenutnega statusa (nikoli ne zaupajte samo koristnim podatkom webhook-a)
  2. Vrnite HTTP 200 za potrditev prejema
  3. 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.

Ustvarjanje plačilne povezave
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:

Povezane končne točke

On this page