Platební odkazy

Platební odkazy jsou znovupoužitelné URL, které umožňují zákazníkům zaplatit objednávku. Na rozdíl od standardních objednávek, které vyprší po jednom neúspěšném pokusu, platební odkazy podporují více pokusů o opakování, což je ideální pro faktury, platby e-mailem a scénáře, kdy zákazník nemusí zaplatit okamžitě.

Klíčové vlastnosti

Znovupoužitelné: Zákazníci mohou opakovat platbu až 25krát, pokud předchozí pokusy selžou.
Dlouhodobé: Výchozí platnost je 30 dní (konfigurovatelné pomocí expiration_period).
Sdílitelné: Odešlete odkaz e-mailem, SMS, chatem nebo ho vložte na svůj web.

Vytvoření platebního odkazu

Odešlete požadavek 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"
  }'

Odpověď obsahuje payment_url ke sdílení se zákazníkem a unikátní id pro sledování:

Response (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://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "new",
  "reason": "Payment Link was created, not yet visited",
  "orders": {},
  "created": "2026-01-15T12:00:00.000000Z"
}

Uložte si id — použijete ho ke kontrole stavu platebního odkazu později.

Povinná pole

Pole	Popis
`merchant_order_id`	Vaše vlastní referenční ID platebního odkazu
`amount`	Částka v centech (např. 9,95 EUR = `995`)
`currency`	Kód měny dle ISO 4217 (např. `EUR`, `GBP`)

Volitelná pole

Pole	Popis
`description`	Popis zobrazený zákazníkovi
`expiration_period`	ISO 8601 doba platnosti. Výchozí je `P30D` (30 dní)
`return_url`	URL pro přesměrování zákazníka po úspěšné platbě
`failure_url`	URL pro přesměrování zákazníka při zrušení, vypršení nebo chybě
`webhook_url`	URL pro příjem notifikací o změně stavu
`customer`	Objekt s údaji zákazníka (jméno, e-mail atd.)

Pokud poskytnete return_url i failure_url, zákazníci jsou přesměrováni na failure_url při stavu objednávky cancelled, expired nebo error. Jinak jsou všechna přesměrování na return_url.

Získání platebního odkazu

Odešlete požadavek GET na /v1/paymentlinks/{id}/ s použitím id platebního odkazu z odpovědi na vytvoření:

GET /v1/paymentlinks/{id}/

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

Odpověď obsahuje aktuální stav a odkazy na všechny objednávky vytvořené z odkazu, seskupené podle jejich stavu:

Response (completed example)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.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 příkladu zákazník provedl jeden neúspěšný pokus (objednávka 0d79014c... ve stavu error) před úspěchem (objednávka 3bb663cc... ve stavu completed). Kompletní detaily libovolné objednávky můžete získat prostřednictvím GET /v1/orders/{order_id}/.

Stavy platebního odkazu

Stav	Popis
`new`	Odkaz byl vytvořen, ale nebyl proveden žádný platební pokus.
`processing`	Probíhá platební pokus.
`all_unsuccessful`	Všechny dosavadní platební pokusy selhaly. Zákazník může stále opakovat (až 25 pokusů).
`completed`	Platba byla úspěšná. Odkaz již není aktivní.
`expired`	Odkaz vypršel před provedením úspěšné platby.

Stav all_unsuccessful není konečný stav. Zákazník může stále pokusit zaplatit znovu, dokud platba neproběhne úspěšně, nebude dosažen maximální počet pokusů (25) nebo odkaz nevyprší.

Jakmile platební odkaz dosáhne stavu completed nebo expired, nelze ho znovu použít. Pokud zákazník potřebuje zaplatit znovu, vytvořte nový platební odkaz.

Příklad pracovního postupu

Vytvořte platební odkaz prostřednictvím POST /v1/paymentlinks/.
Sdílejte vrácenou payment_url se zákazníkem (např. e-mailem, SMS nebo na faktuře).
Zákazník otevře odkaz a dokončí platbu.
Cost+ odešle webhook na vaši webhook_url při změně stavu.
Ověřte stav platebního odkazu prostřednictvím GET /v1/paymentlinks/{id}/.
Vyřiďte objednávku, jakmile je stav completed.

Související endpointy

Vytvoření platebního odkazu — vytvoření znovupoužitelného platebního odkazu
Získání platebního odkazu — získání aktuálního stavu platebního odkazu

On this page