Cost+Docs

Python

Virallinen Python SDK Cost+-maksuportille

Virallinen Python SDK Cost+-maksuportille. Yksinkertaistaa HPP (isännöidyn maksusivun) uudelleenohjausta, HMAC-allekirjoitusta ja webhook-vahvistusta.

Ominaisuudet

  • Minimaaliset riippuvuudet — vain requests
  • Täydet tyyppivihjeet ja jäädytetyt dataclass-palautustyypit
  • HMAC-SHA256-allekirjoituksen luonti ja vakioaikainen vahvistus
  • Webhook-jäsennys + API-pohjainen tilauksen vahvistus
  • Testattu Python 3.10-, 3.11- ja 3.12-versioilla

Vaatimukset

Asennus

pip install nopayn-sdk

Pikaopas

1. Alusta asiakas

from nopayn import NoPaynClient

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

2. Luo maksu ja ohjaa HPP:hen

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. Käsittele webhook (Flask-esimerkki)

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

NoPaynClient(api_key, merchant_id, base_url?)

ParametriTyyppiPakollinenOletus
api_keystrKyllä
merchant_idstrKyllä
base_urlstrEihttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Luo tilauksen kutsulla POST /v1/orders/.

ParametriTyyppiPakollinenKuvaus
amountintKylläSumma pienimmässä valuuttayksikössä (senteissä)
currencystrKylläISO 4217 -koodi (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrEiOma sisäinen tilausviitteesi
descriptionstrEiTilauksen kuvaus
return_urlstrEiUudelleenohjaus onnistuneen maksun jälkeen
failure_urlstrEiUudelleenohjaus peruutuksen/vanhenemisen/virheen yhteydessä
webhook_urlstrEiAsynkroniset tilanmuutosilmoitukset
localestrEiHPP:n kieli (en-GB, de-DE, nl-NL jne.)
payment_methodslist[str]EiSuodata HPP:n maksutapoja
expiration_periodstrEiISO 8601 -kesto (PT30M)

Käytettävissä olevat maksutavat: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Hakee tilauksen tiedot kutsulla GET /v1/orders/{id}/.

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

Tekee täyden tai osittaisen palautuksen kutsulla POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Apumetodi, joka luo tilauksen ja palauttaa:

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

Luo HMAC-SHA256 hex-allekirjoituksen.

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

Vakioaikainen HMAC-SHA256-allekirjoituksen vahvistus.

client.verify_webhook(raw_body) -> VerifiedWebhook

Jäsentää webhook-rungon ja kutsuu sitten GET /v1/orders/{id}/ varmistaakseen todellisen tilan.

Erilliset HMAC-apufunktiot

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)

Datatyypit

Kaikki API-vastaukset palautetaan jäädytettyinä dataclass-olioina:

LuokkaKentät
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

Virheenkäsittely

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

Tilausten tilat

TilaLopullinen?Kuvaus
newEiTilaus luotu
processingEiMaksu käynnissä
completedKylläMaksu onnistui — toimita tavarat
cancelledKylläAsiakas peruutti maksun
expiredKylläMaksulinkki vanheni
errorKylläTekninen virhe

Webhook-parhaat käytännöt

  1. Vahvista aina API:n kautta — webhook-data sisältää vain tilauksen tunnisteen, ei koskaan tilaa. SDK:n verify_webhook() tekee tämän automaattisesti.
  2. Palauta HTTP 200 kuittauksena. Mikä tahansa muu koodi käynnistää enintään 10 uudelleenyritystä (2 minuutin välein).
  3. Toteuta varapolleri — yli 10 minuuttia vanhoille tilauksille, jotka eivät ole saavuttaneet lopullista tilaa, pollaa get_order() turvavarana.
  4. Ole idempotentti — saatat vastaanottaa saman webhookin useita kertoja.

Testikortit

Käytä näitä kortteja Cost+:n testitilassa (sandbox-verkkosivusto):

KorttiNumeroHuomautukset
Visa (onnistunut)4111 1111 1111 1111Mikä tahansa CVV
Mastercard (onnistunut)5544 3300 0003 7Mikä tahansa CVV
Visa (hylätty)4111 1111 1111 1105Do Not Honor
Visa (riittämätön kate)4111 1111 1111 1151Insufficient Funds

Käytä mitä tahansa tulevaa voimassaolopäivää ja mitä tahansa 3-numeroista CVC:tä.

Demosovellus

Flask-pohjainen demosovellus sisältyy GitHub-tietovarastoon täyden maksukulun testaamiseksi.

Tuki

Tarvitsetko apua? Ota yhteyttä tukitiimiimme osoitteessa support@costplus.io.

On this page