Cost+Docs

Python

Službeni Python SDK za Cost+ platni pristupnik

Službeni Python SDK za Cost+ platni pristupnik. Pojednostavljuje tijek preusmjeravanja na HPP (hosted stranicu za plaćanje), HMAC potpisivanje podataka i verifikaciju webhookova.

Značajke

  • Minimalne ovisnosti — samo requests
  • Potpuni type hintovi i frozen dataclass povratni tipovi
  • HMAC-SHA256 generiranje potpisa i verifikacija konstantnim vremenom
  • Raščlamba webhookova + verifikacija narudžbe temeljena na API-ju
  • Testirano na Python 3.10, 3.11 i 3.12

Zahtjevi

Instalacija

pip install nopayn-sdk

Brzi početak

1. Inicijalizirajte klijent

from nopayn import NoPaynClient

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

2. Stvorite plaćanje i preusmjerite 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",
)

# 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. Obradite webhook (Flask primjer)

@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 referenca

NoPaynClient(api_key, merchant_id, base_url?)

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

client.create_order(**kwargs) -> Order

Stvara narudžbu putem POST /v1/orders/.

ParametarTipObaveznoOpis
amountintDaIznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR)
currencystrDaISO 4217 kod (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNeVaša interna referenca narudžbe
descriptionstrNeOpis narudžbe
return_urlstrNePreusmjeravanje nakon uspješnog plaćanja
failure_urlstrNePreusmjeravanje pri poništenju/isteku/grešci
webhook_urlstrNeAsinkrone obavijesti o promjeni statusa
localestrNeJezik HPP-a (en-GB, de-DE, nl-NL itd.)
payment_methodslist[str]NeFiltriranje HPP načina
expiration_periodstrNeISO 8601 trajanje (PT30M)

Dostupni načini plaćanja: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Dohvaća detalje narudžbe putem GET /v1/orders/{id}/.

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

Izdaje potpuni ili djelomični povrat putem POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Praktična metoda koja stvara narudžbu i vraća:

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

Generira HMAC-SHA256 heksadecimalni potpis.

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

Verifikacija HMAC-SHA256 potpisa konstantnim vremenom.

client.verify_webhook(raw_body) -> VerifiedWebhook

Raščlanjuje tijelo webhooka, zatim poziva GET /v1/orders/{id}/ za provjeru stvarnog statusa.

Samostalni HMAC alati

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)

Tipovi podataka

Svi API odgovori vraćaju se kao frozen dataclass objekti:

KlasaPolja
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

Rukovanje greškama

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 narudžbe

StatusKonačan?Opis
newNeNarudžba stvorena
processingNePlaćanje u tijeku
completedDaPlaćanje uspjelo — isporučite robu
cancelledDaPlaćanje poništeno od strane kupca
expiredDaPoveznica za plaćanje je istekla
errorDaTehnički kvar

Najbolje prakse za webhookove

  1. Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov verify_webhook() to radi automatski.
  2. Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
  3. Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte get_order() kao sigurnosnu mrežu.
  4. Budite idempotentni — možete primiti isti webhook više puta.

Testne kartice

Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):

KarticaBrojNapomene
Visa (uspjeh)4111 1111 1111 1111Bilo koji CVV
Mastercard (uspjeh)5544 3300 0003 7Bilo koji CVV
Visa (odbijena)4111 1111 1111 1105Do Not Honor
Visa (nedovoljna sredstva)4111 1111 1111 1151Insufficient Funds

Koristite bilo koji budući datum isteka i bilo koji 3-znamenkasti CVC.

Demo aplikacija

Flask-bazirana demo aplikacija uključena je u GitHub repozitoriju za testiranje potpunog tijeka plaćanja.

Podrška

Trebate pomoć? Obratite se našem timu za podršku na support@costplus.io.

On this page