Payment & Shipping Integrations

Reference for developers wiring a Sparrow e-shop (module sparrow_ecommerce, sparrow 7.4.20+).

Payment backends

SPARROW_ECOMMERCE_PAYMENT_BACKENDS = {
    "bank_transfer": {
        "class": "sparrow_ecommerce.payments_bank_transfer.backend.BankTransferBackend",
        "label": "Bank transfer",
        "iban": "CZ72…", "account": "2300097325/2010", "swift": "FIOBCZPPXXX",
        "bank_name": "Fio", "recipient": "Shop s.r.o.", "message": "Order {number}",
    },
    "cod": {"class": "sparrow_ecommerce.payments.cod.CashOnDeliveryBackend", "label": "Cash on delivery"},
    "stripe": {"class": "sparrow_ecommerce.payments_stripe.backend.StripeBackend", "api_key": "…", "webhook_secret": "…"},
    "paypal": {"class": "sparrow_ecommerce.payments_paypal.backend.PayPalBackend", …},
    "comgate": {"class": "sparrow_ecommerce.payments_comgate.backend.ComgateBackend", …},
}

Bank transfer builds a SPAYD string (variable symbol = digits of the order number) and the confirmation page, account detail and e-mail render it as a QR code ({% payment_qr_svg pay.spayd %}, PNG at /shop/orders/qr/<token>.png). Staff confirm the payment in the admin. Billing sites may leave the config empty and use the Store identity instead.
Cash on delivery is flagged collects_on_delivery; the checkout refuses it when the shipping method has COD allowed off and adds the COD fee line.
Stripe / PayPal / Comgate redirect to the gateway and mark the order paid through the webhook at /shop/payments/webhook/<code>/.

Shipping

Leave SPARROW_ECOMMERCE_SHIPPING_STRATEGIES unset and the checkout uses the admin-managed Shipping methods (prices incl. VAT, free-over thresholds, country limits, COD rules, pick-up kinds). Code-defined strategies (FlatRateShipping, PerCountryShipping, WeightBasedShipping) remain available for special cases; a strategy may return several quotes.

Pick-up point widgets

SPARROW_ECOMMERCE_PICKUP_WIDGETS = {
    "packeta": {"api_key": os.environ["PACKETA_API_KEY"], "country": "cz", "language": "cs"},
    "ppl": {},        # PPL ParcelShop map, no key
    "balikovna": {},  # Česká pošta Balíkovna picker, no key
}

Zásilkovna / Packeta - widget v6 (widget.packeta.com/v6); the public API key comes from the client section of Packeta.
PPL - ParcelShop map (www.ppl.cz/sources/map/main.js), receives the point through the ppl-parcelshop-map DOM event.
Balíkovna - iframe of b2c.cpost.cz/locations/?type=BALIKOVNY, receives the point through postMessage.

The chosen point (id, name, address, raw payload) is stored in Order.shipping_meta["pickup"] and appended to shipping_label; a manual text fallback is always offered.

Order numbers, e-mails, store identity

SPARROW_ECOMMERCE_ORDER_NUMBERING = "sequence"   # default "token" (YYYYMMDD-XXXXXX)
SPARROW_ECOMMERCE_ORDER_SEQUENCE_START = 1001
SPARROW_ECOMMERCE_ORDER_EMAILS = True
SPARROW_ECOMMERCE_SHOP_EMAIL = "orders@example.com"
SPARROW_ECOMMERCE_STORE_NAME = "My Shop"
SPARROW_ECOMMERCE_STORE_ADDRESS = "My Shop s.r.o., Street 1, 110 00 Praha"
SPARROW_ECOMMERCE_MAIL_SIGNOFF = "Thank you, the My Shop team"
SPARROW_ECOMMERCE_SITE_URL = "https://www.example.com"
EMAIL_URL = "smtps://user%40example.com:password@smtp.example.com:465"
DEFAULT_FROM_EMAIL = "My Shop <orders@example.com>"

Mails: order placed (customer + shop copy), payment received, shipped (tracking number, pick-up point), cancelled, refunded - templates under sparrow_ecommerce/email/, overridable per site, with Czech translations included. Status mails fire from Order.mark_paid() / mark_fulfilled(tracking_number) / mark_cancelled() / mark_refunded() and from the admin actions; the signals order_placed and order_status_changed (sparrow_ecommerce.orders.signals) are available for stock, accounting or ERP hooks.

Customer accounts

Install sparrow.account and point LOGIN_URL at sparrow_account:login; order history and details appear as a tab of the account dashboard.

SparrowCMS

Payment & Shipping Integrations