Python
SDK uffiċjali ta' Python għall-gateway tal-ħlas Cost+
SDK uffiċjali ta' Python għall-gateway tal-ħlas Cost+. Jissimplifika l-flusso ta' redirect tal-HPP (Paġna ta' Ħlas Ospitata), il-firma tal-payload HMAC, u l-verifika tal-webhooks.
Karatteristiċi
- Dipendenzi minimi —
requestsbiss - Type hints sħaħ u tipi ta' ritorn frozen dataclass
- Ġenerazzjoni ta' firma HMAC-SHA256 u verifika b'ħin kostanti
- Ipparsjar tal-webhooks + verifika tal-ordni bbażata fuq l-API
- Ittestjat fuq Python 3.10, 3.11, u 3.12
Rekwiżiti
- Python 3.10 jew aktar tard
- Kont ta' kummerċjant Cost+ — dashboard.costplus.io
Installazzjoni
pip install nopayn-sdkBidu Malajr
1. Inizjalizza l-Klijent
from nopayn import NoPaynClient
client = NoPaynClient(
api_key="your-api-key",
merchant_id="your-project",
)2. Oħloq Ħlas u Irridirezzjona lejn il-HPP
result = client.generate_payment_url(
amount=1295, # €12.95 f'ċenteżmi
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",
)
# Irridirezzjona l-klijent
# result.order_url → HPP (il-klijent jagħżel il-metodu ta' ħlas)
# result.payment_url → link dirett lejn il-metodu ta' ħlas tal-ewwel tranżazzjoni
# result.signature → HMAC-SHA256 għall-verifika
# result.order_id → UUID tal-ordni NoPayn3. Ittratta l-Webhook (Eżempju Flask)
@app.route("/webhook", methods=["POST"])
def webhook():
verified = client.verify_webhook(request.get_data(as_text=True))
print(verified.order.status) # 'completed', 'cancelled', eċċ.
print(verified.is_final) # True meta l-ordni ma tinbidilx aktar
if verified.order.status == "completed":
# Issodisfa l-ordni
pass
return "", 200Referenza tal-API
NoPaynClient(api_key, merchant_id, base_url?)
| Parametru | Tip | Meħtieġ | Default |
|---|---|---|---|
api_key | str | Iva | — |
merchant_id | str | Iva | — |
base_url | str | Le | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Joħloq ordni permezz ta' POST /v1/orders/.
| Parametru | Tip | Meħtieġ | Deskrizzjoni |
|---|---|---|---|
amount | int | Iva | Ammont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR) |
currency | str | Iva | Kodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Le | Ir-referenza interna tal-ordni tiegħek |
description | str | Le | Deskrizzjoni tal-ordni |
return_url | str | Le | Redirect wara ħlas li rnexxielu |
failure_url | str | Le | Redirect fuq kanċellazzjoni/skadenza/żball |
webhook_url | str | Le | Notifiki asinkroni ta' bidla fl-istatus |
locale | str | Le | Lingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.) |
payment_methods | list[str] | Le | Iffiltra l-metodi tal-HPP |
expiration_period | str | Le | Tul ta' żmien ISO 8601 (PT30M) |
Metodi ta' ħlas disponibbli: credit-card, apple-pay, google-pay, vipps-mobilepay
client.get_order(order_id) -> Order
Jiġbed id-dettalji tal-ordni permezz ta' GET /v1/orders/{id}/.
client.create_refund(order_id, amount, description?) -> Refund
Joħroġ rifużjoni sħiħa jew parzjali permezz ta' POST /v1/orders/{id}/refunds/.
client.generate_payment_url(**kwargs) -> PaymentUrlResult
Metodu ta' konvenjenza li joħloq ordni u jirritorna:
PaymentUrlResult(
order_id="...", # UUID tal-ordni NoPayn
order_url="...", # URL tal-HPP
payment_url="...", # URL ta' ħlas dirett (l-ewwel tranżazzjoni)
signature="...", # HMAC-SHA256 ta' amount:currency:order_id
order=Order(...), # Oġġett sħiħ tal-ordni
)client.generate_signature(amount, currency, order_id) -> str
Jiġġenera firma HMAC-SHA256 hex.
client.verify_signature(amount, currency, order_id, signature) -> bool
Verifika b'ħin kostanti ta' firma HMAC-SHA256.
client.verify_webhook(raw_body) -> VerifiedWebhook
Jipparsja l-korp tal-webhook, imbagħad isejjaħ GET /v1/orders/{id}/ biex jivverifika l-istatus attwali.
Utilitajiet HMAC Standalone
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)Tipi tad-Data
Ir-risponsi kollha tal-API jiġu rritornati bħala frozen dataclasses:
| Klassi | Oqsma |
|---|---|
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 |
Trattar tal-Żbalji
from nopayn import ApiError, NoPaynError, WebhookError
try:
client.create_order(amount=100, currency="EUR")
except ApiError as exc:
print(exc.status_code) # 401, 400, eċċ.
print(exc.error_body) # Risposta ta' żball mhux ipproċessata tal-API
except NoPaynError as exc:
print(exc) # Żball tan-network jew tal-ipparsjarStatuses tal-Ordni
| Status | Finali? | Deskrizzjoni |
|---|---|---|
new | Le | Ordni maħluqa |
processing | Le | Ħlas qed isir |
completed | Iva | Ħlas irnexxielu — ikkonsenja l-prodotti |
cancelled | Iva | Ħlas ikkanċellat mill-klijent |
expired | Iva | Link tal-ħlas skada |
error | Iva | Falliment tekniku |
L-Aħjar Prattiċi għall-Webhooks
- Dejjem ivverifika permezz tal-API — il-payload tal-webhook fih biss l-ID tal-ordni, qatt l-istatus. Il-
verify_webhook()tal-SDK jagħmel dan awtomatikament. - Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
- Implimenta backup poller — għal ordnijiet itqal minn 10 minuti li għadhom ma laħqux status finali, agħmel polling ta'
get_order()bħala xibka ta' sigurtà. - Kun idempotenti — tista' tirċievi l-istess webhook aktar minn darba.
Karti tat-Test
Uża dawn il-karti f'modalità tat-test ta' Cost+ (website sandbox):
| Karta | Numru | Noti |
|---|---|---|
| Visa (suċċess) | 4111 1111 1111 1111 | Kwalunkwe CVV |
| Mastercard (suċċess) | 5544 3300 0003 7 | Kwalunkwe CVV |
| Visa (miċħuda) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fondi insuffiċjenti) | 4111 1111 1111 1151 | Insufficient Funds |
Uża kwalunkwe data ta' skadenza futura u kwalunkwe CVC ta' 3 ċifri.
App Demo
App demo bbażata fuq Flask hija inkluża fir-repożitorju ta' GitHub għall-ittestjar tal-flusso sħiħ tal-ħlas.
Appoġġ
Għandek bżonn l-għajnuna? Ikkuntattja t-tim tal-appoġġ tagħna fuq support@costplus.io.