Python
Oficiální Python SDK pro platební bránu Cost+
Oficiální Python SDK pro platební bránu Cost+. Zjednodušuje tok přesměrování HPP (Hosted Payment Page), HMAC podepisování payloadu a ověřování webhooků.
Funkce
- Minimální závislosti — pouze
requests - Plné type hints a návratové typy jako frozen dataclasses
- Generování podpisů HMAC-SHA256 a ověřování s konstantním časem
- Parsování webhooků + ověřování objednávek přes API
- Testováno na Python 3.10, 3.11 a 3.12
Požadavky
- Python 3.10 nebo novější
- Obchodní účet Cost+ — dashboard.costplus.io
Instalace
pip install nopayn-sdkRychlý start
1. Inicializace klienta
from nopayn import NoPaynClient
client = NoPaynClient(
api_key="your-api-key",
merchant_id="your-project",
)2. Vytvoření platby a přesměrování na HPP
result = client.generate_payment_url(
amount=1295, # €12.95 in cents
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",
)
# Redirect the customer
# result.order_url → HPP (customer picks payment method)
# result.payment_url → direct link to the first transaction's payment method
# result.signature → HMAC-SHA256 for verification
# result.order_id → NoPayn order UUID3. Zpracování webhooku (příklad Flask)
@app.route("/webhook", methods=["POST"])
def webhook():
verified = client.verify_webhook(request.get_data(as_text=True))
print(verified.order.status) # 'completed', 'cancelled', etc.
print(verified.is_final) # True when the order won't change
if verified.order.status == "completed":
# Fulfil the order
pass
return "", 200API reference
NoPaynClient(api_key, merchant_id, base_url?)
| Parametr | Typ | Povinné | Výchozí |
|---|---|---|---|
api_key | str | Ano | — |
merchant_id | str | Ano | — |
base_url | str | Ne | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Vytvoří objednávku přes POST /v1/orders/.
| Parametr | Typ | Povinné | Popis |
|---|---|---|---|
amount | int | Ano | Částka v nejmenší měnové jednotce (centy) |
currency | str | Ano | ISO 4217 kód (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Ne | Vaše interní reference objednávky |
description | str | Ne | Popis objednávky |
return_url | str | Ne | Přesměrování po úspěšné platbě |
failure_url | str | Ne | Přesměrování při zrušení/vypršení/chybě |
webhook_url | str | Ne | Asynchronní notifikace o změně stavu |
locale | str | Ne | Jazyk HPP (en-GB, de-DE, nl-NL atd.) |
payment_methods | list[str] | Ne | Filtr metod HPP |
expiration_period | str | Ne | ISO 8601 doba trvání (PT30M) |
Dostupné platební metody: credit-card, apple-pay, google-pay, vipps-mobilepay
client.get_order(order_id) -> Order
Načte detaily objednávky přes GET /v1/orders/{id}/.
client.create_refund(order_id, amount, description?) -> Refund
Provede úplnou nebo částečnou refundaci přes POST /v1/orders/{id}/refunds/.
client.generate_payment_url(**kwargs) -> PaymentUrlResult
Pohodlná metoda, která vytvoří objednávku a vrátí:
PaymentUrlResult(
order_id="...", # NoPayn order UUID
order_url="...", # HPP URL
payment_url="...", # Direct payment URL (first transaction)
signature="...", # HMAC-SHA256 of amount:currency:order_id
order=Order(...), # Full order object
)client.generate_signature(amount, currency, order_id) -> str
Generuje HMAC-SHA256 hex podpis.
client.verify_signature(amount, currency, order_id, signature) -> bool
Ověření HMAC-SHA256 podpisu s konstantním časem.
client.verify_webhook(raw_body) -> VerifiedWebhook
Parsuje tělo webhooku a poté zavolá GET /v1/orders/{id}/ pro ověření skutečného stavu.
Samostatné HMAC utility
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)Datové typy
Všechny API odpovědi jsou vráceny jako frozen dataclasses:
| Třída | Pole |
|---|---|
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 |
Zpracování 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, etc.
print(exc.error_body) # Raw API error response
except NoPaynError as exc:
print(exc) # Network or parsing errorStavy objednávek
| Stav | Konečný? | Popis |
|---|---|---|
new | Ne | Objednávka vytvořena |
processing | Ne | Platba probíhá |
completed | Ano | Platba úspěšná — doručte zboží |
cancelled | Ano | Platba zrušena zákazníkem |
expired | Ano | Platební odkaz vypršel |
error | Ano | Technická chyba |
Osvědčené postupy pro webhooky
- Vždy ověřte přes API — webhookový payload obsahuje pouze ID objednávky, nikdy stav. Metoda
verify_webhook()SDK to dělá automaticky. - Vraťte HTTP 200 jako potvrzení přijetí. Jakýkoli jiný kód spustí až 10 opakování (po 2 minutách).
- Implementujte záložní polling — pro objednávky starší než 10 minut, které nedosáhly konečného stavu, dotazujte
get_order()jako záchrannou síť. - Buďte idempotentní — stejný webhook můžete obdržet vícekrát.
Testovací karty
Tyto karty použijte v testovacím režimu Cost+ (sandbox web):
| Karta | Číslo | Poznámky |
|---|---|---|
| Visa (úspěch) | 4111 1111 1111 1111 | Libovolné CVV |
| Mastercard (úspěch) | 5544 3300 0003 7 | Libovolné CVV |
| Visa (zamítnuto) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedostatek prostředků) | 4111 1111 1111 1151 | Insufficient Funds |
Použijte libovolné budoucí datum platnosti a libovolný 3místný CVC.
Demo aplikace
Demo aplikace založená na Flasku je součástí GitHub repozitáře pro testování celého platebního toku.
Podpora
Potřebujete pomoc? Obraťte se na náš tým podpory na support@costplus.io.