Cost+Docs

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/:

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"
  }'

Odpoved obsahuje payment_url na zdielanie so zakaznikom a jediny id na sledovanie:

Odpoved (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"
}

Ulozte si id -- pouzijete ho na kontrolu stavu platobneho odkazu neskor.

Povinne polia

PolePopis
merchant_order_idVase vlastne referencne ID pre platobny odkaz
amountSuma v menovej jednotke ISO 4217 meny (napr. 9,95 EUR = 995)
currencyISO 4217 kod meny (napr. EUR, GBP)

Volitelne polia

PolePopis
descriptionPopis zobrazeny zakaznikovi
expiration_periodISO 8601 trvanie. Predvolene je P30D (30 dni)
return_urlURL na presmerovanie zakaznika po uspesnej platbe
failure_urlURL na presmerovanie zakaznika pri zruseni, exspiracii alebo chybe
webhook_urlURL na prijimanie notifikacii o zmene stavu
customerObjekt 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:

GET /v1/paymentlinks/{id}/
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:

Odpoved (priklad dokoncenia)
{
  "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

StavPopis
newOdkaz bol vytvoreny, ale nebol vykonany ziadny pokus o platbu.
processingPokus o platbu prave prebieha.
all_unsuccessfulVsetky doterajsie pokusy o platbu zlyhali. Zakaznik moze stale skusit znova (az 25 pokusov).
completedPlatba bola uspesna. Odkaz uz nie je aktivny.
expiredOdkaz 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

  1. Vytvorte platobny odkaz cez POST /v1/paymentlinks/.
  2. Zdielate vratenu payment_url so zakaznikom (napr. e-mailom, SMS alebo fakturou).
  3. Zakaznik otvori odkaz a dokonci platbu.
  4. Cost+ posle webhook na vasu webhook_url, ked sa zmeni stav.
  5. Overte stav platobneho odkazu cez GET /v1/paymentlinks/{id}/.
  6. Vybavte objednavku, ked je stav completed.

Suvisiace endpointy

On this page