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
- Python 3.10 tai uudempi
- Cost+-kauppiastili — dashboard.costplus.io
Asennus
pip install nopayn-sdkPikaopas
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 UUID3. 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 "", 200API-viite
NoPaynClient(api_key, merchant_id, base_url?)
| Parametri | Tyyppi | Pakollinen | Oletus |
|---|---|---|---|
api_key | str | Kyllä | — |
merchant_id | str | Kyllä | — |
base_url | str | Ei | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Luo tilauksen kutsulla POST /v1/orders/.
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
amount | int | Kyllä | Summa pienimmässä valuuttayksikössä (senteissä) |
currency | str | Kyllä | ISO 4217 -koodi (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Ei | Oma sisäinen tilausviitteesi |
description | str | Ei | Tilauksen kuvaus |
return_url | str | Ei | Uudelleenohjaus onnistuneen maksun jälkeen |
failure_url | str | Ei | Uudelleenohjaus peruutuksen/vanhenemisen/virheen yhteydessä |
webhook_url | str | Ei | Asynkroniset tilanmuutosilmoitukset |
locale | str | Ei | HPP:n kieli (en-GB, de-DE, nl-NL jne.) |
payment_methods | list[str] | Ei | Suodata HPP:n maksutapoja |
expiration_period | str | Ei | ISO 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:
| Luokka | Kentät |
|---|---|
Order | id, amount, currency, status, created, modified, transactions, description, merchant_order_id, return_url, failure_url, order_url, completed |
Transaction | id, amount, currency, status, created, modified, payment_method, payment_url, expiration_period |
Refund | id, amount, status |
PaymentUrlResult | order_id, order_url, payment_url, signature, order |
VerifiedWebhook | order_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 errorTilausten tilat
| Tila | Lopullinen? | Kuvaus |
|---|---|---|
new | Ei | Tilaus luotu |
processing | Ei | Maksu käynnissä |
completed | Kyllä | Maksu onnistui — toimita tavarat |
cancelled | Kyllä | Asiakas peruutti maksun |
expired | Kyllä | Maksulinkki vanheni |
error | Kyllä | Tekninen virhe |
Webhook-parhaat käytännöt
- Vahvista aina API:n kautta — webhook-data sisältää vain tilauksen tunnisteen, ei koskaan tilaa. SDK:n
verify_webhook()tekee tämän automaattisesti. - Palauta HTTP 200 kuittauksena. Mikä tahansa muu koodi käynnistää enintään 10 uudelleenyritystä (2 minuutin välein).
- Toteuta varapolleri — yli 10 minuuttia vanhoille tilauksille, jotka eivät ole saavuttaneet lopullista tilaa, pollaa
get_order()turvavarana. - Ole idempotentti — saatat vastaanottaa saman webhookin useita kertoja.
Testikortit
Käytä näitä kortteja Cost+:n testitilassa (sandbox-verkkosivusto):
| Kortti | Numero | Huomautukset |
|---|---|---|
| Visa (onnistunut) | 4111 1111 1111 1111 | Mikä tahansa CVV |
| Mastercard (onnistunut) | 5544 3300 0003 7 | Mikä tahansa CVV |
| Visa (hylätty) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (riittämätön kate) | 4111 1111 1111 1151 | Insufficient 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.