Thunder Python SDK
Verify Thai bank transfer slips and TrueMoney Wallet receipts from Python. Check the receiving account, amount and duplicate status before crediting an order.
Features
- Verify a bank slip from an image, QR payload, URL or base64.
- Check whether a transfer pays a linked receiving account for the expected amount.
- Detect previously used slips before accepting payment.
- Verify TrueMoney Wallet receipts.
- Read remaining quota and manage receiving accounts.
- Submit batches, track background jobs and authenticate webhooks.
- Generate PromptPay and bill payment QR codes.
Requirements
Python 3.11 through 3.15. Create a service in the Thunder developer portal, then copy its API key into your server environment as THUNDER_API_KEY. You can instead set THUNDER_API_KEY_FILE to a private file containing the key.
Installation
python -m pip install thunder-solution-sdk
Quick start
Save the program below as verify_payment.py. Put a transfer slip at slip.png and set the API key. In the portal, add your receiving account and link it to the service/branch associated with the key. Change 150.0 to the order amount from your own database, not a value sent by the customer. Each verification can consume quota.
from pathlib import Path
from thunder_slip import Client
from thunder_slip.errors import SlipNotFoundError, SlipPendingError
from thunder_slip.models import MatchedAccount, VerifyOptions
def main() -> None:
with Client() as client: # Reads THUNDER_API_KEY from the environment.
try:
result = client.verify.bank_by_image(
Path("slip.png"),
VerifyOptions(match_account=True, match_amount=150.0, check_duplicate=True),
)
except SlipPendingError:
print("The bank has not made this slip available yet. Check again later.")
return
except SlipNotFoundError:
print("No transfer was found. Ask the customer to check the slip.")
return
if result.is_duplicate is not False:
print("This slip was used before, or duplicate checking was unavailable.")
return
if result.is_amount_matched is not True:
print("The transfer does not match the order amount.")
return
if not isinstance(result.matched_account, MatchedAccount):
print("The transfer did not match a linked receiving account.")
return
slip = result.raw_slip
print("Amount:", result.amount_in_slip)
print("Date:", slip.date)
print("Sender:", slip.sender.account.name.th)
print("Receiver:", slip.receiver.account.name.th)
print("Transaction:", slip.trans_ref)
print("Payment checks passed. Record this transaction once for the order.")
if __name__ == "__main__":
main()
Run python verify_payment.py. A successful check prints output like this (illustrative values):
Amount: 150.0
Date: 2026-10-29T14:32:00+07:00
Sender: ผู้โอนตัวอย่าง
Receiver: ร้านตัวอย่าง
Transaction: EXAMPLE-TRANSFER-001
Payment checks passed. Record this transaction once for the order.
Credit the order only after all checks pass. Store the transaction reference with a database uniqueness constraint and update the order in the same transaction, so concurrent requests cannot credit it twice. The SDK does not update your orders.
Next steps: payment checks, receiving accounts, background jobs, error handling.
Usage
Verify a bank slip
| What you have | Method |
|---|---|
| Image file or uploaded bytes | client.verify.bank_by_image |
| QR payload text | client.verify.bank_by_payload |
| Public image URL | client.verify.bank_by_url |
| Base64 image | client.verify.bank_by_base64 |
Payload means the text decoded from the slip QR, not the transaction reference. Image input accepts a path, bytes or a binary file object. A string is a local file path: never pass an untrusted user string, because the SDK will read that file on your server.
from pathlib import Path
from thunder_slip import Client
with Client() as client:
result = client.verify.bank_by_payload(Path("payload.txt").read_text().strip())
print(result.amount_in_slip, result.raw_slip.trans_ref)
Payment checks
API v2 returns check results in a successful response: is_duplicate=True, is_amount_matched=False, or matched_account=None means you must reject the payment. A mismatch does not raise an API error. The quick start also rejects missing check results. matchAccount checks accounts linked to this service/branch; matchAmount compares the transfer against your order total; checkDuplicate asks whether this slip was used before.
from thunder_slip import Client
from thunder_slip.models import VerifyOptions
with Client() as client:
result = client.verify.bank_by_image(
"slip.png", VerifyOptions(match_account=True, match_amount=150.0, check_duplicate=True)
)
print(result.is_duplicate, result.is_amount_matched, result.matched_account)
TrueMoney Wallet
Use a Wallet receipt image. Check the same payment flags before crediting the order; the receipt reference is raw_slip.transaction_id.
from thunder_slip import Client
from thunder_slip.models import VerifyOptions
with Client() as client:
result = client.verify.truewallet_by_image(
"wallet-slip.png",
VerifyOptions(match_account=True, match_amount=150.0, check_duplicate=True),
)
print(result.amount_in_slip, result.raw_slip.transaction_id)
Account info and quota
Read quota before planning a batch. A null remaining quota means the API did not return a numeric limit; it is not zero.
from thunder_slip import Client
with Client() as client:
info = client.get_info()
print("Remaining quota:", info.application.quota.remaining)
Receiving accounts
This example lists linked accounts with automatic pagination, creates a receiving account, updates its name and links it to the key's branch. Set RECEIVING_ACCOUNT_NUMBER to your own account; run the create step once, then reuse the returned id. list() and list_all() return one page; iterate_all() walks all service accounts.
import os
from thunder_slip import Client
from thunder_slip.models import (
CreateBankAccountParams,
ListBankAccountsParams,
UpdateBankAccountParams,
)
with Client() as client:
for account in client.bank_accounts.iterate(ListBankAccountsParams(limit=50)):
print(account.id, account.name_th)
account = client.bank_accounts.create(
CreateBankAccountParams(
bank_code="004",
bank_number=os.environ["RECEIVING_ACCOUNT_NUMBER"],
name_th="ร้านตัวอย่าง",
name_en="Example Shop",
type="JURISTIC",
)
)
updated = client.bank_accounts.update(
account.id, UpdateBankAccountParams(name_en="Example Shop")
)
print("Updated:", updated.id)
print("Linked:", client.bank_accounts.link(account.id).linked)
Background jobs
Submit QR payloads as a batch and keep each job id. Polling the same job does not submit another verification. wait_for_job waits up to ten minutes by default, including HTTP requests and retry delays; inspect the terminal status and payment checks before accepting a result.
from pathlib import Path
from thunder_slip import Client
from thunder_slip.models import BatchSlip
with Client() as client:
payload = Path("payload.txt").read_text().strip()
batch = client.jobs.submit_bank_batch([BatchSlip(payload=payload, check_duplicate=True)])
for submitted in batch.jobs:
job = client.jobs.wait_for_job(submitted.job_id, timeout=600)
print(job.job_id, job.status, job.result)
Generate a payment QR
Set PROMPTPAY_PHONE to your PromptPay phone number. For bill payment, use type="PROMPTPAY" with biller_id and ref1; ref2 is optional. The older BILL_PAYMENT type still works for existing integrations. Amounts must be from 0.01 to 9,999,999,999.99 with at most two decimal places; omit the amount for an open-amount QR. Save the image returned by the API:
import os
from pathlib import Path
from thunder_slip import Client
from thunder_slip.models import QrRequest
with Client() as client:
qr = client.v1.generate_qr(
QrRequest(
type="PROMPTPAY",
msisdn=os.environ["PROMPTPAY_PHONE"],
amount=150.0,
)
)
Path("payment-qr.png").write_bytes(qr.image_bytes())
print("Saved payment-qr.png")
import os
from thunder_slip import Client
from thunder_slip.models import QrRequest
with Client() as client:
qr = client.v1.generate_qr(
QrRequest(
type="PROMPTPAY",
biller_id=os.environ["BILLER_ID"],
ref1=os.environ["BILL_REFERENCE"],
amount=150.0,
)
)
print(qr.image)
Legacy API v1
Use v2 for new integrations. Existing v1 code can use client.v1; it returns the slip directly, and duplicate detection raises DuplicateSlipError.
from thunder_slip import Client
from thunder_slip.models import V1VerifyOptions
with Client() as client:
slip = client.v1.verify_bank_by_image("slip.png", V1VerifyOptions(check_duplicate=True))
print(slip.amount.amount, slip.trans_ref)
Async requests
Use AsyncClient in an async application and await each operation. Reuse one client for multiple requests; limit concurrency to fit your quota and server resources.
import asyncio
from thunder_slip import AsyncClient
from thunder_slip.models import VerifyOptions
async def main() -> None:
async with AsyncClient() as client:
result = await client.verify.bank_by_image(
"slip.png", VerifyOptions(match_account=True, match_amount=150.0, check_duplicate=True)
)
print(result.amount_in_slip, result.is_duplicate, result.is_amount_matched)
asyncio.run(main())
The result object
The bank and Wallet result share amount and payment-check fields. Bank details are under raw_slip; Wallet uses a different receipt model. Optional fields appear only when the API supplies them: UNSET means absent, while None means JSON null.
| Field | Type | Meaning | Example |
|---|---|---|---|
amount_in_slip |
float | Verified transfer amount in baht | 150.0 |
is_duplicate |
optional bool | Whether the slip was used before | false |
is_amount_matched |
optional bool | Whether the transfer matches the order amount | true |
amount_in_order |
optional float | Order amount sent for comparison | 150.0 |
matched_account |
optional account or null | Linked receiving account that matched | account object |
raw_slip.trans_ref |
string | Bank transaction reference | EXAMPLE-TRANSFER-001 |
raw_slip.date |
string | Transfer date and time, including offset when returned | 2026-10-29T14:32:00+07:00 |
raw_slip.sender.account.name.th |
optional string | Sender name in Thai | ผู้โอนตัวอย่าง |
raw_slip.receiver.account.name.th |
optional string | Receiver name in Thai | ร้านตัวอย่าง |
raw_slip.sender.account.bank.account |
optional string | Sender account number as returned, possibly masked | xxx-x-x1234-x |
raw_slip.receiver.account.bank.account |
optional string | Receiver account number as returned, possibly masked | xxx-x-x5678-x |
raw_slip.transaction_id |
string (Wallet) | Wallet transaction reference | EXAMPLE-WALLET-001 |
raw_slip.sender.name |
string (Wallet) | Wallet sender name | ผู้ส่งตัวอย่าง |
raw_slip.receiver.name |
string (Wallet) | Wallet receiver name | ผู้รับตัวอย่าง |
raw_slip.receiver.phone |
string (Wallet) | Wallet receiver phone as returned | 0xx-xxx-1234 |
See the full Python model reference.
Configuration
| Option | Environment variable | Default | What it does |
|---|---|---|---|
api_key |
THUNDER_API_KEY; THUNDER_API_KEY_FILE | environment/file | Explicit key overrides environment; file is the fallback. |
timeout |
none | 30 seconds | Timeout for each HTTP attempt. |
max_retries |
none | 2 | At most two additional attempts when retry rules allow. |
v2_base_url / v1_base_url |
THUNDER_V2_BASE_URL; THUNDER_V1_BASE_URL | https://api.thunder.in.th/v2; https://api.thunder.in.th/v1 | Override the API endpoints. |
http |
none | new HTTP client | Supply a custom client; close it yourself. |
The example closes the custom HTTP client as well as the SDK client. With the default client, with Client() closes its connections automatically.
import httpx
from thunder_slip import Client
with httpx.Client(trust_env=False, follow_redirects=False) as http:
with Client(timeout=15, max_retries=1, http=http) as client:
print(client.get_info().application.name)
Error handling
ThunderError is the root exception; ApiError covers HTTP failures and RequestTimeoutError is a NetworkError.
A recognized API error code selects the error class first; otherwise the SDK uses the HTTP status. Unmapped 4xx responses use ApiError.
| Error class | HTTP status or stage | When it happens | What to do |
|---|---|---|---|
ThunderError |
varies | Base for all SDK failures. | Catch a specific error first. |
ApiError |
HTTP | Base for rejected API requests. | Use status, code and request id for diagnosis. |
AuthenticationError |
401 | API key is invalid. | Check the key for this service. |
PermissionDeniedError |
403 | Service, branch or IP cannot call the API. | Check service access and IP restrictions. |
QuotaExceededError |
403 | Verification quota is exhausted. | Add quota before accepting more slips. |
InvalidRequestError |
400 | The API rejects an argument. | Correct the request before sending again. |
InvalidImageError |
400 | Image is unreadable, oversized or unsupported. | Send a readable supported image. |
InvalidUrlError |
400 | Image or callback URL is refused. | Use a reachable public HTTPS URL. |
DuplicateSlipError |
400 (v1) | A previously verified slip is submitted with duplicate checking. | Do not credit the same transfer again; inspect slip. |
NotFoundError |
404 | Resource is missing or outside this branch. | Check the account or job id and branch. |
SlipNotFoundError |
404 | No transfer or slip QR was found. | Ask for a readable slip from a completed transfer. |
SlipPendingError |
404 | A recent slip is not available from the bank yet. | Wait before checking again. |
ConflictError |
409 | Receiving account already exists. | Reuse it instead of creating another. |
RateLimitError |
429 | Request rate is too high. | Wait for retry_after when present. |
ServerError |
500, 502, 504; other 5xx except 503 | The API or bank could not finish the request. | Reconcile billed calls before resending. |
ServiceUnavailableError |
503 | A dependency is unavailable. | Wait and check service status. |
InputError |
before sending | Local validation rejects input. | Fix the argument identified by code. |
NetworkError |
network | Connection fails. | Check connectivity and reconcile the outcome. |
RequestTimeoutError |
network | HTTP request exceeds its timeout. | Check the payment outcome before resubmitting. |
JobWaitTimeoutError |
polling deadline | Job polling exceeds the overall deadline. | Keep last_job and poll the same job later. |
BatchSubmitError |
partial batch | A chunk fails after earlier chunks were accepted. | Resume only the unsent chunks. |
WebhookSignatureError |
before processing | Webhook signature is invalid or missing. | Return 400; do not process the event. |
from thunder_slip import Client
from thunder_slip.errors import ApiError, NetworkError, QuotaExceededError, SlipNotFoundError
try:
with Client() as client:
result = client.verify.bank_by_image("slip.png")
print(result.amount_in_slip)
except SlipNotFoundError:
print("Ask the customer for a readable slip from a completed transfer.")
except QuotaExceededError:
print("Add verification quota before processing more payments.")
except ApiError as error:
print("Verification failed:", error.status, error.code, error.request_id)
except NetworkError:
print("The outcome is unknown. Reconcile the payment before resubmitting it.")
| Situation | Automatic retry (default) |
|---|---|
| Connection fails before sending | Up to 2 extra attempts, including verification. |
| HTTP 429 | Up to 2 extra attempts when the delay is at most 60 seconds. |
| Safe reads and idempotent account linking | Up to 2 extra attempts for transport failures and HTTP 500, 502, 503, 504. |
| Verification or job submission after sending | Never retry read timeouts or 5xx: another send could consume quota twice. |
| Other 4xx | No automatic retry; correct the input or permissions. |
Retries use exponential backoff with jitter and respect Retry-After up to 60 seconds. A failed network call does not prove that a billed operation was never processed.
Webhooks
Install Flask with python -m pip install Flask, save this as webhook_app.py, set THUNDER_WEBHOOK_SECRET, then run python webhook_app.py. The handler reads the original body and X-Thunder-Signature, returns 400 for an invalid signature or malformed event, and acknowledges a verified event with 204. Replace the logging step with durable storage or a queue before using it to confirm payments; process each job id once. Deploy behind HTTPS with a production WSGI server.
import os
from flask import Flask, Response, request
from thunder_slip.errors import InputError, WebhookSignatureError
from thunder_slip.webhooks import construct_event
app = Flask(__name__)
webhook_secret = os.environ["THUNDER_WEBHOOK_SECRET"]
@app.post("/webhooks/thunder")
def receive_webhook() -> Response:
raw_body = request.get_data(cache=False)
try:
event = construct_event(
raw_body, request.headers.get("X-Thunder-Signature"), webhook_secret
)
except (WebhookSignatureError, InputError):
return Response("Invalid webhook", status=400)
# Save or enqueue the event durably, using job_id to prevent duplicate processing.
app.logger.info("Verified job %s: %s", event.job_id, event.status)
return Response(status=204)
if __name__ == "__main__":
app.run(port=8000)
Security and privacy
Keep the API key on your server, never in a browser or mobile application. Public errors and response headers redact the configured key, including percent-encoded and JSON-escaped forms, and always hide authorization headers. Transport causes contain sanitized diagnostics. sensitive_raw_body() returns the original error body and can expose secrets; keep it out of logs. Transfer results include personal data such as names and account numbers. Limit access, retention and what you print in application logs.
Versioning and support policy
This SDK follows semantic versioning. Breaking public API changes require a major version. The runtime support policy follows versions still supported upstream; changes to the supported range are announced in the changelog.
Examples and documentation
Runnable examples include one program per operation. Read the Python SDK guide and API reference for all options.
Support
For account, quota or billing questions, use the contact page and include the request id if available. Report bugs and suggest features in issues. Never post API keys or real slip images.
Contributing
See CONTRIBUTING.md for setup, checks and pull requests. Maintainers follow RELEASING.md.
Security reports
Report vulnerabilities privately as described in SECURITY.md, or use the contact page. Never report vulnerabilities in public issues.
License
MIT. Copyright (c) 2026 Thunder Solution Co., Ltd.
Metadata
Release files for thunder-solution-sdk 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| thunder_solution_sdk-1.0.0.tar.gz | 48.4 kB | With provenance | Details for thunder_solution_sdk-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| thunder_solution_sdk-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for thunder_solution_sdk-1.0.0-py3-none-any.whl |
Total release size: 77.7 kB
Release files / thunder_solution_sdk-1.0.0.tar.gz
| Download URL | thunder_solution_sdk-1.0.0.tar.gz |
|---|---|
| Size | 48.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
29d1040155d0a015ac3c0640879034c2a3a50677d88b6e2cf627c85b3553a2aa
|
|
BLAKE2b-256 checksum How to use checksums |
105327e531ff7fb03394d5aca421b5eca70ed03351cb42fa18f8ccce223f7e3d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / thunder_solution_sdk-1.0.0-py3-none-any.whl
| Download URL | thunder_solution_sdk-1.0.0-py3-none-any.whl |
|---|---|
| Size | 29.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6c0cb30cb8ead8eabb5a66d8ff58f3bc11c9d8316c3f0856a3689a116fe1fe26
|
|
BLAKE2b-256 checksum How to use checksums |
1bc07093bb2230c31e6d00fa5b4cf436e418aa9a3d2bf92de8a244bfe03592b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for thunder-solution-sdk 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for thunder_solution_sdk-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.