Platobne odkazy
Vytvarajte opakovane pouzitelne platobne odkazy
Platobne odkazy su opakovane pouzitelne URL adresy, ktore umoznuju zakaznikom zaplatit za objednavku. Na rozdiel od standardnych objednavok, ktore vyprsia po jednom neuspesnom pokuse, platobne odkazy podporuju viacero pokusov o opakovanie, co ich robí idealnym pre faktury, platby cez e-mail a scenare, kde zakaznik nemusi zaplatit okamzite.
Klucove vlastnosti
- Opakovane pouzitelne: Zakaznici mozu skusit platbu az 25-krat, ak predchadzajuce pokusy zlyhaju.
- Dlhodobo platne: Predvolena exspiracia je 30 dni (konfigurovatelna cez
expiration_period). - Zdielatelne: Posliete odkaz e-mailom, SMS, chatom alebo ho vlozite na svoju webovu stranku.
Vytvorenie platobneho odkazu
Posliete poziadavku 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"
}'Odpoved obsahuje payment_url na zdielanie so zakaznikom a jediny id na sledovanie:
{
"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"
}Ulozte si id -- pouzijete ho na kontrolu stavu platobneho odkazu neskor.
Povinne polia
| Pole | Popis |
|---|---|
merchant_order_id | Vase vlastne referencne ID pre platobny odkaz |
amount | Suma v menovej jednotke ISO 4217 meny (napr. 9,95 EUR = 995) |
currency | ISO 4217 kod meny (napr. EUR, GBP) |
Volitelne polia
| Pole | Popis |
|---|---|
description | Popis zobrazeny zakaznikovi |
expiration_period | ISO 8601 trvanie. Predvolene je P30D (30 dni) |
return_url | URL na presmerovanie zakaznika po uspesnej platbe |
failure_url | URL na presmerovanie zakaznika pri zruseni, exspiracii alebo chybe |
webhook_url | URL na prijimanie notifikacii o zmene stavu |
customer | Objekt s udajmi zakaznika (meno, e-mail atd.) |
Ak uvediete obe return_url a failure_url, zakaznici su presmerovani na failure_url, ked je stav objednavky cancelled, expired alebo error. V opacnom pripade su vsetky presmerovania na return_url.
Ziskanie platobneho odkazu
Posliete poziadavku GET na /v1/paymentlinks/{id}/ s pouzitim id platobneho odkazu z odpovede pri vytvoreni:
curl -u YOUR_API_KEY: \
https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/Odpoved obsahuje aktualny stav a referencie na vsetky objednavky vytvorene z odkazu, zoskupene podla ich stavu:
{
"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 tomto priklade zakaznik vykonal jeden neuspesny pokus (objednavka 0d79014c... v stave error) pred uspechom (objednavka 3bb663cc... v stave completed). Uplne podrobnosti akejkolvek objednavky mozete ziskat cez GET /v1/orders/{order_id}/.
Stavy platobneho odkazu
| Stav | Popis |
|---|---|
new | Odkaz bol vytvoreny, ale nebol vykonany ziadny pokus o platbu. |
processing | Pokus o platbu prave prebieha. |
all_unsuccessful | Vsetky doterajsie pokusy o platbu zlyhali. Zakaznik moze stale skusit znova (az 25 pokusov). |
completed | Platba bola uspesna. Odkaz uz nie je aktivny. |
expired | Odkaz vyprsaleste pred uspesnou platbou. |
Stav all_unsuccessful nie je koncovym stavom. Zakaznik moze stale skusit zaplatit znova, kym platba neuspeje, nedosiahne sa maximalny pocet pokusov (25) alebo odkaz nevyprsi.
Ked platobny odkaz dosiahne stav completed alebo expired, nemoze sa znovu pouzit. Ak zakaznik potrebuje zaplatit znova, vytvorte novy platobny odkaz.
Priklad postupu
- Vytvorte platobny odkaz cez
POST /v1/paymentlinks/. - Zdielate vratenu
payment_urlso zakaznikom (napr. e-mailom, SMS alebo fakturou). - Zakaznik otvori odkaz a dokonci platbu.
- Cost+ posle webhook na vasu
webhook_url, ked sa zmeni stav. - Overte stav platobneho odkazu cez
GET /v1/paymentlinks/{id}/. - Vybavte objednavku, ked je stav
completed.
Suvisiace endpointy
- Vytvorenie platobneho odkazu -- vytvorenie opakovane pouzitelneho platobneho odkazu
- Ziskanie platobneho odkazu -- ziskanie aktualneho stavu platobneho odkazu