System Requirements Document for qris-seller

1. Introduction

Payyo QRIS is a QRIS merchant payment provider platform for Indonesian sellers. It lets a seller register for free, top up an account balance, display a QRIS code to collect payments from their own customers, and withdraw the resulting balance out to an e-wallet or a bank account.

The product intent is a plain, sturdy money tool: money in, money out, clearly shown. Payyo QRIS is the provider that supplies the QRIS code to the seller. The QRIS code itself is sourced from iPaymu using an owner-supplied iPaymu VA and API key, but that provider origin is an internal implementation fact and must never be disclosed to sellers — the code is presented as Payyo QRIS only.

The audience is practical, mobile-first, price-sensitive Indonesian merchants: warung owners, online sellers, and side-hustle merchants who want to accept QRIS payments without paperwork. The secondary audience is the internal Payyo QRIS Operator/Admin who configures the provider credentials that keep seller QRIS provisioning working.

2. System Overview

Payyo QRIS is delivered as a first-party web application with its own application-owned identity, backed by a server-side integration to the iPaymu provider API. Sellers self-enroll for free, verify on return visits, and work in a seller workspace covering balance top-up, QRIS display, and withdrawal. The Payyo QRIS Operator/Admin verifies on return visits and works in a restricted provider configuration workspace.

Actors

• Seller (Merchant) — the paying, transacting human actor. Registers free, tops up balance, displays QRIS to collect payment, withdraws balance to e-wallet or bank.
• Payyo QRIS Operator/Admin — the internal human actor who configures the owner-supplied iPaymu VA and API key and keeps seller QRIS provisioning working.
• iPaymu — typed non-persona external provider actor. Owns QRIS generation and the VA/API-key credential surface. Never surfaced to sellers by name, logo, or hint.

Accepted current behavior

• Free seller self-registration and returning verification for both personas.
• Seller balance top-up.
• Seller QRIS display, sourced from iPaymu, presented as Payyo QRIS only.
• Seller balance withdrawal to an e-wallet or a bank.
• Operator configuration of the owner-supplied iPaymu VA and API key, which is a prerequisite for seller QRIS provisioning.

Narrow exclusions

• The iPaymu origin of the QRIS must not be disclosed to sellers anywhere in the seller-facing UI.
• No adjacent account-management, KYC, dispute, refund, settlement-reporting, or multi-user team capabilities are in scope; none were accepted.

2a. Product Interpretation and Delivery Boundary

Payyo QRIS is a first-party web product. The seller-facing surfaces — Landing, Sign Up, Login, Top Up, QRIS, Withdraw — are owned and rendered by the Payyo QRIS application. The operator-facing Provider Settings surface is likewise first-party but restricted to the operator/admin role.

Identity is application-owned. Because sellers must privately own and resume a durable balance, a QRIS display, and withdrawal history, and because the operator must hold a durable provider credential configuration, Payyo QRIS establishes its own accounts. First use is self-service free registration for sellers; operator/admin access is provisioned before provider credentials can be configured. Returning users verify through a shared Login surface.

The iPaymu integration is server-side and provider-owned. Payyo QRIS calls iPaymu with the owner-supplied VA and API key to obtain the QRIS that is then presented to the seller. iPaymu is never a seller-facing destination, and no iPaymu name, logo, wordmark, or visual hint appears in the seller-facing UI.

Everything described in this document is current. No future-horizon capabilities were accepted.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares content_source authority, so no source content inventory is included.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains that Payyo QRIS is a QRIS merchant payment provider, that sellers can register for free, that they can top up a balance, that they can display a QRIS code to collect payments, and that they can withdraw balance to an e-wallet or a bank. No iPaymu name, logo, or reference appears anywhere.
• Primary actions: DAFTAR GRATIS (solid signal-orange slab, 3px ink border, 2px offset ink shadow) → Sign Up. MASUK (outlined ink slab) → Login.
• Supporting actions: Scroll through poster-stacked sections explaining the four seller steps (register free, top up, show QRIS, withdraw).
• Domain entities: Payyo QRIS product description, seller value proposition, free-registration fact, QRIS collection concept, withdrawal-to-e-wallet-or-bank concept.
• Component responsibilities: Full-bleed kraft hero band; left 7 columns hold the small black-badge wordmark PAYYO QRIS, the stacked all-caps Alfa Slab One headline TERIMA QRIS. TARIK DUITNYA. with a 4px ink rule under the first line, and the two slab buttons. Right 5 columns hold a solid denim block bleeding off the right edge with a white square QRIS viewfinder with corner tick marks, a mustard AKTIF status chip, and a tabular SALDO Rp 0 line in Oswald 600. A 4px ink rule runs full width at the hero bottom; a rotated −3° stamp badge GRATIS SELAMANYA sits at the seam. Thick-line vector iconography (QRIS square, wallet, bank building, warung awning, receipt, truck) at 2.5–3px stroke; halftone-dot duotone merchant photographs cropped hard to the grid; optional topographic-line texture at 8% opacity on denim bands.
• States: Loading — static content, no data fetch; no loading state. Empty — not applicable. Success — page renders fully at 375px, 768px, and 1280px with headline clamp(56px, 12vw, 128px) and all readable text and controls whole inside the viewport. Error — not applicable. Recovery — not applicable.

