Python
SDK oficial Python pentru gateway-ul de plăți Cost+
SDK oficial Python pentru gateway-ul de plăți Cost+. Simplifică fluxul de redirecționare HPP (pagina de plată găzduită), semnarea HMAC a payload-ului și verificarea webhook-urilor.
Funcționalități
- Dependențe minime — doar
requests - Type hints complete și tipuri de retur frozen dataclass
- Generare semnătură HMAC-SHA256 și verificare cu timp constant
- Parsare webhook + verificare comenzi bazată pe API
- Testat pe Python 3.10, 3.11 și 3.12
Cerințe
- Python 3.10 sau mai nou
- Un cont de comerciant Cost+ — dashboard.costplus.io
Instalare
pip install nopayn-sdkPornire rapidă
1. Inițializați clientul
from nopayn import NoPaynClient
client = NoPaynClient(
api_key="your-api-key",
merchant_id="your-project",
)2. Creați o plată și redirecționați către 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. Gestionați webhook-ul (Exemplu Flask)
@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 "", 200Referință API
NoPaynClient(api_key, merchant_id, base_url?)
| Parametru | Tip | Obligatoriu | Implicit |
|---|---|---|---|
api_key | str | Da | — |
merchant_id | str | Da | — |
base_url | str | Nu | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Creează o comandă prin POST /v1/orders/.
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
amount | int | Da | Suma în cea mai mică unitate monetară (cenți) |
currency | str | Da | Cod ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Nu | Referința dvs. internă de comandă |
description | str | Nu | Descrierea comenzii |
return_url | str | Nu | Redirecționare după plata reușită |
failure_url | str | Nu | Redirecționare la anulare/expirare/eroare |
webhook_url | str | Nu | Notificări asincrone de schimbare status |
locale | str | Nu | Limba HPP (en-GB, de-DE, nl-NL, etc.) |
payment_methods | list[str] | Nu | Filtrare metode HPP |
expiration_period | str | Nu | Durată ISO 8601 (PT30M) |
Metode de plată disponibile: credit-card, apple-pay, google-pay, vipps-mobilepay
client.get_order(order_id) -> Order
Preia detaliile comenzii prin GET /v1/orders/{id}/.
client.create_refund(order_id, amount, description?) -> Refund
Emite o rambursare totală sau parțială prin POST /v1/orders/{id}/refunds/.
client.generate_payment_url(**kwargs) -> PaymentUrlResult
Metodă de convenință care creează o comandă și returnează:
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
Generează o semnătură hex HMAC-SHA256.
client.verify_signature(amount, currency, order_id, signature) -> bool
Verificare cu timp constant a unei semnături HMAC-SHA256.
client.verify_webhook(raw_body) -> VerifiedWebhook
Parsează corpul webhook-ului, apoi apelează GET /v1/orders/{id}/ pentru a verifica statusul real.
Utilitare HMAC independente
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)Tipuri de date
Toate răspunsurile API sunt returnate ca frozen dataclasses:
| Clasă | Câmpuri |
|---|---|
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 |
Gestionarea erorilor
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 errorStatusuri comandă
| Status | Final? | Descriere |
|---|---|---|
new | Nu | Comandă creată |
processing | Nu | Plată în curs |
completed | Da | Plată reușită — livrați marfa |
cancelled | Da | Plată anulată de client |
expired | Da | Linkul de plată a expirat |
error | Da | Eroare tehnică |
Bune practici pentru webhook-uri
- Verificați întotdeauna prin API — payload-ul webhook conține doar ID-ul comenzii, niciodată statusul. Metoda
verify_webhook()a SDK-ului face acest lucru automat. - Returnați HTTP 200 pentru a confirma recepția. Orice alt cod declanșează până la 10 reîncercări (la 2 minute distanță).
- Implementați un poller de rezervă — pentru comenzile mai vechi de 10 minute care nu au ajuns la un status final, interogați
get_order()ca rețea de siguranță. - Fiți idempotent — puteți primi același webhook de mai multe ori.
Carduri de test
Folosiți aceste carduri în modul de test Cost+ (site web sandbox):
| Card | Număr | Note |
|---|---|---|
| Visa (succes) | 4111 1111 1111 1111 | Orice CVV |
| Mastercard (succes) | 5544 3300 0003 7 | Orice CVV |
| Visa (refuzat) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fonduri insuficiente) | 4111 1111 1111 1151 | Insufficient Funds |
Folosiți orice dată de expirare viitoare și orice CVC de 3 cifre.
Aplicație demo
O aplicație demo bazată pe Flask este inclusă în depozitul GitHub pentru testarea fluxului complet de plată.
Suport
Aveți nevoie de ajutor? Contactați echipa noastră de suport la support@costplus.io.