Cost+Docs

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

Απαιτήσεις

Εγκατάσταση

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 UUID

3. Διαχείριση του 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_keystrΝαι
merchant_idstrΝαι
base_urlstrΌχιhttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Δημιουργεί παραγγελία μέσω POST /v1/orders/.

ΠαράμετροςΤύποςΑπαιτούμενηΠεριγραφή
amountintΝαιΠοσό στη μικρότερη μονάδα νομίσματος (λεπτά)
currencystrΝαιΚωδικός ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrΌχιΗ εσωτερική αναφορά παραγγελίας σας
descriptionstrΌχιΠεριγραφή παραγγελίας
return_urlstrΌχιΑνακατεύθυνση μετά από επιτυχή πληρωμή
failure_urlstrΌχιΑνακατεύθυνση σε ακύρωση/λήξη/σφάλμα
webhook_urlstrΌχιΑσύγχρονες ειδοποιήσεις αλλαγής κατάστασης
localestrΌχιΓλώσσα HPP (en-GB, de-DE, nl-NL, κ.λπ.)
payment_methodslist[str]ΌχιΦιλτράρισμα μεθόδων HPP
expiration_periodstrΌχιΔιάρκεια 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:

ΚλάσηΠεδία
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

Διαχείριση Σφαλμάτων

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

  1. Πάντα επαληθεύετε μέσω API — το payload webhook περιέχει μόνο το αναγνωριστικό παραγγελίας, ποτέ την κατάσταση. Η μέθοδος verify_webhook() του SDK το κάνει αυτόματα.
  2. Επιστρέψτε HTTP 200 για επιβεβαίωση λήψης. Οποιοσδήποτε άλλος κωδικός ενεργοποιεί έως 10 επαναπροσπάθειες (2 λεπτά μεταξύ τους).
  3. Υλοποιήστε εφεδρικό poller — για παραγγελίες παλαιότερες από 10 λεπτά που δεν έχουν φτάσει σε τελική κατάσταση, κάντε polling get_order() ως δίχτυ ασφαλείας.
  4. Να είστε idempotent — μπορεί να λάβετε το ίδιο webhook πολλές φορές.

Δοκιμαστικές Κάρτες

Χρησιμοποιήστε αυτές τις κάρτες στη δοκιμαστική λειτουργία Cost+ (ιστοσελίδα sandbox):

ΚάρταΑριθμόςΣημειώσεις
Visa (επιτυχία)4111 1111 1111 1111Οποιοδήποτε CVV
Mastercard (επιτυχία)5544 3300 0003 7Οποιοδήποτε CVV
Visa (απόρριψη)4111 1111 1111 1105Do Not Honor
Visa (ανεπαρκές υπόλοιπο)4111 1111 1111 1151Insufficient Funds

Χρησιμοποιήστε οποιαδήποτε μελλοντική ημερομηνία λήξης και οποιοδήποτε 3ψήφιο CVC.

Εφαρμογή Επίδειξης

Μια εφαρμογή επίδειξης βασισμένη σε Flask περιλαμβάνεται στο αποθετήριο GitHub για δοκιμή πλήρους ροής πληρωμής.

Υποστήριξη

Χρειάζεστε βοήθεια; Επικοινωνήστε με την ομάδα υποστήριξης στο support@costplus.io.

On this page