Cost+Docs

Python

Oficialne Python SDK pre platobnu branu Cost+

Oficialne Python SDK pre platobnu branu Cost+. Zjednodusuje proces presmerovania HPP (Hosted Payment Page), HMAC podpisovanie payloadov a overovanie webhookov.

Funkcie

  • Minimalne zavislosti -- len requests
  • Uplne type hints a frozen dataclass navratove typy
  • HMAC-SHA256 generovanie podpisov a overovanie v konstantnom case
  • Parsovanie webhookov + overovanie objednavok na zaklade API
  • Testovane na Python 3.10, 3.11 a 3.12

Poziadavky

Instalacia

pip install nopayn-sdk

Rychly start

1. Inicializacia klienta

from nopayn import NoPaynClient

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

2. Vytvorenie platby a presmerovanie na HPP

result = client.generate_payment_url(
    amount=1295,             # €12,95 v centoch
    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",
)

# Presmerujte zakaznika
# result.order_url   → HPP (zakaznik si vyberie platobnu metodu)
# result.payment_url → priamy odkaz na platobnu metodu prvej transakcie
# result.signature   → HMAC-SHA256 na overenie
# result.order_id    → NoPayn UUID objednavky

3. Spracovanie webhooku (priklad Flask)

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

    print(verified.order.status)  # 'completed', 'cancelled', atd.
    print(verified.is_final)      # True, ked sa objednavka uz nezmeni

    if verified.order.status == "completed":
        # Vybavte objednavku
        pass

    return "", 200

API referencia

NoPaynClient(api_key, merchant_id, base_url?)

ParameterTypPovinnePredvolene
api_keystrAno--
merchant_idstrAno--
base_urlstrNiehttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Vytvori objednavku cez POST /v1/orders/.

ParameterTypPovinnePopis
amountintánoSuma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR)
currencystrAnoISO 4217 kod (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNieVasa interna referencia objednavky
descriptionstrNiePopis objednavky
return_urlstrNiePresmerovanie po uspesnej platbe
failure_urlstrNiePresmerovanie pri zruseni/exspiracii/chybe
webhook_urlstrNieAsynchronne notifikacie o zmene stavu
localestrNieJazyk HPP (en-GB, de-DE, nl-NL, atd.)
payment_methodslist[str]NieFilter platobnych metod HPP
expiration_periodstrNieISO 8601 trvanie (PT30M)

Dostupne platobne metody: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Ziskanie podrobnosti objednavky cez GET /v1/orders/{id}/.

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

Vydanie uplneho alebo ciastocneho vratenia cez POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Pomocna metoda, ktora vytvori objednavku a vrati:

PaymentUrlResult(
    order_id="...",       # NoPayn UUID objednavky
    order_url="...",      # HPP URL
    payment_url="...",    # Priama platobna URL (prva transakcia)
    signature="...",      # HMAC-SHA256 z amount:currency:order_id
    order=Order(...),     # Uplny objekt objednavky
)

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

Generuje HMAC-SHA256 hex podpis.

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

Overovanie HMAC-SHA256 podpisu v konstantnom case.

client.verify_webhook(raw_body) -> VerifiedWebhook

Parsuje telo webhooku, potom vola GET /v1/orders/{id}/ na overenie skutocneho stavu.

Samostatne HMAC nastroje

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)

Datove typy

Vsetky API odpovede sa vracaju ako frozen dataclasses:

TriedaPolia
Orderid, amount, currency, status, created, modified, transactions, description, merchant_order_id, return_url, failure_url, order_url, completed
Transactionid, amount, currency, status, created, modified, payment_method, payment_url, expiration_period
Refundid, amount, status
PaymentUrlResultorder_id, order_url, payment_url, signature, order
VerifiedWebhookorder_id, order, is_final

Spracovanie chyb

from nopayn import ApiError, NoPaynError, WebhookError

try:
    client.create_order(amount=100, currency="EUR")
except ApiError as exc:
    print(exc.status_code)  # 401, 400, atd.
    print(exc.error_body)   # Surova API chybova odpoved
except NoPaynError as exc:
    print(exc)              # Sietova alebo parsovania chyba

Stavy objednavok

StavKoncovy?Popis
newNieObjednavka vytvorena
processingNiePlatba prebieha
completedAnoPlatba uspesna -- doructe tovar
cancelledAnoPlatba zrusena zakaznikom
expiredAnoPlatobny odkaz vyprsal
errorAnoTechnicka chyba

Osvedcene postupy pre webhooky

  1. Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK verify_webhook() to robi automaticky.
  2. Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
  3. Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte get_order() ako bezpecnostnu siet.
  4. Budte idempotentni -- ten isty webhook mozete prijat viackrat.

Testovacie karty

Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):

KartaCisloPoznamky
Visa (uspech)4111 1111 1111 1111Akekolvek CVV
Mastercard (uspech)5544 3300 0003 7Akekolvek CVV
Visa (zamietnutie)4111 1111 1111 1105Do Not Honor
Visa (nedostatok prostriedkov)4111 1111 1111 1151Insufficient Funds

Pouzite akykolvek buduci datum exspiracie a akykolvek 3-ciselny CVC.

Demo aplikacia

Demo aplikacia na baze Flask je zahrnuta v GitHub repozitari na testovanie uplneho platobneho procesu.

Podpora

Potrebujete pomoc? Kontaktujte nas tym podpory na support@costplus.io.

On this page