Sign Up

• Information/state: Anonymous self-service enrollment for prospective sellers. States plainly that seller registration is free. Collects the seller's identifying and contact details needed to own a durable Payyo QRIS account.
• Primary actions: Submit the free registration form to create the seller account.
• Supporting actions: Navigate to Login if already registered; return to Landing.
• Domain entities: Seller account, seller identity/contact details, free-registration fact.
• Component responsibilities: Ruled form panel on paper surface with 2px ink border and 0px radius; all-caps Oswald labels at 0.08em letterspacing; slab submit button with 3px ink border and 2px offset ink shadow that presses on hover; inline field-level validation messages in muted clay; a GRATIS stamp badge.
• States: Loading — submit button enters a pressed/disabled state while the account is created. Empty — initial blank form. Success — account created and the seller proceeds to the seller workspace. Error — duplicate or invalid registration details are reported inline against the offending field, with the form preserved for correction. Recovery — the seller corrects the field and resubmits without re-entering the rest of the form.

Login

• Information/state: Shared returning-verification surface for both the Seller (Merchant) and the Payyo QRIS Operator/Admin. Anonymous until credentials are verified.
• Primary actions: Submit credentials to verify identity and resume the correct workspace.
• Supporting actions: Navigate to Sign Up for a new seller account; return to Landing.
• Domain entities: Seller account, operator/admin account, session.
• Component responsibilities: Ruled credential panel with 2px ink border; slab submit button with offset ink shadow; inline error region in muted clay; no role selector exposed as a product concept — the verified account determines the workspace.
• States: Loading — submit button pressed/disabled during verification. Empty — initial blank form. Success — verified seller lands in the seller workspace; verified operator/admin lands in Provider Settings. Error — invalid credentials reported inline without revealing which field was wrong. Recovery — the user retries; repeated failure keeps the form usable and does not lock the surface.

Top Up

• Information/state: Restricted to the verified Seller (Merchant). Shows the current Payyo QRIS balance as the headline number in Oswald 600 tabular, larger than its label, and the top-up amount being entered.
• Primary actions: Enter a top-up amount and submit it to add funds to the Payyo QRIS account balance.
• Supporting actions: View the resulting balance; view receipt-style top-up history rows with dotted leaders and hard-aligned values.
• Domain entities: Seller balance, top-up transaction, top-up amount, top-up history entry.
• Component responsibilities: Persistent 240px left rail of ruled all-caps nav items with a thick orange active-state bar; receipt-style tabular rows with dotted leaders; signal-orange reserved for the Top Up action and the balance number; mustard/forest status chips for pending/settled; slab submit button with offset ink shadow.
• States: Loading — balance and history rows show a ruled skeleton while fetching. Empty — no top-up history yet: a ruled empty panel states that no top-ups have been made. Success — the balance number updates and a new settled top-up row appears. Error — a rejected top-up is reported inline and the balance is left unchanged. Recovery — the seller retries the top-up; a pending top-up is shown with a mustard PENDING chip and resolves to a forest SELESAI chip when confirmed.

QRIS

• Information/state: Restricted to the verified Seller (Merchant). Displays the Payyo QRIS payment code obtained from iPaymu, presented strictly as Payyo QRIS. No iPaymu name, logo, wordmark, or visual hint appears. Shows the current balance as a tabular Oswald 600 number.
• Primary actions: Show/display the QRIS code for the seller's customer to scan.
• Supporting actions: Refresh the displayed code; view the collection status of the displayed code.
• Domain entities: Payyo QRIS code, QRIS display session, seller balance, collection status.
• Component responsibilities: White square QRIS viewfinder with corner tick marks inside a solid denim block — presented as an instrument readout, never a floating card with a soft shadow; signal orange reserved for the show-code action; mustard/forest status chips; tabular balance line.
• States: Loading — the viewfinder frame renders with a ruled placeholder while the code is fetched from the provider. Empty — no code available yet: the viewfinder shows a ruled unavailable state with a plain-language message and a retry control. Success — the QRIS code renders inside the viewfinder with an AKTIF chip. Error — provider fetch failure shows a plain-language error inside the viewfinder frame without naming the provider. Recovery — the seller retries the fetch; the previously displayed code is not silently replaced by a stale or partial one.

Withdraw

