nell-scb-lib 1.1.2

Nellika SCB Payment Integration - Hardened C Module (Commercial License Required)

nell-scb-lib

Python C extension for SCB (Siam Commercial Bank) payment integration with PromptPay QR code generation.

⚠️ IMPORTANT LICENSING INFORMATION

This software is subject to commercial licensing terms and usage fees.

• This library requires a valid commercial license for production use
• Usage telemetry data is collected and transmitted to Nellika Consulting Services Ltd.
• By installing and using this library, you agree to the collection and transmission of usage telemetry
• For licensing inquiries and pricing information, please contact: [e-mail]

Copyright © 2024 Nellika Consulting Services Ltd. All rights reserved.

---

Overview

nell-scb-lib is a high-performance C extension module providing SCB payment integration for Python applications. It handles OAuth token management, QR code generation, and payment status checking through SCB's official API.

Installation

pip install nell-scb-lib

Supported Platforms:

• Linux x86_64 (manylinux_2_31+)
• macOS ARM64 (Apple Silicon M1/M2/M3/M4)
• Python 3.9 through 3.14

Telemetry & Privacy

This library collects the following telemetry data:

• License key usage and validation events
• API operation counts (QR creation, token refresh, payment checks)
• Error rates and types
• Library version and platform information
• No sensitive data (API keys, secrets, transaction details, or customer information) is collected

Telemetry helps us:

• Monitor license compliance
• Improve library stability and performance
• Provide better support to our customers

By using this library, you consent to this data collection.

For questions about data collection or to request data deletion, contact: [e-mail]

---

Quick Start

import nell_scb_lib

# Create QR payment (database-driven, recommended)
result = nell_scb_lib.create_qr_by_bank_account(
    bank_account_id=1,
    amount=250.75,
    ref1="P00001",      # Invoice number (max 20 chars)
    ref2="CUST001",     # Customer code (max 12 chars)
    ref3="SCB"          # Optional reference
)

if result['status']['code'] == 1000:
    qr_image = result['data']['qrImage']  # Base64 PNG
    qr_raw = result['data']['qrRawData']  # PromptPay string
    print(f"QR created: {result['data']['transactionId']}")

Environment Variables

Required for database-driven methods:

export PGDATABASE=your_database
export PGHOST=localhost
export PGPORT=5432
export PGUSER=odoo
export PGPASSWORD=your_password  # optional

API Reference

High-Level API (Recommended)

create_qr_by_bank_account(bank_account_id, amount, ref1, ref2, ref3="SCB")

Create SCB QR payment code using bank account ID. Automatically fetches configuration from database and manages token refresh.

Parameters:

• bank_account_id (str/int): Bank account ID from res.partner.bank
• amount (float): Payment amount in THB
• ref1 (str): Reference 1, max 20 characters
• ref2 (str): Reference 2, max 12 characters
• ref3 (str, optional): Reference 3, defaults to "SCB"

Returns: dict - SCB API response

{
    "status": {"code": 1000, "description": "Success"},
    "data": {
        "qrRawData": "00020101021230...",
        "qrImage": "iVBORw0KGgoAAAANSUhEUgAA...",
        "transactionId": "..."
    }
}

Example:

result = nell_scb_lib.create_qr_by_bank_account(
    bank_account_id=1,
    amount=250.75,
    ref1="P00001",
    ref2="CUST001"
)

---

Mid-Level API

create_qr_full(api_key, access_token, qr_create_url, biller_id, amount, ref1, ref2, ref3="SCB")

Create SCB QR code with explicit parameters (requires manual token management).

Parameters:

• api_key (str): SCB API key
• access_token (str): Valid OAuth token
• qr_create_url (str): SCB QR endpoint URL
• biller_id (str): PromptPay biller ID
• amount (float): Payment amount in THB
• ref1 (str): Reference 1, max 20 characters
• ref2 (str): Reference 2, max 12 characters
• ref3 (str, optional): Reference 3, defaults to "SCB"

