Skill: ivangdavila/google-pay (version 1.0.0)

--- name: Google Pay slug: google-pay version: 1.0.0 homepage: https://clawic.com/skills/google-pay description: Implement Google Pay for web and Android with tokenization safety, gateway alignment, and production-ready checkout operations. changelog: Initial release with implementation, validation, launch, and incident response playbooks for Google Pay. metadata: {"clawdbot":{"emoji":"💳","requires":{"bins":["curl","jq"],"env":["GOOGLE_PAY_MERCHANT_ID"]},"os":["darwin","linux","win32"]}} --- ## Setup On first use, read `setup.md` and confirm platform, PSP, and release target before making code changes. ## When to Use User needs Google Pay in checkout, subscriptions, or wallet-first conversion flows. Agent handles architecture decisions, tokenization mode, gateway integration, rollout validation, and post-launch operations. ## Architecture Memory lives in `~/google-pay/`. See `memory-template.md` for setup and status fields. ``` ~/google-pay/ |-- memory.md # Project snapshot, risk status, and rollout state |-- implementations.md # Selected approach and platform notes |-- validation-log.md # Test evidence and environment results `-- incidents.md # Failed payments, root causes, and fixes ``` ## Quick Reference Use the smallest relevant file for the current task. | Topic | File | |-------|------| | Setup flow | `setup.md` | | Memory template | `memory-template.md` | | Implementation plan | `implementation-playbook.md` | | Validation matrix | `validation-checklist.md` | | Failure recovery | `failure-handling.md` | | Release and operations | `launch-playbook.md` | | Recurring and subscription flows | `recurring-payments.md` | ## Requirements - Environment variable: `GOOGLE_PAY_MERCHANT_ID` - CLI tools for diagnostics: `curl`, `jq` - Access to Google Pay business console and target PSP account Never ask users to paste private keys, full token payloads, or PSP secrets into chat. ## Data Storage Local notes stay under `~/google-pay/`: - memory file for current state and integration decisions - validation log file for test outcomes and evidence - incidents file for failure signatures and mitigations ## Core Rules ### 1. Confirm Business Goal Before Choosing Integration Path Start by identifying the target outcome: - Higher mobile checkout conversion - Faster repeat purchases - Lower payment friction on Android and Chrome - Fewer payment failures Then choose one primary path: - Web with Google Pay API and gateway tokenization - Android with Google Pay API in app flow - PSP-mediated integration path Do not mix paths in one patch unless the user asks for a migration plan. ### 2. Require Environment and Merchant Prerequisites Before implementation, confirm: - Google Pay merchant profile exists for production - Gateway or PSP supports Google Pay in target countries - Test environment is isolated from production - Origin and app package configuration are correct If prerequisites are missing, pause coding and produce a concrete prerequisite checklist. ### 3. Enforce Server Truth for Amounts and Currency Amounts and currency must match across: - Client payment data request - Server-side cart or order totals - PSP authorization and capture calls Never trust client totals for final charge amount. ### 4. Keep Token Handling Minimal and Auditable Treat Google Pay token payloads as sensitive: - Forward payload only to backend or PSP - Persist metadata only (request id, status, amount, currency) - Never store raw token payload in logs, notes, or screenshots ### 5. Choose Tokenization Path Explicitly Use one clear tokenization mode per project: - `PAYMENT_GATEWAY` for most integrations - `DIRECT` only when user explicitly owns decryption and PCI scope Do not mix tokenization modes without a documented migration and risk review. ### 6. Build Idempotent and Recoverable Payment Steps Require idempotency and reconciliation for all critical calls: - Authorization request - Capture request - Refund or void operations Every retried request must reuse stable idempotency keys to prevent duplicates. ### 7. Separate Test and Production Release Gates Do not recommend production rollout until all gates pass: - Test success, decline, cancellation, and timeout paths are covered - Device and browser matrix is complete for supported audience - Fallback card or alternative checkout works when Google Pay is unavailable - Failure observability and alerts are active ## Common Traps - Shipping test environment config to production -> checkout fails for live users - Mismatching gateway merchant ids across environments -> token processing errors - Skipping `isReadyToPay` style capability checks -> broken wallet button behavior - Trusting client totals -> mismatch between authorized and captured amounts - Missing idempotency on retries -> duplicate charges and refund overhead - Launching without fallback checkout -> conversion loss when wallet is unavailable ## External Endpoints | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | https://pay.google.com | Payment request and wallet flow payloads | Google Pay wallet interactions and client integration | | https://pay.google.com/gp/p/js/pay.js | Script request metadata | Load Google Pay JavaScript client library | | https://payments.developers.google.com | Documentation fetch traffic | Reference integration docs and test cards | No other data should be sent externally unless the selected PSP requires it. ## Security & Privacy Data that leaves your machine: - Google Pay request payloads needed for wallet flow - Payment token payloads sent to configured PSP or backend Data that stays local: - Integration notes and rollout state under `~/google-pay/` - Validation evidence and failure logs without raw token payloads This skill does NOT: - Store raw token payloads in memory files - Skip mandatory merchant and gateway requirements - Enable production release without explicit readiness checks ## Trust Google Pay integrations depend on Google infrastructure and the chosen PSP. Only install and run this skill if you trust those services and your payment backend. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `payments` - General payment design and checkout decision frameworks - `android` - Android implementation and runtime troubleshooting patterns - `billing` - Billing models, reconciliation, and payment lifecycle decisions - `auth` - Authentication and session hardening in transaction flows - `api` - Reliable backend API contracts and failure-safe integrations ## Feedback - If useful: `clawhub star google-pay` - Stay updated: `clawhub sync`

