Shopify app architecture
The app should behave like a focused payment method: Shopify owns merchant install and checkout entry, NorthRail owns authorization, state, webhooks, refunds, and reconciliation.
MVP constraint
Model the install and payment contracts now, but do not register a live Shopify payment app or production rail.
Adds Pay from bank with NorthRail as a Shopify payment option and redirects the buyer into NorthRail hosted checkout.
MVP: Prototype links to the sandbox checkout route and never registers a production payment app.
Shopify Payments App approval, provider confirmation that the payment method can be offered to Canadian merchants, and counsel review of buyer authorization language.
Collects buyer intent, presents bank-selection UI, creates the provider payment, and returns a deterministic order-confirmation result to Shopify.
MVP: Uses a fake provider adapter, fixture orders, and sandbox-only payment state transitions.
Provider sandbox certification, privacy/security review, consent capture, and production incident handling.
Owns idempotency, payment state transitions, refund eligibility, webhook fan-out, and reconciliation records.
MVP: Runs as typed in-process domain logic; no secrets, external debits, payouts, or live webhooks.
Durable database, queue-backed retries, audit log, secret rotation, and provider reconciliation parity.
Normalizes payment, refund, settlement, and provider event semantics across fake, VoPay/Flinks, Interac, or future open-banking rails.
MVP: NorthRail fake adapter is the only executable adapter in the MVP.
Signed provider agreement, approved sandbox test suite, production credentials, and documented funds flow.
Shows payment ops, settlement batches, webhook deliveries, and CSV reconciliation exports for finance and support teams.
MVP: Reads typed fixtures and generated CSV only; no merchant install, bank-account edits, or payout instructions.
Merchant authentication, KYB status checks, role-based access, export audit trails, and support escalation paths.
Merchant installs app
MerchantMerchant authorizes the NorthRail Shopify app, completes KYB, connects a settlement account, and waits for provider approval.
Shopify OAuth grant, merchant profile, KYB status
Checkout creates payment intent
Shopify checkoutShopify sends order context to NorthRail with a stable idempotency key before redirecting the buyer.
Payment intent, hosted checkout URL
Buyer authorizes bank payment
BuyerNorthRail hosted checkout presents provider-backed authorization and records the buyer consent result.
Provider payment id, authorization timestamp
NorthRail confirms order
NorthRailThe orchestrator maps provider authorization to a Shopify-safe confirmation signal and starts webhook delivery.
Payment confirmed event, Shopify order reference
Merchant reconciles payout
Merchant financeProvider settlement events roll into NorthRail settlement batches and CSV exports that tie back to Shopify orders.
Settlement batch, reconciliation CSV
shopify.checkout.payment_session.resolve
shopifyCreate or resume a NorthRail payment intent.
idempotency: payment_session_id
provider.payment.authorized
providerMark payment authorized and prepare Shopify confirmation.
idempotency: provider_event_id
provider.payment.settled
providerAttach payment to a settlement batch and update merchant reconciliation.
idempotency: provider_event_id
northrail.payment.confirmed
northrailNotify merchant systems that the Shopify order can be fulfilled under NorthRail rules.
idempotency: payment_id:event_type
northrail.refund.succeeded
northrailNotify Shopify and merchant webhooks that a refund changed net settlement.
idempotency: refund_id:event_type