Python SDK

GitHub Repository: sunbay-nexus-sdk-python

Official SUNBAY Nexus Python SDK, providing clean and professional payment integration capabilities for Python applications.

Features

✅ Clean Pythonic API
✅ Complete type hints
✅ Automatic authentication
✅ Automatic retry for GET requests
✅ Comprehensive exception handling
✅ Connection pool management
✅ Thread-safe
✅ Support for standard logging library

Installation


pip install sunbay-nexus-sdk

Supported Python Versions

Python 3.7+
Python 3.8+
Python 3.9+
Python 3.10+
Python 3.11+
Python 3.12+

Quick Start

1. Initialize Client

NexusClient is thread-safe and can be reused across multiple threads. Create once, reuse throughout the application.


from sunbay_nexus_sdk import NexusClient
 
client = NexusClient(api_key="sk_test_xxx")

2. Create Payment Transaction

Important: All amount fields use the smallest currency unit (e.g., cents for USD, fen for CNY).

For example: 100.00 USD should be passed as 10000 (cents)


from sunbay_nexus_sdk import NexusClient, SUNBAYBusinessError, SUNBAYNetworkError
from sunbay_nexus_sdk.models.common import SaleAmount
from sunbay_nexus_sdk.models.request import SaleRequest
 
client = NexusClient(api_key="sk_test_xxx")
 
# 100.00 USD = 10000 cents
amount = SaleAmount(order_amount=10000, price_currency="USD")
 
request = SaleRequest(
    app_id="app_123456",
    merchant_id="mch_789012",
    reference_order_id="ORDER20231119001",
    transaction_request_id="PAY_REQ_1234567890",
    amount=amount,
    description="Product purchase",
    terminal_sn="T1234567890",
)
 
try:
    # If code reaches here, code == "0" (success), no need to check is_success()
    response = client.sale(request)
    print("Transaction ID:", response.transaction_id)
except SUNBAYNetworkError as e:
    print("Network Error:", e)
except SUNBAYBusinessError as e:
    print("API Error:", e.code, "-", e)

3. Query Transaction


from sunbay_nexus_sdk import NexusClient
from sunbay_nexus_sdk.models.request import QueryRequest
 
client = NexusClient(api_key="sk_test_xxx")
 
request = QueryRequest(
    app_id="app_123456",
    merchant_id="mch_789012",
    transaction_id="TXN20231119001",
)
 
try:
    # If code reaches here, code == "0" (success), no need to check is_success()
    response = client.query(request)
    print("Status:", response.transaction_status)
except SUNBAYBusinessError as e:
    print("API Error:", e.code, "-", e)
except SUNBAYNetworkError as e:
    print("Network Error:", e)

API Overview

The SDK’s NexusClient includes complete payment APIs:

Transaction APIs

sale(request) - Payment transaction
auth(request) - Pre-authorization
forced_auth(request) - Forced authorization
incremental_auth(request) - Incremental authorization
post_auth(request) - Post-authorization completion
refund(request) - Refund
void(request) - Void transaction
abort(request) - Abort transaction
tip_adjust(request) - Tip adjustment

Query APIs

query(request) - Query transaction

Settlement APIs

batch_close(request) - Batch settlement

Exception Handling

The SDK distinguishes between network-level and business-level errors:

SUNBAYNetworkError: Network-related errors (connection timeout, network errors, etc.)
SUNBAYBusinessError: Business logic errors (parameter validation, API business errors, etc.)

If you need to distinguish between them, always catch SUNBAYNetworkError first, then SUNBAYBusinessError.


from sunbay_nexus_sdk import SUNBAYBusinessError, SUNBAYNetworkError
 
try:
    response = client.sale(request)
    # Handle successful response
    print("Transaction ID:", response.transaction_id)
except SUNBAYNetworkError as e:
    # Network error (e.g., connection timeout, network failure)
    print("Network Error:", e)
    if e.is_retryable:
        print("This error is retryable")
except SUNBAYBusinessError as e:
    # Business error (e.g., insufficient funds, parameter error)
    print("API Error:", e.code, "-", e.message)
    if e.trace_id:
        print("Trace ID:", e.trace_id)

Configuration Options

You can configure the client using constructor parameters:


from sunbay_nexus_sdk import NexusClient
 
client = NexusClient(
    api_key="sk_test_xxx",
    base_url="https://open.sunbay.us",  # Default: https://open.sunbay.us
    timeout=30,                          # Default: 30 seconds
    max_retries=3,                       # Default: 3 times
    pool_connections=10,                 # Default: 10
    pool_maxsize=10,                     # Default: 10
)

