Lunixi Python SDK
Version 1.0.2 uses canonical minor-unit strings for money. This is a breaking change from 0.x; update request and response handling together. See migration.
Documentation · Changelog · Issues · Security
Version 1.0.2 adds typed payment APIs and durable checkout orchestration while preserving the existing fraud decision/event API. The SDK is synchronous, thread-safe per client, and ships py.typed.
Turkish · Framework examples · Django · FastAPI · Flask
| Component | Requirement |
|---|---|
| Core SDK | Python 3.9+; use a maintained Python runtime for deployment |
| Runtime dependencies | cryptography>=50.0.2,<51, rfc8785>=0.1.4,<0.2; stdlib HTTP/SQLite |
| Verified framework targets | Django 6.1.2 / FastAPI 0.162.0 / Flask 3.1.3 on Python 3.12.14 |
| Payment form | Official Lunixi browser bundle or hosted pay.lunixi.com |
| Durable example storage | SQLite on disk; Django's native ORM with IMMEDIATE transactions |
Install
pip install lunixi-sdk==1.0.2
Version 1.0.2 is published on PyPI. The 0.x packages use the previous money contract.
From a source checkout, pip install -e . installs the SDK; pip install -e '.[frameworks]' installs optional runtime dependencies. Framework apps and full native tests need Python 3.12+ and the source checkout. They are runnable examples, not separately registered framework packages.
Payment quick start
import os
from lunixi import LunixiClient, CreateIntent
client = LunixiClient(
base_url="https://api-gateway.lunixi.com",
key_id=os.environ["LUNIXI_KEY_ID"],
private_key=os.environ["LUNIXI_PRIVATE_KEY"],
max_retries=0,
)
intent = client.payments().create_intent(
CreateIntent("1990", "TRY", "persisted-order-123",
callback_url="https://shop.example/return/123",
enabled_installments=[1, 2, 3]), # optional: at most 3 installments
idempotency_key=persisted_attempt_key,
)
# Return only after authenticating ownership of the persisted order:
public_form_configuration = intent.browser_config()
# Or redirect to the validated backend paymentPageUrl:
hosted_url = intent.hosted_url
Money is canonical minor-unit strings, from 1 to 9,223,372,036,854,775,807; booleans, floats, zero and removed root amount fields fail before token exchange/network. minor_units('19.90','TRY') converts a plain decimal string exactly; JPY has0 decimals and KWD 3. Preauthorization is a JSON boolean; an authorization is on hold, not paid. Available methods, installments, eligible shopping credit/meal cards, insurance and multi-card options belong to the Lunixi form/panel. enabled_installments only narrows the installment counts the form offers for one payment ([1] = single payment only); the form shows only the counts your panel settings, the card and the platform maximum also allow, and None means no restriction. Counts are integers 1–36, distinct and include 1, otherwise ConfigurationError is raised before any request; the list is sent as enabledInstallments in ascending order. The examples never collect card numbers/CVV.
Gateway bodies that carry basketItems (sent through client.api().request(...); CreateIntent does not build basket items) accept the optional productCategory on each entry: the Lunixi product category code, used by payment methods with legal installment limits (e.g. shopping loan) and other platform features. Leaving it out keeps today's behaviour; the gateway rejects an unknown code with 400. The codes are available as ProductCategory constants (from lunixi import ProductCategory; ProductCategory.MOBILE_PHONE, all 40 in ProductCategory.ALL). The list only grows by appending, so the value stays a plain string and the SDK does not check it before sending.
| Helper | Merchant API |
|---|---|
payments().create_intent(CreateIntent(...), idempotency_key=...) |
POST /api/v1/payments/intents → canonical response paymentId and token |
get(payment_id), list(**filters) |
GET /api/v1/payments/{id}, /api/v1/payments |
capture(id, amount, idempotency_key=...) |
POST /api/v1/payments/{id}/capture |
refund(id, amount, idempotency_key=..., reason=...) |
POST /api/v1/payments/{id}/refund |
void(id, idempotency_key=...) |
POST /api/v1/payments/{id}/void |
list_payment_methods(payment_method=None), methods(payment_method=None) |
GET /api/v1/payments/methods[?paymentMethod=], signed |
direct_method_payment(DirectMethodPaymentRequest(...), idempotency_key=...) |
POST /api/v1/payments/direct/payment, signed |
confirm_payment_action(payment_id, action_id, otp=..., consent_accepted=..., fields=...), resend_payment_action(payment_id, action_id) |
POST /api/v1/payments/{id}/actions/{actionId}/confirm, /resend, signed |
get_promissory_notes(id), cancel_promissory_notes(id, serial_numbers=None), download_promissory_note_document(id, locale=None) |
/api/v1/payments/{id}/promissory-notes, /cancel, /document (PDF), signed |
list_bank_transfer_exceptions(environment=, status=, limit=), accept_bank_transfer_exception(id), mark_bank_transfer_exception_refunded(id) |
/api/v1/payments/bank-transfer/exceptions, /{id}/accept, /{id}/refunded, signed |
create_split_payment(SplitPaymentRequest(...), idempotency_key=...) |
POST /api/v1/payments/split, signed |
get_split(id), list_splits(**filters) |
GET /api/v1/payments/split/{id}, /api/v1/payments/split |
refund_split(id, amount, idempotency_key=...) |
POST /api/v1/payments/split/{id}/refund |
create_marketplace_intent(CreateIntent(...), sellers=[...], multi_seller_policy=None, idempotency_key=None) |
POST /api/v1/payments/marketplace/intents, signed |
bin_info(bin_or_pan), installment_options(InstallmentOptionsRequest(...)), card_taxonomy() |
POST /api/v1/bin/info, /api/v1/bin/installments, GET /api/v1/bin/card-taxonomy |
store_card(StoreCardRequest(...), idempotency_key=...), deactivate_stored_card(token, idempotency_key=...) |
POST /api/v1/payments/cards, DELETE /api/v1/payments/cards/{token}, signed |
list_stored_cards(card_user_key), get_stored_card(token) |
GET /api/v1/payments/cards[?cardUserKey=], /api/v1/payments/cards/{token} |
failover_recovery_analytics(**filters), provider_credential_analytics(credential_id, **filters) |
GET /api/v1/payments/analytics/failover-recovery, /provider-credentials/{id} |
client.reference().list_provinces(), list_districts(province_code), list_neighborhoods(district_code) |
GET /api/v1/reference/tr-address/* |
Non-intent helpers return the complete response envelope, preserving details, pageInfo and request IDs. Financial helper keys are required and must come from durable application records. An HTTP 2xx mutation response does not prove settlement.
Payment methods from your server
list_payment_methods() lists the methods open for your account with, per provider, the providerCode and the inputFields to send. Always read the provider code from this answer; never hard-code it. list_payment_methods("MOBILE_BILLING") narrows the list to one method (QR is sent as QR_CODE; a code that is not [A-Z][A-Z0-9_]{0,31} raises ConfigurationError).
from lunixi import DirectMethodPaymentRequest, PaymentActionType, PaymentMethod
request = (
DirectMethodPaymentRequest("15000", "TRY", "persisted-order-123")
.with_method_fields(PaymentMethod.MOBILE_BILLING, provider_code, {"gsmNumber": "+905321234567"})
.with_callback_url("https://shop.example/return/123")
)
response = client.payments().direct_method_payment(request, idempotency_key=persisted_attempt_key)
action = response["data"].get("action")
if action and action["type"] == PaymentActionType.OTP:
client.payments().confirm_payment_action(
response["data"]["paymentId"], action["id"], otp=code_from_buyer
)
The body carries exactly one method block, named after the method (MOBILE_BILLING → mobileBilling; METHOD_BLOCK_FIELDS lists them). Before anything is sent the SDK refuses: an unknown field, price/paidPrice, a block of another method, a missing block, card fields (CARD_ONLY_FIELDS) on a non-card method, a method without a block, a shopping-loan basket outside 1–100 items, and a block with a shape the gateway would refuse (at most 32 fields with names [A-Za-z][A-Za-z0-9]{0,63}; values are strings of at most 1024 characters, numbers, booleans, ADDRESS objects of at most 16 fields, or GROUP lists of at most 10 objects). A raw body mapping passed instead of the builder is checked with the same rules. The idempotency_key is required. with_card(card) with with_force3d(True) and with_installment(count, quote_token) is the card variant.
confirm_payment_action() sends only otp (digits, at most 16), consent_accepted (boolean) and fields; any other keyword raises ConfigurationError. resend_payment_action() closes the action and opens a new one.
Para Transferi (bank transfer)
BANK_TRANSFER takes no provider code: pass None and the buyer's bank as {"bankCode": ...}, or BANK_TRANSFER_OTHER_BANKS_CODE ("9999") for a bank that is not listed. The answer is a DISPLAY action with the transfer instruction for the buyer:
from lunixi import BankTransferInstruction
request = DirectMethodPaymentRequest("15000", "TRY", "persisted-order-123").with_method_fields(
PaymentMethod.BANK_TRANSFER, None, {"bankCode": buyer_bank_code}
)
response = client.payments().direct_method_payment(request, idempotency_key=persisted_attempt_key)
instruction = BankTransferInstruction.from_response(response) # None without a DISPLAY action
if instruction:
show(instruction.iban, instruction.holder_name, instruction.amount_minor, instruction.payment_code)
The money goes to your own bank account and is matched by the payment code. Late, short and excess transfers are listed with list_bank_transfer_exceptions(environment="LIVE", status="PENDING_DECISION", limit=50) (limit 1–200) and decided with accept_bank_transfer_exception(id) or mark_bank_transfer_exception_refunded(id) (the id is a UUID). Constants: PaymentBankTransferExceptionKind, PaymentBankTransferExceptionStatus and the webhook events PaymentBankTransferEvents (payment.bank_transfer.*).
Promissory notes
A PROMISSORY_NOTE payment carries a plan: with_promissory_note_schedule([{"amount": "10000", "dueDate": "2027-01-15"}, ...]) (1–24 rows, canonical minor-unit amounts adding up to amount, real YYYY-MM-DD dates in ascending order) or with_promissory_note_count(6) (1–24), never both. get_promissory_notes(payment_id) returns the notes, cancel_promissory_notes(payment_id, serial_numbers=None) cancels all open notes or the listed ones, and download_promissory_note_document(payment_id, locale="tr-TR") returns a BinaryResponse whose content holds the PDF bytes (PromissoryNoteDocumentLocale: tr-TR, en-GB). Status, result and event constants: PromissoryNoteStatus, PromissoryNoteCancelResult, PromissoryNoteCancelErrorCode, PromissoryNoteEvents. Codes for an ADDRESS field come from client.reference() (provinces, districts, neighborhoods).
Split payments
from lunixi import SplitPaymentRequest
request = (
SplitPaymentRequest("30000", "TRY", customer_ref)
.with_order_id("persisted-order-123")
.add_card_leg(stored_card_token, "20000")
.add_method_leg(PaymentMethod.WALLET, provider_code, "10000", {})
)
response = client.payments().create_split_payment(request, idempotency_key=persisted_split_key)
The idempotency key (at most 200 characters) is the identity of the split payment: after a step, send the same request with the same key and the payment continues. While it is running the gateway answers HTTP 400 with the status as code (SPLIT_PAYMENT_IN_PROGRESS_STATUSES) and data.splitPaymentId; that answer is returned, not raised. A non-card leg carries only a mobileBilling, wallet or promissoryNote block (SPLIT_LEG_BLOCK_FIELDS) with its provider code; meal card, open banking, shopping loan and bank transfer cannot be legs. list_splits() checks its filters (status, currency, createdFrom, createdTo, orderId, ownerRef, limit 1–100, after). Webhook constants: SplitPaymentEvents and the leg subscription key SPLIT_LEG_EVENTS_SUBSCRIPTION.
Cards, installments and marketplace intents
bin_info("54000000") answers the card, bank and installment eligibility of a BIN; installment_options(InstallmentOptionsRequest("10050", "TRY", bin_or_pan=bin, installment=3, enabled_installments=[1, 2, 3])) returns the installment table and, for a BIN with installment > 1, a binding quoteToken for DirectMethodPaymentRequest.with_installment(count, quote_token). enabled_installments follows the same rule as CreateIntent (integers 1–36, distinct, 1 included). A BIN or card number is digits only and is never placed in an error message. store_card(StoreCardRequest(card, card_user_key, callback_url), idempotency_key=...) and deactivate_stored_card(token, idempotency_key=...) are signed and need the key.
from lunixi import CreateIntent, MultiSellerPolicy
response = client.payments().create_marketplace_intent(
CreateIntent("10050", "TRY", "persisted-order-123"),
sellers=[
{"subDealerId": "d_alice", "amountMinor": "6000"},
{"subDealerId": "d_bob", "amountMinor": "4050"},
],
multi_seller_policy=MultiSellerPolicy.ALL_OR_NOTHING,
idempotency_key=persisted_attempt_key,
)
The sellers' amountMinor values (canonical minor-unit strings) must add up to amount; any other total raises ConfigurationError before sending.
Payment links
client.payment_links() creates and manages shareable payment pages. Every call is signed with your key, reads included; the key's environment decides whether you see TEST or LIVE links.
from lunixi import CreatePaymentLinkRequest, PaymentLinkDeliveryChannel, PaymentLinkUsage
links = client.payment_links()
created = links.create(
CreatePaymentLinkRequest.fixed(PaymentLinkUsage.SINGLE_USE, "150000", "TRY", "Invoice 2026-0042")
.with_recipient({"name": "Test Buyer", "email": "buyer@example.com"}),
idempotency_key=persisted_link_key,
)
links.send(created["id"], channel=PaymentLinkDeliveryChannel.EMAIL, idempotency_key=persisted_send_key)
page = links.list(state=["ACTIVE", "PAUSED"], limit=20)
create() and send() need an idempotency key of 8–200 printable ASCII characters; repeating it returns the stored result with replayed: True. update(link_id, expected_row_version, changes) changes only the given fields (None clears one) and refuses usage, amountMode and currency; pause(), resume() and deactivate() change the state. qr(link_id, format="png", size=512) returns the image as BinaryResponse. list(), list_attempts() and list_payments() return a Page; iterate…() follows the cursors. Unknown body fields and filters raise ConfigurationError.
A link image is uploaded in three steps, or with one call:
image = links.upload_image(file_name="cover.png", content_type="image/png", content=png_bytes)
request = CreatePaymentLinkRequest.fixed(
PaymentLinkUsage.MULTI_USE, "25000", "TRY", "Concert ticket"
).with_image_asset_id(image["assetId"])
upload_image() runs create_image_upload(), a PUT of the bytes to the presigned uploadUrl and confirm_image_upload(asset_id). The PUT goes through your configured transport directly to the storage host with only the returned uploadHeaders: it never carries your access token or the request signature. PNG, JPEG and WebP are accepted (SVG is not), up to 2 MiB and 4096×4096 px. A custom HttpTransport receives bytes as the body of that one request.
Wallet
client.wallet() covers the closed-loop wallet: end users, wallets and accounts, deposits, corporate accounts, fees, transfers, withdrawals, top-ups, merchant payments, QR codes and bulk payouts. Every call is signed. Fields may be passed as a mapping or as keyword arguments, in camelCase or snake_case.
wallet = client.wallet()
user = wallet.end_users.create(
program_id=program_id, account_type="PERSONAL", phone="+905550000000",
idempotency_key=persisted_user_key,
)
started = wallet.transfers.initiate_w2w(
end_user_id=user["endUserId"], source_wallet_account_id=account_id,
destination_wallet_no="W123456", amount="12550", currency="TRY",
idempotency_key=persisted_transfer_key,
)
wallet.transfers.complete_w2w(
started["operationId"], end_user_id=user["endUserId"],
integrity_hash=started["integrityHash"], nonce=started["nonce"], otp_code=otp,
idempotency_key=persisted_complete_key,
)
Every call is checked against one route table, WALLET_ROUTES: an unknown field or filter, a missing required field, an amount that is not a minor-unit digit string ("12550", never 125.5 or 12550), or a missing Idempotency-Key on a route that requires one raises ConfigurationError before anything is sent. The complete_* calls put operationId into the body themselves. Lists return a Page; iterate() follows the cursor. qr.image(qr_id, format="png", scale=4) returns the image as BinaryResponse. Bulk payouts are maker-checker: the approving key must differ from the creating key.
Bank accounts, transfers and currency exchange
client.bank_connect() reads your connected bank accounts (connections are set up in the dashboard). Every call is signed; the key's environment decides whether TEST or LIVE accounts are read.
from datetime import datetime, timezone
bank = client.bank_connect()
page = bank.list_transactions(
account_id=[account_id], booked_from=datetime(2026, 11, 1, tzinfo=timezone.utc),
direction="CREDIT", min_amount_minor="10000", limit=50,
)
for transaction in bank.iterate_transactions(account_id=account_id):
...
Filters are checked locally: known names only, value sets (BankConnectionStatus, BankTransactionDirection, BankTransactionType …), limit 1–100, at most 100 account ids, canonical minor-unit amount strings with min_amount_minor ≤ max_amount_minor, booked_to only together with booked_from, and a window of at most 92 days. request_sync(account_id) asks for a fresh read; new transactions arrive by the bank_account.transaction.received webhook.
Outgoing transfers and currency exchange need the bank-connect:transfer scope and a key with an IP allowlist:
transfer = bank.transfers.create(
account_id=account_id, receiver_iban="TR330006100519786457841326",
receiver_name="Test Receiver", amount_minor="150075",
idempotency_key=persisted_payout_id,
)
quote = bank.fx.create_quote(
source_account_id=try_account_id, target_account_id=usd_account_id,
target_amount_minor="10000",
)
order = bank.fx.create_order(quote_id=quote["id"], idempotency_key=persisted_fx_key)
create() and create_order() check your idempotency_key (8–200 printable ASCII) or generate a UUID v4 when you leave it out; a network error or a 5xx is retried with the same key and body. Keep your own key to retry safely across processes. Webhooks: BankConnectEvents and BankTransferEvents (bank_transfer.*, not the payment.bank_transfer.* events of a payment); read a verified event with BankAccountTransactionReceived.from_event(event) or BankTransferWebhookData.from_event(event).
Sanctions screening
client.sanction() screens names, wallets, accounts and transactions, runs entity intelligence and ongoing monitoring. These calls use the access token (no request signature).
from lunixi import is_clear_screening
result = client.sanction().screen_name(
name="Test Person", subject_type="person", mode="sanctions_pep",
customer_reference="customer-42",
)
if not is_clear_screening(result):
hold_for_review()
Screening returns matches, not verdicts. is_clear_screening() is true only when there is no match or hit, no blocking flag or decision, and — where coverage is reported — coverageStatus is COMPLETE; a PARTIAL or DEGRADED screening is never clear. A screening that could not run raises (HTTP 503, or a 2xx answer whose status is not success); it never comes back as an empty result. Bodies and filters are checked against SANCTION_ROUTES: unknown or missing fields, an empty "at least one of" group, nested row fields and values outside SANCTION_VALUE_SETS raise ConfigurationError.
Insurance
client.insurance() offers insurance for basket items, turns a quote into an order, follows its policies and documents, and submits leads for types sold by request only. Every call is signed.
from datetime import datetime, timezone
from lunixi import InsuranceClient
insurance = client.insurance()
quote = insurance.create_quote(
insurance_type="TICKET_CANCELLATION", currency="TRY", context={"items": basket_items},
)
option = quote["options"][0]
order = insurance.create_order(
quote_id=option["quoteId"],
consent=InsuranceClient.consent_from_quote(option, datetime.now(timezone.utc)),
idempotency_key=persisted_order_key,
)
premium_item = InsuranceClient.premium_basket_item(order, name="Insurance", category1="Insurance")
The basket of a quote is either a payment's recorded basket (payment_intent_id) or the items you will send in the payment (context), never both; send neither for a type sold without a basket item. create_order, confirm_payment, issue_policy, cancel_order, refund_premium and create_lead require an idempotency_key of 8–200 printable ASCII characters; create_quote and bind_payment take one optionally. The type objects (insured, tickets …) are sent as given: the gateway validates them and answers 422 insurance.validation.invalid with every field error at once. Policy documents, receipts and certificates come back as BinaryResponse (PDF); export_reconciliation(from_=..., to=...) returns the CSV with truncated, next_cursor and aborted. Read verified webhooks with InsuranceWebhookData.from_event(event) (order events) and InsuranceLeadWebhookData.from_event(event) (lead events).
Subscriptions
client.subscriptions() covers /api/v1/subscriptions/*: subscriptions plus the sub-clients plans, customers, cards, invoices, portal, products, features, addons and usage. Calls carry the access token (no request signature). Fields may be passed as a mapping or as keyword arguments, in camelCase or snake_case.
from lunixi import SubscriptionCollectionMethod, is_subscription_active
subscriptions = client.subscriptions()
customer = subscriptions.customers.upsert(external_id="user-42", email="ada@example.com")
plan = subscriptions.plans.create(
product_id="prod_1", code="pro-monthly", name="Pro", price="9900", currency="TRY",
billing={"frequency": "MONTHLY", "interval": 1}, trial_period_days=14,
)
# The card comes from the checkout SDK's token; a card number is never sent.
card = subscriptions.cards.add(
customer_id=customer["id"], payment_method_token="pm_tok_1", is_default=True,
)
subscription = subscriptions.create(
customer_id=customer["id"], plan_id=plan["id"], payment_card_id=card["id"],
collection_method=SubscriptionCollectionMethod.AUTO_CHARGE,
idempotency_key="sub-user-42-pro", # required: reuse it when retrying
)
if is_subscription_active(subscription): # TRIALING, ACTIVE or PAST_DUE
...
subscriptions.change_plan(
subscription["id"], new_plan_id="plan_team", behavior="NEXT_PERIOD",
idempotency_key="chg-42-team",
)
subscriptions.cancel(subscription["id"], at_period_end=True, reason="customer request")
create()requires anidempotency_key(or the request'sidempotencyKey; both given, they must agree), sent in the header and the body.plans.create,customers.upsert,cards.add,change_planandinvoices.retry_chargeaccept one.- Amounts (
price,priceSnapshotAmount,totalAmount,amountMinor…) are minor-unit strings, checked in bodies, filters and answers ("0"is a free plan). - Subscription, plan, customer, card and invoice lists return a
SubscriptionPage(next_page_token,page_size); pass the token back aspage_token, or useiterate(). Catalog, feature, add-on and portal-link lists return aPage. - Customer portal:
portal.create_sdk_session(customer_id, origin, sdk_mode=...)returnsportalToken,sessionProof,proofNonceandproofExpiresAtfor the browser portal SDK (originmust be allow-listed).portal.create_portal_link()returns a hosted link;subscription_portal_url(link)is the URL the customer opens. The link routes are under/api/panel/v1/subscriptions/portal, the only panel paths the client accepts. - Webhooks:
SubscriptionEvents(subscription.*,invoice.*,card.*), verified withWebhookVerifierlike payment events. - Every call is checked against
SUBSCRIPTION_ROUTESbefore sending: an unknown field or filter, a missing one or an unknown value raisesConfigurationError.
KYC and identity
client.kyc() creates and reads KYC, KYB and evidence sessions (/api/v1/kyc/*); client.identity() reads device and account-linking signals (/api/v1/identity/*). Both use the access token. The browser SDKs start with your publishable key; these clients are the server side.
from lunixi import KycAssuranceDomain, KycSessionType, is_identity_device_shared, kyc_assurance_meets
created = client.kyc().create_session(
subject_id="user-42", session_type=KycSessionType.KYC,
external_customer_id="user-42", # echoed on every kyc.* webhook
jurisdiction="TR", idempotency_key="kyc-user-42-1",
)
# Hand created["session"]["sessionId"] to the browser SDK; the kyc.* webhook carries the result.
result = client.kyc().get_session(created["session"]["sessionId"])
achieved = (result.get("session") or {}).get("decision", {}).get("assuranceSnapshot", {}).get("achieved", {})
if kyc_assurance_meets(achieved.get(KycAssuranceDomain.IDENTITY), "SUBSTANTIAL"):
... # identity gate passed
links = client.identity().account_links(trace_id_from_browser)
if is_identity_device_shared(links):
... # a second account on this device: review
kyc().list_sessions()takes onlylimitandcursor(page_size/page_tokenare read as the same); any other filter raises instead of silently returning every session.iterate_sessions()follows the cursor.person/companyare sent ascustomerwithcustomerType;metadatais sent asevidenceContextJson.ttl_minutesis 1 to 1440. A document image given toupload_document()never appears in an error message.- No personal data comes back: status, decision, risk level and the achieved assurance per domain (
KycAssuranceDomain).kyc_assurance_meets(achieved, required)compares on the ladderNONE/NOT_PERFORMED<LOW<SUBSTANTIAL<HIGH. KycEventslists thekyc.*,kyb.*,screening.*and monitoring events. A rescreen or a screening match on an approved session must revoke access.- Identity answers are signals (
riskFlags,reasonCodes, probabilities,identitySnapshot), not an allow / review / block verdict; that is the fraud decision.
Marketplace (sub-dealers)
client.marketplace() runs split charges across sub-dealers and manages the sub-dealers, commissions, payouts and the audit log. Split charges (/api/v1/payments/marketplace/*) are signed per request; the other routes (/api/v1/marketplace/*) use the access token.
from lunixi import CreateIntent, MarketplaceMultiSellerPolicy, marketplace_onboarding_url
marketplace = client.marketplace()
dealer = marketplace.create_dealer(
legal_name="Kurgu Ltd.", tax_id="1234567890", external_ref="vendor-7",
)
link = marketplace.onboarding_token(dealer["id"])
# Send the dealer to marketplace_onboarding_url(link): KYC, IBAN and contract, then ACTIVE.
intent = marketplace.create_checkout_intent(
CreateIntent("100000", "TRY", "ORD-7"),
[
{"subDealerId": "d_alice", "amountMinor": "60000"},
{"subDealerId": "d_bob", "amountMinor": "40000"},
],
MarketplaceMultiSellerPolicy.ALL_OR_NOTHING,
idempotency_key="mp-ORD-7",
)
- Seller legs are aggregate per sub-dealer (
{"subDealerId", "amountMinor", "scenario"?}, positive minor-unit strings) and must add up toamount; the client checks the total before sending.create_checkout_intent()raisesApiErrorwhen the answer carries no token or form (for example a seller that is not eligible underALL_OR_NOTHING). It uses the same route aspayments().create_marketplace_intent(). - Direct split card charges (
charge_marketplace_card2d/charge_marketplace_card3d) need the card, buyer, billing address and basket items; they are PCI DSS SAQ-D scope. Card data is sent as given and never logged or put in an error message. - Only
ACTIVEdealers receive a split (MarketplaceDealerStatus). Dealer lists, the payout ledger, transactions, commission rules and the audit log return aPage. resolve_commission(sub_dealer_id, category_code=..., mtd_volume_minor=...)andpreview_commission_rule(rule)read the effective commission; payout amounts (amountMinor) are minor-unit strings, checked in bodies, filters and answers.
Durable native checkout
lunixi.commerce.CheckoutService persists an immutable merchant/order/amount/currency snapshot and a stable attempt key before network I/O. It encrypts persisted browser tokens with a separate 32-byte server key. A native adapter supplies the transaction store and an idempotent native order callback using that same connection/transaction.
from lunixi.commerce import CheckoutService, SqliteLedgerStore, SecretBox, OrderSnapshot
ledger = SqliteLedgerStore("/secure/state/commerce.sqlite3")
ledger.install() # explicit schema setup, outside request handling
service = CheckoutService(client, ledger, SecretBox(server_encryption_key_bytes))
session = service.start(
"order-123", OrderSnapshot(merchant_id, "order-123", "1990", "TRY"),
"https://shop.example/return/order-123", hosted=False,
)
# `apply_native` validates current native totals/holds and writes using tx.connection.
decision = service.reconcile("order-123", apply_native)
The runnable framework integrations implement real order, stock, inbox and native outbox writes; a no-op callback is not a fulfillment implementation. Native fraud/manual holds remain effective after capture. Changed native totals/currency cannot be completed by an older intent. Buyer installment fees require the persisted fingerprint and stay separate from the basket; split success requires complete, balanced parent evidence with no compensation/reconciliation requirement. Partial capture is on hold.
Browser query parameters/form events never mark paid. service.webhook(raw_bytes, headers, secret, apply_native) verifies raw-body v2 HMAC/freshness/signed id/type, then queries authenticated payment/split evidence. Payment GET's data.id, create result paymentId and webhook data.intentId identify the same payment. Durable row locking and unique event hashes commit with native writes; a failed callback rolls back both. Signed event-ID content collisions fail. Lost create responses recover only from a verified payment webhook plus authenticated GET echoing the original opaque reservation hash/fingerprint; an existing payment ID is never rebound.
service.mutate(order_key, persisted_operation_id, 'capture'|'refund'|'void', amount_or_none, apply_native) reserves a durable operation and stable gateway key. operation_status(...) returns pending, uncertain or confirmed without exposing the key. New IDs are blocked while a prior operation is unresolved. Only authenticated balances/releases confirm success; refunds cannot exceed captured funds. Retry the exact original operation ID/amount after a timeout. Unconfirmed create/mutation retries older than 23 hours are blocked before POST, since gateway key retention is finite. GET reconciliation remains available. FAILED without outcome certainty stays review; this version provides no automatic ambiguous-attempt reset.
Authentication, transport and JSON
Generate Ed25519 keys with generate_key_pair() and register only the public key. The SDK accepts PKCS8 PEM/DER, base64/hex seeds and validated 64-byte seed/public exports. cryptography provides curve/AES-GCM primitives. Keep one client per origin/merchant key; token refresh coalesces concurrent threads. A custom TokenStore must be explicitly scoped to that origin/key. Cache lifetime respects expiration/skew; credentials do not appear in config representations.
HTTPS origins cannot contain credentials, path prefixes, query or fragment. API paths remain under /api/v1/ without traversal or normalization escapes. Redirects are not followed, including authentication redirects. Defaults:30 seconds/request,8MiB response cap,2 extra retries; timeout is bounded to 120 seconds and retries to5. Writes retry only with a nonempty stable key, including a401 refresh. Signing uses exact compact UTF-8 JSON, JavaScript numeric-key ordering and RFC8785 ECMAScript scalar formatting; unsafe integers/non-finite numbers fail locally. An explicit numeric-loopback HTTP opt-in exists for transport tests; Commerce always requires HTTPS.
Existing fraud API
from lunixi import Channel
result = client.fraud().evaluate(
channel=Channel.STANDALONE_API,
transaction_ref="persisted-order-123",
payment={"amount":"1990","currency":"TRY"},
)
if result.blocked:
refuse_order()
elif result.requires_review or result.requires_three_d:
hold_for_review_or_three_ds()
Fraud evaluate, decision-log list/get and event record/batch APIs retain their names/results. Decision/log calls remain bearer-authenticated; event ingest is signed per request. Batch ingestion supports up to 500 events and may partially succeed; inspect result.failures() and resend failed events with the same event IDs. Page preserves top-level cursor metadata; iterate using the returned cursor. No internal console route is a supported merchant API.
Other documented services and errors
response = client.api().request(
"GET", "/api/v1/payments/methods", step_up=True,
) # same as client.payments().list_payment_methods()
The generic authenticated layer can reach other documented merchant services with explicit step_up=True when required; client.api().request_binary("GET", path, step_up=True) returns a file answer as BinaryResponse. Browser form submission belongs to the official bundle.
Catch LunixiError or typed ApiError/ValidationError/AuthenticationError/RateLimitError/ServiceUnavailableError. Status, machine code, request ID and quota metadata remain available; raw remote error messages/bodies and transport exception text are withheld. Do not log raw successful responses either: they can carry browser tokens/customer data.
Low-level WebhookVerifier verifies signatures but does not claim replay IDs. Default signed id/type binding is strict. allow_legacy_header_fields=True preserves the old nonfinancial fallback explicitly and produces no financial replay proof; never use it for order fulfillment. tolerance_seconds=None is an explicit offline-fixture option, not a live setting. A secret list supports rotation; retain old endpoint secrets through the grace window.
Verify and build
pip install -r requirements-dev.lock
pip install --no-deps -e .
ruff check src integrations tests
ruff format --check src integrations tests
mypy src/lunixi
bandit -r src/lunixi integrations -q
pip-audit
pytest -q
python -m build
The lock targets the verified Python 3.12 development environment. Core CI also exercises Python 3.9/3.10/3.14; framework tests run on 3.12. Native tests use real framework clients/users/CSRF/ORM/databases and synthetic external gateway transport. The HTTPS transport fixture binds only loopback. No live charge, external email or automatic shipment occurs in tests. Wheel contains the typed SDK; sdist/source also contains runnable apps, tests, original logos and EN/TR guides.
MIT · Security · Contribution guide · Changelog.
Embedded default and optional backend payment page
The framework examples default to LUNIXI_CHECKOUT_MODE=embedded: the existing form mounts on the merchant website using only https://cdn.lunixi.com/lunixi-checkout.min.js and the official object/token/mount API. Explicit hosted remains supported. IntentResult.payment_page_url reads the optional backend paymentPageUrl; hosted_url validates and returns that exact URL, whose opaque page token can differ from the embedded token. Missing/invalid URLs fail closed; no URL is built from the browser token.
The shared form owns enabled methods, multi-card, installments and insurance in either mode; none requires a redirect. Persisted tokens and page URLs are encrypted with distinct authenticated contexts. The original callback/mode/body/hash/key remain bound to an existing attempt: changing configuration does not create a replacement charge. An older hosted record without a backend URL requires reconciliation. Strict raw webhooks, owner/session/CSRF checks, authenticated settlement and informational 3DS/split returns remain required.
Historical 0.2.1 focused checks: 27 SDK/native Django/FastAPI/Flask cases passed; prior full 0.2.0 verification remains the baseline. No live merchant charge or broad new merchant acceptance was run.
Before upgrading from 0.x, follow the money-string migration.
Metadata
Release files for lunixi-sdk 1.5.1
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 |
|---|---|---|---|---|
| lunixi_sdk-1.5.1.tar.gz | 395.8 kB | With provenance | Details for lunixi_sdk-1.5.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lunixi_sdk-1.5.1-py3-none-any.whl | Python 3 | none | any | Details for lunixi_sdk-1.5.1-py3-none-any.whl |
Total release size: 641.5 kB
Release files / lunixi_sdk-1.5.1.tar.gz
| Download URL | lunixi_sdk-1.5.1.tar.gz |
|---|---|
| Size | 395.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
94d2ff159c43ea503a778cb0b7bd7993937f8a7507860973696e7c18bf1cdb8a
|
|
BLAKE2b-256 checksum How to use checksums |
284d083ea093929a557f3fdd330b27d5c87a1cbcbd748cda66883876fd99ec83
|
| 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 15, 2026.
Transparency logRelease files / lunixi_sdk-1.5.1-py3-none-any.whl
| Download URL | lunixi_sdk-1.5.1-py3-none-any.whl |
|---|---|
| Size | 245.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ecb04a30f64ec454491b1bdbe72d02ca3e7a720fbb69f6aa8e121c9141686d15
|
|
BLAKE2b-256 checksum How to use checksums |
b8ebea73bf307f35997caa15630299f10727610e5b45d833b5104dbff99f87ac
|
| 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 15, 2026.
Transparency logSecurity for lunixi-sdk 1.5.1
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 lunixi_sdk-1.5.1.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 15, 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.