Cost+Docs

Python

Ametlik Python SDK Cost+ makselüüsi jaoks

Ametlik Python SDK Cost+ makselüüsi jaoks. Lihtsustab HPP (hostitud makselehe) ümbersuunamise voogu, HMAC andmete allkirjastamist ja veebihaagi kontrollimist.

Funktsioonid

  • Minimaalsed sõltuvused — ainult requests
  • Täielikud tüübivihjed ja külmutatud andmeklasside tagastustüübid
  • HMAC-SHA256 allkirja genereerimine ja konstantse aja kontrollimine
  • Veebihaagi parsimine + API-põhine tellimuse kontrollimine
  • Testitud Python 3.10, 3.11 ja 3.12 peal

Nõuded

Paigaldamine

pip install nopayn-sdk

Kiirstart

1. Kliendi initsialiseerimine

from nopayn import NoPaynClient

client = NoPaynClient(
    api_key="your-api-key",
    merchant_id="your-project",
)

2. Makse loomine ja HPP-le suunamine

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. Veebihaagi käsitlemine (Flask näide)

@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

API viide

NoPaynClient(api_key, merchant_id, base_url?)

ParameeterTüüpKohustuslikVaikeväärtus
api_keystrJah
merchant_idstrJah
base_urlstrEihttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Loob tellimuse päringuga POST /v1/orders/.

ParameeterTüüpKohustuslikKirjeldus
amountintJahSumma väikseimas valuutaühikus (sendid)
currencystrJahISO 4217 kood (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrEiTeie sisemine tellimuse viide
descriptionstrEiTellimuse kirjeldus
return_urlstrEiÜmbersuunamine pärast edukat makset
failure_urlstrEiÜmbersuunamine tühistamise/aegumise/vea korral
webhook_urlstrEiAsünkroonsed olekumuutuse teavitused
localestrEiHPP keel (en-GB, de-DE, nl-NL jne)
payment_methodslist[str]EiHPP meetodite filtreerimine
expiration_periodstrEiISO 8601 kestvus (PT30M)

Saadaolevad makseviisid: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Pärib tellimuse üksikasjad päringuga GET /v1/orders/{id}/.

client.create_refund(order_id, amount, description?) -> Refund

Teeb täieliku või osalise tagasimakse päringuga POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Abimeetod, mis loob tellimuse ja tagastab:

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

Genereerib HMAC-SHA256 hex allkirja.

client.verify_signature(amount, currency, order_id, signature) -> bool

Konstantse aja HMAC-SHA256 allkirja kontrollimine.

client.verify_webhook(raw_body) -> VerifiedWebhook

Parsib veebihaagi keha, seejärel kutsub GET /v1/orders/{id}/, et kontrollida tegelikku olekut.

Eraldiseisvad HMAC utiliidid

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)

Andmetüübid

Kõik API vastused tagastatakse külmutatud andmeklassidena:

KlassVäljad
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

Veakäsitlus

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

Tellimuse olekud

OlekLõplik?Kirjeldus
newEiTellimus loodud
processingEiMakse pooleli
completedJahMakse edukas — tarnige kaup
cancelledJahMakse tühistatud kliendi poolt
expiredJahMakselink aegunud
errorJahTehniline tõrge

Veebihaagi parimad tavad

  1. Kontrollige alati API kaudu — veebihaagi andmed sisaldavad ainult tellimuse ID-d, mitte kunagi olekut. SDK verify_webhook() teeb seda automaatselt.
  2. Tagastage HTTP 200 kättesaamise kinnitamiseks. Iga muu kood käivitab kuni 10 korduskatset (2 minuti vahega).
  3. Rakendage varuküsitleja — tellimuste jaoks, mis on vanemad kui 10 minutit ja pole jõudnud lõppolekusse, küsitlege get_order() turvavõrguna.
  4. Olge idempotentne — võite sama veebihaagi saada mitu korda.

Testkaardid

Kasutage neid kaarte Cost+ testrežiimis (liivakasti veebileht):

KaartNumberMärkused
Visa (edukas)4111 1111 1111 1111Suvaline CVV
Mastercard (edukas)5544 3300 0003 7Suvaline CVV
Visa (keeldutud)4111 1111 1111 1105Do Not Honor
Visa (ebapiisav saldo)4111 1111 1111 1151Insufficient Funds

Kasutage suvalist tulevast aegumiskuupäeva ja suvalist 3-kohalist CVC-d.

Demorakendus

Flaskil põhinev demorakendus on kaasas GitHub hoidlas täieliku maksevoo testimiseks.

Tugi

Vajate abi? Võtke ühendust meie tugimeeskonnaga aadressil support@costplus.io.

On this page