Poveznice za plaćanje
Stvorite poveznice za plaćanje za višestruku upotrebu
Poveznice za plaćanje su URL-ovi za višestruku upotrebu koji omogućuju kupcima plaćanje narudžbe. Za razliku od standardnih narudžbi koje istječu nakon jednog neuspjelog pokušaja, poveznice za plaćanje podržavaju više ponovnih pokušaja, što ih čini idealnim za račune, plaćanja putem e-pošte i scenarije gdje kupac možda neće odmah platiti.
Ključne značajke
- Višestruka upotreba: Kupci mogu ponoviti plaćanje do 25 puta ako prethodni pokušaji ne uspiju.
- Dugotrajne: Zadani rok isteka je 30 dana (konfigurirano putem
expiration_period). - Dijeljive: Pošaljite poveznicu putem e-pošte, SMS-a, chata ili je ugradite na svoju web stranicu.
Stvaranje poveznice za plaćanje
Pošaljite POST zahtjev 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 uključuje payment_url za dijeljenje s kupcem i jedinstveni id za praćenje:
{
"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"
}Spremite id — koristit ćete ga za kasniju provjeru statusa poveznice za plaćanje.
Obavezna polja
| Polje | Opis |
|---|---|
merchant_order_id | Vaš vlastiti referentni ID za poveznicu za plaćanje |
amount | Iznos u manjoj jedinici ISO 4217 valute (npr. 9,95 EUR = 995) |
currency | ISO 4217 kod valute (npr. EUR, GBP) |
Neobavezna polja
| Polje | Opis |
|---|---|
description | Opis prikazan kupcu |
expiration_period | ISO 8601 trajanje. Zadano je P30D (30 dana) |
return_url | URL za preusmjeravanje kupca nakon uspješnog plaćanja |
failure_url | URL za preusmjeravanje kupca pri odustajanju, isteku ili grešci |
webhook_url | URL za primanje obavijesti o promjeni statusa |
customer | Objekt s podacima o kupcu (ime, e-pošta itd.) |
Ako navedete i return_url i failure_url, kupci se preusmjeravaju na failure_url kada je status narudžbe cancelled, expired ili error. U suprotnom, sva preusmjeravanja idu na return_url.
Dohvaćanje poveznice za plaćanje
Pošaljite GET zahtjev na /v1/paymentlinks/{id}/ koristeći id poveznice za plaćanje iz odgovora na stvaranje:
curl -u YOUR_API_KEY: \
https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/Odgovor uključuje trenutni status i reference na sve narudžbe stvorene iz poveznice, grupirane prema njihovom 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"]
}
}U ovom primjeru, kupac je imao jedan neuspjeli pokušaj (narudžba 0d79014c... u statusu error) prije uspjeha (narudžba 3bb663cc... u statusu completed). Potpune detalje bilo koje narudžbe možete dohvatiti putem GET /v1/orders/{order_id}/.
Statusi poveznice za plaćanje
| Status | Opis |
|---|---|
new | Poveznica je stvorena, ali nije napravljen nijedan pokušaj plaćanja. |
processing | Pokušaj plaćanja je trenutno u tijeku. |
all_unsuccessful | Svi dosadašnji pokušaji plaćanja nisu uspjeli. Kupac još uvijek može pokušati ponovo (do 25 pokušaja). |
completed | Plaćanje je uspjelo. Poveznica više nije aktivna. |
expired | Poveznica je istekla prije uspješnog plaćanja. |
Status all_unsuccessful nije konačni status. Kupac još uvijek može pokušati platiti sve dok plaćanje ne uspije, dok se ne dosegne maksimalni broj pokušaja (25) ili dok poveznica ne istekne.
Nakon što poveznica za plaćanje dosegne status completed ili expired, ne može se ponovno koristiti. Stvorite novu poveznicu za plaćanje ako kupac treba ponovo platiti.
Primjer tijeka rada
- Stvorite poveznicu za plaćanje putem
POST /v1/paymentlinks/. - Podijelite vraćeni
payment_urlsa svojim kupcem (npr. putem e-pošte, SMS-a ili računa). - Kupac otvara poveznicu i dovršava plaćanje.
- Cost+ šalje webhook na vaš
webhook_urlkada se status promijeni. - Provjerite status poveznice za plaćanje putem
GET /v1/paymentlinks/{id}/. - Ispunite narudžbu kada je status
completed.
Povezane krajnje točke
- Stvori poveznicu za plaćanje — stvorite poveznicu za plaćanje za višestruku upotrebu
- Dohvati poveznicu za plaćanje — dohvatite trenutni status poveznice za plaćanje