Axiom

Appearance

Payments Diagnostics ​

Systematic troubleshooting for failure modes across the entire payments suite. The discipline skills cover how to do things right; this skill covers what's wrong when symptoms appear. Each branch maps a symptom to a root cause and points back at the discipline skill that fixes it.

Symptoms This Diagnoses ​

Use when you're experiencing:

  • No payment sheet appears, canMakePayments() returns false unexpectedly, or present()/begin() returns silently
  • Web sheet appears but merchant validation fails — the most common single web-integration blocker after domain verification
  • Sheet completes but PSP rejects authorization (decryption or production-key issues)
  • Tap to Pay button greyed, isSupported returns false, or the entitlement request is stuck in "Submitted" status
  • Tap to Pay never reaches readyForTap, or the first read after foreground hangs indefinitely
  • .pkpass file won't import — Wallet shows nothing, "invalid pass," or silently fails
  • Pass imports but APNs-pushed updates don't reach the device
  • Apple Pay payment succeeded with PKPaymentOrderDetails set but the order never appears in Wallet
  • Order added but subsequent fulfillment-status updates never arrive
  • App Review rejection citing 3.1.1, 3.1.2, 3.1.3, 3.2.1(vi), 3.2.2(iv), 4.9, or Apple Pay AUG
  • Sandbox transaction succeeds, production fails (or vice versa)

Example Prompts ​

Questions developers ask that this diagnostic answers:

  • "Why doesn't my Apple Pay button do anything?"
  • "Domain verification keeps failing — what am I missing?"
  • "My Tap to Pay entitlement has been Submitted for two weeks — what now?"
  • "My .pkpass won't import — Wallet just silently does nothing."
  • "Why doesn't my order appear in Wallet after the Apple Pay confirmation?"
  • "App Review rejected my app for using IAP for restaurant delivery — what do I switch to?"
  • "Why does my first tap after the app foregrounds hang?"
  • "Sandbox transactions work but production declines — what's wrong?"

Diagnostic Workflow ​

The skill organizes failure modes by symptom branch. Each branch covers the full surface and points at the discipline skill that prescribes the fix.

BranchHeadline cause
No payment sheet appearsCapability not enabled, profile stale, domain not verified, third-party browser using CSS button instead of JS SDK
Web merchant validation failsDomain not verified, wrong cert type (Merchant Identity vs Payment Processing), cert expired, validation called from browser, session inspected/modified, sandbox vs production endpoint mismatch
PSP rejects post-authWrong CSR uploaded for Payment Processing Cert, cert not activated after creation (the two-stage workflow's second stage skipped), production vs sandbox key mismatch, applicationData hash doesn't match
Tap to Pay entitlement stuckOrg vs individual account, distribution entitlement not re-requested, per-extension request missing, region mismatch; 7-business-day rule before opening an Apple Developer Support case
Tap to Pay never readyForTapprepare() not called on foreground (95% of cases), PSP token expired, reader created but events stream never emits
Wallet pass won't importMissing WWDR Intermediate cert (most common), wrong WWDR generation, manifest missing files, identifier mismatch, team mismatch, .DS_Store in bundle, expired cert, PEM/p12/DER format confusion, dates not ISO 8601
Pass updates don't arriveMalformed webServiceURL, token shorter than 16 chars, APNs cert confusion (use the Pass Type ID Cert, not a separate one), wrong push topic, updated pass not re-signed
Order won't addWrong cert (Order Type ID Cert vs Pass Type ID Cert vs Apple Pay Merchant Cert), order package not signed, PKPaymentOrderDetails set via init parameter, token too short, webServiceURL returns 4xx/5xx
Order updates don't arriveWrong APNs cert (use Order Type ID Cert), wrong push topic (= order type identifier), webServiceURL 4xx/5xx, updated package not re-signed
App Review rejection (payment-related)Wrong rail (IAP for physical goods or Apple Pay for digital content), AUG parity violation, AUG primary-option violation, custom button mimicking Apple Pay branding, Tap to Pay label for non-payment actions, donations collected by non-approved app
Sandbox vs productionSandbox transactions decline pre-fulfillment by design; production needs production keys plus activated certs

The skill includes a Quick-Reference Crisis Card for production triage — the probability-weighted first checks for each symptom (e.g. "Tap to Pay first-tap hangs → 95% chance prepare() not called on foreground"), plus the curl-test-first incident-response sequence for web merchant validation.

Released under the MIT License

Copyright © 2026 Charles Wiltgen • v3.5.2