Python
Hivatalos Python SDK a Cost+ fizetési átjáróhoz
Hivatalos Python SDK a Cost+ fizetési átjáróhoz. Egyszerűsíti a HPP (tárolt fizetési oldal) átirányítási folyamatot, a HMAC adatcsomag-aláírást és a webhook ellenőrzést.
Funkciók
- Minimális függőségek — csak
requests - Teljes típusjelölések és fagyasztott adatosztály visszatérési típusok
- HMAC-SHA256 aláírás generálás és állandó idejű ellenőrzés
- Webhook feldolgozás + API-alapú rendelés ellenőrzés
- Tesztelve Python 3.10, 3.11 és 3.12 verziókkal
Követelmények
- Python 3.10 vagy újabb
- Cost+ kereskedői fiók — dashboard.costplus.io
Telepítés
pip install nopayn-sdkGyorsindítás
1. A kliens inicializálása
from nopayn import NoPaynClient
client = NoPaynClient(
api_key="your-api-key",
merchant_id="your-project",
)2. Fizetés létrehozása és átirányítás a HPP-re
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 kezelése (Flask példa)
@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-referencia
NoPaynClient(api_key, merchant_id, base_url?)
| Paraméter | Típus | Kötelező | Alapértelmezett |
|---|---|---|---|
api_key | str | Igen | — |
merchant_id | str | Igen | — |
base_url | str | Nem | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Rendelést hoz létre a POST /v1/orders/ végponton.
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
amount | int | Igen | Összeg a legkisebb pénznem-egységben (cent) |
currency | str | Igen | ISO 4217 kód (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Nem | Az Ön belső rendelési hivatkozása |
description | str | Nem | Rendelés leírása |
return_url | str | Nem | Átirányítás sikeres fizetés után |
failure_url | str | Nem | Átirányítás törlés/lejárat/hiba esetén |
webhook_url | str | Nem | Aszinkron állapotváltozási értesítések |
locale | str | Nem | HPP nyelv (en-GB, de-DE, nl-NL stb.) |
payment_methods | list[str] | Nem | HPP módok szűrése |
expiration_period | str | Nem | ISO 8601 időtartam (PT30M) |
Elérhető fizetési módok: credit-card, apple-pay, google-pay, vipps-mobilepay
client.get_order(order_id) -> Order
Rendelés részleteinek lekérdezése a GET /v1/orders/{id}/ végponton.
client.create_refund(order_id, amount, description?) -> Refund
Teljes vagy részleges visszatérítés kiadása a POST /v1/orders/{id}/refunds/ végponton.
client.generate_payment_url(**kwargs) -> PaymentUrlResult
Kényelmi metódus, amely rendelést hoz létre és visszaadja:
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 aláírást generál.
client.verify_signature(amount, currency, order_id, signature) -> bool
HMAC-SHA256 aláírás állandó idejű ellenőrzése.
client.verify_webhook(raw_body) -> VerifiedWebhook
Feldolgozza a webhook törzset, majd meghívja a GET /v1/orders/{id}/ végpontot az aktuális állapot ellenőrzéséhez.
Önálló HMAC segédeszközök
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)Adattípusok
Minden API-válasz fagyasztott adatosztályként kerül visszaadásra:
| Osztály | Mezők |
|---|---|
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 |
Hibakezelés
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 errorRendelés állapotok
| Állapot | Végleges? | Leírás |
|---|---|---|
new | Nem | Rendelés létrehozva |
processing | Nem | Fizetés folyamatban |
completed | Igen | Fizetés sikeres — szállítsa az árut |
cancelled | Igen | Fizetés törölve az ügyfél által |
expired | Igen | A fizetési link lejárt |
error | Igen | Technikai hiba |
Webhook bevált gyakorlatok
- Mindig ellenőrizze az API-n keresztül — a webhook adatcsomag csak a rendelés azonosítóját tartalmazza, soha nem az állapotot. Az SDK
verify_webhook()metódusa ezt automatikusan elvégzi. - Válaszoljon HTTP 200-zal a fogadás nyugtázásához. Bármely más kód legfeljebb 10 újrapróbálkozást vált ki (2 percenként).
- Alkalmazzon tartalék lekérdezést — a 10 percnél régebbi, végleges állapotot még el nem ért rendelésekhez kérdezze le a
get_order()metódust biztonsági hálóként. - Legyen idempotens — ugyanazt a webhookot többször is megkaphatja.
Tesztkártyák
Használja ezeket a kártyákat Cost+ teszt módban (sandbox weboldal):
| Kártya | Szám | Megjegyzés |
|---|---|---|
| Visa (sikeres) | 4111 1111 1111 1111 | Bármely CVV |
| Mastercard (sikeres) | 5544 3300 0003 7 | Bármely CVV |
| Visa (elutasítva) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (elégtelen fedezet) | 4111 1111 1111 1151 | Insufficient Funds |
Használjon bármely jövőbeli lejárati dátumot és bármely 3 számjegyű CVC-t.
Demo alkalmazás
Egy Flask-alapú demo alkalmazás található a GitHub tárolóban a teljes fizetési folyamat teszteléséhez.
Támogatás
Segítségre van szüksége? Forduljon ügyfélszolgálatunkhoz: support@costplus.io.