Payment Layer

QODY Payment Layer 

 Author: Finverge (Markos Zachariadis) | Date: 2026-06-22 

 Payment Provider Strategy per Market 

 Bosnia & Herzegovina / Balkans (Primary Market) 

 
 
 
 Provider 
 Use Case 
 Coverage 
 Integration Complexity 
 
 
 
 
 Stripe 
 Card payments (Visa/Mastercard) 
 Global, BiH-supported 
 Low (REST API, Kotlin SDK) 
 
 
 MonriPay 
 Local Balkan PSP 
 Regional card acquiring 
 Medium (API docs available) 
 
 
 Corvus Pay 
 Regional card processor 
 Croatia + BiH 
 Medium (REST API) 
 
 
 

 Recommendation: 
 
 Start with Stripe — best developer experience, supports BiH merchants (USD/EUR settlement), card tokenization, PCI-compliant 
 Add Monri as Phase 2 — local brand recognition, BAM settlement option, lower interchange for Balkan cards 
 

 Norway (Secondary Market) 

 
 
 
 Provider 
 Use Case 
 Coverage 
 Integration Complexity 
 
 
 
 
 Vipps MobilePay 
 Dominant Norwegian wallet 
 Norway only 
 Medium (OAuth, polling) 
 
 
 Stripe 
 Card payments + Apple Pay 
 Global 
 Low 
 
 
 

 Recommendation: Vipps MobilePay (90%+ Norwegian adoption) + Stripe as fallback for international cards. 

 Provider Abstraction Layer 

 CRITICAL: QODY must NOT be locked into one provider. Payment Gateway Abstraction pattern: 

 interface PaymentGateway {
 suspend fun createPaymentIntent(request: PaymentIntentRequest): PaymentIntentResponse
 suspend fun confirmPayment(intentId: String): PaymentConfirmationResponse
 suspend fun refund(paymentId: String, amount: Money): RefundResponse
 suspend fun handleWebhook(payload: String, signature: String): WebhookEvent
}

// Implementations:
class StripeGateway : PaymentGateway { /* Stripe-specific */ }
class VippsGateway : PaymentGateway { /* Vipps-specific */ }
class MonriGateway : PaymentGateway { /* Monri-specific */ }

// Factory for per-venue routing:
class PaymentGatewayFactory(private val config: PaymentConfig) {
 fun forVenue(venueId: UUID): PaymentGateway {
 return when (config.getProviderForVenue(venueId)) {
 PaymentProvider.STRIPE -> StripeGateway(config.stripe)
 PaymentProvider.VIPPS -> VippsGateway(config.vipps)
 PaymentProvider.MONRI -> MonriGateway(config.monri)
 }
 }
}
 

 Checkout Flows 

 Pay-Now (Per Order) 

 Flow: 
 
 Guest adds items to cart 
 Guest taps "Pay Now" 
 Backend creates PaymentIntent (provider-agnostic) 
 Frontend redirects to payment provider (Stripe Checkout, Vipps landing page, or Monri hosted form) 
 Provider webhooks payment.succeeded → backend confirms order → notifies kitchen 
 

 Pay-at-End (Open Tab) 

 Flow: 
 
 Guest orders multiple rounds (drinks, appetizers, mains) 
 Each order appends to the same session_id (table session) 
 When guest requests bill, backend aggregates all unpaid orders for that session 
 Guest sees total → pays once 
 

 Split Bill 

 Three Modes: 

 
 
 
 Mode 
 Description 
 Backend Logic 
 
 
 
 
 By Item 
 Guest A pays for items 1, 3; Guest B pays for items 2, 4 
 Create separate orders per guest 
 
 
 Evenly 
 Total divided by N guests 
 Single order, N payment intents of total / N 
 
 
 By Amount 
 Guest A pays 30 BAM, Guest B pays 20 BAM 
 Validate sum(amounts) == order_total 
 
 
 

 Tipping 

 Implementation: 
 
 After payment intent created, frontend shows tip options (10%, 15%, 20%, custom) 
 Tip is added to payment.amount before provider confirmation 
 Backend splits tip revenue in settlement 
 

 Feature Flag: Tipping may be disabled for some markets. Use Unleash flag qody.tipping.enabled (venue-level). 

 Money Model 

 Amount Storage 

 RULE: Always store monetary amounts in minor units (cents, øre, feninga). 

 data class Money(
 val amountMinor: Int, // e.g., 1250 = 12.50 BAM
 val currency: Currency
) {
 val amountMajor: BigDecimal
 get() = BigDecimal(amountMinor).divide(BigDecimal(100), 2, RoundingMode.HALF_UP)
}

