Cost+Docs

Python

Offizielles Python SDK für das Cost+ Zahlungsgateway

Offizielles Python SDK für das Cost+ Zahlungsgateway. Vereinfacht den HPP (Hosted Payment Page) Weiterleitungsablauf, die HMAC-Payload-Signierung und die Webhook-Verifizierung.

Funktionen

  • Minimale Abhängigkeiten — nur requests
  • Vollständige Type-Hints und Frozen-Dataclass-Rückgabetypen
  • HMAC-SHA256-Signaturgenerierung und zeitkonstante Verifizierung
  • Webhook-Parsing + API-basierte Bestellungsverifizierung
  • Getestet mit Python 3.10, 3.11 und 3.12

Voraussetzungen

Installation

pip install nopayn-sdk

Schnellstart

1. Client initialisieren

from nopayn import NoPaynClient

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

2. Zahlung erstellen und zur HPP weiterleiten

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. Webhook verarbeiten (Flask-Beispiel)

@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-Referenz

NoPaynClient(api_key, merchant_id, base_url?)

ParameterTypErforderlichStandard
api_keystrJa
merchant_idstrJa
base_urlstrNeinhttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Erstellt eine Bestellung über POST /v1/orders/.

ParameterTypErforderlichBeschreibung
amountintJaBetrag in kleinster Währungseinheit (Cent)
currencystrJaISO 4217 Code (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNeinIhre interne Bestellreferenz
descriptionstrNeinBestellbeschreibung
return_urlstrNeinWeiterleitung nach erfolgreicher Zahlung
failure_urlstrNeinWeiterleitung bei Abbruch/Ablauf/Fehler
webhook_urlstrNeinAsynchrone Statusänderungs-Benachrichtigungen
localestrNeinHPP-Sprache (en-GB, de-DE, nl-NL usw.)
payment_methodslist[str]NeinHPP-Methoden filtern
expiration_periodstrNeinISO 8601 Dauer (PT30M)

Verfügbare Zahlungsmethoden: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Ruft Bestellungsdetails über GET /v1/orders/{id}/ ab.

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

Stellt eine vollständige oder teilweise Erstattung über POST /v1/orders/{id}/refunds/ aus.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Komfortmethode, die eine Bestellung erstellt und zurückgibt:

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

Generiert eine HMAC-SHA256-Hex-Signatur.

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

Zeitkonstante Verifizierung einer HMAC-SHA256-Signatur.

client.verify_webhook(raw_body) -> VerifiedWebhook

Parst den Webhook-Body und ruft dann GET /v1/orders/{id}/ auf, um den tatsächlichen Status zu verifizieren.

Eigenständige HMAC-Hilfsfunktionen

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)

Datentypen

Alle API-Antworten werden als Frozen-Dataclasses zurückgegeben:

KlasseFelder
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

Fehlerbehandlung

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

Bestellungsstatus

StatusEndgültig?Beschreibung
newNeinBestellung erstellt
processingNeinZahlung in Bearbeitung
completedJaZahlung erfolgreich — Ware liefern
cancelledJaZahlung vom Kunden storniert
expiredJaZahlungslink abgelaufen
errorJaTechnischer Fehler

Webhook Best Practices

  1. Immer über die API verifizieren — der Webhook-Payload enthält nur die Bestell-ID, niemals den Status. Die verify_webhook()-Methode des SDK erledigt dies automatisch.
  2. HTTP 200 zurückgeben, um den Empfang zu bestätigen. Jeder andere Code löst bis zu 10 Wiederholungsversuche aus (im 2-Minuten-Abstand).
  3. Backup-Poller implementieren — für Bestellungen, die älter als 10 Minuten sind und noch keinen Endstatus erreicht haben, get_order() als Sicherheitsnetz abfragen.
  4. Idempotent sein — Sie können denselben Webhook mehrfach erhalten.

Testkarten

Verwenden Sie diese Karten im Cost+ Testmodus (Sandbox-Website):

KarteNummerHinweise
Visa (Erfolg)4111 1111 1111 1111Beliebiger CVV
Mastercard (Erfolg)5544 3300 0003 7Beliebiger CVV
Visa (abgelehnt)4111 1111 1111 1105Do Not Honor
Visa (unzureichendes Guthaben)4111 1111 1111 1151Insufficient Funds

Verwenden Sie ein beliebiges zukünftiges Ablaufdatum und eine beliebige 3-stellige CVC.

Demo-App

Eine Flask-basierte Demo-App ist im GitHub-Repository enthalten, um den vollständigen Zahlungsablauf zu testen.

Support

Brauchen Sie Hilfe? Kontaktieren Sie unser Support-Team unter support@costplus.io.

On this page