Cost+Docs

Python

Officiellt Python SDK för Cost+ betalningsgateway

Officiellt Python SDK för Cost+ betalningsgateway. Förenklar HPP-omdirigeringsflödet (Hosted Payment Page), HMAC payload-signering och webhook-verifiering.

Funktioner

  • Minimala beroenden — bara requests
  • Fullständiga type hints och frusna dataclass-returtyper
  • HMAC-SHA256 signaturgenerering och verifiering med konstant tid
  • Webhook-tolkning + API-baserad orderverifiering
  • Testad med Python 3.10, 3.11 och 3.12

Krav

Installation

pip install nopayn-sdk

Snabbstart

1. Initiera klienten

from nopayn import NoPaynClient

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

2. Skapa en betalning och omdirigera till 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. Hantera webhooken (Flask-exempel)

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

NoPaynClient(api_key, merchant_id, base_url?)

ParameterTypObligatoriskStandard
api_keystrJa
merchant_idstrJa
base_urlstrNejhttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Skapar en order via POST /v1/orders/.

ParameterTypObligatoriskBeskrivning
amountintJaBelopp i minsta valutaenhet (cent)
currencystrJaISO 4217-kod (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNejDin interna orderreferens
descriptionstrNejOrderbeskrivning
return_urlstrNejOmdirigering efter lyckad betalning
failure_urlstrNejOmdirigering vid avbrytning/utgång/fel
webhook_urlstrNejAsynkrona statusändringsnotifieringar
localestrNejHPP-språk (en-GB, de-DE, nl-NL, etc.)
payment_methodslist[str]NejFiltrera HPP-metoder
expiration_periodstrNejISO 8601-duration (PT30M)

Tillgängliga betalningsmetoder: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Hämtar orderdetaljer via GET /v1/orders/{id}/.

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

Utfärdar en fullständig eller partiell återbetalning via POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Bekvämlighetsmetod som skapar en order och returnerar:

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

Genererar en HMAC-SHA256 hex-signatur.

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

Verifiering med konstant tid av en HMAC-SHA256-signatur.

client.verify_webhook(raw_body) -> VerifiedWebhook

Tolkar webhook-kroppen och anropar sedan GET /v1/orders/{id}/ för att verifiera faktisk status.

Fristående HMAC-verktyg

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)

Datatyper

Alla API-svar returneras som frusna dataclasses:

KlassFält
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

Felhantering

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

Orderstatusar

StatusSlutgiltig?Beskrivning
newNejOrder skapad
processingNejBetalning pågår
completedJaBetalning lyckades — leverera varorna
cancelledJaBetalning avbruten av kunden
expiredJaBetalningslänken löpte ut
errorJaTekniskt fel

Bästa praxis för webhooks

  1. Verifiera alltid via API:et — webhook-payloaden innehåller bara order-ID:t, aldrig statusen. SDK:ts verify_webhook() gör detta automatiskt.
  2. Returnera HTTP 200 för att bekräfta mottagandet. Annan kod utlöser upp till 10 omförsök (2 minuter emellan).
  3. Implementera en reservpoller — för ordrar äldre än 10 minuter som inte har nått slutgiltig status, polla get_order() som säkerhetsnät.
  4. Var idempotent — du kan ta emot samma webhook flera gånger.

Testkort

Använd dessa kort i Cost+ testläge (sandbox-webbplats):

KortNummerNoteringar
Visa (lyckad)4111 1111 1111 1111Valfritt CVV
Mastercard (lyckad)5544 3300 0003 7Valfritt CVV
Visa (nekad)4111 1111 1111 1105Do Not Honor
Visa (otillräckligt saldo)4111 1111 1111 1151Insufficient Funds

Använd valfritt framtida utgångsdatum och valfri 3-siffrig CVC.

Demoapplikation

En Flask-baserad demoapplikation ingår i GitHub-repositoryt för att testa det fullständiga betalningsflödet.

Support

Behöver du hjälp? Kontakta vårt supportteam på support@costplus.io.

On this page