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
✅ Dataclass-based request/response models
✅ Automatic authentication
✅ Automatic retry for GET requests
✅ Comprehensive exception handling
✅ Connection pool management (requests library)
✅ Thread-safe
✅ Standard logging library support
✅ Environment variable support for API key and base URL

Installation


pip install sunbay-nexus-sdk

Quick Start

1. Initialize Client

NexusClient is thread-safe and should be created once and reused globally. Do not create a new instance for every request — the client manages its own HTTP connection pool.


from sunbay_nexus_sdk import NexusClient
 
# API key can also be set via SUNBAY_API_KEY environment variable
client = NexusClient(
    api_key="sk_test_xxx",
    base_url="https://open.sunbay.us",    # or set via SUNBAY_BASE_URL env var
)

We recommend tuning connect_timeout, read_timeout, max_retries, and max_connections based on your concurrency level and business requirements. See Configuration Options for details.

2. Create Payment Transaction

Important: All amount fields use the smallest currency unit (e.g., cents for USD). For example: 100.00 USD = 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")
 
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:
    # SDK automatically raises SunbayBusinessError when code != "0"
    # If code reaches here, response is guaranteed successful
    response = client.sale(request)
    print("Transaction ID:", response.transaction_id)
except SunbayNetworkError as e:
    print("Network Error:", e)
    if e.retryable:
        print("This error is retryable")
except SunbayBusinessError as e:
    print("API Error:", e.code, "-", e)
    if e.trace_id:
        print("Trace ID:", e.trace_id)

API Methods

All request/response models are Python @dataclass classes.

In-Person Payment 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_transaction(request) - Void transaction
abort(request) - Abort transaction
tip_adjust(request) - Tip adjustment
batch_query(request) - Query open (unsettled) batches
batch_close(request) - Batch settlement
batch_close_list(request) - Query closed (settled) batches

Online Payment APIs

create_checkout_session(request) - Create hosted checkout session
expire_checkout_session(request) - Expire a checkout session
checkout_sale(request) - Direct payment (server-to-server)
online_refund(request) - Online refund

Transaction Query APIs

query(request) - Query transaction

Merchant APIs

merchant_query(request) - Retrieve merchant information
merchant_terminals_query(request) - List terminals bound to a merchant

Exception Handling

The SDK has three exception types:

SunbayError — Base class
SunbayBusinessError — Business logic errors (API returns non-zero code). Properties: code, message, trace_id
SunbayNetworkError — Network errors (timeout, connection failure). Properties: message, retryable


from sunbay_nexus_sdk import SunbayBusinessError, SunbayNetworkError
 
try:
    response = client.sale(request)
    print("Transaction ID:", response.transaction_id)
except SunbayNetworkError as e:
    print("Network Error:", e)
    if e.retryable:
        print("This error is retryable")
except SunbayBusinessError as e:
    print("API Error:", e.code, "-", e)
    if e.trace_id:
        print("Trace ID:", e.trace_id)

Configuration Options


from sunbay_nexus_sdk import NexusClient
 
client = NexusClient(
    api_key="sk_test_xxx",                          # Required (or set SUNBAY_API_KEY env var)
    base_url="https://open.sunbay.us",              # Default: https://open.sunbay.us
    connect_timeout=10.0,                            # Default: 10.0 seconds
    read_timeout=30.0,                               # Default: 30.0 seconds
    max_retries=3,                                   # Default: 3 (GET request retry)
    max_connections=200,                             # Default: 200 (connection pool size)
)

Enums

All enums inherit from (str, Enum), available from sunbay_nexus_sdk.enums or top-level sunbay_nexus_sdk:


from sunbay_nexus_sdk import TransactionStatus, CardNetworkType
 
response = client.query(request)
if response.transaction_status == TransactionStatus.SUCCESS:
    print("Transaction successful")
print(response.transaction_status.value)  # 'S'

Available enums:

TransactionStatus - INITIAL (I), PROCESSING (P), SUCCESS (S), FAIL (F), CLOSED (C)
TransactionType - SALE, AUTH, FORCED_AUTH, INCREMENTAL, POST_AUTH, REFUND, VOID
CardNetworkType - CREDIT, DEBIT, EBT, EGC, UNKNOWN
EntryMode - MANUAL, SWIPE, FALLBACK_SWIPE, CONTACT, CONTACTLESS
PaymentCategory - CARD, CARD_CREDIT, CARD_DEBIT, QR_MPM, QR_CPM
AuthenticationMethod - NOT_AUTHENTICATED, PIN, OFFLINE_PIN, BY_PASS, SIGNATURE
PrintReceipt - NONE, MERCHANT, CUSTOMER, BOTH
BatchClosePrintReceipt - TOTAL, DETAIL, BOTH, NONE, AUTO
DigitalWalletPaymentMethod - GOOGLE_PAY, APPLE_PAY
EbtSubId - SNAP, VOUCHER, BENEFIT
RelatedTransactionStatus - VOIDED, INCREMENTAL, REFUNDED, CAPTURE, PART_REFUNDED
TransactionBatchStatus - N, U, C
SignatureEntryLocation - ON_SCREEN, ON_RECEIPT, NONE

Logging

The SDK uses the standard Python logging library:


import logging
 
logging.basicConfig(level=logging.DEBUG)
 
# Or configure only SDK logging
logger = logging.getLogger("sunbay_nexus_sdk")
logger.setLevel(logging.DEBUG)

You can also pass a custom logger to the client:


import logging
 
logger = logging.getLogger("my_app.nexus")
client = NexusClient(api_key="sk_test_xxx", logger=logger)

Web Framework Integration

Create a single NexusClient at startup and reuse it:

FastAPI


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

Django


# 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
 
logging.basicConfig(level=logging.INFO)
 
client = NexusClient(
    api_key="sk_test_xxx",
    base_url="https://open.sunbay.us",
)
 
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:
    response = client.sale(request)
    print(f"Transaction successful!")
    print(f"Transaction ID: {response.transaction_id}")
    print(f"Reference Order ID: {response.reference_order_id}")
except SunbayNetworkError as e:
    print(f"Network error: {e}")
    if e.retryable:
        print("This error is retryable")
except SunbayBusinessError as e:
    print(f"Business error: {e.code} - {e}")
    if e.trace_id:
        print(f"Trace ID: {e.trace_id}")

System Requirements

Python 3.8 or higher
requests >= 2.28

License

MIT License