Returns: dict - SCB API response

Example:

# Step 1: Get access token
token_resp = nell_scb_lib.refresh_token(api_key, api_secret, token_url)
access_token = token_resp['data']['accessToken']

# Step 2: Create QR
result = nell_scb_lib.create_qr_full(
    api_key="your_api_key",
    access_token=access_token,
    qr_create_url="https://api.scb/...",
    biller_id="894547854396914",
    amount=100.50,
    ref1="P00001",
    ref2="TEST"
)

---

refresh_token(api_key, api_secret, token_url)

Refresh SCB OAuth access token.

Parameters:

• api_key (str): SCB API key
• api_secret (str): SCB API secret
• token_url (str): Token endpoint URL

Returns: dict - Token response

{
    "status": {"code": 1000, "description": "Success"},
    "data": {
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expiresIn": 1800,
        "tokenType": "Bearer"
    }
}

---

Low-Level API

create_qr(config_id, amount, reference, channel="ecomm")

Create QR code using config ID from database (legacy method).

Parameters:

• config_id (str): SCB API configuration ID
• amount (float): Payment amount
• reference (str): Payment reference
• channel (str, optional): Payment channel, defaults to "ecomm"

Returns: dict - SCB API response

---

check_payment(reference)

Check SCB payment status by reference.

Parameters:

• reference (str): Payment reference to check

Returns: dict - Payment status

{
    "status": {"code": 1000, "description": "Success"},
    "data": {
        "paymentStatus": "SUCCESS",
        "transactionId": "...",
        "amount": 100.50
    }
}

---

version()

Get module version string.

Returns: str - Version (e.g., "1.1.0")

---

Database Schema Requirements

For database-driven methods, these tables are required:

res_partner_bank:

• Column: scb_biller_id (VARCHAR) - PromptPay biller ID

scb_api_config:

• Columns: api_key, api_secret, environment, token_url, qr_create_url, payment_inquiry_url
• Must have active configuration record

Error Handling

All functions raise RuntimeError for failures:

try:
    result = nell_scb_lib.create_qr_by_bank_account(
        bank_account_id=1,
        amount=250.75,
        ref1="P00001",
        ref2="CUST001"
    )
    
    if result['status']['code'] == 1000:
        # Success
        qr_data = result['data']
    else:
        # API error
        print(f"Error: {result['status']['description']}")
        
except RuntimeError as e:
    # System error
    print(f"Failed: {e}")

Response Status Codes

• 1000: Success
• 1001: Invalid request
• 1002: Authentication failed
• 1003: Insufficient balance
• 1004: Transaction not found
• 1005: System error

Always check the status code:

if result['status']['code'] == 1000:
    # Process successful response
    pass
else:
    # Handle error
    error_msg = result['status']['description']

Best Practices

1. Use High-Level API: Prefer create_qr_by_bank_account() for automatic configuration management
2. Validate References: Keep ref1 ≤ 20 chars, ref2 ≤ 12 chars
3. Check Status Codes: Always verify status.code == 1000 before using data
4. Handle Errors: Wrap API calls in try-except blocks
5. Environment Setup: Configure PostgreSQL environment variables before use

Features

• ✅ Native C implementation for high performance
• ✅ Automatic OAuth token management
• ✅ Database-driven configuration
• ✅ PromptPay QR code generation
• ✅ Payment status checking
• ✅ Thread-safe operations
• ✅ Secure API communication (libcurl)
• ✅ Built-in license management
• ✅ Usage telemetry for compliance and support

Support & Contact

• Sales & Licensing: [e-mail]
• Technical Support: [e-mail]
• Privacy Inquiries: [e-mail]
• Website: https://nellika.co.th

Legal

Copyright © 2024 Nellika Consulting Services Ltd. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, distribution, or use of this software, via any medium, is strictly prohibited without prior written permission from Nellika Consulting Services Ltd.

For licensing terms and conditions, please contact [e-mail]