enum class Currency(val code: String, val symbol: String, val minorUnits: Int) {
 BAM("BAM", "KM", 2),
 NOK("NOK", "kr", 2),
 EUR("EUR", "€", 2)
}
 

 Tax / VAT Calculation 

 
 
 
 Market 
 Category 
 Rate 
 
 
 
 
 Bosnia & Herzegovina 
 All items (food, alcohol, general) 
 17% 
 
 
 Norway 
 Food 
 15% 
 
 
 Norway 
 Alcohol 
 25% 
 
 
 Norway 
 General 
 25% 
 
 
 

 val TAX_RULES = mapOf(
 "BA" to mapOf(
 "food" to BigDecimal("0.17"),
 "alcohol" to BigDecimal("0.17"),
 "general" to BigDecimal("0.17")
 ),
 "NO" to mapOf(
 "food" to BigDecimal("0.15"),
 "alcohol" to BigDecimal("0.25"),
 "general" to BigDecimal("0.25")
 )
)

fun calculateTax(item: MenuItem, quantity: Int, country: String): Int {
 val rate = TAX_RULES[country]?.get(item.taxCategory) ?: BigDecimal("0.25")
 val subtotal = item.priceMinor * quantity
 return (subtotal.toBigDecimal() * rate).toInt()
}
 

 Currency & Rounding 

 Multi-Currency Note: QODY must support BAM (BiH), NOK (Norway), EUR (potential expansion). Venue sets its default currency in venues.default_currency . Prices in menu_items.price_minor are always in that venue's currency. 

 Reconciliation 

 Daily Reconciliation Flow: 
 
 Batch job runs nightly (cron or Ktor scheduled task) 
 For each venue, query all payments.status = 'succeeded' from yesterday 
 Compare with provider settlement reports (Stripe Payouts API, Vipps reports) 
 Flag discrepancies (missing payments, refunds not recorded) 
 

 Settlement & Payouts to Venues 

 Marketplace Model vs Venue-Direct PSP 

 
 
 
 Model 
 Description 
 Pros 
 Cons 
 
 
 
 
 Marketplace (Stripe Connect) 
 QODY holds master Stripe account; venues are Connected Accounts 
 Centralized control, auto platform fee 
 QODY responsible for payouts, regulatory complexity 
 
 
 Venue-Direct PSP 
 Each venue has own Stripe/Vipps account 
 No payment license needed, venue owns relationship 
 Cannot auto-deduct SaaS fees 
 
 
 

 Recommendation: 
 
 Phase 1 (MVP): Marketplace model (Stripe Connect) — simpler for pilot venues, faster onboarding 
 Phase 2: Offer venue-direct option for large chains with existing PSP contracts 
 

 Stripe Connect Implementation (Marketplace Model) 

 val paymentIntent = stripe.paymentIntents.create(
 PaymentIntentCreateParams.builder()
 .setAmount(order.totalMinor.toLong())
 .setCurrency(order.currency.code.lowercase())
 .setApplicationFeeAmount((order.totalMinor * 0.05).toLong()) // 5% QODY fee
 .setTransferData(
 PaymentIntentCreateParams.TransferData.builder()
 .setDestination(venue.stripeConnectedAccountId)
 .build()
 )
 .build()
)
 

 Payout Cadence: Stripe automatically pays out to venue bank account (default: daily for Standard accounts, weekly for Express). 

 Fiscalization / Receipts 

 Bosnia & Herzegovina 

 Fiscal Device Requirement: Cash sales require ESET fiscal devices . Card/online payments: Current regulation unclear whether ESET required for cashless-only venues. 

 QODY Implementation: 
 
 Phase 1: Generate PDF receipt (not fiscalized). Mark as "Proforma" or "Non-Fiscal Receipt" 
 Phase 2: Integrate CPF API for B2B invoices (when CPF specs published) 
 ESET Integration: Requires hardware device. Send order data to ESET device via REST API (if device supports) 
 

 Recommendation: Launch QODY in BiH with non-fiscal receipts (PDF) for pilot phase. Add ESET integration when regulatory clarity is confirmed. 

 Norway 

 Fiscal Requirement: Norway requires sales records for VAT reporting, but no real-time fiscal device. Receipts must include: 
 
 Venue name, address, org.nr 
 Date, time 
 Itemized list with VAT breakdown 
 Payment method 
 Receipt number (sequential or unique) 
 

 QODY Implementation: Generate receipt with VAT breakdown (25% vs 15% for food). Store receipt PDF in cloud storage. Email receipt to guest (optional). 

 Webhooks & Idempotency 

 Webhook Handling 

 Providers send webhooks for: 
 
 payment.succeeded (confirm order, notify kitchen) 
 payment.failed (mark order as failed, notify guest) 
 refund.created (update order status to refunded) 
 

 post("/webhooks/stripe") {
 val payload = call.receiveText()
 val signature = call.request.header("Stripe-Signature") ?: throw BadRequestException("Missing signature")

 val event = stripeGateway.handleWebhook(payload, signature)

 when (event.type) {
 "payment_intent.succeeded" -> {
 val paymentIntentId = event.data["id"] as String
 paymentService.confirmPayment(paymentIntentId)
 }
 "payment_intent.payment_failed" -> {
 val paymentIntentId = event.data["id"] as String
 paymentService.markFailed(paymentIntentId)
 }
 }

 call.respond(HttpStatusCode.OK)
}
 

 Security: Verify webhook signature (Stripe uses HMAC SHA256, Vipps uses HMAC SHA512). Store webhook secret in environment variable. 

 Idempotency 

 RULE: Payment confirmations must be idempotent. A webhook may arrive multiple times. 

 suspend fun confirmPayment(paymentIntentId: String) {
 val payment = paymentRepository.findByProviderPaymentId(paymentIntentId)
 ?: throw NotFoundException("Payment not found")

 if (payment.status == PaymentStatus.SUCCEEDED) {
 // Already processed; idempotent return
 return
 }

 transaction {
 paymentRepository.updateStatus(payment.id, PaymentStatus.SUCCEEDED, Instant.now())
 orderRepository.updateTotalPaid(payment.orderId, payment.amountMinor)
 // Notify kitchen, send receipt, etc.
 }
}
 

 Database Constraint: 
 CREATE UNIQUE INDEX idx_payments_provider_id ON payments(provider, provider_payment_id);
 

 This ensures (provider, provider_payment_id) is unique → prevents duplicate payment records. 

 Feature-Flag Gating 

 
 
 
 Feature 
 Unleash Flag 
 Default 
 Gating Reason 
 
 
 
 
 Split Bill 
 qody.payment.split_bill 
 OFF 
 Premium plan only 
 
 
 Tipping 
 qody.payment.tipping 
 ON (BiH), OFF (NO) 
 Cultural preference 
 
 
 Partial Payments 
 qody.payment.partial_payments 
 OFF 
 Premium plan only 
 
 
 Service Charge 
 qody.payment.service_charge 
 OFF 
 Per-venue opt-in 
 
 
 

 Implementation Roadmap 

 Phase 1 (MVP — 4-6 weeks) 

 
 Stripe integration (card payments) 
 Pay-now per order 
 Pay-at-end (open tab) 
 Basic receipt generation (PDF, non-fiscal) 
 Marketplace model (Stripe Connect) 
 Payment webhook handling + idempotency 
 Unleash feature flags for tipping, split bill 
 

 Phase 2 (Expansion — 8-10 weeks) 

 
 Split bill (by item, evenly, by amount) 
 Tipping with configurable rates 
 Vipps integration (Norway) 
 Monri integration (BiH) 
 Partial payments 
 ESET fiscal device integration (BiH) 
 Reconciliation reports 
 

 Phase 3 (Advanced — 12+ weeks) 

 
 Venue-direct PSP option 
 Multi-currency support (BAM, NOK, EUR) 
 CPF e-invoice integration (BiH B2B) 
 Refund self-service for venues 
 Payment analytics dashboard 
 

 Summary — Key Decisions 

 
 Stripe-first for BiH/Balkans (card), Vipps for Norway (wallet), Monri as Phase 2 local option 
 Provider abstraction layer ( PaymentGateway interface) to avoid lock-in 
 Marketplace model (Stripe Connect) for Phase 1 — QODY takes 3-5% platform fee, venues auto-paid out 
 Money in minor units (Int, never Float) — strict double-entry discipline 
 Split bill, tipping, partial payments — all gated by Unleash flags (plan-tier and market-specific) 
 Non-fiscal receipts Phase 1 — add ESET/CPF when regulatory clarity achieved 
 Idempotent webhook handling — (provider, provider_payment_id) unique constraint 
 Reconciliation nightly — compare QODY ledger vs provider settlement reports