Python
Официално Python SDK за разплащателния шлюз Cost+
Официално Python SDK за разплащателния шлюз Cost+. Опростява потока за пренасочване към HPP (хоствана страница за плащане), HMAC подписването на данни и верификацията на уебхукове.
Характеристики
- Минимални зависимости — само
requests - Пълни type hints и замразени dataclass типове за връщане
- HMAC-SHA256 генериране на подписи и верификация с постоянно време
- Анализиране на уебхукове + верификация на поръчки, базирана на API
- Тествано с Python 3.10, 3.11 и 3.12
Изисквания
- Python 3.10 или по-нова версия
- Търговски акаунт в Cost+ — dashboard.costplus.io
Инсталация
pip install nopayn-sdkБързо начало
1. Инициализиране на клиента
from nopayn import NoPaynClient
client = NoPaynClient(
api_key="your-api-key",
merchant_id="your-project",
)2. Създаване на плащане и пренасочване към 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. Обработка на уебхука (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 "", 200API справочник
NoPaynClient(api_key, merchant_id, base_url?)
| Параметър | Тип | Задължителен | По подразбиране |
|---|---|---|---|
api_key | str | Да | — |
merchant_id | str | Да | — |
base_url | str | Не | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Създава поръчка чрез POST /v1/orders/.
| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
amount | int | да | Сума в ISO 4217 второстепенна единица на валутата (например центове за EUR) |
currency | str | Да | ISO 4217 код (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Не | Ваш вътрешен идентификатор на поръчка |
description | str | Не | Описание на поръчката |
return_url | str | Не | Пренасочване след успешно плащане |
failure_url | str | Не | Пренасочване при отказ/изтичане/грешка |
webhook_url | str | Не | Асинхронни известия за промяна на статуса |
locale | str | Не | Език на HPP (en-GB, de-DE, nl-NL и др.) |
payment_methods | list[str] | Не | Филтриране на HPP методи |
expiration_period | str | Не | ISO 8601 продължителност (PT30M) |
Налични методи на плащане: credit-card, apple-pay, google-pay, vipps-mobilepay
client.get_order(order_id) -> Order
Извлича детайли на поръчка чрез GET /v1/orders/{id}/.
client.create_refund(order_id, amount, description?) -> Refund
Издава пълно или частично възстановяване чрез POST /v1/orders/{id}/refunds/.
client.generate_payment_url(**kwargs) -> PaymentUrlResult
Удобен метод, който създава поръчка и връща:
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
Генерира HMAC-SHA256 шестнадесетичен подпис.
client.verify_signature(amount, currency, order_id, signature) -> bool
Верификация с постоянно време на HMAC-SHA256 подпис.
client.verify_webhook(raw_body) -> VerifiedWebhook
Анализира тялото на уебхука, след което извиква GET /v1/orders/{id}/, за да провери действителния статус.
Самостоятелни HMAC помощни функции
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)Типове данни
Всички API отговори се връщат като замразени dataclasses:
| Клас | Полета |
|---|---|
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 |
Обработка на грешки
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Статуси на поръчки
| Статус | Финален? | Описание |
|---|---|---|
new | Не | Поръчката е създадена |
processing | Не | Плащането е в ход |
completed | Да | Плащането е успешно — доставете стоката |
cancelled | Да | Плащането е отменено от клиента |
expired | Да | Линкът за плащане е изтекъл |
error | Да | Техническа грешка |
Добри практики за уебхукове
- Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса.
verify_webhook()на SDK-то прави това автоматично. - Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
- Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с
get_order()като мрежа за безопасност. - Бъдете идемпотентни — може да получите един и същ уебхук многократно.
Тестови карти
Използвайте тези карти в тестов режим на Cost+ (sandbox уебсайт):
| Карта | Номер | Бележки |
|---|---|---|
| Visa (успех) | 4111 1111 1111 1111 | Произволен CVV |
| Mastercard (успех) | 5544 3300 0003 7 | Произволен CVV |
| Visa (отхвърлена) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (недостатъчни средства) | 4111 1111 1111 1151 | Insufficient Funds |
Използвайте произволна бъдеща дата на валидност и произволен 3-цифрен CVC.
Демо приложение
Демо приложение, базирано на Flask, е включено в GitHub хранилището за тестване на пълния поток на плащане.
Поддръжка
Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.