Szybki start

Ten przewodnik przeprowadzi Cię przez proces tworzenia i realizacji testowej płatności za pomocą API Cost+. Po zakończeniu będziesz mieć działającą integrację, na której możesz dalej budować.

Wymagania wstępne

• Konto Cost+ ze stroną testową — utwórz je w portalu sprzedawcy
• Twój testowy klucz API (dostępny w sekcji Strony → Twoja strona testowa → Integracja)

Krok 1: Utwórz zamówienie

Wyślij żądanie POST, aby utworzyć zamówienie płatności. Zamień YOUR_API_KEY na swój testowy klucz API:

curl -X POST https://api.costplus.online/v1/orders/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 1295,
    "merchant_order_id": "my-first-order",
    "description": "Test order",
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook",
    "transactions": [
      {
        "payment_method": "credit-card"
      }
    ]
  }'

API zwraca pełny obiekt zamówienia. Kluczowe pola to id, status oraz payment_url wewnątrz transakcji:

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "description": "Test order",
  "return_url": "https://example.com/return",
  "webhook_url": "https://example.com/webhook",
  "created": "2026-01-15T12:00:05.433502+00:00",
  "modified": "2026-01-15T12:00:05.553125+00:00",
  "expiration_period": "PT1H",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "amount": 1295,
      "currency": "EUR",
      "payment_url": "https://pay.costplus.online/4851e31c.../credit-card/d291f03f...",
      "is_capturable": false,
      "expiration_period": "PT30M"
    }
  ]
}

Zapisz id — będzie potrzebne w kroku 3.

Krok 2: Zrealizuj testową płatność

1. Otwórz payment_url z odpowiedzi w przeglądarce
2. Na stronie płatności wprowadź testowe dane karty:

3. Zatwierdź płatność
4. Zostaniesz przekierowany z powrotem na Twój return_url

Krok 3: Zweryfikuj płatność

Pobierz zamówienie, aby potwierdzić jego realizację:

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/

Pomyślna płatność wygląda tak:

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "completed": "2026-01-15T12:02:30.123456+00:00",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "completed",
      "amount": 1295,
      "currency": "EUR",
      "payment_method_details": {
        "truncated_pan": "1111",
        "card_expiry": "122028"
      }
    }
  ]
}

Status zamówienia to "completed" — płatność zakończyła się sukcesem.

Krok 4: Obsłuż webhook (zalecane)

Gdy status płatności się zmieni, Cost+ wyśle żądanie POST na Twój webhook_url:

{
  "event": "status_changed",
  "order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}

Po otrzymaniu:

1. Wywołaj GET /v1/orders/{order_id}/, aby zweryfikować aktualny status (nigdy nie ufaj samej treści webhooka)
2. Zwróć HTTP 200, aby potwierdzić odbiór
3. Zrealizuj zamówienie, jeśli status to "completed"

Zobacz przewodnik po webhookach, aby poznać logikę ponowień, najlepsze praktyki i szczegóły dotyczące treści.

Alternatywa: Linki płatności

Jeśli nie potrzebujesz logiki przekierowań po stronie serwera, linki płatności oferują prostszą ścieżkę. Utwórz link, udostępnij adres URL swojemu klientowi i sprawdź status później.

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": 2500,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

Odpowiedź zawiera payment_url, który możesz udostępnić przez e-mail, SMS lub czat. Klient może próbować dokonać płatności wielokrotnie (do 25 razy), dopóki link nie wygaśnie lub płatność nie zostanie zrealizowana.

Zobacz przewodnik po linkach płatności, aby poznać pełny proces.

Co dalej?

Zrealizowałeś swoją pierwszą płatność. Oto co możesz zrobić dalej:

• Hostowana strona płatności — pełna dokumentacja HPP ze wszystkimi polami żądania i opcjami
• Płatności cykliczne — konfiguracja subskrypcji i zaplanowanych obciążeń
• Płatności jednym kliknięciem — szybka realizacja zamówień dla powracających klientów
• Autoryzacja / Przechwycenie / Anulowanie — najpierw autoryzuj, potem pobierz środki (np. przy wysyłce)
• Zwroty — przetwarzanie pełnych i częściowych zwrotów
• SDK — oficjalne biblioteki dla Node.js, Python, PHP, Java/Kotlin, C#/.NET i Ruby
• Wtyczki — gotowe integracje dla Shopify, WooCommerce, Magento i innych

Powiązane punkty końcowe

• Utwórz zamówienie — pełna dokumentacja API do tworzenia zamówień
• Pobierz zamówienie — pobranie szczegółów i statusu zamówienia
• Utwórz link płatności — tworzenie linków płatności wielokrotnego użytku