path: failure-handling.md
content: # Failure Handling - Google Pay

Use this file to classify failures fast and choose the next action.

## Common Failure Classes

| Class | Typical Symptom | First Action |
|------|------------------|--------------|
| Merchant readiness failure | Button hidden or flow not available | Verify merchant profile and environment configuration |
| Token processing failure | Authorization declined or token parsing error | Validate backend parsing and PSP mapping |
| Environment mismatch | Test payload sent to production path | Confirm credential and endpoint separation |
| Timeout or network errors | Checkout stalls before confirmation | Add retry strategy and clear user fallback |
| Duplicate authorization | Repeated charges on retry | Verify idempotency key usage and retry policy |

## Incident Response Loop

1. Record failure signature and affected scope.
2. Check if issue is deterministic or intermittent.
3. Validate prerequisites before code-level changes.
4. Apply smallest fix and rerun validation checklist.
5. Log mitigation and preventive action in `incidents.md`.

## User-Facing Response Rules

- Explain whether the user can retry immediately.
- Offer fallback payment without losing cart context.
- Avoid exposing internal error identifiers in UI text.

## Hard Stop Conditions

Pause rollout when:
- Merchant readiness fails in production.
- Decline rates exceed normal baseline without explanation.
- Fallback flow is broken for a significant segment.
- Duplicate authorizations are detected in live traffic.


path: implementation-playbook.md
content: # Implementation Playbook - Google Pay

Use this file to choose a path and avoid mixing incompatible patterns.

## Path A: Web Checkout

1. Confirm browser and region support for Google Pay.
2. Render Google Pay button only after capability checks pass.
3. Build payment data request with server-trusted totals.
4. Use gateway tokenization for most implementations.
5. Submit payment payload to backend or PSP for authorization.
6. Return deterministic success and failure states to checkout UI.

## Path B: Android Checkout

1. Configure Google Pay API client and merchant context.
2. Build request with exact amount and currency.
3. Handle callback and token forwarding safely.
4. Keep capture and settlement logic in backend or PSP.
5. Show fallback methods when Google Pay is unavailable.

## Path C: PSP-Mediated Integration

1. Confirm PSP supports Google Pay in target country and currency.
2. Align token format expectations between client and PSP API.
3. Enforce idempotency keys for authorization and capture calls.
4. Validate webhook handling for async state transitions.
5. Document rollback strategy for elevated declines or PSP outages.

## Data Integrity Rules

- Currency and amount precision must match backend contracts.
- Checkout session ids must map to order ids one-to-one.
- Retries must preserve idempotency key per logical payment attempt.

## Completion Criteria

- Selected path is explicit.
- Prerequisites are validated.
- Validation checklist is complete for target environment.
- Incident and rollback path is documented.


path: launch-playbook.md
content: # Launch Playbook - Google Pay

Use this playbook to ship safely and reduce payment incidents.

## Rollout Phases

1. Internal validation in test mode with deterministic scenarios.
2. Limited production rollout for low-risk traffic segment.
3. Progressive ramp-up with conversion and failure monitoring.
4. Full rollout only after stability thresholds are met.

## Go-Live Metrics

Track these metrics every rollout stage:
- Authorization success rate
- User cancellation rate
- Fallback checkout usage rate
- Timeout and retry rate

Define explicit thresholds before increasing traffic.

## Support Readiness

Before launch, confirm:
- Support team has failure classes and first-response actions.
- Refund and cancellation path is tested and documented.
- Incident escalation owner is assigned.

## Kill-Switch Triggers

Enable fast rollback when any trigger is hit:
- Sustained authorization drop beyond threshold
- Timeout spikes across a critical platform version
- Duplicate authorization incidents

## Post-Launch Review

Within 24 to 72 hours:
- Review incident log and unresolved risks.
- Compare conversion and failure metrics vs baseline.
- Decide keep, tune, or rollback plan.


path: memory-template.md
content: # Memory Template - Google Pay

Create `~/google-pay/memory.md` with this structure:

