Mena Payment Testing

COD Edge Cases

• Order cancellation before delivery: verify refund/void is not triggered (no payment was collected).
• Partial delivery: verify the system handles partial COD collection.
• Failed delivery attempt: verify the order can be rescheduled or cancelled.

Country Profile Verification

Verify packages/contracts/src/recipes.ts defines correct profiles for each target country:

For each country, verify:

• Currency code and symbol are correct in the country profile.
• Tax rate matches current legislation (rates change -- verify against latest).
• Gateway configuration references the correct payment provider.
• COD is available and positioned appropriately in the payment method list.

Stripe Integration with MENA Currencies

Currency Handling

• Zero-decimal currencies: KWD, BHD, OMR use 3 decimal places in display but Stripe treats amounts in the smallest unit. Verify conversion is correct.
• Amount conversion: all internal amounts should be in cents/smallest unit. Display formatting uses formatMoney() from the appropriate formatter.
• Currency symbol position: verify the symbol renders on the correct side per locale (Arabic typically puts the symbol after the number).

Gateway Credential Security

• Payment gateway credentials are stored as encrypted JSONB. Verify:
  • Credentials are never exposed in list endpoints (admin routes omit them).
  • Credentials are decrypted only at the point of use (payment processing).
  • The encryption/decryption mechanism handles key rotation.

Webhook Handling

• Return 200 on all requests: webhook endpoints must return HTTP 200 even when processing fails. Returning 4xx/5xx causes the gateway to retry, creating duplicate processing.
• Idempotency keys: verify every webhook event is processed with an idempotency key. Use inhouse_event_deliveries with atomic claim (INSERT ... ON CONFLICT DO NOTHING).
• Signature verification: verify webhook payloads are signature-verified. Missing signature + configured secret = reject. Never default to accepting unverified payloads.

Event Bridge Integration

Payment events must correctly flow through the event pipeline:

1. Domain event emission: when a payment is created/updated, verify InhouseCommerceService (or equivalent) calls emitEvent() to write to inhouse_domain_events.
2. Event bridge translation: verify DOMAIN_TO_BUSINESS_MAP (or the event bridge cron) translates payment domain events into business_events.
3. KPI display: verify the Run Hub displays payment KPIs correctly:
   • Revenue KPI reads from the correct source (business_events, not raw domain tables).
   • KPI values are in major units (display), not cents (storage). Verify the conversion.
   • Labels match data: a KPI card labeled "Revenue" must display revenue data, not order count. Trace: label -> component prop -> API field -> DB column -> bridge source.

Order State Machine

Verify state transitions are enforced by the service layer using {DOMAIN}_TRANSITIONS records from contracts:

PENDING -> CONFIRMED -> PROCESSING -> SHIPPED -> DELIVERED
              |                          |
              v                          v
           CANCELLED                  RETURNED

• Valid transitions only: attempting an invalid transition (e.g., PENDING -> DELIVERED) must be rejected by the service, not silently accepted.
• Transition validation in service, not routes: the route layer passes the desired status; the service validates against the transition map.
• Side effects after commit: activities, events, webhooks fire after successful DB write, never before.

Refund Flows

• Full refund: verify a completed payment can be fully refunded. Payment status transitions to refunded. Stripe refund API is called. Refund event is emitted.
• Partial refund: verify partial refund amount is tracked. Payment status shows partially_refunded with remaining amount.
• COD refund: COD orders that were paid on delivery can be refunded. Verify the flow handles this (it may require manual merchant action, not an automated gateway call).
• Refund idempotency: duplicate refund requests must not process twice.

KPI Accuracy Verification

For payment-related KPIs displayed in the Run Hub:

• Seed data path: verify test data follows the correct pipeline. If the dashboard reads from business_events (via event bridge), seeding data into inhouse_orders alone will not make it appear. Seed where the UI reads, not where the domain writes.
• Label-data match: for every KPI card, trace the full path: card label -> component prop -> API response field -> database column -> bridge/rollup source. Any mismatch is a trust-breaking bug.
• Empty state handling: a new project with no orders should show an appropriate empty state, not "0 revenue" or "$0.00" -- show nothing or "still tracking" to avoid faking certainty.

Report Format

## COD Flow
- [PASS/FAIL] COD is default payment method in checkout
- [PASS/FAIL] Order state machine transitions work correctly
- [PASS/FAIL] Payment collection on delivery updates status
- [FAIL] COD cancellation before delivery triggers erroneous refund event

## Country Profiles
- [FAIL] Egypt VAT rate is 14% in code but should be 14% -- PASS
- [FAIL] Kuwait country profile missing COD configuration

## Stripe Integration
- [PASS/FAIL] Webhook signature verification fails closed
- [PASS/FAIL] Idempotency prevents duplicate processing
- [FAIL] BHD amounts not converted correctly (3 decimal places)

## Event Bridge
- [FAIL] Payment events not appearing in business_events -- bridge cron not picking up event type "payment.completed"
- [PASS] Revenue KPI reads from correct source

## KPI Accuracy
- [FAIL] "Total Revenue" card displays order count, not revenue amount
  - Label: "Total Revenue"
  - Component prop: revenue
  - API field: orderCount  <-- MISMATCH

Every failure must include: what was expected, what was observed, and the specific file/table/field where the issue originates.