Cost+Docs

Python

Oficiālais Python SDK Cost+ maksājumu vārtejai

Oficiālais Python SDK Cost+ maksājumu vārtejai. Vienkāršo HPP (mitinātās maksājuma lapas) novirzīšanas plūsmu, HMAC datu parakstīšanu un webhook verifikāciju.

Funkcijas

  • Minimālas atkarības — tikai requests
  • Pilnas tipa norādes un iesaldēti dataclass atgriešanas tipi
  • HMAC-SHA256 parakstu ģenerēšana un konstantā laika verifikācija
  • Webhook parsēšana + API bāzēta pasūtījuma verifikācija
  • Testēts Python 3.10, 3.11 un 3.12

Prasības

Instalācija

pip install nopayn-sdk

Ātrais sākums

1. Inicializējiet klientu

from nopayn import NoPaynClient

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

2. Izveidojiet maksājumu un novirziet uz 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. Apstrādājiet webhook (Flask piemērs)

@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 atsauce

NoPaynClient(api_key, merchant_id, base_url?)

ParametrsTipsObligātsNoklusējums
api_keystr
merchant_idstr
base_urlstrhttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Izveido pasūtījumu caur POST /v1/orders/.

ParametrsTipsObligātsApraksts
amountintSumma mazākajā valūtas vienībā (centos)
currencystrISO 4217 kods (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrJūsu iekšējā pasūtījuma atsauce
descriptionstrPasūtījuma apraksts
return_urlstrNovirzīšana pēc veiksmīga maksājuma
failure_urlstrNovirzīšana atcelšanas/termiņa beigšanās/kļūdas gadījumā
webhook_urlstrAsinhroniem statusa izmaiņu paziņojumiem
localestrHPP valoda (en-GB, de-DE, nl-NL utt.)
payment_methodslist[str]Filtrēt HPP metodes
expiration_periodstrISO 8601 ilgums (PT30M)

Pieejamās maksājumu metodes: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Iegūst pasūtījuma datus caur GET /v1/orders/{id}/.

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

Veic pilnu vai daļēju atmaksu caur POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Ērtuma metode, kas izveido pasūtījumu un atgriež:

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

Ģenerē HMAC-SHA256 heksadecimālo parakstu.

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

Konstantā laika HMAC-SHA256 paraksta verifikācija.

client.verify_webhook(raw_body) -> VerifiedWebhook

Parsē webhook saturu, tad izsauc GET /v1/orders/{id}/, lai verificētu faktisko statusu.

Atsevišķās HMAC utilītas

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)

Datu tipi

Visas API atbildes tiek atgrieztas kā iesaldētas datu klases:

KlaseLauki
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

Kļūdu apstrāde

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

Pasūtījumu statusi

StatussGalīgs?Apraksts
newPasūtījums izveidots
processingMaksājums procesā
completedMaksājums veiksmīgs — piegādājiet preci
cancelledMaksājums atcelts klienta
expiredMaksājuma saites termiņš beidzies
errorTehniska kļūme

Webhook labākā prakse

  1. Vienmēr verificējiet caur API — webhook saturs satur tikai pasūtījuma ID, nekad statusu. SDK verify_webhook() to dara automātiski.
  2. Atgrieziet HTTP 200, lai apstiprinātu saņemšanu. Jebkurš cits kods izsauc līdz 10 atkārtojumiem (2 minūtes starpā).
  3. Ieviesiet rezerves aptaujātāju — pasūtījumiem, kas vecāki par 10 minūtēm un nav sasnieguši galīgo statusu, aptaujājiet get_order() kā drošības tīklu.
  4. Esiet idempotents — jūs varat saņemt vienu un to pašu webhook vairākas reizes.

Testa kartes

Izmantojiet šīs kartes Cost+ testa režīmā (sandbox vietne):

KarteNumursPiezīmes
Visa (veiksmīgs)4111 1111 1111 1111Jebkurš CVV
Mastercard (veiksmīgs)5544 3300 0003 7Jebkurš CVV
Visa (noraidīts)4111 1111 1111 1105Do Not Honor
Visa (nepietiekami līdzekļi)4111 1111 1111 1151Insufficient Funds

Izmantojiet jebkuru nākotnes derīguma termiņu un jebkuru 3 ciparu CVC.

Demo lietotne

Flask bāzēta demo lietotne ir iekļauta GitHub repozitorijā pilnas maksājumu plūsmas testēšanai.

Atbalsts

Nepieciešama palīdzība? Sazinieties ar mūsu atbalsta komandu: support@costplus.io.

On this page