Python

Oficjalny SDK Python dla bramki płatności Cost+. Upraszcza przepływ przekierowań HPP (hostowanej strony płatności), podpisywanie HMAC i weryfikację webhooków.

Funkcje

Minimalne zależności — tylko requests
Pełne podpowiedzi typów i zamrożone dataclass jako typy zwracane
Generowanie podpisów HMAC-SHA256 i weryfikacja w stałym czasie
Parsowanie webhooków + weryfikacja zamówienia przez API
Testowany na Python 3.10, 3.11 i 3.12

Wymagania

Python 3.10 lub nowszy
Konto sprzedawcy Cost+ — dashboard.costplus.io

Instalacja

pip install nopayn-sdk

Szybki start

1. Zainicjalizuj klienta

from nopayn import NoPaynClient

client = NoPaynClient(
    api_key="your-api-key",
    merchant_id="your-project",
)

2. Utwórz płatność i przekieruj na HPP

result = client.generate_payment_url(
    amount=1295,             # 12,95 EUR w centach
    currency="EUR",
    merchant_order_id="ORDER-001",
    description="Premium Widget",
    return_url="https://shop.example.com/success",
    failure_url="https://shop.example.com/failure",
    webhook_url="https://shop.example.com/webhook",
    locale="en-GB",
    expiration_period="PT30M",
)

# Przekieruj klienta
# result.order_url   → HPP (klient wybiera metodę płatności)
# result.payment_url → bezpośredni link do metody płatności pierwszej transakcji
# result.signature   → HMAC-SHA256 do weryfikacji
# result.order_id    → UUID zamówienia NoPayn

3. Obsłuż webhook (przykład Flask)

@app.route("/webhook", methods=["POST"])
def webhook():
    verified = client.verify_webhook(request.get_data(as_text=True))

    print(verified.order.status)  # 'completed', 'cancelled', itp.
    print(verified.is_final)      # True gdy zamówienie się nie zmieni

    if verified.order.status == "completed":
        # Zrealizuj zamówienie
        pass

    return "", 200

Dokumentacja API

`NoPaynClient(api_key, merchant_id, base_url?)`

Parametr	Typ	Wymagany	Domyślnie
`api_key`	`str`	Tak	—
`merchant_id`	`str`	Tak	—
`base_url`	`str`	Nie	`https://api.nopayn.co.uk`

`client.create_order(**kwargs) -> Order`

Tworzy zamówienie przez POST /v1/orders/.

Parametr	Typ	Wymagany	Opis
`amount`	`int`	Tak	Kwota w najmniejszej jednostce waluty (centy)
`currency`	`str`	Tak	Kod ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchant_order_id`	`str`	Nie	Twoja wewnętrzna referencja zamówienia
`description`	`str`	Nie	Opis zamówienia
`return_url`	`str`	Nie	Przekierowanie po pomyślnej płatności
`failure_url`	`str`	Nie	Przekierowanie przy anulowaniu/wygaśnięciu/błędzie
`webhook_url`	`str`	Nie	Asynchroniczne powiadomienia o zmianie statusu
`locale`	`str`	Nie	Język HPP (`en-GB`, `de-DE`, `nl-NL`, itp.)
`payment_methods`	`list[str]`	Nie	Filtruj metody HPP
`expiration_period`	`str`	Nie	Czas trwania ISO 8601 (`PT30M`)

Dostępne metody płatności: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.get_order(order_id) -> Order`

Pobiera szczegóły zamówienia przez GET /v1/orders/{id}/.

`client.create_refund(order_id, amount, description?) -> Refund`

Dokonuje pełnego lub częściowego zwrotu przez POST /v1/orders/{id}/refunds/.

`client.generate_payment_url(**kwargs) -> PaymentUrlResult`

Metoda pomocnicza, która tworzy zamówienie i zwraca:

PaymentUrlResult(
    order_id="...",       # UUID zamówienia NoPayn
    order_url="...",      # URL HPP
    payment_url="...",    # Bezpośredni URL płatności (pierwsza transakcja)
    signature="...",      # HMAC-SHA256 z amount:currency:order_id
    order=Order(...),     # Pełny obiekt zamówienia
)

`client.generate_signature(amount, currency, order_id) -> str`

Generuje podpis HMAC-SHA256 w formacie hex.

`client.verify_signature(amount, currency, order_id, signature) -> bool`

Weryfikacja HMAC-SHA256 w stałym czasie.

`client.verify_webhook(raw_body) -> VerifiedWebhook`

Parsuje treść webhooka, następnie wywołuje GET /v1/orders/{id}/, aby zweryfikować rzeczywisty status.

Samodzielne narzędzia HMAC

from nopayn import generate_signature, verify_signature

sig = generate_signature("your-api-key", 1295, "EUR", "order-uuid")
ok = verify_signature("your-api-key", 1295, "EUR", "order-uuid", sig)

Typy danych

Wszystkie odpowiedzi API są zwracane jako zamrożone dataclass:

Klasa	Pola
`Order`	`id`, `amount`, `currency`, `status`, `created`, `modified`, `transactions`, `description`, `merchant_order_id`, `return_url`, `failure_url`, `order_url`, `completed`
`Transaction`	`id`, `amount`, `currency`, `status`, `created`, `modified`, `payment_method`, `payment_url`, `expiration_period`
`Refund`	`id`, `amount`, `status`
`PaymentUrlResult`	`order_id`, `order_url`, `payment_url`, `signature`, `order`
`VerifiedWebhook`	`order_id`, `order`, `is_final`

Obsługa błędów

from nopayn import ApiError, NoPaynError, WebhookError

try:
    client.create_order(amount=100, currency="EUR")
except ApiError as exc:
    print(exc.status_code)  # 401, 400, itp.
    print(exc.error_body)   # Surowa odpowiedź błędu API
except NoPaynError as exc:
    print(exc)              # Błąd sieci lub parsowania

Statusy zamówień

Status	Końcowy?	Opis
`new`	Nie	Zamówienie utworzone
`processing`	Nie	Płatność w toku
`completed`	Tak	Płatność zakończona sukcesem — wydaj towar
`cancelled`	Tak	Płatność anulowana przez klienta
`expired`	Tak	Link płatności wygasł
`error`	Tak	Błąd techniczny

Najlepsze praktyki dotyczące webhooków

Zawsze weryfikuj przez API — treść webhooka zawiera tylko identyfikator zamówienia, nigdy status. verify_webhook() SDK robi to automatycznie.
Zwracaj HTTP 200, aby potwierdzić odbiór. Każdy inny kod powoduje do 10 ponowień (co 2 minuty).
Zaimplementuj zapasowe odpytywanie — dla zamówień starszych niż 10 minut, które nie osiągnęły końcowego statusu, odpytuj get_order() jako zabezpieczenie.
Bądź idempotentny — możesz otrzymać ten sam webhook wielokrotnie.

Karty testowe

Użyj tych kart w trybie testowym Cost+ (strona testowa):

Karta	Numer	Uwagi
Visa (sukces)	`4111 1111 1111 1111`	Dowolny CVV
Mastercard (sukces)	`5544 3300 0003 7`	Dowolny CVV
Visa (odrzucona)	`4111 1111 1111 1105`	Do Not Honor
Visa (brak środków)	`4111 1111 1111 1151`	Insufficient Funds

Użyj dowolnej przyszłej daty ważności i dowolnego 3-cyfrowego CVC.

Aplikacja demonstracyjna

Aplikacja demonstracyjna oparta na Flask jest dołączona w repozytorium GitHub do testowania pełnego przepływu płatności.

Wsparcie

Potrzebujesz pomocy? Skontaktuj się z naszym zespołem wsparcia pod adresem support@costplus.io.

On this page