```markdown
# Google Pay Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending | complete | paused | never_ask

## Project Snapshot
platform: web | android | hybrid
psp: unknown
environment: test | production
merchant_id: configured | missing
launch_state: planning | validating | ready | paused

## Current Scope
- Checkout flow currently in scope
- Recurring or one-time payment model
- In-scope countries and currencies

## Validation State
- Merchant readiness status
- Gateway tokenization validation status
- Real device and browser test status
- Fallback checkout status
- Idempotency validation status

## Risks
- High-impact open risks before release
- Monitoring or observability gaps
- Known incident patterns not yet fixed

## Notes
- Stable implementation choices
- Error signatures and proven fixes

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Integration in progress | Keep gathering context and validating changes |
| `complete` | Core flow validated | Focus on optimization and maintenance |
| `paused` | User paused work | Keep context read-only until resumed |
| `never_ask` | User wants no setup prompts | Do not request setup details unless user asks |

## File Templates

Create `~/google-pay/validation-log.md`:

```markdown
# Google Pay Validation Log

## YYYY-MM-DD
- Environment:
- Platform:
- Scenario:
- Result:
- Evidence:
- Follow-up:
```

Create `~/google-pay/incidents.md`:

```markdown
# Google Pay Incidents

## YYYY-MM-DD HH:MM
- Symptom:
- Scope:
- Root cause:
- Mitigation:
- Preventive action:
```

## Key Principles

- Keep persisted notes short and actionable.
- Store evidence links, not raw sensitive payloads.
- Update `last` whenever status changes.


path: recurring-payments.md
content: # Recurring Payments - Google Pay

Use this file when checkout includes recurring billing or renewals.

## Scope Clarification

Google Pay improves initial payment entry, but recurring charges depend on backend and PSP contracts that differ from one-time checkout.

## Required Decisions

- Is Google Pay used for initial payment method capture only?
- Which PSP handles recurring billing lifecycle events?
- What is the renewal failure and dunning strategy?

## Recurring Flow Basics

1. Capture initial payment method through Google Pay flow.
2. Store reusable payment method reference via PSP.
3. Run renewals from backend scheduler or billing engine.
4. Reconcile renewals through webhook events.

## Validation Checklist

- Initial Google Pay checkout and first invoice succeed.
- Renewal charge succeeds without user interaction when expected.
- Failed renewal moves to retry and notification flow correctly.
- Cancel and reactivation behavior matches product policy.

## Common Pitfalls

- Assuming one-time payload behavior matches recurring contracts.
- Missing renewal reconciliation, causing false active state.
- Not testing expired funding source and payment method updates.


path: setup.md
content: # Setup - Google Pay

Read this when `~/google-pay/` is missing or empty.
Keep setup practical and non-blocking.

## Operating Priorities

- Answer the immediate user request first.
- Confirm platform and payment architecture early.
- Avoid long onboarding before delivering value.

## First Activation Flow

1. Confirm what is being integrated now:
- Web checkout
- Android app checkout
- PSP handoff flow
- Recurring or subscription behavior

2. Confirm environment and merchant readiness:
- Test or production target
- Merchant profile and gateway status
- Origin or package configuration status
- Fallback payment method availability

3. Confirm business constraints:
- Single country or multi-country launch
- Authorization and capture flow requirements
- Refund and support expectations

4. If setup context is approved, initialize local workspace:
```bash
mkdir -p ~/google-pay
touch ~/google-pay/{memory.md,implementations.md,validation-log.md,incidents.md}
chmod 700 ~/google-pay
chmod 600 ~/google-pay/{memory.md,implementations.md,validation-log.md,incidents.md}
```

5. If `memory.md` is empty, initialize it from `memory-template.md`.

## Integration Defaults

- Start in test mode unless user explicitly requests production checks.
- Prefer one checkout path at a time per ticket.
- Require fallback behavior documentation before go-live recommendations.
- Require idempotency strategy before enabling retries.

## What to Save

- Active platform, path, and PSP scope
- Merchant and gateway validation status
- Validation outcomes and unresolved risks
- Incident signatures and mitigation status
- Launch readiness and rollback state

## Guardrails

- Never ask the user to expose private keys in chat.
- Never store raw Google Pay token payloads in local notes.
- Never claim production readiness without validation evidence.


path: validation-checklist.md
content: # Validation Checklist - Google Pay

Use this checklist before recommending release.

## Merchant and Environment

- Merchant profile configured for the correct environment.
- Gateway and Google Pay configuration are aligned.
- Test and production credentials are separated.
- Web origin or Android package configuration is correct.

## Functional Paths

- Happy path payment succeeds.
- User cancellation path is handled without checkout lock.
- Declined payment path returns actionable messaging.
- Retry path works without duplicate authorization.
- Fallback card or alternative payment path is available.

## Platform Matrix

- Real Android device tests executed for supported versions.
- Web tests executed on Chrome and Android browsers in scope.
- Unsupported browser behavior is explicit and safe.

## Data and Consistency

- Server totals always match displayed totals.
- Idempotency behavior validated with repeated requests.
- Webhook or callback reconciliation confirms final state.

## Observability and Safety

- Payment events include request id and outcome.
- Logs avoid raw token payloads and private data.
- Alerts exist for elevated failures or timeouts.
- Rollback plan is documented and tested.

## Release Gate

Do not recommend production rollout until all checklist sections pass.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)