Cost+Docs

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

Instalare

pip install nopayn-sdk

Pornire 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 UUID

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

Referință API

NoPaynClient(api_key, merchant_id, base_url?)

ParametruTipObligatoriuImplicit
api_keystrDa
merchant_idstrDa
base_urlstrNuhttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Creează o comandă prin POST /v1/orders/.

ParametruTipObligatoriuDescriere
amountintDaSuma în cea mai mică unitate monetară (cenți)
currencystrDaCod ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNuReferința dvs. internă de comandă
descriptionstrNuDescrierea comenzii
return_urlstrNuRedirecționare după plata reușită
failure_urlstrNuRedirecționare la anulare/expirare/eroare
webhook_urlstrNuNotificări asincrone de schimbare status
localestrNuLimba HPP (en-GB, de-DE, nl-NL, etc.)
payment_methodslist[str]NuFiltrare metode HPP
expiration_periodstrNuDurată 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
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

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 error

Statusuri comandă

StatusFinal?Descriere
newNuComandă creată
processingNuPlată în curs
completedDaPlată reușită — livrați marfa
cancelledDaPlată anulată de client
expiredDaLinkul de plată a expirat
errorDaEroare tehnică

Bune practici pentru webhook-uri

  1. 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.
  2. 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ță).
  3. 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ță.
  4. 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):

CardNumărNote
Visa (succes)4111 1111 1111 1111Orice CVV
Mastercard (succes)5544 3300 0003 7Orice CVV
Visa (refuzat)4111 1111 1111 1105Do Not Honor
Visa (fonduri insuficiente)4111 1111 1111 1151Insufficient 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.

On this page