Python
Επίσημο Python SDK για την πύλη πληρωμών Cost+
Επίσημο Python SDK για την πύλη πληρωμών Cost+. Απλοποιεί τη ροή ανακατεύθυνσης HPP (Φιλοξενούμενη Σελίδα Πληρωμής), την υπογραφή HMAC payload και την επαλήθευση webhook.
Χαρακτηριστικά
- Ελάχιστες εξαρτήσεις — μόνο
requests - Πλήρη type hints και frozen dataclass τύποι επιστροφής
- Δημιουργία υπογραφής HMAC-SHA256 και επαλήθευση σταθερού χρόνου
- Ανάλυση webhook + επαλήθευση παραγγελίας μέσω API
- Δοκιμασμένο σε Python 3.10, 3.11 και 3.12
Απαιτήσεις
- Python 3.10 ή νεότερο
- Λογαριασμός εμπόρου Cost+ — dashboard.costplus.io
Εγκατάσταση
pip install nopayn-sdkΓρήγορη Εκκίνηση
1. Αρχικοποίηση του Client
from nopayn import NoPaynClient
client = NoPaynClient(
api_key="your-api-key",
merchant_id="your-project",
)2. Δημιουργία Πληρωμής και Ανακατεύθυνση στο 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. Διαχείριση του Webhook (Παράδειγμα 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
NoPaynClient(api_key, merchant_id, base_url?)
| Παράμετρος | Τύπος | Απαιτούμενη | Προεπιλογή |
|---|---|---|---|
api_key | str | Ναι | — |
merchant_id | str | Ναι | — |
base_url | str | Όχι | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Δημιουργεί παραγγελία μέσω POST /v1/orders/.
| Παράμετρος | Τύπος | Απαιτούμενη | Περιγραφή |
|---|---|---|---|
amount | int | Ναι | Ποσό στη μικρότερη μονάδα νομίσματος (λεπτά) |
currency | str | Ναι | Κωδικός ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Όχι | Η εσωτερική αναφορά παραγγελίας σας |
description | str | Όχι | Περιγραφή παραγγελίας |
return_url | str | Όχι | Ανακατεύθυνση μετά από επιτυχή πληρωμή |
failure_url | str | Όχι | Ανακατεύθυνση σε ακύρωση/λήξη/σφάλμα |
webhook_url | str | Όχι | Ασύγχρονες ειδοποιήσεις αλλαγής κατάστασης |
locale | str | Όχι | Γλώσσα HPP (en-GB, de-DE, nl-NL, κ.λπ.) |
payment_methods | list[str] | Όχι | Φιλτράρισμα μεθόδων HPP |
expiration_period | str | Όχι | Διάρκεια ISO 8601 (PT30M) |
Διαθέσιμες μέθοδοι πληρωμής: credit-card, apple-pay, google-pay, vipps-mobilepay
client.get_order(order_id) -> Order
Ανακτά λεπτομέρειες παραγγελίας μέσω GET /v1/orders/{id}/.
client.create_refund(order_id, amount, description?) -> Refund
Εκδίδει πλήρη ή μερική επιστροφή χρημάτων μέσω POST /v1/orders/{id}/refunds/.
client.generate_payment_url(**kwargs) -> PaymentUrlResult
Μέθοδος ευκολίας που δημιουργεί παραγγελία και επιστρέφει:
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
Δημιουργεί υπογραφή HMAC-SHA256 σε hex.
client.verify_signature(amount, currency, order_id, signature) -> bool
Επαλήθευση σταθερού χρόνου υπογραφής HMAC-SHA256.
client.verify_webhook(raw_body) -> VerifiedWebhook
Αναλύει το σώμα webhook, στη συνέχεια καλεί GET /v1/orders/{id}/ για επαλήθευση πραγματικής κατάστασης.
Αυτόνομα Εργαλεία HMAC
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)Τύποι Δεδομένων
Όλες οι αποκρίσεις API επιστρέφονται ως frozen dataclasses:
| Κλάση | Πεδία |
|---|---|
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 |
Διαχείριση Σφαλμάτων
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Καταστάσεις Παραγγελίας
| Κατάσταση | Τελική; | Περιγραφή |
|---|---|---|
new | Όχι | Η παραγγελία δημιουργήθηκε |
processing | Όχι | Πληρωμή σε εξέλιξη |
completed | Ναι | Η πληρωμή ήταν επιτυχής — παραδώστε τα αγαθά |
cancelled | Ναι | Η πληρωμή ακυρώθηκε από τον πελάτη |
expired | Ναι | Ο σύνδεσμος πληρωμής έληξε |
error | Ναι | Τεχνική αποτυχία |
Βέλτιστες Πρακτικές Webhook
- Πάντα επαληθεύετε μέσω API — το payload webhook περιέχει μόνο το αναγνωριστικό παραγγελίας, ποτέ την κατάσταση. Η μέθοδος
verify_webhook()του SDK το κάνει αυτόματα. - Επιστρέψτε HTTP 200 για επιβεβαίωση λήψης. Οποιοσδήποτε άλλος κωδικός ενεργοποιεί έως 10 επαναπροσπάθειες (2 λεπτά μεταξύ τους).
- Υλοποιήστε εφεδρικό poller — για παραγγελίες παλαιότερες από 10 λεπτά που δεν έχουν φτάσει σε τελική κατάσταση, κάντε polling
get_order()ως δίχτυ ασφαλείας. - Να είστε idempotent — μπορεί να λάβετε το ίδιο webhook πολλές φορές.
Δοκιμαστικές Κάρτες
Χρησιμοποιήστε αυτές τις κάρτες στη δοκιμαστική λειτουργία Cost+ (ιστοσελίδα sandbox):
| Κάρτα | Αριθμός | Σημειώσεις |
|---|---|---|
| Visa (επιτυχία) | 4111 1111 1111 1111 | Οποιοδήποτε CVV |
| Mastercard (επιτυχία) | 5544 3300 0003 7 | Οποιοδήποτε CVV |
| Visa (απόρριψη) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (ανεπαρκές υπόλοιπο) | 4111 1111 1111 1151 | Insufficient Funds |
Χρησιμοποιήστε οποιαδήποτε μελλοντική ημερομηνία λήξης και οποιοδήποτε 3ψήφιο CVC.
Εφαρμογή Επίδειξης
Μια εφαρμογή επίδειξης βασισμένη σε Flask περιλαμβάνεται στο αποθετήριο GitHub για δοκιμή πλήρους ροής πληρωμής.
Υποστήριξη
Χρειάζεστε βοήθεια; Επικοινωνήστε με την ομάδα υποστήριξης στο support@costplus.io.