• Information/state: Restricted to the verified Seller (Merchant). Shows the current Payyo QRIS balance as the headline tabular number and the withdrawal amount being requested.
• Primary actions: Choose an e-wallet or a bank as the withdrawal destination, enter the destination details and amount, and submit the withdrawal.
• Supporting actions: View receipt-style withdrawal history rows with dotted leaders and hard-aligned values.
• Domain entities: Seller balance, withdrawal request, withdrawal destination type (e-wallet or bank), destination details, withdrawal amount, withdrawal history entry.
• Component responsibilities: Destination-type selection between e-wallet and bank; ruled destination-detail fields; receipt-style tabular history; signal orange reserved for the Withdraw action and the balance number; mustard/forest status chips for pending/settled; slab submit button with offset ink shadow.
• States: Loading — balance and history rows show a ruled skeleton while fetching. Empty — no withdrawal history yet: a ruled empty panel states that no withdrawals have been made. Success — the balance decreases and a new withdrawal row appears with a forest SELESAI chip. Error — an invalid destination or an amount exceeding the available balance is reported inline and the balance is left unchanged. Recovery — the seller corrects the destination or amount and resubmits; a pending withdrawal shows a mustard PENDING chip and resolves to SELESAI when settled.

Provider Settings

• Information/state: Restricted to the verified Payyo QRIS Operator/Admin. Shows the configuration state of the owner-supplied iPaymu VA and API key used for QRIS provisioning, and whether seller QRIS provisioning is currently operational.
• Primary actions: Enter and save the owner-supplied iPaymu VA and API key.
• Supporting actions: View the current configuration status and the last-saved state; re-save after a credential change.
• Domain entities: iPaymu VA, iPaymu API key, provider configuration state, QRIS provisioning availability.
• Component responsibilities: Ruled configuration panel with 2px ink border; masked credential fields; slab save button with offset ink shadow; status chip showing configuration state; a plain-language note that these credentials are required before seller QRIS provisioning can operate. This surface is operator-only and is never reachable by a seller.
• States: Loading — the configuration panel shows a ruled skeleton while the current state is fetched. Empty — no credentials configured yet: a ruled panel states that provider credentials are required before seller QRIS provisioning can operate. Success — credentials saved and the configuration status chip updates. Error — a rejected credential save is reported inline and the previously saved configuration is left intact. Recovery — the operator corrects the credential values and re-saves; seller QRIS provisioning continues to use the last valid configuration until a new one is saved successfully.

3. Functional Requirements

FR-01 — Free seller registration (explicit) As a prospective Seller (Merchant), I should be able to register a Payyo QRIS account for free, so that I can start accepting QRIS payments without paperwork or cost.

• Trigger/input: the prospective seller submits the free registration form on Sign Up.
• Observable result: a Payyo QRIS seller account is created and the seller enters the seller workspace.
• Access state: Sign Up is anonymously reachable; no account is required to begin.
• Failure/recovery: invalid or duplicate registration details are reported inline against the offending field with the form preserved; the seller corrects and resubmits.
• Continuation: the seller proceeds to top up balance or display QRIS.

FR-02 — Returning verification for sellers and operator/admin (required_inference) As a Seller (Merchant) or Payyo QRIS Operator/Admin, I should be able to verify my identity on return, so that I can resume my durable balance, QRIS display, withdrawal history, or provider configuration.

• Trigger/input: the user submits credentials on Login.
• Observable result: the verified seller resumes the seller workspace; the verified operator/admin resumes Provider Settings.
• Access state: Login is anonymously reachable; protected state remains unavailable until identity is verified.
• Failure/recovery: invalid credentials are reported inline without revealing which field was wrong; the user retries and the surface stays usable.
• Continuation: the user continues the work belonging to their role.

FR-03 — Operator/admin access provisioning (required_inference) As a Payyo QRIS Operator/Admin, I should have my access provisioned before provider credentials can be configured, so that only an authorized operator can set the credentials that seller QRIS provisioning depends on.

• Trigger/input: operator/admin access is provisioned by the platform owner.
• Observable result: the operator/admin can verify on Login and reach Provider Settings.
• Access state: Provider Settings is role-restricted to the operator/admin; a seller cannot reach it.
• Failure/recovery: an unverified or non-operator account cannot reach Provider Settings and is returned to Login.
• Continuation: the operator proceeds to configure the provider credentials.

FR-04 — Configure owner-supplied iPaymu VA and API key (explicit) As a Payyo QRIS Operator/Admin, I should be able to configure the owner-supplied iPaymu VA and API key, so that Payyo QRIS can provision QRIS codes for sellers.

• Trigger/input: the operator enters the owner-supplied iPaymu VA and API key on Provider Settings and saves.
• Observable result: the provider configuration is stored and the configuration status reflects the saved state.
• Access state: role-restricted to the verified operator/admin.
• Failure/recovery: a rejected save is reported inline and the previously saved configuration is left intact.
• Continuation: seller QRIS provisioning operates using the saved credentials.

FR-05 — Provider credentials are a prerequisite for seller QRIS provisioning (required_inference) As a Payyo QRIS Operator/Admin, I should see that the owner-supplied iPaymu VA and API key must be configured before seller QRIS provisioning can operate, so that I know why sellers may be unable to display a QRIS code.

