Payout

Python

Python SDK для интеграции с Payment Easy Payout API.

Python

Python SDK для интеграции с Payment Easy Payout API.

Установка

pip install "payout-sdk @ git+https://github.com/unitewt/sdk-payout.git#subdirectory=python"

Или локально:

git clone https://github.com/unitewt/sdk-payout.git
cd sdk-payout/python
pip install .

Быстрый старт

from datetime import datetime, timezone
from payout_sdk import Config, PayoutClient, ServiceCode, BankCode

config = Config(
    base_url="https://your-server.example.com",
    username="your_username",
    private_key_pem=open("private-key.pem", "rb").read(),
)

client = PayoutClient(config)

# Запрос баланса
balance = client.balance()
print(f"Баланс: {balance.balance} копеек")

# Выплата на карту
resp = client.payment(
    id="unique-tx-id",
    sum=100000,  # 1000 рублей в копейках
    service=ServiceCode.BANK_CARD,
    account="4277255555555555",
    date=datetime.now(timezone.utc),
    phone="79999999999",
)

if resp.is_final():
    print(f"Успех: {resp.is_successful()}")

# Проверка статуса
status = client.get_status("unique-tx-id")
print(f"code={status.code}, state={status.state}, final={status.final}")

Конфигурация

config = Config(
    base_url="https://your-server.example.com",
    username="your_username",
    private_key_pem=b"-----BEGIN PRIVATE KEY-----...",
    server_public_key_pem=b"-----BEGIN PUBLIC KEY-----...",  # опционально
    timeout=300.0,  # секунды, по умолчанию 300
)

Параметр	Тип	Обязательный	По умолчанию	Описание
`base_url`	`str`	да	—	URL сервера
`username`	`str`	да	—	Имя пользователя
`private_key_pem`	`bytes`	да	—	RSA приватный ключ (PEM)
`server_public_key_pem`	`bytes \| None`	нет	`None`	Публичный ключ сервера
`timeout`	`float`	нет	`300.0`	HTTP таймаут (секунды)

API

`PayoutClient`

Метод	Описание	Возвращает
`balance()`	Запрос баланса	`BalanceResponse`
`payment(...)`	Выполнение выплаты	`PaymentResponse`
`get_status(tx_id)`	Проверка статуса	`PaymentResponse`

Параметры `payment()`

Параметр	Тип	Обязательный	Описание
`id`	`str`	да	Уникальный ID транзакции (до 64 байт)
`sum`	`int`	да	Сумма в копейках
`service`	`ServiceCode \| int`	да	Тип сервиса
`account`	`str`	да	Номер карты / телефона / кошелька
`date`	`datetime`	да	Дата транзакции
`phone`	`str`	да	Телефон плательщика
`payee_bank_code`	`str \| None`	нет	Код банка получателя (для СБП)

`PaymentResponse`

Поле/Метод	Тип	Описание
`id`	`str`	Ваш ID транзакции
`code`	`int`	Код результата
`state`	`int`	Состояние платежа
`final`	`int`	1 = финальный статус
`trans`	`str`	ID транзакции на стороне шлюза
`fee`	`int \| None`	Комиссия в копейках
`error_description`	`str \| None`	Описание ошибки
`is_successful()`	`bool`	code=0, state=60, final=1
`is_failed()`	`bool`	code=20, state=80, final=1
`is_not_found()`	`bool`	code=15, state=-2, final=1
`is_processing()`	`bool`	code=1, state=40, final=0
`is_final()`	`bool`	final=1

`BalanceResponse`

Поле	Тип	Описание
`balance`	`int`	Баланс в копейках
`overdraft`	`int`	Овердрафт в копейках

Сервисы

ServiceCode.BANK_CARD    # "24" — банковские карты
ServiceCode.QIWI_WALLET  # "25" — кошельки QIWI
ServiceCode.SBP           # "26" — СБП
ServiceCode.MOBILE_PHONE  # "28" — мобильные телефоны

Коды банков (СБП)

BankCode.SBERBANK_OF_RUSSIA  # "100000000111"
BankCode.TINKOFF_BANK        # "100000000004"
BankCode.ALFA_BANK           # "100000000008"
# ... 238 банков

Выплата через СБП

resp = client.payment(
    id="sbp-tx-id",
    sum=50000,
    service=ServiceCode.SBP,
    account="79876543210",
    date=datetime.now(timezone.utc),
    phone="79999999999",
    payee_bank_code=BankCode.SBERBANK_OF_RUSSIA,
)

Обработка ошибок

SDK определяет три класса исключений:

PayoutError — базовый класс
ApiError — ошибки API (атрибуты: transaction_id, status_code)
SignatureError — ошибки подписи

from payout_sdk import ApiError, SignatureError

try:
    resp = client.payment(...)
except ApiError as e:
    print(f"API ошибка: {e}, status={e.status_code}")
except SignatureError as e:
    print(f"Ошибка подписи: {e}")

Примеры

examples/generate_keys.py — генерация RSA-ключей
examples/integration_test.py — полный интеграционный тест

export PAYOUT_BASE_URL="https://your-server.example.com"
export PAYOUT_USERNAME="your_username"
export PAYOUT_PRIVATE_KEY_PATH="./private-key.pem"

python examples/integration_test.py

Зависимости

cryptography >= 41.0
Python >= 3.11

PHP

PHP SDK для интеграции с Payment Easy Payout API.