Payment platform readiness

Payment Platform Readiness

Use this skill to make payments reliable, compliant, supportable, replayable, and product-friendly across app stores, web checkout, wallets, subscriptions, refunds, disputes, promos, and entitlement systems.

Composition contract

Own provider authority/readback, ingestion, money ledger, entitlement projection, settlement, reconciliation, and finance-close facts. In particular, this artifact owns whether a provider-confirmed refund, revocation, dispute, or chargeback event occurred and how it projects into ledger/entitlement truth. refund-and-support-flow-review consumes that authority and owns customer messaging, grace, repayment, restrictions, appeal, and account consequences.

For every artifact, record artifactVersion, artifactRevision, and artifactState; never put artifactDigest on the top-level artifact. Use the shared product artifact envelope for structured drafts and sealed artifacts. Consume product, pricing, catalog, tax, and release inputs through input references. A sealed input additionally requires artifactDigest and digestRule: sha256-exact-bytes; every input requires fulfillsHandoffId, while a draft contains no digest fields. Emit payment, entitlement, refund-authority, support, and finance handoffs without copying sibling facts.

Workflow

1. Identify payment channel, product type, billing model, provider identifiers, catalog mapping, entitlement semantics, refund/dispute policy, settlement/fee model, support surfaces, and reconciliation owner.
2. Read references/payment-platform-patterns.md; load references/billing-reconciliation-patterns.md when settlement, finance close, or cross-system reconciliation is in scope.
3. Map catalog, checkout, receipt/webhook processing, idempotent ledger ingestion, entitlement projection, refund/revoke/dispute handling, support corrections, settlement, and reconciliation.
4. Define provider-specific precedence for Apple IAP, Google Play Billing, Stripe/web checkout, wallets, promo/admin grants, restore purchases, renewals, refunds, chargebacks, and delayed events.
5. Check platform-specific constraints, sandbox/live separation, fallback paths, customer messaging, finance close, and operational rollback.
6. For outages or backlogs, define explicit ingestion states: paused, quarantined, deduplicated, ordered by provider effective time, replaying, projector-repaired, finance-reconciled, and resumed.
7. For invoice/tax/finance-close launches, model invoice, tax, coupon, credit note, refund, dispute, fee, settlement, revenue export, entitlement, dunning, and manual adjustment as separate events with owners and exception queues.
8. For finance close, name numeric tolerances, cadence, owner, source systems, exception queue, and close blocker for every money/tax/settlement/revenue check.
9. Produce payment state model, ledger schema, event precedence rules, reconciliation plan, support tooling, blockers, observability dashboards, rollback controls, and launch checklist.

When not to use

• Use saas-subscription-pricing when the primary decision is packaging, price, value metric, or commercial experimentation.
• Use marketplace-payouts-review when the primary authority is seller/creator earnings, holds, reserves, and payout.
• Use refund-and-support-flow-review for a refund/chargeback/restore support state machine that does not require redesigning the payment platform.

Source verification

• Verify current Apple, Google, wallet, processor, tax, invoice, settlement, and dispute requirements from official sources at use.
• Record provider, API/policy version, jurisdiction, access date, and source URL for any requirement that can block money movement or customer access.
• Treat remembered numeric thresholds, fee schedules, review rules, and platform policies as unverified until read back from the authority.

Guardrails

• Do not grant durable value from client-only confirmation.
• Keep payment records, entitlement state, and support cases reconcilable.
• Do not use payment confusion as retention.
• Do not collapse refund, cancellation, revocation, dispute, chargeback, grace, billing retry, restore, promo, and manual adjustment into one generic state.
• Do not silently edit entitlements; append corrective ledger events and replay the projector.
• Do not make customer punishment, grace, repayment, appeal, or commerce-restriction policy here. Emit authoritative refund/entitlement facts to refund-and-support-flow-review.
• Do not let support agents change provider truth. Support corrections must be role-gated, reason-coded, expiring where appropriate, and auditable.
• Do not ship payments without fee, tax, settlement, invoice, refund, dispute, and entitlement reconciliation evidence.
• Do not call release gates complete unless every gate names the fixture, dashboard/alert, rollback or kill-switch path, owner, and approval evidence.
• Do not describe webhook replay as a generic queue drain; every replay state needs required evidence, ordering/idempotency rule, exit gate, dead-letter handling, customer/support impact, and incident-review artifact.

Output format

Artifact identity:
- schemaVersion / artifactId / productId / artifactKind / ownerSkill
- artifactVersion / artifactRevision / artifactState / inputArtifacts
- a sealed artifact does not self-hash; its exact-byte digest appears only in a downstream reference
- canonicalFactsOwned / handoffOutputs / assumptions / proofState / proofEvidence

Payment surfaces:
Billing model:
Authority boundary:

Readiness matrix:
- Catalog:
- Checkout:
- Confirmation and ledger:
- Entitlement projection:
- Refund/revoke/dispute:
- Support/reconciliation:

Payment and entitlement state model:
- <state> -> <provider evidence, internal projection, customer access, support note>

Provider precedence rules:
- <Apple/Google/Stripe/promo/admin/restore event> -> <idempotency key, effective timestamp, ledger event, entitlement effect>

Reconciliation and finance close:
- <money/settlement/tax/fee/entitlement check> -> <source, cadence, owner, exception action>
- Close control table -> check, source systems, cadence, numeric tolerance, owner, exception queue, close blocker
- Explicit close events -> invoice_created / tax_calculated / coupon_applied / credit_note_issued / payment_succeeded_or_failed / refund_or_dispute / fee_recorded / settlement_received / revenue_exported / entitlement_granted_or_revoked / dunning_started_or_exhausted / manual_adjustment

Support-safe correction flow:
- <case> -> lookup keys (account_id, user_id, invoice_id, payment_intent/charge, subscription, entitlement_id, tax document, support_case_id), evidence, allowed action, approval, ledger event, customer message

Webhook outage replay flow:
- Use a table: state, owner, required evidence, ordering/idempotency rule, dead-letter handling, exit gate, customer/support impact
- Include incident review: provider timeline, retry/dead-letter metrics, projector diff, false-revoke/over-grant disposition, finance exceptions, control fix, approval artifact

Blockers:
- <blocker>

Observability and rollback controls:
- <dashboard/alert> -> <signal, threshold, owner, runbook>
- <rollback/kill switch> -> <scope, trigger, customer impact, recovery proof>

Release gates:
- <gate> -> <test fixture, dashboard/alert, rollback or kill switch, owner approval>