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
- Python 3.10 vai jaunāka versija
- Cost+ tirgotāja konts — dashboard.costplus.io
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 UUID3. 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 "", 200API atsauce
NoPaynClient(api_key, merchant_id, base_url?)
| Parametrs | Tips | Obligāts | Noklusējums |
|---|---|---|---|
api_key | str | Jā | — |
merchant_id | str | Jā | — |
base_url | str | Nē | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Izveido pasūtījumu caur POST /v1/orders/.
| Parametrs | Tips | Obligāts | Apraksts |
|---|---|---|---|
amount | int | Jā | Summa mazākajā valūtas vienībā (centos) |
currency | str | Jā | ISO 4217 kods (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Nē | Jūsu iekšējā pasūtījuma atsauce |
description | str | Nē | Pasūtījuma apraksts |
return_url | str | Nē | Novirzīšana pēc veiksmīga maksājuma |
failure_url | str | Nē | Novirzīšana atcelšanas/termiņa beigšanās/kļūdas gadījumā |
webhook_url | str | Nē | Asinhroniem statusa izmaiņu paziņojumiem |
locale | str | Nē | HPP valoda (en-GB, de-DE, nl-NL utt.) |
payment_methods | list[str] | Nē | Filtrēt HPP metodes |
expiration_period | str | Nē | ISO 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:
| Klase | Lauki |
|---|---|
Order | id, amount, currency, status, created, modified, transactions, description, merchant_order_id, return_url, failure_url, order_url, completed |
Transaction | id, amount, currency, status, created, modified, payment_method, payment_url, expiration_period |
Refund | id, amount, status |
PaymentUrlResult | order_id, order_url, payment_url, signature, order |
VerifiedWebhook | order_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 errorPasūtījumu statusi
| Statuss | Galīgs? | Apraksts |
|---|---|---|
new | Nē | Pasūtījums izveidots |
processing | Nē | Maksājums procesā |
completed | Jā | Maksājums veiksmīgs — piegādājiet preci |
cancelled | Jā | Maksājums atcelts klienta |
expired | Jā | Maksājuma saites termiņš beidzies |
error | Jā | Tehniska kļūme |
Webhook labākā prakse
- Vienmēr verificējiet caur API — webhook saturs satur tikai pasūtījuma ID, nekad statusu. SDK
verify_webhook()to dara automātiski. - Atgrieziet HTTP 200, lai apstiprinātu saņemšanu. Jebkurš cits kods izsauc līdz 10 atkārtojumiem (2 minūtes starpā).
- 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. - 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):
| Karte | Numurs | Piezīmes |
|---|---|---|
| Visa (veiksmīgs) | 4111 1111 1111 1111 | Jebkurš CVV |
| Mastercard (veiksmīgs) | 5544 3300 0003 7 | Jebkurš CVV |
| Visa (noraidīts) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nepietiekami līdzekļi) | 4111 1111 1111 1151 | Insufficient 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.