Python
Službeni Python SDK za Cost+ platni pristupnik
Službeni Python SDK za Cost+ platni pristupnik. Pojednostavljuje tijek preusmjeravanja na HPP (hosted stranicu za plaćanje), HMAC potpisivanje podataka i verifikaciju webhookova.
Značajke
- Minimalne ovisnosti — samo
requests - Potpuni type hintovi i frozen dataclass povratni tipovi
- HMAC-SHA256 generiranje potpisa i verifikacija konstantnim vremenom
- Raščlamba webhookova + verifikacija narudžbe temeljena na API-ju
- Testirano na Python 3.10, 3.11 i 3.12
Zahtjevi
- Python 3.10 ili noviji
- Cost+ trgovački račun — dashboard.costplus.io
Instalacija
pip install nopayn-sdkBrzi početak
1. Inicijalizirajte klijent
from nopayn import NoPaynClient
client = NoPaynClient(
api_key="your-api-key",
merchant_id="your-project",
)2. Stvorite plaćanje i preusmjerite na 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 UUID3. Obradite webhook (Flask primjer)
@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 referenca
NoPaynClient(api_key, merchant_id, base_url?)
| Parametar | Tip | Obavezno | Zadano |
|---|---|---|---|
api_key | str | Da | — |
merchant_id | str | Da | — |
base_url | str | Ne | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Stvara narudžbu putem POST /v1/orders/.
| Parametar | Tip | Obavezno | Opis |
|---|---|---|---|
amount | int | Da | Iznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR) |
currency | str | Da | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Ne | Vaša interna referenca narudžbe |
description | str | Ne | Opis narudžbe |
return_url | str | Ne | Preusmjeravanje nakon uspješnog plaćanja |
failure_url | str | Ne | Preusmjeravanje pri poništenju/isteku/grešci |
webhook_url | str | Ne | Asinkrone obavijesti o promjeni statusa |
locale | str | Ne | Jezik HPP-a (en-GB, de-DE, nl-NL itd.) |
payment_methods | list[str] | Ne | Filtriranje HPP načina |
expiration_period | str | Ne | ISO 8601 trajanje (PT30M) |
Dostupni načini plaćanja: credit-card, apple-pay, google-pay, vipps-mobilepay
client.get_order(order_id) -> Order
Dohvaća detalje narudžbe putem GET /v1/orders/{id}/.
client.create_refund(order_id, amount, description?) -> Refund
Izdaje potpuni ili djelomični povrat putem POST /v1/orders/{id}/refunds/.
client.generate_payment_url(**kwargs) -> PaymentUrlResult
Praktična metoda koja stvara narudžbu i vraća:
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
Generira HMAC-SHA256 heksadecimalni potpis.
client.verify_signature(amount, currency, order_id, signature) -> bool
Verifikacija HMAC-SHA256 potpisa konstantnim vremenom.
client.verify_webhook(raw_body) -> VerifiedWebhook
Raščlanjuje tijelo webhooka, zatim poziva GET /v1/orders/{id}/ za provjeru stvarnog statusa.
Samostalni HMAC alati
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)Tipovi podataka
Svi API odgovori vraćaju se kao frozen dataclass objekti:
| Klasa | Polja |
|---|---|
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 |
Rukovanje greškama
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 errorStatusi narudžbe
| Status | Konačan? | Opis |
|---|---|---|
new | Ne | Narudžba stvorena |
processing | Ne | Plaćanje u tijeku |
completed | Da | Plaćanje uspjelo — isporučite robu |
cancelled | Da | Plaćanje poništeno od strane kupca |
expired | Da | Poveznica za plaćanje je istekla |
error | Da | Tehnički kvar |
Najbolje prakse za webhookove
- Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov
verify_webhook()to radi automatski. - Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
- Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte
get_order()kao sigurnosnu mrežu. - Budite idempotentni — možete primiti isti webhook više puta.
Testne kartice
Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):
| Kartica | Broj | Napomene |
|---|---|---|
| Visa (uspjeh) | 4111 1111 1111 1111 | Bilo koji CVV |
| Mastercard (uspjeh) | 5544 3300 0003 7 | Bilo koji CVV |
| Visa (odbijena) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedovoljna sredstva) | 4111 1111 1111 1151 | Insufficient Funds |
Koristite bilo koji budući datum isteka i bilo koji 3-znamenkasti CVC.
Demo aplikacija
Flask-bazirana demo aplikacija uključena je u GitHub repozitoriju za testiranje potpunog tijeka plaćanja.
Podrška
Trebate pomoć? Obratite se našem timu za podršku na support@costplus.io.