Cost+Docs

Python

Oficialus Python SDK Cost+ mokėjimų šliuzui

Oficialus Python SDK Cost+ mokėjimų šliuzui. Supaprastina HPP (mokėjimo puslapio) nukreipimo procesą, HMAC turinio pasirašymą ir webhook patvirtinimą.

Savybės

  • Minimalios priklausomybės — tik requests
  • Pilnos tipo užuominos ir užšaldytos dataclass grąžinimo tipai
  • HMAC-SHA256 parašo generavimas ir pastovaus laiko patikrinimas
  • Webhook analizė + API pagrįstas užsakymo patikrinimas
  • Testuota Python 3.10, 3.11 ir 3.12 versijose

Reikalavimai

Diegimas

pip install nopayn-sdk

Greitas startas

1. Inicializuokite klientą

from nopayn import NoPaynClient

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

2. Sukurkite mokėjimą ir nukreipkite į 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. Apdorokite Webhook (Flask pavyzdys)

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

NoPaynClient(api_key, merchant_id, base_url?)

ParametrasTipasPrivalomasNumatytasis
api_keystrTaip
merchant_idstrTaip
base_urlstrNehttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Sukuria užsakymą per POST /v1/orders/.

ParametrasTipasPrivalomasAprašymas
amountintTaipSuma mažiausiu valiutos vienetu (centais)
currencystrTaipISO 4217 kodas (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNeJūsų vidinis užsakymo nuorodos ID
descriptionstrNeUžsakymo aprašymas
return_urlstrNeNukreipimas po sėkmingo mokėjimo
failure_urlstrNeNukreipimas atšaukimo/galiojimo pabaigos/klaidos atveju
webhook_urlstrNeAsinchroniniai būsenos pakeitimo pranešimai
localestrNeHPP kalba (en-GB, de-DE, nl-NL ir kt.)
payment_methodslist[str]NeFiltruoti HPP mokėjimo būdus
expiration_periodstrNeISO 8601 trukmė (PT30M)

Prieinami mokėjimo būdai: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Gauna užsakymo detales per GET /v1/orders/{id}/.

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

Atlieka pilną arba dalinį grąžinimą per POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Patogus metodas, kuris sukuria užsakymą ir grąžina:

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

Generuoja HMAC-SHA256 hex parašą.

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

Pastovaus laiko HMAC-SHA256 parašo patikrinimas.

client.verify_webhook(raw_body) -> VerifiedWebhook

Analizuoja webhook turinį, tada iškviečia GET /v1/orders/{id}/, kad patikrintų tikrąją būseną.

Atskiros HMAC priemonės

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)

Duomenų tipai

Visi API atsakymai grąžinami kaip užšaldytos dataclass:

KlasėLaukai
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

Klaidų tvarkymas

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

Užsakymo būsenos

BūsenaGalutinė?Aprašymas
newNeUžsakymas sukurtas
processingNeMokėjimas vykdomas
completedTaipMokėjimas sėkmingas — pristatykite prekes
cancelledTaipMokėjimas atšauktas kliento
expiredTaipMokėjimo nuorodos laikas baigėsi
errorTaipTechninė klaida

Webhook geriausios praktikos

  1. Visada patikrinkite per API — webhook turinys pateikia tik užsakymo ID, niekada būsenos. SDK verify_webhook() tai atlieka automatiškai.
  2. Grąžinkite HTTP 200, kad patvirtintumėte gavimą. Bet koks kitas kodas suaktyvina iki 10 pakartotinių bandymų (kas 2 minutes).
  3. Įgyvendinkite atsarginį tikrintuvą — užsakymams, senesniems nei 10 minučių, kurie nepasiekė galutinės būsenos, naudokite get_order() kaip saugos tinklą.
  4. Būkite idempotentiški — galite gauti tą patį webhook kelis kartus.

Testinės kortelės

Naudokite šias korteles Cost+ testavimo režimu (testavimo svetainė):

KortelėNumerisPastabos
Visa (sėkminga)4111 1111 1111 1111Bet koks CVV
Mastercard (sėkminga)5544 3300 0003 7Bet koks CVV
Visa (atmesta)4111 1111 1111 1105Do Not Honor
Visa (nepakankamos lėšos)4111 1111 1111 1151Insufficient Funds

Naudokite bet kurią ateities galiojimo datą ir bet kokį 3 skaitmenų CVC.

Demonstracinė programa

Flask pagrįsta demonstracinė programa įtraukta į GitHub saugyklą pilnam mokėjimo proceso testavimui.

Palaikymas

Reikia pagalbos? Kreipkitės į mūsų palaikymo komandą adresu support@costplus.io.

On this page