Cost+Docs

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

Instalace

pip install nopayn-sdk

Rychlý 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 UUID

3. 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 "", 200

API reference

NoPaynClient(api_key, merchant_id, base_url?)

ParametrTypPovinnéVýchozí
api_keystrAno
merchant_idstrAno
base_urlstrNehttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Vytvoří objednávku přes POST /v1/orders/.

ParametrTypPovinnéPopis
amountintAnoČástka v nejmenší měnové jednotce (centy)
currencystrAnoISO 4217 kód (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNeVaše interní reference objednávky
descriptionstrNePopis objednávky
return_urlstrNePřesměrování po úspěšné platbě
failure_urlstrNePřesměrování při zrušení/vypršení/chybě
webhook_urlstrNeAsynchronní notifikace o změně stavu
localestrNeJazyk HPP (en-GB, de-DE, nl-NL atd.)
payment_methodslist[str]NeFiltr metod HPP
expiration_periodstrNeISO 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řídaPole
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

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 error

Stavy objednávek

StavKonečný?Popis
newNeObjednávka vytvořena
processingNePlatba probíhá
completedAnoPlatba úspěšná — doručte zboží
cancelledAnoPlatba zrušena zákazníkem
expiredAnoPlatební odkaz vypršel
errorAnoTechnická chyba

Osvědčené postupy pro webhooky

  1. Vždy ověřte přes API — webhookový payload obsahuje pouze ID objednávky, nikdy stav. Metoda verify_webhook() SDK to dělá automaticky.
  2. Vraťte HTTP 200 jako potvrzení přijetí. Jakýkoli jiný kód spustí až 10 opakování (po 2 minutách).
  3. 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íť.
  4. 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ČísloPoznámky
Visa (úspěch)4111 1111 1111 1111Libovolné CVV
Mastercard (úspěch)5544 3300 0003 7Libovolné CVV
Visa (zamítnuto)4111 1111 1111 1105Do Not Honor
Visa (nedostatek prostředků)4111 1111 1111 1151Insufficient 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.

On this page