| Name | hotpayments-python-sdk JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Python SDK for HotPayments API - Handle payments, subscriptions, PIX transactions with a clean, async-ready interface. |
| upload_time | 2025-08-02 19:14:31 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
payments
pix
subscriptions
hotpayments
sdk
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# HotPayments Python SDK
A modern, async-ready Python SDK for the HotPayments API. This SDK provides an easy-to-use interface for integrating HotPayments services into your Python applications.
## Installation
Install the SDK via pip:
```bash
pip install hotpayments-python-sdk
```
## Quick Start
### Basic Usage
```python
import asyncio
from hotpayments import Hotpayments
# Set your API key
Hotpayments.auth('your-api-key-here')
async def main():
# Initialize the client
client = Hotpayments()
# Create a customer
customer = await client.customers().create({
'name': 'João Silva',
'email': 'joao@example.com',
'phone_number': '11999999999',
'document': '12345678901'
})
# Create a PIX QR Code transaction
transaction = await client.transactions().create_pix_qr_code({
'amount': 100.50,
'customer_id': customer.uuid,
'description': 'Payment for services'
})
print(f"QR Code: {transaction.qr_code}")
print(f"Transaction ID: {transaction.transaction_id}")
# Run async code
asyncio.run(main())
```
### Synchronous Usage
You can also use the SDK synchronously:
```python
from hotpayments import Hotpayments
# Set your API key
Hotpayments.auth('your-api-key-here')
# Initialize the client
client = Hotpayments()
# Create a customer (synchronous)
customer = client.customers().create_sync({
'name': 'João Silva',
'email': 'joao@example.com',
'phone_number': '11999999999',
'document': '12345678901'
})
# Create a PIX QR Code transaction (synchronous)
transaction = client.transactions().create_pix_qr_code_sync({
'amount': 100.50,
'customer_id': customer.uuid,
'description': 'Payment for services'
})
```
## Authentication
The SDK requires an API key for authentication. You can set it globally:
```python
from hotpayments import Hotpayments
# Set API key globally
Hotpayments.auth('your-api-key-here')
```
Or pass it directly to the client:
```python
client = Hotpayments(api_key='your-api-key-here')
```
## API Reference
### Customers Service
#### Create Customer
```python
# Async
customer = await client.customers().create({
'name': 'João Silva',
'email': 'joao@example.com',
'phone_number': '11999999999',
'document': '12345678901'
})
# Sync
customer = client.customers().create_sync({
'name': 'João Silva',
'email': 'joao@example.com',
'phone_number': '11999999999',
'document': '12345678901'
})
```
#### List Customers
```python
# Async
customers = await client.customers().list(
page=1,
per_page=20,
search='João'
)
# Sync
customers = client.customers().list_sync(
page=1,
per_page=20,
search='João'
)
print(f"Total customers: {customers.total}")
for customer in customers.data:
print(f"Customer: {customer.name}")
```
### Transactions Service
#### Create PIX QR Code
```python
# Async
qr_code = await client.transactions().create_pix_qr_code({
'amount': 150.75,
'customer_id': 'customer-uuid',
'description': 'Payment description',
'expires_at': 3600, # 1 hour in seconds
'splits': [
{
'slug': 'partner-company',
'type': 'percentage',
'value': 10.5
}
]
})
# Sync
qr_code = client.transactions().create_pix_qr_code_sync({
'amount': 150.75,
'customer_id': 'customer-uuid',
'description': 'Payment description'
})
```
#### PIX Cashout
```python
# Async
cashout = await client.transactions().pix_cashout({
'amount': 100.00,
'pix_key': 'user@example.com',
'customer_id': 'customer-uuid',
'description': 'Cashout request'
})
# Sync
cashout = client.transactions().pix_cashout_sync({
'amount': 100.00,
'pix_key': 'user@example.com',
'customer_id': 'customer-uuid',
'description': 'Cashout request'
})
```
#### Check Transaction Status
```python
# Async
transaction = await client.transactions().check('transaction-uuid')
print(f"Status: {transaction.status}")
# Sync
transaction = client.transactions().check_sync('transaction-uuid')
print(f"Status: {transaction.status}")
```
### Subscriptions Service
#### Create Subscription
```python
# Async
subscription_data = await client.subscriptions().create({
'customer_id': 'customer-uuid',
'plan_id': 'plan-uuid',
'payment_method': 'pix'
})
# Sync
subscription_data = client.subscriptions().create_sync({
'customer_id': 'customer-uuid',
'plan_id': 'plan-uuid',
'payment_method': 'pix'
})
```
#### Get Subscription Details
```python
# Async
subscription = await client.subscriptions().show('subscription-uuid')
# Sync
subscription = client.subscriptions().show_sync('subscription-uuid')
```
#### Cancel Subscription
```python
# Async
subscription = await client.subscriptions().cancel('subscription-uuid', {
'reason': 'Customer requested cancellation'
})
# Sync
subscription = client.subscriptions().cancel_sync('subscription-uuid', {
'reason': 'Customer requested cancellation'
})
```
#### Suspend Subscription
```python
# Async
subscription = await client.subscriptions().suspend('subscription-uuid', {
'reason': 'Payment failure'
})
# Sync
subscription = client.subscriptions().suspend_sync('subscription-uuid', {
'reason': 'Payment failure'
})
```
#### Reactivate Subscription
```python
# Async
subscription = await client.subscriptions().reactivate('subscription-uuid')
# Sync
subscription = client.subscriptions().reactivate_sync('subscription-uuid')
```
### Subscription Plans Service
#### List Subscription Plans
```python
# Async
plans = await client.subscription_plans().list(
page=1,
per_page=20,
currency='BRL'
)
# Sync
plans = client.subscription_plans().list_sync(
page=1,
per_page=20,
currency='BRL'
)
print(f"Total plans: {plans.total}")
for plan in plans.data:
print(f"Plan: {plan.name} - Price: {plan.price}")
```
#### Get All Plans
```python
# Async
all_plans = await client.subscription_plans().all(currency='BRL')
# Sync
all_plans = client.subscription_plans().all_sync(currency='BRL')
```
## Type Safety with Pydantic
The SDK uses Pydantic models for type safety and validation:
```python
from hotpayments import CreateCustomerRequest, CreateQrCodeRequest
# Type-safe customer creation
customer_data = CreateCustomerRequest(
name='João Silva',
email='joao@example.com',
phone_number='11999999999',
document='12345678901'
)
customer = await client.customers().create(customer_data)
# Type-safe QR code creation
qr_data = CreateQrCodeRequest(
amount=100.50,
customer_id=customer.uuid,
description='Payment for order #123'
)
transaction = await client.transactions().create_pix_qr_code(qr_data)
```
## Error Handling
The SDK provides a simple exception class for API errors:
```python
from hotpayments import Hotpayments, HotpaymentsException
try:
customer = await client.customers().create({
'name': 'João Silva',
'email': 'invalid-email',
})
except HotpaymentsException as e:
print(f"API Error: {e}")
if e.status_code:
print(f"Status Code: {e.status_code}")
```
## Async vs Sync
The SDK supports both asynchronous and synchronous operations:
- **Async methods**: Use `await` with methods like `create()`, `list()`, `show()`, etc.
- **Sync methods**: Use methods ending with `_sync` like `create_sync()`, `list_sync()`, `show_sync()`, etc.
Choose async for better performance in I/O-bound applications, and sync for simpler integration in traditional synchronous codebases.
## Configuration
### Custom Base URL
```python
client = Hotpayments(
api_key='your-api-key',
base_url='https://api.hotpayments.com', # Custom base URL
timeout=60.0 # Custom timeout in seconds
)
```
### Environment Variables
You can also set the API key using environment variables:
```bash
export HOTPAYMENTS_API_KEY=your-api-key-here
```
## Requirements
- Python 3.8 or higher
- httpx (for HTTP requests)
- pydantic (for data validation and serialization)
## Development
### Installing for Development
```bash
git clone https://github.com/hotpayments/python-sdk.git
cd python-sdk
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black src tests
isort src tests
```
### Type Checking
```bash
mypy src
```
## Support
For support, please contact [contato@hotpayments.net](mailto:contato@hotpayments.net) or visit our documentation.
## License
This package is open-sourced software licensed under the [MIT license](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "hotpayments-python-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "payments, pix, subscriptions, hotpayments, sdk",
"author": null,
"author_email": "HotPayments <contato@hotpayments.net>",
"download_url": "https://files.pythonhosted.org/packages/f7/bf/a92d2d78d530d27f2c833295ae2454d304fe8a1d7cc116c4231d3a07a7f2/hotpayments_python_sdk-1.0.0.tar.gz",
"platform": null,
"description": "# HotPayments Python SDK\r\n\r\nA modern, async-ready Python SDK for the HotPayments API. This SDK provides an easy-to-use interface for integrating HotPayments services into your Python applications.\r\n\r\n## Installation\r\n\r\nInstall the SDK via pip:\r\n\r\n```bash\r\npip install hotpayments-python-sdk\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nimport asyncio\r\nfrom hotpayments import Hotpayments\r\n\r\n# Set your API key\r\nHotpayments.auth('your-api-key-here')\r\n\r\nasync def main():\r\n # Initialize the client\r\n client = Hotpayments()\r\n \r\n # Create a customer\r\n customer = await client.customers().create({\r\n 'name': 'Jo\u00e3o Silva',\r\n 'email': 'joao@example.com',\r\n 'phone_number': '11999999999',\r\n 'document': '12345678901'\r\n })\r\n \r\n # Create a PIX QR Code transaction\r\n transaction = await client.transactions().create_pix_qr_code({\r\n 'amount': 100.50,\r\n 'customer_id': customer.uuid,\r\n 'description': 'Payment for services'\r\n })\r\n \r\n print(f\"QR Code: {transaction.qr_code}\")\r\n print(f\"Transaction ID: {transaction.transaction_id}\")\r\n\r\n# Run async code\r\nasyncio.run(main())\r\n```\r\n\r\n### Synchronous Usage\r\n\r\nYou can also use the SDK synchronously:\r\n\r\n```python\r\nfrom hotpayments import Hotpayments\r\n\r\n# Set your API key\r\nHotpayments.auth('your-api-key-here')\r\n\r\n# Initialize the client\r\nclient = Hotpayments()\r\n\r\n# Create a customer (synchronous)\r\ncustomer = client.customers().create_sync({\r\n 'name': 'Jo\u00e3o Silva',\r\n 'email': 'joao@example.com',\r\n 'phone_number': '11999999999',\r\n 'document': '12345678901'\r\n})\r\n\r\n# Create a PIX QR Code transaction (synchronous)\r\ntransaction = client.transactions().create_pix_qr_code_sync({\r\n 'amount': 100.50,\r\n 'customer_id': customer.uuid,\r\n 'description': 'Payment for services'\r\n})\r\n```\r\n\r\n## Authentication\r\n\r\nThe SDK requires an API key for authentication. You can set it globally:\r\n\r\n```python\r\nfrom hotpayments import Hotpayments\r\n\r\n# Set API key globally\r\nHotpayments.auth('your-api-key-here')\r\n```\r\n\r\nOr pass it directly to the client:\r\n\r\n```python\r\nclient = Hotpayments(api_key='your-api-key-here')\r\n```\r\n\r\n## API Reference\r\n\r\n### Customers Service\r\n\r\n#### Create Customer\r\n\r\n```python\r\n# Async\r\ncustomer = await client.customers().create({\r\n 'name': 'Jo\u00e3o Silva',\r\n 'email': 'joao@example.com',\r\n 'phone_number': '11999999999',\r\n 'document': '12345678901'\r\n})\r\n\r\n# Sync\r\ncustomer = client.customers().create_sync({\r\n 'name': 'Jo\u00e3o Silva',\r\n 'email': 'joao@example.com',\r\n 'phone_number': '11999999999',\r\n 'document': '12345678901'\r\n})\r\n```\r\n\r\n#### List Customers\r\n\r\n```python\r\n# Async\r\ncustomers = await client.customers().list(\r\n page=1,\r\n per_page=20,\r\n search='Jo\u00e3o'\r\n)\r\n\r\n# Sync\r\ncustomers = client.customers().list_sync(\r\n page=1,\r\n per_page=20,\r\n search='Jo\u00e3o'\r\n)\r\n\r\nprint(f\"Total customers: {customers.total}\")\r\nfor customer in customers.data:\r\n print(f\"Customer: {customer.name}\")\r\n```\r\n\r\n### Transactions Service\r\n\r\n#### Create PIX QR Code\r\n\r\n```python\r\n# Async\r\nqr_code = await client.transactions().create_pix_qr_code({\r\n 'amount': 150.75,\r\n 'customer_id': 'customer-uuid',\r\n 'description': 'Payment description',\r\n 'expires_at': 3600, # 1 hour in seconds\r\n 'splits': [\r\n {\r\n 'slug': 'partner-company',\r\n 'type': 'percentage',\r\n 'value': 10.5\r\n }\r\n ]\r\n})\r\n\r\n# Sync\r\nqr_code = client.transactions().create_pix_qr_code_sync({\r\n 'amount': 150.75,\r\n 'customer_id': 'customer-uuid',\r\n 'description': 'Payment description'\r\n})\r\n```\r\n\r\n#### PIX Cashout\r\n\r\n```python\r\n# Async\r\ncashout = await client.transactions().pix_cashout({\r\n 'amount': 100.00,\r\n 'pix_key': 'user@example.com',\r\n 'customer_id': 'customer-uuid',\r\n 'description': 'Cashout request'\r\n})\r\n\r\n# Sync\r\ncashout = client.transactions().pix_cashout_sync({\r\n 'amount': 100.00,\r\n 'pix_key': 'user@example.com',\r\n 'customer_id': 'customer-uuid',\r\n 'description': 'Cashout request'\r\n})\r\n```\r\n\r\n#### Check Transaction Status\r\n\r\n```python\r\n# Async\r\ntransaction = await client.transactions().check('transaction-uuid')\r\nprint(f\"Status: {transaction.status}\")\r\n\r\n# Sync\r\ntransaction = client.transactions().check_sync('transaction-uuid')\r\nprint(f\"Status: {transaction.status}\")\r\n```\r\n\r\n### Subscriptions Service\r\n\r\n#### Create Subscription\r\n\r\n```python\r\n# Async\r\nsubscription_data = await client.subscriptions().create({\r\n 'customer_id': 'customer-uuid',\r\n 'plan_id': 'plan-uuid',\r\n 'payment_method': 'pix'\r\n})\r\n\r\n# Sync\r\nsubscription_data = client.subscriptions().create_sync({\r\n 'customer_id': 'customer-uuid',\r\n 'plan_id': 'plan-uuid',\r\n 'payment_method': 'pix'\r\n})\r\n```\r\n\r\n#### Get Subscription Details\r\n\r\n```python\r\n# Async\r\nsubscription = await client.subscriptions().show('subscription-uuid')\r\n\r\n# Sync\r\nsubscription = client.subscriptions().show_sync('subscription-uuid')\r\n```\r\n\r\n#### Cancel Subscription\r\n\r\n```python\r\n# Async\r\nsubscription = await client.subscriptions().cancel('subscription-uuid', {\r\n 'reason': 'Customer requested cancellation'\r\n})\r\n\r\n# Sync\r\nsubscription = client.subscriptions().cancel_sync('subscription-uuid', {\r\n 'reason': 'Customer requested cancellation'\r\n})\r\n```\r\n\r\n#### Suspend Subscription\r\n\r\n```python\r\n# Async\r\nsubscription = await client.subscriptions().suspend('subscription-uuid', {\r\n 'reason': 'Payment failure'\r\n})\r\n\r\n# Sync\r\nsubscription = client.subscriptions().suspend_sync('subscription-uuid', {\r\n 'reason': 'Payment failure'\r\n})\r\n```\r\n\r\n#### Reactivate Subscription\r\n\r\n```python\r\n# Async\r\nsubscription = await client.subscriptions().reactivate('subscription-uuid')\r\n\r\n# Sync\r\nsubscription = client.subscriptions().reactivate_sync('subscription-uuid')\r\n```\r\n\r\n### Subscription Plans Service\r\n\r\n#### List Subscription Plans\r\n\r\n```python\r\n# Async\r\nplans = await client.subscription_plans().list(\r\n page=1,\r\n per_page=20,\r\n currency='BRL'\r\n)\r\n\r\n# Sync\r\nplans = client.subscription_plans().list_sync(\r\n page=1,\r\n per_page=20,\r\n currency='BRL'\r\n)\r\n\r\nprint(f\"Total plans: {plans.total}\")\r\nfor plan in plans.data:\r\n print(f\"Plan: {plan.name} - Price: {plan.price}\")\r\n```\r\n\r\n#### Get All Plans\r\n\r\n```python\r\n# Async\r\nall_plans = await client.subscription_plans().all(currency='BRL')\r\n\r\n# Sync\r\nall_plans = client.subscription_plans().all_sync(currency='BRL')\r\n```\r\n\r\n## Type Safety with Pydantic\r\n\r\nThe SDK uses Pydantic models for type safety and validation:\r\n\r\n```python\r\nfrom hotpayments import CreateCustomerRequest, CreateQrCodeRequest\r\n\r\n# Type-safe customer creation\r\ncustomer_data = CreateCustomerRequest(\r\n name='Jo\u00e3o Silva',\r\n email='joao@example.com',\r\n phone_number='11999999999',\r\n document='12345678901'\r\n)\r\n\r\ncustomer = await client.customers().create(customer_data)\r\n\r\n# Type-safe QR code creation\r\nqr_data = CreateQrCodeRequest(\r\n amount=100.50,\r\n customer_id=customer.uuid,\r\n description='Payment for order #123'\r\n)\r\n\r\ntransaction = await client.transactions().create_pix_qr_code(qr_data)\r\n```\r\n\r\n## Error Handling\r\n\r\nThe SDK provides a simple exception class for API errors:\r\n\r\n```python\r\nfrom hotpayments import Hotpayments, HotpaymentsException\r\n\r\ntry:\r\n customer = await client.customers().create({\r\n 'name': 'Jo\u00e3o Silva',\r\n 'email': 'invalid-email',\r\n })\r\nexcept HotpaymentsException as e:\r\n print(f\"API Error: {e}\")\r\n if e.status_code:\r\n print(f\"Status Code: {e.status_code}\")\r\n```\r\n\r\n## Async vs Sync\r\n\r\nThe SDK supports both asynchronous and synchronous operations:\r\n\r\n- **Async methods**: Use `await` with methods like `create()`, `list()`, `show()`, etc.\r\n- **Sync methods**: Use methods ending with `_sync` like `create_sync()`, `list_sync()`, `show_sync()`, etc.\r\n\r\nChoose async for better performance in I/O-bound applications, and sync for simpler integration in traditional synchronous codebases.\r\n\r\n## Configuration\r\n\r\n### Custom Base URL\r\n\r\n```python\r\nclient = Hotpayments(\r\n api_key='your-api-key',\r\n base_url='https://api.hotpayments.com', # Custom base URL\r\n timeout=60.0 # Custom timeout in seconds\r\n)\r\n```\r\n\r\n### Environment Variables\r\n\r\nYou can also set the API key using environment variables:\r\n\r\n```bash\r\nexport HOTPAYMENTS_API_KEY=your-api-key-here\r\n```\r\n\r\n## Requirements\r\n\r\n- Python 3.8 or higher\r\n- httpx (for HTTP requests)\r\n- pydantic (for data validation and serialization)\r\n\r\n## Development\r\n\r\n### Installing for Development\r\n\r\n```bash\r\ngit clone https://github.com/hotpayments/python-sdk.git\r\ncd python-sdk\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Running Tests\r\n\r\n```bash\r\npytest\r\n```\r\n\r\n### Code Formatting\r\n\r\n```bash\r\nblack src tests\r\nisort src tests\r\n```\r\n\r\n### Type Checking\r\n\r\n```bash\r\nmypy src\r\n```\r\n\r\n## Support\r\n\r\nFor support, please contact [contato@hotpayments.net](mailto:contato@hotpayments.net) or visit our documentation.\r\n\r\n## License\r\n\r\nThis package is open-sourced software licensed under the [MIT license](LICENSE).\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for HotPayments API - Handle payments, subscriptions, PIX transactions with a clean, async-ready interface.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/hotpayments/python-sdk/issues",
"Documentation": "https://github.com/hotpayments/python-sdk",
"Homepage": "https://github.com/hotpayments/python-sdk",
"Repository": "https://github.com/hotpayments/python-sdk.git"
},
"split_keywords": [
"payments",
" pix",
" subscriptions",
" hotpayments",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "693e601c23cbc18be793bc8795638279ffdf219e4182b2239f3c549f154376b2",
"md5": "a9eb1ef2cbf01e8b05525a8c8a6a39f1",
"sha256": "c216b877ae35826e6f5dd22361440ab03ba96dd1727fc421d9d65ba0edb3a547"
},
"downloads": -1,
"filename": "hotpayments_python_sdk-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a9eb1ef2cbf01e8b05525a8c8a6a39f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13791,
"upload_time": "2025-08-02T19:14:30",
"upload_time_iso_8601": "2025-08-02T19:14:30.256677Z",
"url": "https://files.pythonhosted.org/packages/69/3e/601c23cbc18be793bc8795638279ffdf219e4182b2239f3c549f154376b2/hotpayments_python_sdk-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f7bfa92d2d78d530d27f2c833295ae2454d304fe8a1d7cc116c4231d3a07a7f2",
"md5": "641e7cf0f882bdf89165a00ce371bbc3",
"sha256": "9812ccab9931f5920cf51b4e376098f22b8653147b48d6e6d00002509fefb8e2"
},
"downloads": -1,
"filename": "hotpayments_python_sdk-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "641e7cf0f882bdf89165a00ce371bbc3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13705,
"upload_time": "2025-08-02T19:14:31",
"upload_time_iso_8601": "2025-08-02T19:14:31.642334Z",
"url": "https://files.pythonhosted.org/packages/f7/bf/a92d2d78d530d27f2c833295ae2454d304fe8a1d7cc116c4231d3a07a7f2/hotpayments_python_sdk-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 19:14:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hotpayments",
"github_project": "python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hotpayments-python-sdk"
}