Connection Pool Configuration

pool_connections: Number of connection pools to cache (default: 10)
pool_maxsize: Maximum connections to save in the pool (default: 10)

These settings help optimize performance in high-concurrency scenarios.

Logging

The SDK uses the standard Python logging library:


import logging
 
# Configure log level
logging.basicConfig(level=logging.DEBUG)
 
# Or configure logging only for the SDK
logger = logging.getLogger('sunbay_nexus_sdk')
logger.setLevel(logging.DEBUG)

Using Enums

For certain fields (e.g., transaction status and card network type), the SDK provides enums to make code more self-documenting:


from sunbay_nexus_sdk.models.enums import TransactionStatus, CardNetworkType
 
response = client.query(request)
 
# Use enum comparison
if response.transaction_status == TransactionStatus.SUCCESS:
    print("Transaction successful")
 
# Get enum value
print(response.transaction_status.value)  # 'S'
 
# Check card type
if response.card_network_type == CardNetworkType.CREDIT:
    print("Credit card transaction")

Available enums:

TransactionStatus - Transaction status (INITIAL, PROCESSING, SUCCESS, FAIL, CLOSED)
TransactionType - Transaction type (SALE, AUTH, REFUND, VOID, etc.)
CardNetworkType - Card network type (CREDIT, DEBIT, EBT, etc.)
EntryMode - Card entry mode (MANUAL, SWIPE, CONTACT, CONTACTLESS, etc.)
AuthenticationMethod - Authentication method (PIN, SIGNATURE, etc.)

Web Framework Integration

In web frameworks (e.g., FastAPI or Django), it’s recommended to create a single NexusClient instance at startup and reuse it:

FastAPI Example


from fastapi import FastAPI
from sunbay_nexus_sdk import NexusClient
 
app = FastAPI()
 
# Create client at startup
@app.on_event("startup")
async def startup_event():
    app.state.nexus_client = NexusClient(api_key="sk_test_xxx")
 
# Use client in routes
@app.post("/payment")
async def create_payment(request: PaymentRequest):
    client = app.state.nexus_client
    response = client.sale(request)
    return {"transaction_id": response.transaction_id}

Django Example


# settings.py
from sunbay_nexus_sdk import NexusClient
 
NEXUS_CLIENT = NexusClient(api_key="sk_test_xxx")
 
# views.py
from django.conf import settings
 
def create_payment(request):
    client = settings.NEXUS_CLIENT
    response = client.sale(payment_request)
    return JsonResponse({"transaction_id": response.transaction_id})

Complete Example


from sunbay_nexus_sdk import NexusClient, SUNBAYBusinessError, SUNBAYNetworkError
from sunbay_nexus_sdk.models.common import SaleAmount
from sunbay_nexus_sdk.models.request import SaleRequest
import logging
 
# Configure logging
logging.basicConfig(level=logging.INFO)
 
# Initialize client
client = NexusClient(
    api_key="sk_test_xxx",
    base_url="https://open.sunbay.us",
    timeout=30,
)
 
# Create payment request
amount = SaleAmount(
    order_amount=10000,  # 100.00 USD = 10000 cents
    price_currency="USD"
)
 
request = SaleRequest(
    app_id="app_123456",
    merchant_id="mch_789012",
    reference_order_id="ORDER20231119001",
    transaction_request_id="PAY_REQ_1234567890",
    amount=amount,
    description="Product purchase",
    terminal_sn="T1234567890",
)
 
# Execute transaction
try:
    response = client.sale(request)
    
    # Handle successful response
    print(f"Transaction successful!")
    print(f"Transaction ID: {response.transaction_id}")
    print(f"Reference Order ID: {response.reference_order_id}")
    print(f"Amount: ${response.amount.order_amount / 100:.2f}")
    
except SUNBAYNetworkError as e:
    # Network error
    print(f"Network error: {e}")
    if e.is_retryable:
        print("This error is retryable, you can retry the request")
        
except SUNBAYBusinessError as e:
    # Business error
    print(f"Business error: {e.code} - {e.message}")
    if e.trace_id:
        print(f"Trace ID: {e.trace_id}")
    
    # Handle based on error code
    if e.code == "INSUFFICIENT_FUNDS":
        print("Customer has insufficient funds")
    elif e.code == "INVALID_CARD":
        print("Invalid card information")

System Requirements

Python 3.7 or higher

License

MIT License