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
- Python 3.10 oder neuer
- Ein Cost+ Händlerkonto — dashboard.costplus.io
Installation
pip install nopayn-sdkSchnellstart
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 UUID3. 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 "", 200API-Referenz
NoPaynClient(api_key, merchant_id, base_url?)
| Parameter | Typ | Erforderlich | Standard |
|---|---|---|---|
api_key | str | Ja | — |
merchant_id | str | Ja | — |
base_url | str | Nein | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Erstellt eine Bestellung über POST /v1/orders/.
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
amount | int | Ja | Betrag in kleinster Währungseinheit (Cent) |
currency | str | Ja | ISO 4217 Code (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Nein | Ihre interne Bestellreferenz |
description | str | Nein | Bestellbeschreibung |
return_url | str | Nein | Weiterleitung nach erfolgreicher Zahlung |
failure_url | str | Nein | Weiterleitung bei Abbruch/Ablauf/Fehler |
webhook_url | str | Nein | Asynchrone Statusänderungs-Benachrichtigungen |
locale | str | Nein | HPP-Sprache (en-GB, de-DE, nl-NL usw.) |
payment_methods | list[str] | Nein | HPP-Methoden filtern |
expiration_period | str | Nein | ISO 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:
| Klasse | Felder |
|---|---|
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 |
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 errorBestellungsstatus
| Status | Endgültig? | Beschreibung |
|---|---|---|
new | Nein | Bestellung erstellt |
processing | Nein | Zahlung in Bearbeitung |
completed | Ja | Zahlung erfolgreich — Ware liefern |
cancelled | Ja | Zahlung vom Kunden storniert |
expired | Ja | Zahlungslink abgelaufen |
error | Ja | Technischer Fehler |
Webhook Best Practices
- 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. - HTTP 200 zurückgeben, um den Empfang zu bestätigen. Jeder andere Code löst bis zu 10 Wiederholungsversuche aus (im 2-Minuten-Abstand).
- Backup-Poller implementieren — für Bestellungen, die älter als 10 Minuten sind und noch keinen Endstatus erreicht haben,
get_order()als Sicherheitsnetz abfragen. - Idempotent sein — Sie können denselben Webhook mehrfach erhalten.
Testkarten
Verwenden Sie diese Karten im Cost+ Testmodus (Sandbox-Website):
| Karte | Nummer | Hinweise |
|---|---|---|
| Visa (Erfolg) | 4111 1111 1111 1111 | Beliebiger CVV |
| Mastercard (Erfolg) | 5544 3300 0003 7 | Beliebiger CVV |
| Visa (abgelehnt) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (unzureichendes Guthaben) | 4111 1111 1111 1151 | Insufficient 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.