• Trigger/input: the operator views Provider Settings while no valid credentials are configured.
• Observable result: the surface states that provider credentials are required before seller QRIS provisioning can operate.
• Access state: role-restricted to the verified operator/admin.
• Failure/recovery: if credentials are missing or invalid, seller QRIS provisioning does not operate and the seller-facing QRIS surface shows a plain-language unavailable state without naming the provider.
• Continuation: the operator saves valid credentials and seller QRIS provisioning resumes.

FR-06 — Seller balance top-up (explicit) As a Seller (Merchant), I should be able to top up my Payyo QRIS balance, so that I have funds available in my Payyo QRIS account.

• Trigger/input: the seller enters a top-up amount on Top Up and submits.
• Observable result: the Payyo QRIS balance increases and a new top-up history row appears.
• Access state: role-restricted to the verified seller.
• Failure/recovery: a rejected top-up is reported inline and the balance is left unchanged; the seller retries.
• Continuation: the seller sees the updated balance and can display QRIS or withdraw.

FR-07 — Display QRIS code for payment collection (explicit) As a Seller (Merchant), I should be able to display a QRIS code, so that my customer can scan it and pay me.

• Trigger/input: the seller opens QRIS and triggers the show-code action.
• Observable result: the Payyo QRIS payment code renders inside the viewfinder with an AKTIF status chip.
• Access state: role-restricted to the verified seller.
• Failure/recovery: a provider fetch failure shows a plain-language error inside the viewfinder frame without naming the provider; the seller retries and no stale or partial code is silently substituted.
• Continuation: the seller's customer scans the code and the collection is reflected against the seller's balance.

FR-08 — QRIS is sourced from iPaymu (explicit) As a Seller (Merchant), I should receive a QRIS code that Payyo QRIS obtains from iPaymu on my behalf, so that I can collect QRIS payments through Payyo QRIS.

• Trigger/input: the seller triggers the show-code action on QRIS.
• Observable result: Payyo QRIS requests the QRIS from iPaymu using the configured VA and API key and renders the returned code.
• Access state: role-restricted to the verified seller; the iPaymu call is server-side.
• Failure/recovery: if the provider call fails, the seller sees a plain-language error and can retry.
• Continuation: the rendered code is displayed as Payyo QRIS only.

FR-09 — iPaymu origin is never disclosed to sellers (explicit) As a Seller (Merchant), I should never be told that the QRIS comes from iPaymu, so that the QRIS is presented to me as Payyo QRIS only.

• Trigger/input: any seller-facing render of the QRIS or its surrounding surface.
• Observable result: no iPaymu name, logo, wordmark, or visual hint appears anywhere in the seller-facing UI, including error and empty states.
• Access state: applies to all seller-facing surfaces.
• Failure/recovery: if a provider error would otherwise surface a provider name, it is rendered as a plain-language Payyo QRIS message instead.
• Continuation: the seller continues to use the QRIS as a Payyo QRIS code.

FR-10 — Seller balance withdrawal to e-wallet or bank (explicit) As a Seller (Merchant), I should be able to withdraw my balance to an e-wallet or a bank, so that I can cash out the funds I have collected.

• Trigger/input: the seller chooses e-wallet or bank on Withdraw, enters the destination details and amount, and submits.
• Observable result: the Payyo QRIS balance decreases and a new withdrawal history row appears.
• Access state: role-restricted to the verified seller.
• Failure/recovery: an invalid destination or an amount exceeding the available balance is reported inline and the balance is left unchanged; the seller corrects and resubmits.
• Continuation: the seller sees the updated balance and the withdrawal status resolving from pending to settled.

FR-11 — Durable seller balance and history (required_inference) As a Seller (Merchant), I should have my balance and my top-up and withdrawal history persist across sessions, so that I can trust that money in and money out are recorded.

• Trigger/input: the seller returns and verifies on Login.
• Observable result: the balance and receipt-style history rows are shown as they were left.
• Access state: role-restricted to the verified seller; the state is bound to the correct seller account.
• Failure/recovery: if the history cannot be fetched, a ruled skeleton or plain-language error is shown and the seller can retry.
• Continuation: the seller continues from the recorded state.

FR-12 — Durable provider configuration (required_inference) As a Payyo QRIS Operator/Admin, I should have my saved provider configuration persist across sessions, so that seller QRIS provisioning keeps working without re-entry.

• Trigger/input: the operator returns and verifies on Login.
• Observable result: Provider Settings shows the current saved configuration state.
• Access state: role-restricted to the verified operator/admin.
• Failure/recovery: if the configuration cannot be fetched, a ruled skeleton or plain-language error is shown and the operator can retry.
• Continuation: the operator re-saves only when the credentials change.

4. User Personas

Seller (Merchant)

Product context. A practical, mobile-first Indonesian merchant — a warung owner, an online seller, or a side-hustle merchant — who wants to accept QRIS payments without paperwork. They are price-sensitive and slightly suspicious of fintech polish; they need to feel that money in equals money out, clearly, with no fine print games.

Primary goal. Accept QRIS payments from their own customers and cash out the collected funds to an e-wallet or a bank.

Distinct accepted responsibilities.

