qvapay 0.9.0

Python SDK for the QvaPay API

Python SDK for the QvaPay API

Non official, but friendly QvaPay library for the Python language.

Installation

pip install qvapay

Or with uv:

uv add qvapay

Sign up on QvaPay

Create your account to process payments through QvaPay at qvapay.com/register.

Quick start

The SDK provides two types of clients:

• User clients (AsyncQvaPayClient / SyncQvaPayClient) — Bearer-token authenticated, for user-level operations.
• Merchant clients (AsyncQvaPayMerchant / SyncQvaPayMerchant) — UUID + secret key authenticated, for app-level operations like invoicing.

Authentication

Use the standalone auth module to obtain an access token:

from qvapay import auth

# Async
token = await auth.login("[e-mail]", "password")
print(token.access_token)

For the sync equivalent:

from qvapay._sync import auth

token = auth.login("[e-mail]", "password")

The auth module also provides register, request_pin, check, and logout functions.

User client

Create a client with the access token obtained from login:

from qvapay import AsyncQvaPayClient

async with AsyncQvaPayClient(access_token="your-token") as client:
    profile = await client.user.me()
    print(profile.username)

Or synchronously:

from qvapay import SyncQvaPayClient

with SyncQvaPayClient(access_token="your-token") as client:
    profile = client.user.me()
    print(profile.username)

Merchant client

For app-level operations, use the merchant client with your app UUID and secret key (get these at qvapay.com/apps/create):

from qvapay import AsyncQvaPayMerchant

async with AsyncQvaPayMerchant(uuid="app-uuid", secret_key="app-secret") as merchant:
    invoice = await merchant.create_invoice(
        amount=10.00,
        description="Ebook",
        remote_id="EE-BOOK-123",
    )
    print(invoice.url)

User client modules

The user client organizes functionality into modules accessed as attributes:

Transactions (client.transactions)

# List recent transactions (with optional filters)
transactions = await client.transactions.list(
    start="2024-01-01",
    end="2024-12-31",
    status="completed",
)

# Get a specific transaction
detail = await client.transactions.get("transaction-uuid")

# Transfer balance to another user (by UUID, email, or phone)
tx = await client.transactions.transfer(
    to="[e-mail]",
    amount=5.00,
    description="Payment for services",
)

# Pay a pending transaction
tx = await client.transactions.pay("transaction-uuid", pin="1234")

# Download transaction PDF
pdf_bytes = await client.transactions.get_pdf("transaction-uuid")

User profile (client.user)

profile = await client.user.me()
extended = await client.user.me_extended()

# Update profile
await client.user.update(bio="Hello world")
await client.user.update_username("new_username")

# Search users
users = await client.user.search("john")

# KYC verification
status = await client.user.kyc_status()

# Sub-modules
contacts = await client.user.contacts.list()
methods = await client.user.payment_methods.list()
domains = await client.user.domains.check("example.com")

Apps (client.app)

apps = await client.app.list()
app = await client.app.get("app-uuid")
new_app = await client.app.create(
    name="My App",
    url="https://example.com",
    desc="My QvaPay app",
    callback="https://example.com/callback",
)

P2P trading (client.p2p)

offers = await client.p2p.get_offers(coin="USDT", type="buy")
offer = await client.p2p.create_offer(coin="USDT", amount=100, price=1.05, type="sell")

# Chat
messages = await client.p2p.chat.get("offer-uuid")
await client.p2p.chat.send("offer-uuid", "Hello!")

# Trade flow
await client.p2p.apply("offer-uuid")
await client.p2p.mark_paid("offer-uuid")
await client.p2p.confirm_received("offer-uuid")

Withdrawals (client.withdraw)

withdrawal = await client.withdraw.create(
    pay_method="USDT",
    amount=50.00,
    details={"address": "0x..."},
)
withdrawals = await client.withdraw.list()

Payment links (client.payment_links)

links = await client.payment_links.list()
link = await client.payment_links.create(
    name="Donation",
    product_id="product-uuid",
    amount=5.00,
)

Store (client.store)

products = await client.store.products()
purchased = await client.store.my_purchased()

# Sub-modules
packages = await client.store.phone_package.list()
cards = await client.store.gift_card.catalog()

Top-up (client.topup)

packages = await client.topup.list_products()

Merchant client methods

async with AsyncQvaPayMerchant(uuid="app-uuid", secret_key="secret") as merchant:
    # App info and balance
    info = await merchant.info()
    balance = await merchant.balance()

    # Invoicing
    invoice = await merchant.create_invoice(
        amount=25.00,
        description="Premium Plan",
        remote_id="INV-001",
        signed=True,
    )
    await merchant.modify_invoice("invoice-uuid", amount=30.00)

    # Transactions
    txs = await merchant.get_transactions()
    status = await merchant.get_transaction_status("tx-uuid")

    # Payment authorization
    auth_url = await merchant.get_payments_authorization(redirect_url="https://...")
    await merchant.charge_user(token="auth-token", amount=10.00)

Standalone modules

Coins

from qvapay import coins

categories = await coins.list()
operational = await coins.list_v2(enabled_in=True)
coin = await coins.get(coin_id=1)
history = await coins.price_history("BTC", timeframe="7D")

Stocks

from qvapay import stocks

data = await stocks.list()

Error handling

All API errors raise QvaPayError:

from qvapay import QvaPayError

try:
    await client.transactions.transfer(to="[e-mail]", amount=1000)
except QvaPayError as e:
    print(e.status_code, e.status_message)

For developers

Setup

git clone https://github.com/ragnarok22/qvapay-python.git
cd qvapay-python
make install  # or: uv sync

Commands

• make tests — run linting and tests with coverage
• make coverage — tests with terminal coverage report
• make format — auto-format with ruff
• make lint — check formatting without modifying files

Migration guide

0.3.0 -> 0.9.0

• Imports moved from qvapay.v1 to qvapay (e.g., from qvapay import AsyncQvaPayClient)
• Client methods are now organized into modules: client.transactions.list() instead of client.get_transactions()
• New AsyncQvaPayMerchant / SyncQvaPayMerchant for app-level operations (invoicing, balance)
• Standalone auth, coins, and stocks modules replace the old QvaPayAuth helper
• Client constructor takes access_token instead of app_id / app_secret

0.2.0 -> 0.3.0

• QvaPayClient was divided into two classes: AsyncQvaPayClient and SyncQvaPayClient. Both classes have the same methods and properties, with the difference that the methods in AsyncQvaPayClient are asynchronous and in SyncQvaPayClient are synchronous.

0.1.0 -> 0.2.0

• user_id of Transaction model was removed
• paid_by_user_id of Transaction model was removed

0.0.3 -> 0.1.0

• from qvapay.v1 import * instead of from qvapay import *
• QvaPayClient instead of Client
• client.get_info instead of client.info
• client.get_balance instead of client.balance
• client.get_transactions instead of client.transactions

Contributors

Thanks goes to these wonderful people (emoji key):

Carlos Lugones 💻

Ozkar L. Garcell 💻

Leynier Gutiérrez González 💻

Jorge Alejandro Jimenez Luna 💻

Reinier Hernández 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!