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
- Python 3.10 alebo novsi
- Ucet obchodnika Cost+ -- dashboard.costplus.io
Instalacia
pip install nopayn-sdkRychly 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 objednavky3. 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 "", 200API referencia
NoPaynClient(api_key, merchant_id, base_url?)
| Parameter | Typ | Povinne | Predvolene |
|---|---|---|---|
api_key | str | Ano | -- |
merchant_id | str | Ano | -- |
base_url | str | Nie | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Vytvori objednavku cez POST /v1/orders/.
| Parameter | Typ | Povinne | Popis |
|---|---|---|---|
amount | int | áno | Suma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR) |
currency | str | Ano | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Nie | Vasa interna referencia objednavky |
description | str | Nie | Popis objednavky |
return_url | str | Nie | Presmerovanie po uspesnej platbe |
failure_url | str | Nie | Presmerovanie pri zruseni/exspiracii/chybe |
webhook_url | str | Nie | Asynchronne notifikacie o zmene stavu |
locale | str | Nie | Jazyk HPP (en-GB, de-DE, nl-NL, atd.) |
payment_methods | list[str] | Nie | Filter platobnych metod HPP |
expiration_period | str | Nie | ISO 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:
| Trieda | Polia |
|---|---|
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 |
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 chybaStavy objednavok
| Stav | Koncovy? | Popis |
|---|---|---|
new | Nie | Objednavka vytvorena |
processing | Nie | Platba prebieha |
completed | Ano | Platba uspesna -- doructe tovar |
cancelled | Ano | Platba zrusena zakaznikom |
expired | Ano | Platobny odkaz vyprsal |
error | Ano | Technicka chyba |
Osvedcene postupy pre webhooky
- Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK
verify_webhook()to robi automaticky. - Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
- Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte
get_order()ako bezpecnostnu siet. - Budte idempotentni -- ten isty webhook mozete prijat viackrat.
Testovacie karty
Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):
| Karta | Cislo | Poznamky |
|---|---|---|
| Visa (uspech) | 4111 1111 1111 1111 | Akekolvek CVV |
| Mastercard (uspech) | 5544 3300 0003 7 | Akekolvek CVV |
| Visa (zamietnutie) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedostatok prostriedkov) | 4111 1111 1111 1151 | Insufficient 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.