Cost+Docs

Plačilne povezave

Ustvarite plačilne povezave za večkratno uporabo

Plačilne povezave so URL-ji za večkratno uporabo, ki strankam omogočajo plačilo naročila. Za razliko od standardnih naročil, ki potečejo po enem neuspešnem poskusu, plačilne povezave podpirajo več ponovnih poskusov, kar jih naredi idealne za račune, plačila prek e-pošte in scenarije, ko stranka morda ne plača takoj.

Ključne lastnosti

  • Večkratna uporaba: Stranke lahko poskusijo plačilo do 25-krat, če prejšnji poskusi spodletijo.
  • Dolga veljavnost: Privzeti rok poteka je 30 dni (nastavljiv prek expiration_period).
  • Deljenje: Pošljite povezavo prek e-pošte, SMS-a, klepeta ali jo vgradite na svoje spletno mesto.

Ustvarjanje plačilne povezave

Pošljite zahtevo POST na /v1/paymentlinks/:

POST /v1/paymentlinks/
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": 995,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

Odgovor vključuje payment_url za deljenje s stranko in edinstveni id za sledenje:

Odgovor (201 Created)
{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://api.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "new",
  "reason": "Payment Link was created, not yet visited",
  "orders": {},
  "created": "2026-01-15T12:00:00.000000Z"
}

Shranite id — uporabili ga boste za kasnejše preverjanje statusa plačilne povezave.

Obvezna polja

PoljeOpis
merchant_order_idVaša lastna referenčna oznaka za plačilno povezavo
amountZnesek v manjši enoti ISO 4217 valute (npr. 9,95 EUR = 995)
currencyValutna koda ISO 4217 (npr. EUR, GBP)

Neobvezna polja

PoljeOpis
descriptionOpis, prikazan stranki
expiration_periodTrajanje ISO 8601. Privzeto je P30D (30 dni)
return_urlURL za preusmeritev stranke po uspešnem plačilu
failure_urlURL za preusmeritev stranke ob preklicu, poteku ali napaki
webhook_urlURL za prejemanje obvestil o spremembi statusa
customerObjekt s podatki stranke (ime, e-pošta itd.)

Če navedete tako return_url kot failure_url, so stranke preusmerjene na failure_url, ko je status naročila cancelled, expired ali error. V nasprotnem primeru gredo vse preusmeritve na return_url.

Pridobivanje plačilne povezave

Pošljite zahtevo GET na /v1/paymentlinks/{id}/ z uporabo id plačilne povezave iz odgovora ob ustvarjanju:

GET /v1/paymentlinks/{id}/
curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/

Odgovor vključuje trenutni status in reference na vsa naročila, ustvarjena iz povezave, razvrščena po statusu:

Odgovor (primer dokončanega)
{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://api.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "completed",
  "reason": "Completed",
  "completed": "2026-01-15T12:05:30.123456+00:00",
  "completed_order_id": "3bb663cc-2a20-400d-8bf6-18d9695d0c66",
  "orders": {
    "error": ["0d79014c-0aaa-4fd6-87c5-c8cfa5f5ac69"],
    "completed": ["3bb663cc-2a20-400d-8bf6-18d9695d0c66"]
  }
}

V tem primeru je stranka imela en neuspešen poskus (naročilo 0d79014c... s statusom error), preden je uspela (naročilo 3bb663cc... s statusom completed). Celotne podrobnosti kateregakoli naročila lahko pridobite prek GET /v1/orders/{order_id}/.

Statusi plačilne povezave

StatusOpis
newPovezava je bila ustvarjena, vendar noben poskus plačila še ni bil izveden.
processingPoskus plačila je trenutno v teku.
all_unsuccessfulVsi dosedanji poskusi plačila so spodleteli. Stranka lahko še vedno poskusi znova (do 25 poskusov).
completedPlačilo je bilo uspešno. Povezava ni več aktivna.
expiredPovezava je potekla pred uspešnim plačilom.

Status all_unsuccessful ni končni status. Stranka lahko še vedno poskusi plačati, dokler plačilo ne uspe, dokler ni doseženo največje število poskusov (25) ali dokler povezava ne poteče.

Ko plačilna povezava doseže status completed ali expired, je ni mogoče več uporabiti. Ustvarite novo plačilno povezavo, če mora stranka znova plačati.

Primer poteka dela

  1. Ustvarite plačilno povezavo prek POST /v1/paymentlinks/.
  2. Delite vrnjeni payment_url s stranko (npr. prek e-pošte, SMS-a ali računa).
  3. Stranka odpre povezavo in dokonča plačilo.
  4. Cost+ pošlje webhook na vaš webhook_url, ko se status spremeni.
  5. Preverite status plačilne povezave prek GET /v1/paymentlinks/{id}/.
  6. Izpolnite naročilo, ko je status completed.

Povezane končne točke

On this page