Cost+Docs

Python

Officielt Python SDK til Cost+ betalingsgateway

Officielt Python SDK til Cost+ betalingsgateway. Forenkler HPP (Hosted Payment Page) redirect-flowet, HMAC payload-signering og webhook-verificering.

Funktioner

  • Minimale afhængigheder — kun requests
  • Fulde type hints og frosne dataclass-returtyper
  • HMAC-SHA256 signaturgenerering og tidskonstant verificering
  • Webhook-parsing + API-baseret ordreverificering
  • Testet på tværs af Python 3.10, 3.11 og 3.12

Krav

Installation

pip install nopayn-sdk

Hurtigstart

1. Initialiser klienten

from nopayn import NoPaynClient

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

2. Opret en betaling og omdiriger til HPP'en

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. Håndter webhooken (Flask-eksempel)

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

NoPaynClient(api_key, merchant_id, base_url?)

ParameterTypePåkrævetStandard
api_keystrJa
merchant_idstrJa
base_urlstrNejhttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Opretter en ordre via POST /v1/orders/.

ParameterTypePåkrævetBeskrivelse
amountintJaBeløb i mindste valutaenhed (øre/cent)
currencystrJaISO 4217-kode (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNejDin interne ordrereference
descriptionstrNejOrdrebeskrivelse
return_urlstrNejOmdirigering efter vellykket betaling
failure_urlstrNejOmdirigering ved annullering/udløb/fejl
webhook_urlstrNejAsynkrone statusændringsnotifikationer
localestrNejHPP-sprog (en-GB, de-DE, nl-NL osv.)
payment_methodslist[str]NejFiltrer HPP-metoder
expiration_periodstrNejISO 8601-varighed (PT30M)

Tilgængelige betalingsmetoder: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Henter ordredetaljer via GET /v1/orders/{id}/.

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

Udsteder en fuld eller delvis refusion via POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Convenience-metode der opretter en ordre og returnerer:

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

Genererer en HMAC-SHA256 hex-signatur.

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

Tidskonstant verificering af en HMAC-SHA256-signatur.

client.verify_webhook(raw_body) -> VerifiedWebhook

Parser webhook-kroppen og kalder derefter GET /v1/orders/{id}/ for at verificere den faktiske status.

Selvstændige HMAC-hjælpefunktioner

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

Alle API-svar returneres som frosne dataclasses:

KlasseFelter
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

Fejlhåndtering

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

Ordrestatusser

StatusEndelig?Beskrivelse
newNejOrdre oprettet
processingNejBetaling i gang
completedJaBetaling vellykket — lever varerne
cancelledJaBetaling annulleret af kunden
expiredJaBetalingslink udløbet
errorJaTeknisk fejl

Webhook best practices

  1. Verificer altid via API'et — webhook-payloaden indeholder kun ordre-ID'et, aldrig status. SDK'ets verify_webhook() gør dette automatisk.
  2. Returner HTTP 200 for at bekræfte modtagelsen. Enhver anden kode udløser op til 10 genforsøg (2 minutters mellemrum).
  3. Implementer en backup-poller — for ordrer ældre end 10 minutter, der ikke har nået en endelig status, poll get_order() som sikkerhedsnet.
  4. Vær idempotent — du kan modtage den samme webhook flere gange.

Testkort

Brug disse kort i Cost+ testtilstand (sandbox-website):

KortNummerNoter
Visa (succes)4111 1111 1111 1111Vilkårlig CVV
Mastercard (succes)5544 3300 0003 7Vilkårlig CVV
Visa (afvist)4111 1111 1111 1105Do Not Honor
Visa (utilstrækkelig saldo)4111 1111 1111 1151Insufficient Funds

Brug en vilkårlig fremtidig udløbsdato og en vilkårlig 3-cifret CVC.

Demo-app

En Flask-baseret demo-app er inkluderet i GitHub-repositoriet til test af det fulde betalingsflow.

Support

Brug for hjælp? Kontakt vores supportteam på support@costplus.io.

On this page