Client
The Client
class is the main entry point for interacting with the TossPayments API.
Class Definition
class Client:
def __init__(
self,
secret_key: str,
api_version: str = "v1",
timeout: int = 30,
max_retries: int = 3,
)
Constructor Parameters
Parameter | Type | Default | Description |
---|---|---|---|
secret_key |
str |
Required | TossPayments secret key (test_sk_* or live_sk_* ) |
api_version |
str |
"v1" |
TossPayments API version |
timeout |
int |
30 |
HTTP request timeout in seconds |
max_retries |
int |
3 |
Maximum number of retry attempts for failed requests |
Properties
is_live_mode
Returns True
if the client is configured for live (production) mode.
Returns: bool
Example:
is_test_mode
Returns True
if the client is configured for test mode.
Returns: bool
Example:
Resource Access
payments
Access to payment-related operations.
Returns: PaymentResource
Example:
webhooks
Access to webhook-related operations.
Returns: WebhookResource
Example:
client = Client(secret_key="test_sk_...")
webhook_event = client.webhooks.verify_and_parse(request_body)
Usage Examples
Basic Initialization
from tosspayments_server_sdk import Client
# Test environment
client = Client(secret_key="test_sk_your_key_here")
# Live environment
client = Client(secret_key="live_sk_your_key_here")
Advanced Configuration
from tosspayments_server_sdk import Client
client = Client(
secret_key="test_sk_your_key_here",
api_version="v1",
timeout=60, # 60 second timeout
max_retries=5 # 5 retry attempts
)
Environment Detection
client = Client(secret_key="test_sk_your_key_here")
if client.is_test_mode:
print("Running in test mode")
# Use test payment methods
elif client.is_live_mode:
print("Running in live mode")
# Process real payments
Using Environment Variables
import os
from tosspayments_server_sdk import Client
client = Client(secret_key=os.getenv("TOSS_SECRET_KEY"))
# Verify configuration
print(f"Environment: {'Test' if client.is_test_mode else 'Live'}")
print(f"API URL: {client.config.api_url}")
Configuration Details
The client automatically configures internal components:
HTTP Client Settings
- Base URL:
https://api.tosspayments.com
- Authentication: Basic Auth with secret key
- Retry Policy: Exponential backoff for 5xx errors
- Timeout: Configurable (default: 30 seconds)
Retry Behavior
The client automatically retries requests for the following HTTP status codes:
- 500
- Internal Server Error
- 502
- Bad Gateway
- 503
- Service Unavailable
- 504
- Gateway Timeout
Retry delay follows exponential backoff with a factor of 0.5 seconds.
Error Handling
The client may raise the following exceptions during initialization:
from tosspayments_server_sdk import Client, ValidationError
try:
client = Client(secret_key="invalid_key_format")
except ValidationError as e:
print(f"Configuration error: {e}")
Common Validation Errors
- Invalid secret key format: Key must start with
test_sk_
orlive_sk_
- Invalid timeout: Must be a positive integer
- Invalid max_retries: Must be a non-negative integer
Related Documentation
- PaymentResource - Payment operations
- WebhookResource - Webhook handling
- Models - Data structures
- Getting Started - Quickstart guide