Cost+Docs

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 — requests biss
  • 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

Installazzjoni

pip install nopayn-sdk

Bidu 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 NoPayn

3. 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 "", 200

Referenza tal-API

NoPaynClient(api_key, merchant_id, base_url?)

ParametruTipMeħtieġDefault
api_keystrIva—
merchant_idstrIva—
base_urlstrLehttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Joħloq ordni permezz ta' POST /v1/orders/.

ParametruTipMeħtieġDeskrizzjoni
amountintIvaAmmont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR)
currencystrIvaKodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrLeIr-referenza interna tal-ordni tiegħek
descriptionstrLeDeskrizzjoni tal-ordni
return_urlstrLeRedirect wara ħlas li rnexxielu
failure_urlstrLeRedirect fuq kanċellazzjoni/skadenza/żball
webhook_urlstrLeNotifiki asinkroni ta' bidla fl-istatus
localestrLeLingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.)
payment_methodslist[str]LeIffiltra l-metodi tal-HPP
expiration_periodstrLeTul 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:

KlassiOqsma
Orderid, amount, currency, status, created, modified, transactions, description, merchant_order_id, return_url, failure_url, order_url, completed
Transactionid, amount, currency, status, created, modified, payment_method, payment_url, expiration_period
Refundid, amount, status
PaymentUrlResultorder_id, order_url, payment_url, signature, order
VerifiedWebhookorder_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-ipparsjar

Statuses tal-Ordni

StatusFinali?Deskrizzjoni
newLeOrdni maħluqa
processingLeĦlas qed isir
completedIvaĦlas irnexxielu — ikkonsenja l-prodotti
cancelledIvaĦlas ikkanċellat mill-klijent
expiredIvaLink tal-ħlas skada
errorIvaFalliment tekniku

L-Aħjar Prattiċi għall-Webhooks

  1. 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.
  2. Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
  3. 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à.
  4. 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):

KartaNumruNoti
Visa (suċċess)4111 1111 1111 1111Kwalunkwe CVV
Mastercard (suċċess)5544 3300 0003 7Kwalunkwe CVV
Visa (miċħuda)4111 1111 1111 1105Do Not Honor
Visa (fondi insuffiċjenti)4111 1111 1111 1151Insufficient 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.

On this page