• Register a Payyo QRIS account for free (FR-01).
• Verify on return visits to resume their own durable state (FR-02).
• Top up their Payyo QRIS balance (FR-06).
• Display the Payyo QRIS code so a customer can scan and pay (FR-07, FR-08).
• Withdraw their balance to an e-wallet or a bank (FR-10).
• Rely on their balance and history persisting across sessions (FR-11).

Relevant inputs and decisions. The top-up amount; when to show the QRIS code; the withdrawal destination type (e-wallet or bank), the destination details, and the withdrawal amount. The seller never makes a decision about the QRIS provider — that is not theirs to see or choose.

Interactions with other accepted participants. The seller's customer scans the displayed QRIS code and pays, which is the collection event the seller is waiting on. The Payyo QRIS Operator/Admin is invisible to the seller but is the reason the QRIS is available at all: if the operator has not configured valid provider credentials, the seller's QRIS surface shows a plain-language unavailable state. iPaymu is never an interaction the seller is aware of.

Observable success. The seller's balance reflects collected funds, the QRIS code displays and is scannable, and a withdrawal to the chosen e-wallet or bank settles with the balance reduced accordingly.

What makes this role different. The seller is the money-holding party and the only persona who initiates value movement in both directions — top-up in, withdrawal out — and the only persona who displays a code to a third party. Their entire experience must be free of provider disclosure, which is a constraint no other persona carries.

Payyo QRIS Operator/Admin

Product context. The internal operator behind Payyo QRIS. Because Payyo QRIS is the QRIS provider that supplies the iPaymu-backed QRIS to sellers and holds the VA and API key credentials, someone must configure those credentials and keep seller-facing QRIS provisioning working.

Primary goal. Keep seller QRIS provisioning uninterrupted so sellers can display QRIS and transact.

Distinct accepted responsibilities.

• Have access provisioned before provider credentials can be configured (FR-03).
• Verify on return visits to resume the provider configuration (FR-02).
• Configure the owner-supplied iPaymu VA and API key (FR-04).
• Understand that these credentials are a prerequisite for seller QRIS provisioning (FR-05).
• Rely on the saved configuration persisting across sessions (FR-12).

Relevant inputs and decisions. The owner-supplied iPaymu VA and API key values, and when to re-save them after a credential change. The operator decides whether the current configuration is valid enough for seller QRIS provisioning to operate.

Interactions with other accepted participants. The operator's work is the precondition for every seller's QRIS display. The operator never interacts with a seller directly; the observable effect of the operator's work is that sellers can display QRIS and transact. iPaymu is the external provider whose credential surface the operator configures.

Observable success. The configuration status reflects saved credentials and seller QRIS provisioning operates without interruption.

What makes this role different. The operator is the only persona who touches provider credentials and the only persona whose success is measured by another persona's uninterrupted service rather than by their own money movement. Their surface is restricted and never reachable by a seller, and unlike the seller they are fully aware that the QRIS originates from iPaymu.

5. Core User Flows

Flow 1 — Seller registers for free and reaches the seller workspace

1. The prospective Seller (Merchant) arrives anonymously on Landing and reads that Payyo QRIS is a QRIS merchant payment provider, that registration is free, and that they can top up, show QRIS, and withdraw to an e-wallet or bank.
2. The seller selects DAFTAR GRATIS and lands on Sign Up.
3. The seller enters their identifying and contact details and submits the free registration form.
4. Observable result: a Payyo QRIS seller account is created and the seller enters the seller workspace.
5. Failure/recovery: if a detail is invalid or already registered, the error is reported inline against that field and the rest of the form is preserved; the seller corrects it and resubmits.
6. Continuation: the seller proceeds to Flow 2 or Flow 3.

Flow 2 — Seller tops up balance

1. The verified Seller (Merchant) is in the seller workspace and opens Top Up from the left rail.
2. The seller sees the current Payyo QRIS balance as the headline tabular number and the top-up history as receipt-style rows with dotted leaders.
3. The seller enters a top-up amount and submits.
4. Observable result: the balance number increases and a new top-up row appears, resolving from a mustard PENDING chip to a forest SELESAI chip when confirmed.
5. Failure/recovery: if the top-up is rejected, the error is reported inline and the balance is left unchanged; the seller retries.
6. Continuation: the seller proceeds to Flow 3 to display QRIS, or Flow 4 to withdraw.

Flow 3 — Seller displays QRIS and collects payment

1. The verified Seller (Merchant) opens QRIS from the left rail.
2. The seller triggers the show-code action.
3. Payyo QRIS server-side requests the QRIS from iPaymu using the configured VA and API key, and renders the returned code inside the white viewfinder square with corner tick marks, inside a solid denim block, with an AKTIF status chip.
4. Observable result: the seller's customer scans the displayed code and pays; the collection is reflected against the seller's balance.
5. Constraint in effect: no iPaymu name, logo, wordmark, or visual hint appears anywhere on this surface, including in loading, empty, and error states.
6. Failure/recovery: if the provider fetch fails, a plain-language error appears inside the viewfinder frame without naming the provider, and the seller retries; no stale or partial code is silently substituted.
7. Continuation: the seller proceeds to Flow 4 to withdraw the collected funds.

