Cost+Docs

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 UUID

3. Обработка на уебхука (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

API справочник

NoPaynClient(api_key, merchant_id, base_url?)

ПараметърТипЗадължителенПо подразбиране
api_keystrДа—
merchant_idstrДа—
base_urlstrНеhttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Създава поръчка чрез POST /v1/orders/.

ПараметърТипЗадължителенОписание
amountintдаСума в ISO 4217 второстепенна единица на валутата (например центове за EUR)
currencystrДаISO 4217 код (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrНеВаш вътрешен идентификатор на поръчка
descriptionstrНеОписание на поръчката
return_urlstrНеПренасочване след успешно плащане
failure_urlstrНеПренасочване при отказ/изтичане/грешка
webhook_urlstrНеАсинхронни известия за промяна на статуса
localestrНеЕзик на HPP (en-GB, de-DE, nl-NL и др.)
payment_methodslist[str]НеФилтриране на HPP методи
expiration_periodstrНе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:

КласПолета
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

Обработка на грешки

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ДаТехническа грешка

Добри практики за уебхукове

  1. Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса. verify_webhook() на SDK-то прави това автоматично.
  2. Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
  3. Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с get_order() като мрежа за безопасност.
  4. Бъдете идемпотентни — може да получите един и същ уебхук многократно.

Тестови карти

Използвайте тези карти в тестов режим на Cost+ (sandbox уебсайт):

КартаНомерБележки
Visa (успех)4111 1111 1111 1111Произволен CVV
Mastercard (успех)5544 3300 0003 7Произволен CVV
Visa (отхвърлена)4111 1111 1111 1105Do Not Honor
Visa (недостатъчни средства)4111 1111 1111 1151Insufficient Funds

Използвайте произволна бъдеща дата на валидност и произволен 3-цифрен CVC.

Демо приложение

Демо приложение, базирано на Flask, е включено в GitHub хранилището за тестване на пълния поток на плащане.

Поддръжка

Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.

On this page