Cost+Docs

Python

SDK oifigiúil Python do gheata íocaíochta Cost+

SDK oifigiúil Python do gheata íocaíochta Cost+. Simpliú an tsreabha atreoraithe HPP (Leathanach Íocaíochta Óstáilte), síniú sonraí HMAC, agus fíorú webhook.

Gnéithe

  • Spleáchais íosta -- requests amháin
  • Leideanna cineáil iomlána agus cineálacha tuairisceáin ranganna sonraí reoite
  • Giniúint sínithe HMAC-SHA256 agus fíorú ama-leanúnaigh
  • Parsáil webhook + fíorú ordaithe bunaithe ar API
  • Tástáilte ar fud Python 3.10, 3.11, agus 3.12

Riachtanais

Suiteáil

pip install nopayn-sdk

Mearthosnú

1. Túsaigh an Cliant

from nopayn import NoPaynClient

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

2. Cruthaigh Íocaíocht agus Atreorófar chuig an 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. Láimhseáil an Webhook (Sampla 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

Tagairt API

NoPaynClient(api_key, merchant_id, base_url?)

ParaiméadarCineálRiachtanachRéamhshocrú
api_keystrTá--
merchant_idstrTá--
base_urlstrNílhttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Cruthaíonn ordú tríd an POST /v1/orders/.

ParaiméadarCineálRiachtanachCur Síos
amountintTáMéid i mionaonad ISO 4217 an airgeadra (mar shampla, cent le haghaidh EUR)
currencystrTáCód ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNílDo thagairt inmheánach ordaithe
descriptionstrNílCur síos ar an ordú
return_urlstrNílAtreorú tar éis íocaíochta rathúla
failure_urlstrNílAtreorú ar cheallú/éag/earráid
webhook_urlstrNílFógraí athraithe stádais asincrónach
localestrNílTeanga HPP (en-GB, de-DE, nl-NL, srl.)
payment_methodslist[str]NílScag modhanna HPP
expiration_periodstrNílFad ISO 8601 (PT30M)

Modhanna íocaíochta ar fáil: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Faigheann sonraí ordaithe tríd an GET /v1/orders/{id}/.

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

Eisíonn aisíocaíocht iomlán nó pháirteach tríd an POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Modh áise a chruthaíonn ordú agus a sheolann ar ais:

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

Gineann síniú HMAC-SHA256 hex.

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

Fíorú ama-leanúnaigh ar shíniú HMAC-SHA256.

client.verify_webhook(raw_body) -> VerifiedWebhook

Parsáileann corp an webhook, ansin glaonn GET /v1/orders/{id}/ chun an stádas iarbhír a fhíorú.

Fóntais HMAC Neamhspleácha

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)

Cineálacha Sonraí

Seoltar gach freagra API ar ais mar ranganna sonraí reoite:

RangRéimsí
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

Láimhseáil Earráidí

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

Stádais Ordaithe

StádasDeiridh?Cur Síos
newNílOrdú cruthaithe
processingNílÍocaíocht ar siúl
completedTáD'éirigh leis an íocaíocht -- seachaid na hearraí
cancelledTáCheal an custaiméir an íocaíocht
expiredTáD'éag an nasc íocaíochta
errorTáTeip theicniúil

Dea-Chleachtais Webhook

  1. Fíoraigh tríd an API i gcónaí -- ní bhíonn ach aitheantas an ordaithe sa sonraí webhook, ní an stádas riamh. Déanann verify_webhook() an SDK é seo go huathoibríoch.
  2. Seol HTTP 200 ar ais chun fáiltiú a admháil. Spreagann aon chód eile suas le 10 n-atriail (2 nóiméad eatarthu).
  3. Cuir cúltaca pólaí i bhfeidhm -- d'orduithe atá níos sine ná 10 nóiméad nach bhfuil stádas deiridh bainte amach acu, pólail get_order() mar líontán sábháilteachta.
  4. Bí idéimpotent -- d'fhéadfá an webhook céanna a fháil arís is arís eile.

Cártaí Tástála

Úsáid na cártaí seo i mód tástála Cost+ (suíomh gréasáin gaineamhchláir):

CártaUimhirNótaí
Visa (rath)4111 1111 1111 1111Aon CVV
Mastercard (rath)5544 3300 0003 7Aon CVV
Visa (diúltaithe)4111 1111 1111 1105Do Not Honor
Visa (cistí neamhleor)4111 1111 1111 1151Insufficient Funds

Úsáid aon dáta éaga amach anseo agus aon CVC 3 dhigit.

Aip Thaispeána

Tá aip thaispeána Flask-bhunaithe san áireamh sa stór GitHub chun an sreabhadh íocaíochta iomlán a thástáil.

Tacaíocht

Cabhair ag teastáil? Déan teagmháil lenár bhfoireann tacaíochta ag support@costplus.io.

On this page