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/:
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:
{
"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
| Polje | Opis |
|---|---|
merchant_order_id | Vaša lastna referenčna oznaka za plačilno povezavo |
amount | Znesek v manjši enoti ISO 4217 valute (npr. 9,95 EUR = 995) |
currency | Valutna koda ISO 4217 (npr. EUR, GBP) |
Neobvezna polja
| Polje | Opis |
|---|---|
description | Opis, prikazan stranki |
expiration_period | Trajanje ISO 8601. Privzeto je P30D (30 dni) |
return_url | URL za preusmeritev stranke po uspešnem plačilu |
failure_url | URL za preusmeritev stranke ob preklicu, poteku ali napaki |
webhook_url | URL za prejemanje obvestil o spremembi statusa |
customer | Objekt 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:
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:
{
"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
| Status | Opis |
|---|---|
new | Povezava je bila ustvarjena, vendar noben poskus plačila še ni bil izveden. |
processing | Poskus plačila je trenutno v teku. |
all_unsuccessful | Vsi dosedanji poskusi plačila so spodleteli. Stranka lahko še vedno poskusi znova (do 25 poskusov). |
completed | Plačilo je bilo uspešno. Povezava ni več aktivna. |
expired | Povezava 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
- Ustvarite plačilno povezavo prek
POST /v1/paymentlinks/. - Delite vrnjeni
payment_urls stranko (npr. prek e-pošte, SMS-a ali računa). - Stranka odpre povezavo in dokonča plačilo.
- Cost+ pošlje webhook na vaš
webhook_url, ko se status spremeni. - Preverite status plačilne povezave prek
GET /v1/paymentlinks/{id}/. - Izpolnite naročilo, ko je status
completed.
Povezane končne točke
- Ustvari plačilno povezavo — ustvarite plačilno povezavo za večkratno uporabo
- Pridobi plačilno povezavo — pridobite trenutni status plačilne povezave