# PayAgency API Python SDK
A comprehensive Python SDK for PayAgency payment processing platform, supporting multiple payment methods including card payments, cryptocurrency transactions, payouts, and payment links.
## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [API Reference](#api-reference)
- [Payment](#payment)
- [Payout](#payout)
- [Payment Links](#payment-links)
- [Cryptocurrency](#cryptocurrency)
- [Transactions](#transactions)
- [Refunds](#refunds)
- [Error Handling](#error-handling)
- [Security](#security)
- [Environment](#environment)
- [Type Hints Support](#type-hints-support)
- [License](#license)
## Installation
```bash
pip install payagency-api
```
## Quick Start
```python
from payagency_api import PayAgencyApi
# Initialize the SDK with minimal configuration
pay_agency = PayAgencyApi(
encryption_key="89ca59fb3b49ada55851021df12cfbc5", # 32-character encryption key
secret_key="PA_TEST_your-secret-key", # or PA_LIVE_ for production
# base_url is optional - defaults to https://backend.pay.agency
)
# Or with custom base URL
pay_agency = PayAgencyApi(
encryption_key="89ca59fb3b49ada55851021df12cfbc5",
secret_key="PA_TEST_your-secret-key",
base_url="https://CUSTOM_SUB_DOMAIN.pay.agency"
)
# Make a payment
payment = pay_agency.payment.s2s({
"first_name": "James",
"last_name": "Dean",
"email": "james@gmail.com",
"address": "64 Hertingfordbury Rd",
"country": "GB",
"city": "Newport",
"state": "GB",
"zip": "TF10 8DF",
"ip_address": "127.0.0.1",
"phone_number": "7654233212",
"amount": 100,
"currency": "GBP",
"card_number": "4111111111111111",
"card_expiry_month": "12",
"card_expiry_year": "2027",
"card_cvv": "029",
"redirect_url": "https://pay.agency",
"webhook_url": "https://pay.agency/webhook",
"terminal_id": "T12345", # optional
})
```
## Configuration
### PayAgencyClientOptions
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ----------------------------------------------------------------- |
| `encryption_key` | str | Yes | 32-character encryption key for payload encryption |
| `secret_key` | str | Yes | Your API secret key (PA_TEST for test, PA_LIVE for live) |
| `base_url` | str | No | PayAgency API base URL (defaults to `https://backend.pay.agency`) |
### Environment Detection
The SDK automatically detects the environment based on your secret key:
- Keys starting with `PA_LIVE_` use live endpoints
- Keys starting with `PA_TEST_` use test endpoints
## API Reference
### Payment
The Payment module supports multiple payment methods:
#### Server-to-Server (S2S) Card Payments
```python
result = pay_agency.payment.s2s({
"first_name": "James",
"last_name": "Dean",
"email": "james@gmail.com",
"address": "64 Hertingfordbury Rd",
"country": "GB",
"city": "Newport",
"state": "GB",
"zip": "TF10 8DF",
"ip_address": "127.0.0.1",
"phone_number": "7654233212",
"amount": 100,
"currency": "GBP",
"card_number": "4111111111111111",
"card_expiry_month": "12",
"card_expiry_year": "2027",
"card_cvv": "029",
"redirect_url": "https://pay.agency",
"webhook_url": "https://pay.agency/webhook", # optional
"order_id": "ORDER_123", # optional
"terminal_id": "T12345", # optional
})
# Response format (Python dict):
{
"status": "SUCCESS" | "REDIRECT" | "FAILED",
"message": str,
"data": {
"amount": int,
"currency": str,
"order_id": str | None,
"transaction_id": str,
"customer": {
"first_name": str,
"last_name": str,
"email": str,
},
"refund": {
"status": bool,
"refund_date": str | None,
},
"chargeback": {
"status": bool,
"chargeback_date": str | None,
},
},
"redirect_url": str # Present for REDIRECT status
}
```
#### Hosted Payment
```python
hosted_payment = pay_agency.payment.hosted({
"first_name": "James",
"last_name": "Dean",
"email": "james@gmail.com",
"address": "64 Hertingfordbury Rd",
"country": "GB",
"city": "Newport",
"state": "GB",
"zip": "TF10 8DF",
"ip_address": "127.0.0.1",
"phone_number": "7654233212",
"amount": 100,
"currency": "GBP",
"redirect_url": "https://pay.agency",
"webhook_url": "https://pay.agency/webhook", # optional
"order_id": "ORDER_123", # optional
"terminal_id": "T12345", # optional
})
# Returns the same response format as S2S
```
#### Alternative Payment Methods (APM)
```python
apm_payment = pay_agency.payment.apm({
"first_name": "James",
"last_name": "Dean",
"email": "james@gmail.com",
"address": "64 Hertingfordbury Rd",
"country": "GB",
"city": "Newport",
"state": "GB",
"zip": "TF10 8DF",
"ip_address": "127.0.0.1",
"phone_number": "7654233212",
"amount": 100,
"currency": "GBP",
"redirect_url": "https://pay.agency",
"webhook_url": "https://pay.agency/webhook", # optional
"order_id": "ORDER_123", # optional
"terminal_id": "T12345", # optional
})
# Returns the same response format as S2S
```
### Payout
Manage payouts and wallet operations:
#### Create Payout
```python
payout = pay_agency.payout.create_payout({
"wallet_id": "WAL1234567890",
"first_name": "James",
"last_name": "Dean",
"email": "james@gmail.com",
"address": "64 Hertingfordbury Rd",
"country": "US",
"city": "Newport",
"state": "US",
"zip": "TF10 8DF",
"ip_address": "127.0.0.1",
"phone_number": "7654233212",
"amount": 100,
"currency": "USD",
"card_number": "4222222222222222",
"card_expiry_month": "10",
"card_expiry_year": "2030",
"webhook_url": "https://pay.agency/webhook", # optional
"order_id": "ORDER_123", # optional
})
# Response format:
{
"status": "SUCCESS" | "BLOCKED" | "PENDING",
"message": str,
"data": {
"amount": int,
"currency": str,
"order_id": str | None,
"transaction_id": str,
"customer": {
"first_name": str,
"last_name": str,
"email": str,
},
},
"redirect_url": str # optional
}
```
#### Get Wallets
```python
# Get all wallets
wallets = pay_agency.payout.get_wallets()
# Response format:
{
"data": [
{
"wallet_id": str,
"currency": str,
"amount": int,
"payment_method": str,
"status": "Active" | "Inactive",
}
]
}
```
#### Estimate Payout Fee
```python
fee_estimate = pay_agency.payout.estimate_fee({
"wallet_id": "WAL7825818519632620",
"amount": 200,
"card_number": "4111111111111111",
})
# Response format:
{
"data": {
"amount_required": int,
"wallet_balance": int,
"total_fee": int,
}
}
```
#### Check Payout Status
```python
status = pay_agency.payout.get_payout_status("PAYOUT_REFERENCE_123")
# Response format:
{
"status": "SUCCESS" | "PENDING" | "FAILED",
"message": str,
"data": {
"amount": int,
"currency": str,
"order_id": str | None,
"transaction_id": str,
"customer": {
"first_name": str,
"last_name": str,
"email": str,
},
}
}
```
### Payment Links
Create and manage payment links:
#### Create Payment Link
```python
payment_link = pay_agency.payment_link.create({
"payment_template_id": "PLI07435325281394735", # Required
"amount": 1000, # optional
"currency": "USD", # optional
"expiry_date": "2024-12-31", # optional
"terminal_id": "T12345", # optional
"order_id": "ORDER_123", # optional
})
# Response format:
{
"message": str,
"data": str # The payment link URL
}
```
#### Get Payment Templates
```python
templates = pay_agency.payment_link.get_templates()
# Response format:
{
"data": [
{
"template_id": str,
"template_name": str,
"payment_template_id": str,
"template_screenshot": str,
"redirect_url": str,
"webhook_url": str,
}
]
}
```
### Cryptocurrency
Handle cryptocurrency transactions:
#### Comprehensive Methods
The Crypto module provides both individual convenience methods and comprehensive methods for full control:
##### Full-Featured Payment Method
```python
# Full crypto payment method - handles both OnRamp and OffRamp based on transaction_type
crypto_payment = pay_agency.crypto.payment({
"transaction_type": "ONRAMP", # or "OFFRAMP"
"first_name": "Diana",
"last_name": "Prince",
"email": "diana@pay.agency",
"phone_number": "0123456789",
"fiat_amount": 200, # Required for ONRAMP, omit for OFFRAMP
# "crypto_amount": "0.05", # Required for OFFRAMP, omit for ONRAMP
"fiat_currency": "EUR",
"crypto_currency": "BTC",
"wallet_address": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
"ip_address": "127.0.0.1",
"country": "GB",
"crypto_network": "BITCOIN",
"redirect_url": "https://pay.agency",
"webhook_url": "https://pay.agency/webhook", # optional
"order_id": "ORDER_123", # optional
"terminal_id": "T12345", # optional
})
```
##### OnRamp (Fiat to Crypto)
```python
# Create OnRamp payment link
on_ramp_link = pay_agency.crypto.on_ramp_link({
"fiat_amount": 100,
"fiat_currency": "GBP",
"crypto_currency": "BTC",
"payment_template_id": "PLI07435325281394735",
"order_id": "ORDER_123", # optional
"terminal_id": "T12345", # optional
"expiry_date": "2024-12-31", # optional
})
# Direct OnRamp transaction
on_ramp = pay_agency.crypto.on_ramp({
"first_name": "Diana",
"last_name": "Prince",
"email": "diana@pay.agency",
"phone_number": "0123456789",
"fiat_amount": 200,
"fiat_currency": "EUR",
"crypto_currency": "BTC",
"wallet_address": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
"ip_address": "127.0.0.1",
"country": "GB",
"crypto_network": "BITCOIN",
"redirect_url": "https://pay.agency",
"webhook_url": "https://pay.agency/webhook", # optional
"order_id": "ORDER_123", # optional
"terminal_id": "T12345", # optional
})
# Response format:
{
"status": "REDIRECT" | "PENDING" | "FAILED",
"message": str,
"redirect_url": str, # optional
"data": {
"transaction_id": str,
"fiat": str,
"fiat_amount": int,
"crypto": str,
"crypto_amount": int,
"customer": {
"first_name": str,
"last_name": str,
"email": str,
},
}
}
```
##### OffRamp (Crypto to Fiat)
```python
# Create OffRamp payment link
off_ramp_link = pay_agency.crypto.off_ramp_link({
"fiat_currency": "GBP",
"crypto_currency": "BTC",
"crypto_amount": "0.01",
"payment_template_id": "PLI07435325281394735",
"order_id": "ORDER_123", # optional
"terminal_id": "T12345", # optional
"expiry_date": "2024-12-31", # optional
})
# Direct OffRamp transaction
off_ramp = pay_agency.crypto.off_ramp({
"first_name": "Ethan",
"last_name": "Hunt",
"email": "ethan@pay.agency",
"phone_number": "0123456789",
"fiat_currency": "GBP",
"crypto_currency": "BTC",
"crypto_amount": "0.05",
"wallet_address": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
"ip_address": "127.0.0.1",
"country": "GB",
"crypto_network": "BITCOIN",
"redirect_url": "https://pay.agency",
"webhook_url": "https://pay.agency/webhook", # optional
"order_id": "ORDER_123", # optional
"terminal_id": "T12345", # optional
})
# Returns the same response format as OnRamp
```
#### Crypto PayIn
```python
# Get supported currencies
currencies = pay_agency.crypto.get_currencies({
"country": "GB", # ISO 3166-1 alpha-2 country code
"amount": 100,
})
# Response format:
{
"message": str,
"data": [
{
"name": str,
"code": str,
"symbol": str,
}
]
}
# Create PayIn link
payin_link = pay_agency.crypto.payin_link({
"fiat_amount": 150,
"fiat_currency": "USD",
"crypto_currency": "BTC",
"payment_template_id": "PLI07435325281394735",
"order_id": "ORDER_123", # optional
"terminal_id": "T12345", # optional
"expiry_date": "2024-12-31", # optional
})
# Direct crypto payin
payin = pay_agency.crypto.payin({
"first_name": "Fiona",
"last_name": "Gallagher",
"email": "hello@gmail.com",
"address": "64 Hertingfordbury Rd",
"phone_number": "0123456789",
"ip_address": "127.0.0.1",
"crypto_currency": "BTC",
"amount": 300,
"currency": "USD",
"crypto_network": "BITCOIN",
"country": "US",
"redirect_url": "https://pay.agency",
"webhook_url": "https://pay.agency/webhook", # optional
"order_id": "ORDER_123", # optional
"terminal_id": "T12345", # optional
})
# Response format:
{
"status": "SUCCESS" | "PENDING" | "FAILED",
"message": str,
"redirect_url": str, # optional
"data": {
"amount": int,
"currency": str,
"order_id": str | None,
"transaction_id": str,
"customer": {
"first_name": str,
"last_name": str,
"email": str,
},
"crypto_currency": str,
}
}
```
### Transactions
Query transaction history:
#### Get Transactions
```python
transactions = pay_agency.txn.get_transactions({
"transaction_start_date": "2023-01-01", # optional
"transaction_end_date": "2023-12-31", # optional
"next_cursor": "cursor_value", # optional - for pagination
"prev_cursor": "cursor_value", # optional - for pagination
})
# Response format:
{
"message": str,
"data": [
{
"first_name": str,
"last_name": str,
"converted_amount": str,
"converted_currency": str,
"transaction_id": str,
"amount": str,
"currency": str,
"status": str,
"card_type": str | None,
"card_number": str | None,
"transaction_type": str,
"order_id": str | None,
"country": str,
"email": str,
"created_at": str,
"transaction_date": str,
"chargeback_date": str | None,
"refund_date": str | None,
"suspicious_date": str | None,
"merchant_connector": {
"name": str,
},
"user": {
"name": str,
"user_kyc": {
"name": str,
},
},
}
],
"meta": {
"has_next_page": bool,
"has_previous_page": bool,
"next_cursor": str, # optional
"prev_cursor": str, # optional
"total_count": int,
}
}
```
#### Get Wallet Transactions
```python
wallet_transactions = pay_agency.txn.get_wallet_transactions({
"transaction_start_date": "2023-01-01", # optional
"transaction_end_date": "2023-12-31", # optional
"next_cursor": "cursor_value", # optional - for pagination
"prev_cursor": "cursor_value", # optional - for pagination
})
# Returns the same response format as get_transactions
```
### Refunds
Process refunds:
```python
# Direct refund method
refund = pay_agency.refund({
"reason": "Customer request",
"transaction_id": "TXN_123",
})
# Response format:
{
"status": "SUCCESS",
"message": str,
"data": {
"amount": int,
"currency": str,
"order_id": str | None,
"transaction_id": str,
"customer": {
"first_name": str,
"last_name": str,
"email": str,
},
"refund": {
"status": bool,
"refund_date": str | None,
},
"chargeback": {
"status": bool,
"chargeback_date": str | None,
},
}
}
```
## Error Handling
The SDK uses requests for HTTP requests and will raise exceptions for failed requests:
```python
from payagency_api import PayAgencyApi, PayAgencyError
try:
payment = pay_agency.payment.s2s(payment_data)
print("Payment successful:", payment)
except PayAgencyError as e:
# PayAgency API error
print(f"Payment failed: {e}")
print(f"Status code: {e.status_code}")
print(f"Response: {e.response}")
except requests.RequestException as e:
# Network error
print(f"Network error: {e}")
except Exception as e:
# Other error
print(f"Error: {e}")
```
## Security
### Encryption
The SDK automatically encrypts request payloads using AES-256-CBC encryption with your provided encryption key. Some endpoints (like payment links and refunds) skip encryption as indicated by the `skip_encryption` parameter.
### API Key Security
- Never expose your API keys in client-side code
- Use test keys (`PA_TEST_`) for development
- Use live keys (`PA_LIVE_`) only in production
- Rotate your keys regularly
### Best Practices
1. Store API keys in environment variables
2. Use HTTPS for all webhook URLs
3. Validate webhook signatures on your server
4. Implement proper error handling
5. Log transactions for auditing
## Environment
The SDK supports both test and live environments:
### Test Environment
- Use secret keys starting with `PA_TEST_`
- Returns mock data for certain endpoints (wallets, fee estimation)
- Safe for development and testing
### Live Environment
- Use secret keys starting with `PA_LIVE_`
- Processes real transactions
- Use only in production
## Type Hints Support
The SDK is written with comprehensive type hints for better IDE support and type checking:
```python
from payagency_api import PayAgencyApi
from payagency_api.types import (
PaymentResponse,
PayoutResponse,
CryptoPaymentResponse,
RefundResponse,
)
# Type hints are included for all methods and responses
def process_payment(pay_agency: PayAgencyApi) -> PaymentResponse:
return pay_agency.payment.s2s({
"first_name": "John",
"last_name": "Doe",
# ... other fields
})
```
### Important Notes
- **Payment amounts**: Use actual currency amounts as integers (e.g., 1 for $1.00 or £1.00)
- **Crypto amounts**: For crypto, use string format for precise decimal values (e.g., "0.01" for Bitcoin)
- **Country codes**: Use ISO 3166-1 alpha-2 country codes (e.g., "GB", "US")
- **Currency codes**: Use ISO 4217 currency codes (e.g., "USD", "GBP", "EUR")
- **Crypto networks**: Use uppercase format (e.g., "BITCOIN", "ETHEREUM")
- **Card expiry years**: Use full 4-digit format (e.g., "2027", not "27")
- **Optional fields**: Fields marked as optional can be omitted from the payload
## License
MIT License - see the LICENSE file for details.
## Support
For support and documentation, please visit [PayAgency Documentation](https://docs.pay.agency) or contact support@pay.agency
---
**Version**: 1.0.0
**Author**: PaneruVipin
**Repository**: [payagency-python](https://github.com/vp-payomatix/payagency-python-sdk)
Raw data
{
"_id": null,
"home_page": "https://github.com/vp-payomatix/payagency-python",
"name": "payagency-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "payagency, payment, api, sdk, cryptocurrency, payout, card",
"author": "PaneruVipin",
"author_email": "PaneruVipin <support@pay.agency>",
"download_url": "https://files.pythonhosted.org/packages/56/04/6d98c084a242b3414bc4d12b01326462fe290169691f6e45f4c97f2f107b/payagency_api-1.0.0.tar.gz",
"platform": null,
"description": "# PayAgency API Python SDK\n\nA comprehensive Python SDK for PayAgency payment processing platform, supporting multiple payment methods including card payments, cryptocurrency transactions, payouts, and payment links.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [API Reference](#api-reference)\n - [Payment](#payment)\n - [Payout](#payout)\n - [Payment Links](#payment-links)\n - [Cryptocurrency](#cryptocurrency)\n - [Transactions](#transactions)\n - [Refunds](#refunds)\n- [Error Handling](#error-handling)\n- [Security](#security)\n- [Environment](#environment)\n- [Type Hints Support](#type-hints-support)\n- [License](#license)\n\n## Installation\n\n```bash\npip install payagency-api\n```\n\n## Quick Start\n\n```python\nfrom payagency_api import PayAgencyApi\n\n# Initialize the SDK with minimal configuration\npay_agency = PayAgencyApi(\n encryption_key=\"89ca59fb3b49ada55851021df12cfbc5\", # 32-character encryption key\n secret_key=\"PA_TEST_your-secret-key\", # or PA_LIVE_ for production\n # base_url is optional - defaults to https://backend.pay.agency\n)\n\n# Or with custom base URL\npay_agency = PayAgencyApi(\n encryption_key=\"89ca59fb3b49ada55851021df12cfbc5\",\n secret_key=\"PA_TEST_your-secret-key\",\n base_url=\"https://CUSTOM_SUB_DOMAIN.pay.agency\"\n)\n\n# Make a payment\npayment = pay_agency.payment.s2s({\n \"first_name\": \"James\",\n \"last_name\": \"Dean\",\n \"email\": \"james@gmail.com\",\n \"address\": \"64 Hertingfordbury Rd\",\n \"country\": \"GB\",\n \"city\": \"Newport\",\n \"state\": \"GB\",\n \"zip\": \"TF10 8DF\",\n \"ip_address\": \"127.0.0.1\",\n \"phone_number\": \"7654233212\",\n \"amount\": 100,\n \"currency\": \"GBP\",\n \"card_number\": \"4111111111111111\",\n \"card_expiry_month\": \"12\",\n \"card_expiry_year\": \"2027\",\n \"card_cvv\": \"029\",\n \"redirect_url\": \"https://pay.agency\",\n \"webhook_url\": \"https://pay.agency/webhook\",\n \"terminal_id\": \"T12345\", # optional\n})\n```\n\n## Configuration\n\n### PayAgencyClientOptions\n\n| Parameter | Type | Required | Description |\n| ---------------- | ---- | -------- | ----------------------------------------------------------------- |\n| `encryption_key` | str | Yes | 32-character encryption key for payload encryption |\n| `secret_key` | str | Yes | Your API secret key (PA_TEST for test, PA_LIVE for live) |\n| `base_url` | str | No | PayAgency API base URL (defaults to `https://backend.pay.agency`) |\n\n### Environment Detection\n\nThe SDK automatically detects the environment based on your secret key:\n\n- Keys starting with `PA_LIVE_` use live endpoints\n- Keys starting with `PA_TEST_` use test endpoints\n\n## API Reference\n\n### Payment\n\nThe Payment module supports multiple payment methods:\n\n#### Server-to-Server (S2S) Card Payments\n\n```python\nresult = pay_agency.payment.s2s({\n \"first_name\": \"James\",\n \"last_name\": \"Dean\",\n \"email\": \"james@gmail.com\",\n \"address\": \"64 Hertingfordbury Rd\",\n \"country\": \"GB\",\n \"city\": \"Newport\",\n \"state\": \"GB\",\n \"zip\": \"TF10 8DF\",\n \"ip_address\": \"127.0.0.1\",\n \"phone_number\": \"7654233212\",\n \"amount\": 100,\n \"currency\": \"GBP\",\n \"card_number\": \"4111111111111111\",\n \"card_expiry_month\": \"12\",\n \"card_expiry_year\": \"2027\",\n \"card_cvv\": \"029\",\n \"redirect_url\": \"https://pay.agency\",\n \"webhook_url\": \"https://pay.agency/webhook\", # optional\n \"order_id\": \"ORDER_123\", # optional\n \"terminal_id\": \"T12345\", # optional\n})\n\n# Response format (Python dict):\n{\n \"status\": \"SUCCESS\" | \"REDIRECT\" | \"FAILED\",\n \"message\": str,\n \"data\": {\n \"amount\": int,\n \"currency\": str,\n \"order_id\": str | None,\n \"transaction_id\": str,\n \"customer\": {\n \"first_name\": str,\n \"last_name\": str,\n \"email\": str,\n },\n \"refund\": {\n \"status\": bool,\n \"refund_date\": str | None,\n },\n \"chargeback\": {\n \"status\": bool,\n \"chargeback_date\": str | None,\n },\n },\n \"redirect_url\": str # Present for REDIRECT status\n}\n```\n\n#### Hosted Payment\n\n```python\nhosted_payment = pay_agency.payment.hosted({\n \"first_name\": \"James\",\n \"last_name\": \"Dean\",\n \"email\": \"james@gmail.com\",\n \"address\": \"64 Hertingfordbury Rd\",\n \"country\": \"GB\",\n \"city\": \"Newport\",\n \"state\": \"GB\",\n \"zip\": \"TF10 8DF\",\n \"ip_address\": \"127.0.0.1\",\n \"phone_number\": \"7654233212\",\n \"amount\": 100,\n \"currency\": \"GBP\",\n \"redirect_url\": \"https://pay.agency\",\n \"webhook_url\": \"https://pay.agency/webhook\", # optional\n \"order_id\": \"ORDER_123\", # optional\n \"terminal_id\": \"T12345\", # optional\n})\n\n# Returns the same response format as S2S\n```\n\n#### Alternative Payment Methods (APM)\n\n```python\napm_payment = pay_agency.payment.apm({\n \"first_name\": \"James\",\n \"last_name\": \"Dean\",\n \"email\": \"james@gmail.com\",\n \"address\": \"64 Hertingfordbury Rd\",\n \"country\": \"GB\",\n \"city\": \"Newport\",\n \"state\": \"GB\",\n \"zip\": \"TF10 8DF\",\n \"ip_address\": \"127.0.0.1\",\n \"phone_number\": \"7654233212\",\n \"amount\": 100,\n \"currency\": \"GBP\",\n \"redirect_url\": \"https://pay.agency\",\n \"webhook_url\": \"https://pay.agency/webhook\", # optional\n \"order_id\": \"ORDER_123\", # optional\n \"terminal_id\": \"T12345\", # optional\n})\n\n# Returns the same response format as S2S\n```\n\n### Payout\n\nManage payouts and wallet operations:\n\n#### Create Payout\n\n```python\npayout = pay_agency.payout.create_payout({\n \"wallet_id\": \"WAL1234567890\",\n \"first_name\": \"James\",\n \"last_name\": \"Dean\",\n \"email\": \"james@gmail.com\",\n \"address\": \"64 Hertingfordbury Rd\",\n \"country\": \"US\",\n \"city\": \"Newport\",\n \"state\": \"US\",\n \"zip\": \"TF10 8DF\",\n \"ip_address\": \"127.0.0.1\",\n \"phone_number\": \"7654233212\",\n \"amount\": 100,\n \"currency\": \"USD\",\n \"card_number\": \"4222222222222222\",\n \"card_expiry_month\": \"10\",\n \"card_expiry_year\": \"2030\",\n \"webhook_url\": \"https://pay.agency/webhook\", # optional\n \"order_id\": \"ORDER_123\", # optional\n})\n\n# Response format:\n{\n \"status\": \"SUCCESS\" | \"BLOCKED\" | \"PENDING\",\n \"message\": str,\n \"data\": {\n \"amount\": int,\n \"currency\": str,\n \"order_id\": str | None,\n \"transaction_id\": str,\n \"customer\": {\n \"first_name\": str,\n \"last_name\": str,\n \"email\": str,\n },\n },\n \"redirect_url\": str # optional\n}\n```\n\n#### Get Wallets\n\n```python\n# Get all wallets\nwallets = pay_agency.payout.get_wallets()\n\n# Response format:\n{\n \"data\": [\n {\n \"wallet_id\": str,\n \"currency\": str,\n \"amount\": int,\n \"payment_method\": str,\n \"status\": \"Active\" | \"Inactive\",\n }\n ]\n}\n```\n\n#### Estimate Payout Fee\n\n```python\nfee_estimate = pay_agency.payout.estimate_fee({\n \"wallet_id\": \"WAL7825818519632620\",\n \"amount\": 200,\n \"card_number\": \"4111111111111111\",\n})\n\n# Response format:\n{\n \"data\": {\n \"amount_required\": int,\n \"wallet_balance\": int,\n \"total_fee\": int,\n }\n}\n```\n\n#### Check Payout Status\n\n```python\nstatus = pay_agency.payout.get_payout_status(\"PAYOUT_REFERENCE_123\")\n\n# Response format:\n{\n \"status\": \"SUCCESS\" | \"PENDING\" | \"FAILED\",\n \"message\": str,\n \"data\": {\n \"amount\": int,\n \"currency\": str,\n \"order_id\": str | None,\n \"transaction_id\": str,\n \"customer\": {\n \"first_name\": str,\n \"last_name\": str,\n \"email\": str,\n },\n }\n}\n```\n\n### Payment Links\n\nCreate and manage payment links:\n\n#### Create Payment Link\n\n```python\npayment_link = pay_agency.payment_link.create({\n \"payment_template_id\": \"PLI07435325281394735\", # Required\n \"amount\": 1000, # optional\n \"currency\": \"USD\", # optional\n \"expiry_date\": \"2024-12-31\", # optional\n \"terminal_id\": \"T12345\", # optional\n \"order_id\": \"ORDER_123\", # optional\n})\n\n# Response format:\n{\n \"message\": str,\n \"data\": str # The payment link URL\n}\n```\n\n#### Get Payment Templates\n\n```python\ntemplates = pay_agency.payment_link.get_templates()\n\n# Response format:\n{\n \"data\": [\n {\n \"template_id\": str,\n \"template_name\": str,\n \"payment_template_id\": str,\n \"template_screenshot\": str,\n \"redirect_url\": str,\n \"webhook_url\": str,\n }\n ]\n}\n```\n\n### Cryptocurrency\n\nHandle cryptocurrency transactions:\n\n#### Comprehensive Methods\n\nThe Crypto module provides both individual convenience methods and comprehensive methods for full control:\n\n##### Full-Featured Payment Method\n\n```python\n# Full crypto payment method - handles both OnRamp and OffRamp based on transaction_type\ncrypto_payment = pay_agency.crypto.payment({\n \"transaction_type\": \"ONRAMP\", # or \"OFFRAMP\"\n \"first_name\": \"Diana\",\n \"last_name\": \"Prince\",\n \"email\": \"diana@pay.agency\",\n \"phone_number\": \"0123456789\",\n \"fiat_amount\": 200, # Required for ONRAMP, omit for OFFRAMP\n # \"crypto_amount\": \"0.05\", # Required for OFFRAMP, omit for ONRAMP\n \"fiat_currency\": \"EUR\",\n \"crypto_currency\": \"BTC\",\n \"wallet_address\": \"1BoatSLRHtKNngkdXEeobR76b53LETtpyT\",\n \"ip_address\": \"127.0.0.1\",\n \"country\": \"GB\",\n \"crypto_network\": \"BITCOIN\",\n \"redirect_url\": \"https://pay.agency\",\n \"webhook_url\": \"https://pay.agency/webhook\", # optional\n \"order_id\": \"ORDER_123\", # optional\n \"terminal_id\": \"T12345\", # optional\n})\n```\n\n##### OnRamp (Fiat to Crypto)\n\n```python\n# Create OnRamp payment link\non_ramp_link = pay_agency.crypto.on_ramp_link({\n \"fiat_amount\": 100,\n \"fiat_currency\": \"GBP\",\n \"crypto_currency\": \"BTC\",\n \"payment_template_id\": \"PLI07435325281394735\",\n \"order_id\": \"ORDER_123\", # optional\n \"terminal_id\": \"T12345\", # optional\n \"expiry_date\": \"2024-12-31\", # optional\n})\n\n# Direct OnRamp transaction\non_ramp = pay_agency.crypto.on_ramp({\n \"first_name\": \"Diana\",\n \"last_name\": \"Prince\",\n \"email\": \"diana@pay.agency\",\n \"phone_number\": \"0123456789\",\n \"fiat_amount\": 200,\n \"fiat_currency\": \"EUR\",\n \"crypto_currency\": \"BTC\",\n \"wallet_address\": \"1BoatSLRHtKNngkdXEeobR76b53LETtpyT\",\n \"ip_address\": \"127.0.0.1\",\n \"country\": \"GB\",\n \"crypto_network\": \"BITCOIN\",\n \"redirect_url\": \"https://pay.agency\",\n \"webhook_url\": \"https://pay.agency/webhook\", # optional\n \"order_id\": \"ORDER_123\", # optional\n \"terminal_id\": \"T12345\", # optional\n})\n\n# Response format:\n{\n \"status\": \"REDIRECT\" | \"PENDING\" | \"FAILED\",\n \"message\": str,\n \"redirect_url\": str, # optional\n \"data\": {\n \"transaction_id\": str,\n \"fiat\": str,\n \"fiat_amount\": int,\n \"crypto\": str,\n \"crypto_amount\": int,\n \"customer\": {\n \"first_name\": str,\n \"last_name\": str,\n \"email\": str,\n },\n }\n}\n```\n\n##### OffRamp (Crypto to Fiat)\n\n```python\n# Create OffRamp payment link\noff_ramp_link = pay_agency.crypto.off_ramp_link({\n \"fiat_currency\": \"GBP\",\n \"crypto_currency\": \"BTC\",\n \"crypto_amount\": \"0.01\",\n \"payment_template_id\": \"PLI07435325281394735\",\n \"order_id\": \"ORDER_123\", # optional\n \"terminal_id\": \"T12345\", # optional\n \"expiry_date\": \"2024-12-31\", # optional\n})\n\n# Direct OffRamp transaction\noff_ramp = pay_agency.crypto.off_ramp({\n \"first_name\": \"Ethan\",\n \"last_name\": \"Hunt\",\n \"email\": \"ethan@pay.agency\",\n \"phone_number\": \"0123456789\",\n \"fiat_currency\": \"GBP\",\n \"crypto_currency\": \"BTC\",\n \"crypto_amount\": \"0.05\",\n \"wallet_address\": \"1BoatSLRHtKNngkdXEeobR76b53LETtpyT\",\n \"ip_address\": \"127.0.0.1\",\n \"country\": \"GB\",\n \"crypto_network\": \"BITCOIN\",\n \"redirect_url\": \"https://pay.agency\",\n \"webhook_url\": \"https://pay.agency/webhook\", # optional\n \"order_id\": \"ORDER_123\", # optional\n \"terminal_id\": \"T12345\", # optional\n})\n\n# Returns the same response format as OnRamp\n```\n\n#### Crypto PayIn\n\n```python\n# Get supported currencies\ncurrencies = pay_agency.crypto.get_currencies({\n \"country\": \"GB\", # ISO 3166-1 alpha-2 country code\n \"amount\": 100,\n})\n\n# Response format:\n{\n \"message\": str,\n \"data\": [\n {\n \"name\": str,\n \"code\": str,\n \"symbol\": str,\n }\n ]\n}\n\n# Create PayIn link\npayin_link = pay_agency.crypto.payin_link({\n \"fiat_amount\": 150,\n \"fiat_currency\": \"USD\",\n \"crypto_currency\": \"BTC\",\n \"payment_template_id\": \"PLI07435325281394735\",\n \"order_id\": \"ORDER_123\", # optional\n \"terminal_id\": \"T12345\", # optional\n \"expiry_date\": \"2024-12-31\", # optional\n})\n\n# Direct crypto payin\npayin = pay_agency.crypto.payin({\n \"first_name\": \"Fiona\",\n \"last_name\": \"Gallagher\",\n \"email\": \"hello@gmail.com\",\n \"address\": \"64 Hertingfordbury Rd\",\n \"phone_number\": \"0123456789\",\n \"ip_address\": \"127.0.0.1\",\n \"crypto_currency\": \"BTC\",\n \"amount\": 300,\n \"currency\": \"USD\",\n \"crypto_network\": \"BITCOIN\",\n \"country\": \"US\",\n \"redirect_url\": \"https://pay.agency\",\n \"webhook_url\": \"https://pay.agency/webhook\", # optional\n \"order_id\": \"ORDER_123\", # optional\n \"terminal_id\": \"T12345\", # optional\n})\n\n# Response format:\n{\n \"status\": \"SUCCESS\" | \"PENDING\" | \"FAILED\",\n \"message\": str,\n \"redirect_url\": str, # optional\n \"data\": {\n \"amount\": int,\n \"currency\": str,\n \"order_id\": str | None,\n \"transaction_id\": str,\n \"customer\": {\n \"first_name\": str,\n \"last_name\": str,\n \"email\": str,\n },\n \"crypto_currency\": str,\n }\n}\n```\n\n### Transactions\n\nQuery transaction history:\n\n#### Get Transactions\n\n```python\ntransactions = pay_agency.txn.get_transactions({\n \"transaction_start_date\": \"2023-01-01\", # optional\n \"transaction_end_date\": \"2023-12-31\", # optional\n \"next_cursor\": \"cursor_value\", # optional - for pagination\n \"prev_cursor\": \"cursor_value\", # optional - for pagination\n})\n\n# Response format:\n{\n \"message\": str,\n \"data\": [\n {\n \"first_name\": str,\n \"last_name\": str,\n \"converted_amount\": str,\n \"converted_currency\": str,\n \"transaction_id\": str,\n \"amount\": str,\n \"currency\": str,\n \"status\": str,\n \"card_type\": str | None,\n \"card_number\": str | None,\n \"transaction_type\": str,\n \"order_id\": str | None,\n \"country\": str,\n \"email\": str,\n \"created_at\": str,\n \"transaction_date\": str,\n \"chargeback_date\": str | None,\n \"refund_date\": str | None,\n \"suspicious_date\": str | None,\n \"merchant_connector\": {\n \"name\": str,\n },\n \"user\": {\n \"name\": str,\n \"user_kyc\": {\n \"name\": str,\n },\n },\n }\n ],\n \"meta\": {\n \"has_next_page\": bool,\n \"has_previous_page\": bool,\n \"next_cursor\": str, # optional\n \"prev_cursor\": str, # optional\n \"total_count\": int,\n }\n}\n```\n\n#### Get Wallet Transactions\n\n```python\nwallet_transactions = pay_agency.txn.get_wallet_transactions({\n \"transaction_start_date\": \"2023-01-01\", # optional\n \"transaction_end_date\": \"2023-12-31\", # optional\n \"next_cursor\": \"cursor_value\", # optional - for pagination\n \"prev_cursor\": \"cursor_value\", # optional - for pagination\n})\n\n# Returns the same response format as get_transactions\n```\n\n### Refunds\n\nProcess refunds:\n\n```python\n# Direct refund method\nrefund = pay_agency.refund({\n \"reason\": \"Customer request\",\n \"transaction_id\": \"TXN_123\",\n})\n\n# Response format:\n{\n \"status\": \"SUCCESS\",\n \"message\": str,\n \"data\": {\n \"amount\": int,\n \"currency\": str,\n \"order_id\": str | None,\n \"transaction_id\": str,\n \"customer\": {\n \"first_name\": str,\n \"last_name\": str,\n \"email\": str,\n },\n \"refund\": {\n \"status\": bool,\n \"refund_date\": str | None,\n },\n \"chargeback\": {\n \"status\": bool,\n \"chargeback_date\": str | None,\n },\n }\n}\n```\n\n## Error Handling\n\nThe SDK uses requests for HTTP requests and will raise exceptions for failed requests:\n\n```python\nfrom payagency_api import PayAgencyApi, PayAgencyError\n\ntry:\n payment = pay_agency.payment.s2s(payment_data)\n print(\"Payment successful:\", payment)\nexcept PayAgencyError as e:\n # PayAgency API error\n print(f\"Payment failed: {e}\")\n print(f\"Status code: {e.status_code}\")\n print(f\"Response: {e.response}\")\nexcept requests.RequestException as e:\n # Network error\n print(f\"Network error: {e}\")\nexcept Exception as e:\n # Other error\n print(f\"Error: {e}\")\n```\n\n## Security\n\n### Encryption\n\nThe SDK automatically encrypts request payloads using AES-256-CBC encryption with your provided encryption key. Some endpoints (like payment links and refunds) skip encryption as indicated by the `skip_encryption` parameter.\n\n### API Key Security\n\n- Never expose your API keys in client-side code\n- Use test keys (`PA_TEST_`) for development\n- Use live keys (`PA_LIVE_`) only in production\n- Rotate your keys regularly\n\n### Best Practices\n\n1. Store API keys in environment variables\n2. Use HTTPS for all webhook URLs\n3. Validate webhook signatures on your server\n4. Implement proper error handling\n5. Log transactions for auditing\n\n## Environment\n\nThe SDK supports both test and live environments:\n\n### Test Environment\n\n- Use secret keys starting with `PA_TEST_`\n- Returns mock data for certain endpoints (wallets, fee estimation)\n- Safe for development and testing\n\n### Live Environment\n\n- Use secret keys starting with `PA_LIVE_`\n- Processes real transactions\n- Use only in production\n\n## Type Hints Support\n\nThe SDK is written with comprehensive type hints for better IDE support and type checking:\n\n```python\nfrom payagency_api import PayAgencyApi\nfrom payagency_api.types import (\n PaymentResponse,\n PayoutResponse,\n CryptoPaymentResponse,\n RefundResponse,\n)\n\n# Type hints are included for all methods and responses\ndef process_payment(pay_agency: PayAgencyApi) -> PaymentResponse:\n return pay_agency.payment.s2s({\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n # ... other fields\n })\n```\n\n### Important Notes\n\n- **Payment amounts**: Use actual currency amounts as integers (e.g., 1 for $1.00 or \u00a31.00)\n- **Crypto amounts**: For crypto, use string format for precise decimal values (e.g., \"0.01\" for Bitcoin)\n- **Country codes**: Use ISO 3166-1 alpha-2 country codes (e.g., \"GB\", \"US\")\n- **Currency codes**: Use ISO 4217 currency codes (e.g., \"USD\", \"GBP\", \"EUR\")\n- **Crypto networks**: Use uppercase format (e.g., \"BITCOIN\", \"ETHEREUM\")\n- **Card expiry years**: Use full 4-digit format (e.g., \"2027\", not \"27\")\n- **Optional fields**: Fields marked as optional can be omitted from the payload\n\n## License\n\nMIT License - see the LICENSE file for details.\n\n## Support\n\nFor support and documentation, please visit [PayAgency Documentation](https://docs.pay.agency) or contact support@pay.agency\n\n---\n\n**Version**: 1.0.0\n\n**Author**: PaneruVipin\n\n**Repository**: [payagency-python](https://github.com/vp-payomatix/payagency-python-sdk)\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive Python SDK for PayAgency payment processing platform",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/vp-payomatix/payagency-python/issues",
"Documentation": "https://docs.pay.agency",
"Homepage": "https://github.com/vp-payomatix/payagency-python",
"Repository": "https://github.com/vp-payomatix/payagency-python.git"
},
"split_keywords": [
"payagency",
" payment",
" api",
" sdk",
" cryptocurrency",
" payout",
" card"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2a80428a1e382b833bd186846c7d4e41ed7fa98412086881267ba4fa3478b22c",
"md5": "59dd14f54d5e4635deae24407e1bb42a",
"sha256": "347efa8e32afb9294b65e05700ad20882f6a966fcdb66a75217c353c2de97ad5"
},
"downloads": -1,
"filename": "payagency_api-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "59dd14f54d5e4635deae24407e1bb42a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 20312,
"upload_time": "2025-10-29T07:37:54",
"upload_time_iso_8601": "2025-10-29T07:37:54.586507Z",
"url": "https://files.pythonhosted.org/packages/2a/80/428a1e382b833bd186846c7d4e41ed7fa98412086881267ba4fa3478b22c/payagency_api-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "56046d98c084a242b3414bc4d12b01326462fe290169691f6e45f4c97f2f107b",
"md5": "7fa0f60d0f8b621684d8f093a16f9b9e",
"sha256": "b89b53e3816a2b47b83b438568d368da7170b547de9c63f2a9618719bd21138b"
},
"downloads": -1,
"filename": "payagency_api-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "7fa0f60d0f8b621684d8f093a16f9b9e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 24719,
"upload_time": "2025-10-29T07:37:56",
"upload_time_iso_8601": "2025-10-29T07:37:56.471672Z",
"url": "https://files.pythonhosted.org/packages/56/04/6d98c084a242b3414bc4d12b01326462fe290169691f6e45f4c97f2f107b/payagency_api-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-29 07:37:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vp-payomatix",
"github_project": "payagency-python",
"github_not_found": true,
"lcname": "payagency-api"
}
JSON
