Python
Oficialus Python SDK Cost+ mokėjimų šliuzui
Oficialus Python SDK Cost+ mokėjimų šliuzui. Supaprastina HPP (mokėjimo puslapio) nukreipimo procesą, HMAC turinio pasirašymą ir webhook patvirtinimą.
Savybės
- Minimalios priklausomybės — tik
requests - Pilnos tipo užuominos ir užšaldytos dataclass grąžinimo tipai
- HMAC-SHA256 parašo generavimas ir pastovaus laiko patikrinimas
- Webhook analizė + API pagrįstas užsakymo patikrinimas
- Testuota Python 3.10, 3.11 ir 3.12 versijose
Reikalavimai
- Python 3.10 arba naujesnė
- Cost+ prekybininko paskyra — dashboard.costplus.io
Diegimas
pip install nopayn-sdkGreitas startas
1. Inicializuokite klientą
from nopayn import NoPaynClient
client = NoPaynClient(
api_key="your-api-key",
merchant_id="your-project",
)2. Sukurkite mokėjimą ir nukreipkite į 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. Apdorokite Webhook (Flask pavyzdys)
@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 nuoroda
NoPaynClient(api_key, merchant_id, base_url?)
| Parametras | Tipas | Privalomas | Numatytasis |
|---|---|---|---|
api_key | str | Taip | — |
merchant_id | str | Taip | — |
base_url | str | Ne | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Sukuria užsakymą per POST /v1/orders/.
| Parametras | Tipas | Privalomas | Aprašymas |
|---|---|---|---|
amount | int | Taip | Suma mažiausiu valiutos vienetu (centais) |
currency | str | Taip | ISO 4217 kodas (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Ne | Jūsų vidinis užsakymo nuorodos ID |
description | str | Ne | Užsakymo aprašymas |
return_url | str | Ne | Nukreipimas po sėkmingo mokėjimo |
failure_url | str | Ne | Nukreipimas atšaukimo/galiojimo pabaigos/klaidos atveju |
webhook_url | str | Ne | Asinchroniniai būsenos pakeitimo pranešimai |
locale | str | Ne | HPP kalba (en-GB, de-DE, nl-NL ir kt.) |
payment_methods | list[str] | Ne | Filtruoti HPP mokėjimo būdus |
expiration_period | str | Ne | ISO 8601 trukmė (PT30M) |
Prieinami mokėjimo būdai: credit-card, apple-pay, google-pay, vipps-mobilepay
client.get_order(order_id) -> Order
Gauna užsakymo detales per GET /v1/orders/{id}/.
client.create_refund(order_id, amount, description?) -> Refund
Atlieka pilną arba dalinį grąžinimą per POST /v1/orders/{id}/refunds/.
client.generate_payment_url(**kwargs) -> PaymentUrlResult
Patogus metodas, kuris sukuria užsakymą ir grąžina:
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
Generuoja HMAC-SHA256 hex parašą.
client.verify_signature(amount, currency, order_id, signature) -> bool
Pastovaus laiko HMAC-SHA256 parašo patikrinimas.
client.verify_webhook(raw_body) -> VerifiedWebhook
Analizuoja webhook turinį, tada iškviečia GET /v1/orders/{id}/, kad patikrintų tikrąją būseną.
Atskiros HMAC priemonės
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)Duomenų tipai
Visi API atsakymai grąžinami kaip užšaldytos dataclass:
| Klasė | Laukai |
|---|---|
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 |
Klaidų tvarkymas
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 errorUžsakymo būsenos
| Būsena | Galutinė? | Aprašymas |
|---|---|---|
new | Ne | Užsakymas sukurtas |
processing | Ne | Mokėjimas vykdomas |
completed | Taip | Mokėjimas sėkmingas — pristatykite prekes |
cancelled | Taip | Mokėjimas atšauktas kliento |
expired | Taip | Mokėjimo nuorodos laikas baigėsi |
error | Taip | Techninė klaida |
Webhook geriausios praktikos
- Visada patikrinkite per API — webhook turinys pateikia tik užsakymo ID, niekada būsenos. SDK
verify_webhook()tai atlieka automatiškai. - Grąžinkite HTTP 200, kad patvirtintumėte gavimą. Bet koks kitas kodas suaktyvina iki 10 pakartotinių bandymų (kas 2 minutes).
- Įgyvendinkite atsarginį tikrintuvą — užsakymams, senesniems nei 10 minučių, kurie nepasiekė galutinės būsenos, naudokite
get_order()kaip saugos tinklą. - Būkite idempotentiški — galite gauti tą patį webhook kelis kartus.
Testinės kortelės
Naudokite šias korteles Cost+ testavimo režimu (testavimo svetainė):
| Kortelė | Numeris | Pastabos |
|---|---|---|
| Visa (sėkminga) | 4111 1111 1111 1111 | Bet koks CVV |
| Mastercard (sėkminga) | 5544 3300 0003 7 | Bet koks CVV |
| Visa (atmesta) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nepakankamos lėšos) | 4111 1111 1111 1151 | Insufficient Funds |
Naudokite bet kurią ateities galiojimo datą ir bet kokį 3 skaitmenų CVC.
Demonstracinė programa
Flask pagrįsta demonstracinė programa įtraukta į GitHub saugyklą pilnam mokėjimo proceso testavimui.
Palaikymas
Reikia pagalbos? Kreipkitės į mūsų palaikymo komandą adresu support@costplus.io.