Flow 4 — Seller withdraws balance to an e-wallet or a bank

1. The verified Seller (Merchant) opens Withdraw from the left rail.
2. The seller sees the current Payyo QRIS balance as the headline tabular number and the withdrawal history as receipt-style rows.
3. The seller chooses the destination type — e-wallet or bank — enters the destination details and the withdrawal amount, and submits.
4. Observable result: the balance decreases and a new withdrawal row appears, resolving from a mustard PENDING chip to a forest SELESAI chip when settled.
5. Failure/recovery: if the destination is invalid or the amount exceeds the available balance, the error is reported inline and the balance is left unchanged; the seller corrects the destination or amount and resubmits.
6. Continuation: the seller returns to Flow 2 or Flow 3 as needed.

Flow 5 — Seller returns and resumes

1. The Seller (Merchant) arrives anonymously on Landing and selects MASUK, landing on Login.
2. The seller submits their credentials.
3. Observable result: the seller is verified and resumes the seller workspace with their balance and receipt-style top-up and withdrawal history as they were left.
4. Failure/recovery: invalid credentials are reported inline without revealing which field was wrong; the seller retries and the surface stays usable.
5. Continuation: the seller continues with Flow 2, Flow 3, or Flow 4.

Flow 6 — Operator configures provider credentials

1. The Payyo QRIS Operator/Admin has their access provisioned by the platform owner, then arrives on Login and submits their credentials.
2. Observable result: the operator is verified and lands on Provider Settings.
3. The operator sees the current configuration state. If no credentials are configured, the surface states that provider credentials are required before seller QRIS provisioning can operate.
4. The operator enters the owner-supplied iPaymu VA and API key and saves.
5. Observable result: the configuration is stored and the configuration status chip updates; seller QRIS provisioning operates using the saved credentials.
6. Failure/recovery: if the save is rejected, the error is reported inline and the previously saved configuration is left intact; seller QRIS provisioning continues to use the last valid configuration until a new one saves successfully. The operator corrects the values and re-saves.
7. Continuation: the operator returns to Flow 7 when credentials change.

Flow 7 — Operator keeps seller QRIS provisioning working

1. The verified Payyo QRIS Operator/Admin returns to Login and verifies.
2. Observable result: Provider Settings shows the current saved configuration state as it was left.
3. If the credentials have changed, the operator re-saves them per Flow 6.
4. Observable effect for the Seller (Merchant): sellers can continue to display QRIS and transact without interruption.
5. Failure/recovery: if the configuration cannot be fetched, a ruled skeleton or plain-language error is shown and the operator retries.
6. Continuation: the operator monitors the configuration state and re-saves when credentials change.

6. Visuals Colors and Theme

Muse and headline. Aaron Draplin. Thick-line field badges for a QRIS payment provider that works like a tool, not a bank. The register is trustworthy, plain-spoken, sturdy, local, unglamorous but proud — the opposite of generic blue-on-white fintech.

Colour tokens (light mode).

No gradients anywhere.

Typography. Headings and wordmark: Alfa Slab One, heavy slab, all caps, tight tracking, at poster scale. Everything else: Oswald in 400/500/600 — labels in all caps with 0.08em letterspacing, body copy at 16–18px with 1.55 line-height. Numbers (balance, amounts, VA) are always set in Oswald 600 tabular, larger than surrounding copy — the number is the headline.

Type scale (1.333 modular). 14 / 16 / 18 / 24 / 32 / 48 / 64 / 96 / 128. Display hero clamp(56px, 12vw, 128px). Section opener clamp(32px, 5vw, 64px). Card title 24px. Body 16px. Micro-label 12px all-caps with 0.1em tracking.

Shape language. Sharp corners everywhere (0px radius) with 2px solid ink borders on every panel and card. Badge and stamp motifs: circular seal badges with concentric rings for status (AKTIF, TERVERIFIKASI, SELESAI), and chunky rectangular stamps rotated −3° for one-off callouts. Thick 4px horizontal rules separate sections like a ruled ledger. Buttons are rectangular slabs with a 3px ink border and a 2px offset ink shadow (no blur) — they look pressed into the page. The QRIS code sits inside a square frame with corner tick marks, like a viewfinder.

Layout. Poster-like stacked sections on a 12-column grid with a visible 1px column rule option on desktop. The landing hero is a full-bleed kraft band with an oversized stacked headline on the left 7 columns and a solid denim block holding the QRIS viewfinder on the right 5. The seller workspace uses a persistent left rail (240px) of ruled nav items with all-caps labels and a thick active-state orange bar. Dashboard content is tabular: label/value rows aligned on a hard left edge with dotted leaders, like a receipt. Sections are separated by full-width denim or orange bands, never by whitespace alone. Mobile (375px) collapses to a single column, headline clamp 56px, cards stack full-width with the same 2px borders.

