Cost+Docs

Python

Uradni Python SDK za plačilni prehod Cost+

Uradni Python SDK za plačilni prehod Cost+. Poenostavlja tok preusmeritve HPP (gostovane plačilne strani), HMAC podpisovanje koristnih podatkov in preverjanje webhook-ov.

Lastnosti

  • Minimalne odvisnosti — samo requests
  • Polni type hints in zamrznjeni dataclass tipi vrnjenih vrednosti
  • HMAC-SHA256 generiranje podpisov in preverjanje s konstantnim časom
  • Razčlenjevanje webhook-ov + preverjanje naročil na osnovi API-ja
  • Testirano na Python 3.10, 3.11 in 3.12

Zahteve

Namestitev

pip install nopayn-sdk

Hitri začetek

1. Inicializirajte odjemalca

from nopayn import NoPaynClient

client = NoPaynClient(
    api_key="your-api-key",
    merchant_id="your-project",
)

2. Ustvarite plačilo in preusmerite na 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",
)

# Preusmerite stranko
# result.order_url   → HPP (stranka izbere plačilno metodo)
# result.payment_url → neposredna povezava do plačilne metode prve transakcije
# result.signature   → HMAC-SHA256 za preverjanje
# result.order_id    → NoPayn UUID naročila

3. Obdelajte webhook (primer 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":
        # Izpolnite naročilo
        pass

    return "", 200

API referenca

NoPaynClient(api_key, merchant_id, base_url?)

ParameterTipObveznoPrivzeto
api_keystrDa—
merchant_idstrDa—
base_urlstrNehttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Ustvari naročilo prek POST /v1/orders/.

ParameterTipObveznoOpis
amountintjaZnesek v manjši enoti ISO 4217 valute (na primer centi za EUR)
currencystrDaKoda ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNeVaša interna referenca naročila
descriptionstrNeOpis naročila
return_urlstrNePreusmeritev po uspešnem plačilu
failure_urlstrNePreusmeritev ob preklicu/poteku/napaki
webhook_urlstrNeAsinhrona obvestila o spremembi statusa
localestrNeJezik HPP (en-GB, de-DE, nl-NL itd.)
payment_methodslist[str]NeFiltriraj metode HPP
expiration_periodstrNeTrajanje ISO 8601 (PT30M)

Razpoložljive plačilne metode: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Pridobi podrobnosti naročila prek GET /v1/orders/{id}/.

client.create_refund(order_id, amount, description?) -> Refund

Izda celotno ali delno vračilo prek POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Priročna metoda, ki ustvari naročilo in vrne:

PaymentUrlResult(
    order_id="...",       # NoPayn UUID naročila
    order_url="...",      # HPP URL
    payment_url="...",    # Neposredni plačilni URL (prva transakcija)
    signature="...",      # HMAC-SHA256 od amount:currency:order_id
    order=Order(...),     # Celoten objekt naročila
)

client.generate_signature(amount, currency, order_id) -> str

Generira HMAC-SHA256 šestnajstiški podpis.

client.verify_signature(amount, currency, order_id, signature) -> bool

Preverjanje HMAC-SHA256 podpisa s konstantnim časom.

client.verify_webhook(raw_body) -> VerifiedWebhook

Razčleni telo webhook-a, nato pokliče GET /v1/orders/{id}/ za preverjanje dejanskega statusa.

Samostojne HMAC pripomočke

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)

Podatkovni tipi

Vsi API odgovori so vrnjeni kot zamrznjeni dataclass objekti:

RazredPolja
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

Obravnava napak

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

Statusi naročil

StatusKončni?Opis
newNeNaročilo ustvarjeno
processingNePlačilo v teku
completedDaPlačilo uspešno — dostavite blago
cancelledDaPlačilo preklicano s strani stranke
expiredDaPlačilna povezava je potekla
errorDaTehnična napaka

Najboljše prakse za webhook-e

  1. Vedno preverite prek API-ja — koristni podatki webhook-a vsebujejo samo ID naročila, nikoli statusa. SDK-jev verify_webhook() to naredi samodejno.
  2. Vrnite HTTP 200 za potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
  3. Implementirajte rezervno poizvedovanje — za naročila, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte get_order() kot varnostno mrežo.
  4. Bodite idempotentni — isti webhook lahko prejmete večkrat.

Testne kartice

Uporabite te kartice v testnem načinu Cost+ (spletno mesto peskovnika):

KarticaŠtevilkaOpombe
Visa (uspeh)4111 1111 1111 1111Katerikoli CVV
Mastercard (uspeh)5544 3300 0003 7Katerikoli CVV
Visa (zavrnjena)4111 1111 1111 1105Zavrnitev
Visa (nezadostna sredstva)4111 1111 1111 1151Nezadostna sredstva

Uporabite katerikoli prihodnji datum veljavnosti in katerokoli 3-mestno CVC kodo.

Predstavitvena aplikacija

Predstavitvena aplikacija na osnovi Flask je vključena v GitHub repozitorij za testiranje celotnega plačilnega toka.

Podpora

Potrebujete pomoč? Obrnite se na našo ekipo za podporo na support@costplus.io.

On this page