Cost+Docs

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

Telepítés

pip install nopayn-sdk

Gyorsindí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 UUID

3. 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 "", 200

API-referencia

NoPaynClient(api_key, merchant_id, base_url?)

ParaméterTípusKötelezőAlapértelmezett
api_keystrIgen
merchant_idstrIgen
base_urlstrNemhttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Rendelést hoz létre a POST /v1/orders/ végponton.

ParaméterTípusKötelezőLeírás
amountintIgenÖsszeg a legkisebb pénznem-egységben (cent)
currencystrIgenISO 4217 kód (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNemAz Ön belső rendelési hivatkozása
descriptionstrNemRendelés leírása
return_urlstrNemÁtirányítás sikeres fizetés után
failure_urlstrNemÁtirányítás törlés/lejárat/hiba esetén
webhook_urlstrNemAszinkron állapotváltozási értesítések
localestrNemHPP nyelv (en-GB, de-DE, nl-NL stb.)
payment_methodslist[str]NemHPP módok szűrése
expiration_periodstrNemISO 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ályMezők
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

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 error

Rendelés állapotok

ÁllapotVégleges?Leírás
newNemRendelés létrehozva
processingNemFizetés folyamatban
completedIgenFizetés sikeres — szállítsa az árut
cancelledIgenFizetés törölve az ügyfél által
expiredIgenA fizetési link lejárt
errorIgenTechnikai hiba

Webhook bevált gyakorlatok

  1. 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.
  2. 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).
  3. 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.
  4. 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ártyaSzámMegjegyzés
Visa (sikeres)4111 1111 1111 1111Bármely CVV
Mastercard (sikeres)5544 3300 0003 7Bármely CVV
Visa (elutasítva)4111 1111 1111 1105Do Not Honor
Visa (elégtelen fedezet)4111 1111 1111 1151Insufficient 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.

On this page