Linki płatności

Linki płatności to adresy URL wielokrotnego użytku, które umożliwiają klientom zapłacenie za zamówienie. W przeciwieństwie do standardowych zamówień, które wygasają po jednej nieudanej próbie, linki płatności obsługują wiele prób ponowienia, co czyni je idealnymi do faktur, płatności e-mailowych i scenariuszy, w których klient może nie zapłacić od razu.

Kluczowe cechy

Wielokrotnego użytku: Klienci mogą ponawiać próby płatności do 25 razy, jeśli poprzednie się nie powiodły.
Długo ważne: Domyślny czas ważności to 30 dni (konfigurowalne przez expiration_period).
Udostępnialne: Wyślij link przez e-mail, SMS, czat lub osadź go na swojej stronie.

Tworzenie linku płatności

Wyślij żądanie 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"
  }'

Odpowiedź zawiera payment_url do udostępnienia klientowi oraz unikalny id do śledzenia:

Odpowiedź (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"
}

Zapisz id — użyjesz go później do sprawdzenia statusu linku płatności.

Pola wymagane

Pole	Opis
`merchant_order_id`	Twój własny identyfikator referencyjny linku płatności
`amount`	Kwota w groszach/centach (np. 9,95 EUR = `995`)
`currency`	Kod waluty ISO 4217 (np. `EUR`, `GBP`)

Pola opcjonalne

Pole	Opis
`description`	Opis wyświetlany klientowi
`expiration_period`	Czas trwania w formacie ISO 8601. Domyślnie `P30D` (30 dni)
`return_url`	URL do przekierowania klienta po pomyślnej płatności
`failure_url`	URL do przekierowania klienta w przypadku anulowania, wygaśnięcia lub błędu
`webhook_url`	URL do otrzymywania powiadomień o zmianie statusu
`customer`	Obiekt z danymi klienta (imię, e-mail itp.)

Jeśli podasz zarówno return_url, jak i failure_url, klienci są przekierowywani na failure_url, gdy status zamówienia to cancelled, expired lub error. W przeciwnym razie wszystkie przekierowania prowadzą na return_url.

Pobieranie linku płatności

Wyślij żądanie GET na /v1/paymentlinks/{id}/, używając id linku płatności z odpowiedzi na żądanie tworzenia:

GET /v1/paymentlinks/{id}/

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

Odpowiedź zawiera aktualny status oraz odniesienia do wszystkich zamówień utworzonych z linku, pogrupowane według ich statusu:

Odpowiedź (przykład zakończony sukcesem)

{
  "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"]
  }
}

W tym przykładzie klient dokonał jednej nieudanej próby (zamówienie 0d79014c... ze statusem error) przed sukcesem (zamówienie 3bb663cc... ze statusem completed). Pełne szczegóły dowolnego zamówienia możesz pobrać przez GET /v1/orders/{order_id}/.

Statusy linków płatności

Status	Opis
`new`	Link został utworzony, ale nie podjęto jeszcze żadnej próby płatności.
`processing`	Próba płatności jest w trakcie realizacji.
`all_unsuccessful`	Wszystkie dotychczasowe próby płatności zakończyły się niepowodzeniem. Klient nadal może ponowić próbę (do 25 prób).
`completed`	Płatność zakończyła się sukcesem. Link nie jest już aktywny.
`expired`	Link wygasł przed dokonaniem pomyślnej płatności.

Status all_unsuccessful nie jest statusem końcowym. Klient nadal może próbować zapłacić, dopóki płatność się nie powiedzie, nie zostanie osiągnięta maksymalna liczba prób (25) lub link nie wygaśnie.

Gdy link płatności osiągnie status completed lub expired, nie może być ponownie użyty. Utwórz nowy link płatności, jeśli klient musi ponownie zapłacić.

Przykładowy przepływ

Utwórz link płatności przez POST /v1/paymentlinks/.
Udostępnij klientowi zwrócony payment_url (np. przez e-mail, SMS lub fakturę).
Klient otwiera link i realizuje płatność.
Cost+ wysyła webhook na Twój webhook_url, gdy status się zmieni.
Zweryfikuj status linku płatności przez GET /v1/paymentlinks/{id}/.
Zrealizuj zamówienie, gdy status to completed.

Powiązane punkty końcowe

Utwórz link płatności — utwórz link płatności wielokrotnego użytku
Pobierz link płatności — pobierz aktualny status linku płatności

On this page