Imagery. Thick-line vector iconography drawn at 2.5–3px stroke weight: a QRIS square, a wallet, a bank building, a warung awning, a receipt, a truck. Halftone-dot photographs (duotone in denim + kraft) of real Indonesian merchants — a warung counter, a phone held over a QR code, hands counting cash — cropped hard to the grid. No stock-photo smiling people, no 3D renders, no glass. Optional topographic-line texture at 8% opacity on denim bands.

Forbidden. Blue-indigo gradients, glassmorphism, frosted panels, soft drop shadows with blur; any mention, logo, wordmark, or visual hint of iPaymu anywhere in the seller-facing UI; rounded corners above 0px on panels, cards, or buttons; pill shapes; Inter, Roboto, Poppins, system-ui, or any neutral geometric sans as the display voice; a centred hero with subtext and a single blue CTA; grids of identical hover-lift cards with uniform elevation; illustrated mascots, cartoon characters, or 3D isometric renders; photographic stock imagery of generic smiling businesspeople in offices.

7. Signature Design Concept

The Payyo QRIS Landing hero — a stamped field instrument.

A full-bleed kraft (#F1E7D0) band, no gradient, no blob. The composition is asymmetric and block-built, split 7/5.

Left 7 columns. The wordmark PAYYO QRIS is stamped small at the top inside a black badge. Beneath it, a stacked all-caps Alfa Slab One headline reading TERIMA QRIS. TARIK DUITNYA. at clamp(56px, 12vw, 128px), each line sitting flush-left and filling the column width, with a 4px ink rule under the first line. Beneath the headline, two rectangular slab buttons sit side by side: a solid signal-orange (#E4572E) DAFTAR GRATIS with a 3px ink border and a 2px offset ink shadow, and an outlined ink MASUK.

Right 5 columns. A solid denim (#1B2A41) block that bleeds off the right edge of the viewport, holding a white square QRIS viewfinder with corner tick marks, a mustard status chip AKTIF, and a tabular balance line SALDO Rp 0 in Oswald 600. The code is presented as an instrument readout, never as a floating card with a soft shadow.

Seam and rules. A 4px ink rule runs the full width of the viewport at the bottom of the hero. A thin rotated −3° stamp badge GRATIS SELAMANYA sits at the seam between the two halves.

Hard constraint in the composition. No iPaymu name, logo, or reference appears anywhere in the composition. The QRIS is presented as Payyo QRIS only.

Readability. At 375px, 768px, and 1280px the headline, wordmark, labels, numbers, and both buttons stay entirely inside the viewport and their container, wrapping or scaling via the clamp to fit. Decoration — the denim block, the topographic texture, the halftone imagery — may bleed off the edge; readable text and controls never do.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: the white QRIS viewfinder square with corner tick marks, sitting inside the solid denim block on the right 5 columns — the instrument readout that is the product's defining object.
• Input → transformation → outcome thesis: on mount, the hero's sections snap in with a 120ms translateY(8px) + opacity — no bounce, no stagger theatre — so the kraft band, the stacked headline, and the denim block arrive as one sturdy printed sheet. The AKTIF badge stamp then thunks in once with a 200ms scale(1.06 → 1). The outcome is a composed, still, poster-like first frame in which the QRIS viewfinder reads as a physical instrument and the two slab buttons read as pressable hardware.
• Motion vocabulary: sturdy and minimal. Entrance is a 120ms translateY(8px) + opacity with no bounce. Button hover collapses the 2px offset ink shadow to 0 and translates the button 2px down/right — a physical press. Badge stamps animate once on mount with a 200ms scale(1.06 → 1) thunk. No parallax, no marquee, no gradients drifting.
• Composed first frame: the full-bleed kraft band with the black-badge wordmark, the stacked all-caps headline with its 4px ink rule under the first line, the two slab buttons, the denim block bleeding off the right edge holding the white viewfinder with the mustard AKTIF chip and the tabular SALDO Rp 0 line, the full-width 4px ink rule at the hero bottom, and the rotated −3° GRATIS SELAMANYA stamp at the seam.
• Reduced-motion state: all transforms are removed; only opacity fades remain. The hero renders as a complete, usable static arrangement with every readable text and control whole inside the viewport at 375px, 768px, and 1280px.

9. Non-Functional Requirements

NFR-01 — Provider origin confidentiality (explicit) The iPaymu origin of the QRIS must not be disclosed to sellers. No iPaymu name, logo, wordmark, or visual hint may appear in any seller-facing surface, including loading, empty, success, error, and recovery states. Provider errors are rendered as plain-language Payyo QRIS messages. Rationale: explicit hard constraint in the authoritative user evidence.

NFR-02 — Free seller registration (explicit) Seller registration must be free. No payment, fee, or paid tier gates the creation of a seller account. Rationale: explicit hard constraint in the authoritative user evidence.

NFR-03 — Owner-supplied provider credentials (explicit) Payyo QRIS must use the owner-supplied iPaymu VA and API key for QRIS provisioning. These credentials are configured by the Payyo QRIS Operator/Admin and are never exposed to sellers. Rationale: explicit hard constraint in the authoritative user evidence.

NFR-04 — Credential secrecy (required_inference) The iPaymu VA and API key must be stored server-side and never transmitted to or rendered in any seller-facing surface. Provider calls are made server-side. Rationale: indispensable to keep the provider origin undisclosed per NFR-01.

NFR-05 — Durable state (required_inference) Seller balance, top-up history, withdrawal history, and provider configuration must persist across sessions and be bound to the correct account. Rationale: indispensable for the accepted top-up, QRIS, withdrawal, and provider-configuration lifecycles to be usable.

NFR-06 — Access control (required_inference) Top Up, QRIS, and Withdraw are restricted to the verified Seller (Merchant). Provider Settings is restricted to the verified Payyo QRIS Operator/Admin. A seller cannot reach Provider Settings. Rationale: indispensable to keep provider credentials and seller money state bound to the correct participant.

NFR-07 — Readable text and controls at every viewport (explicit, from the creative direction) Headlines, wordmarks, labels, numbers, cards' text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration, and motion may be cropped, bled off an edge, rotated, overlapped, or cut as the direction asks, as long as they cover no readable text or control.

NFR-08 — Reduced motion (explicit, from the creative direction) With prefers-reduced-motion, all transforms are removed and only opacity fades remain, providing a usable static arrangement.

NFR-09 — No gradients (explicit, from the creative direction) No gradients anywhere in the interface.

10. Tech Stack

• Frontend: React web application, styled to the creative direction (Alfa Slab One + Oswald, 0px radius, 2px ink borders, 3px ink borders with 2px offset ink shadows on slab buttons, no gradients).
• Backend: Python / FastAPI, extended with routes and modules for seller accounts, balance and top-up, QRIS provisioning, withdrawal, and provider configuration. The iPaymu integration is a server-side module inside this backend.
• Storage: a persistent relational store for seller accounts, balances, top-up and withdrawal history, and provider configuration.
• Deployment: Docker / docker-compose for the frontend and backend services.

No separate queue worker, additional container, or Kubernetes deployment is required by the accepted behavior.

11. Assumptions and Constraints

Assumptions

• [Assumption — required_inference] Seller identity is application-owned: sellers self-enroll through free registration and verify on return, because they must privately own and resume a durable balance, QRIS display, and withdrawal history.
• [Assumption — required_inference] Operator/admin access is provisioned by the platform owner before provider credentials can be configured, because no self-service operator enrollment was accepted.
• [Assumption — required_inference] The owner-supplied iPaymu VA and API key are valid and sufficient for iPaymu to return a QRIS for a seller; Payyo QRIS does not manage iPaymu-side onboarding.
• [Assumption — required_inference] Withdrawal destination details (e-wallet or bank account) are entered by the seller on Withdraw; no pre-saved destination book was accepted.
• [Assumption — required_inference] Top-up and withdrawal may settle asynchronously, so a pending state is shown and resolves to settled.

Constraints

• The QRIS shown to sellers must not be disclosed as originating from iPaymu. This applies to all seller-facing surfaces and all states.
• Seller registration is free.
• Payyo QRIS uses the owner-supplied iPaymu VA and API key for QRIS provisioning.
• The generic indigo/blue-on-white SaaS template is forbidden for this project.
• No adjacent account-management, KYC, dispute, refund, settlement-reporting, or multi-user team capabilities are in scope.

Presentation and technology defaults

• [Default — not specified by user] Relational storage choice and its schema details.
• [Default — not specified by user] Exact session lifetime and credential complexity rules.
• [Default — not specified by user] Exact top-up and withdrawal settlement timing.

12. Glossary

• Payyo QRIS — the QRIS merchant payment provider product described in this document; the brand under which the QRIS is presented to sellers.
• QRIS — the Indonesian national QR code standard for merchant payments.
• Seller (Merchant) — the accepted human persona who registers free, tops up balance, displays QRIS to collect payment, and withdraws balance to an e-wallet or a bank.
• Payyo QRIS Operator/Admin — the accepted internal human persona who configures the owner-supplied iPaymu VA and API key and keeps seller QRIS provisioning working.
• iPaymu — the external provider that supplies the QRIS and whose VA and API key are owner-supplied. Its origin must never be disclosed to sellers.
• VA (Virtual Account) — the owner-supplied iPaymu virtual account identifier used with the API key for QRIS provisioning.
• API key — the owner-supplied iPaymu credential used server-side for QRIS provisioning.
• Top Up — the seller action of adding funds to the Payyo QRIS account balance.
• Withdraw — the seller action of moving balance out to an e-wallet or a bank.
• Provider Settings — the operator/admin-restricted surface for configuring the owner-supplied iPaymu VA and API key.
• Viewfinder — the white square QRIS display frame with corner tick marks inside a solid denim block, presenting the code as an instrument readout.