Repository navigation
docs operations payments
Stripe cards, Asaas conventional Pix and Pix Automático run disabled by default. This runbook covers everything beyond pasting API keys: catalog, webhook registration, events, API versions, merchant identity, eligibility, notifications, fiscal boundaries, preflight, rotation, channel-disable, queue recovery, backup/restore and bounded tests. Production prices, live modes and any real charge stay separately gated (PAY-21 commercial acceptance); inserting secrets never activates them.
- Copy
infra/env.staging.exampleto the staging env file and fill theREPLACE_ME_*placeholders with test-mode credentials only (sk_test_*/rk_test_*,whsec_*,acct_*,price_*for Stripe; sandbox API key, distinct webhook token, merchant UUID for Asaas). - Catalog:
ANPFUEL_PAYMENTS_CATALOG_VERSIONstayspay-catalog-v1. Production prices are unresolved (PAY-01): no offer is sellable and checkout refuses with unknown-offer until the commercial catalog lands. - Return origin: public
https://origin of the billing return pages (card checkout requires it; loopbackhttp://is dev-only). - Stripe Dashboard: register the webhook endpoint
https://<host>/v1/payments/stripe/webhookfor the pinned API version2026-09-30.endive, test mode, with invoice, subscription, checkout and dispute events; copy the signing secret (whsec_*). Restrict the API key to the account (acct_*merchant must match). - Asaas: register
https://<host>/v1/payments/asaas/webhookwith a dedicated webhook token (32+ characters, never the API key); the handler additionally accepts the previous token during rotation. Merchant UUID must match the account. TLS is mandatory at the edge. - Portal (optional): create a customer-portal configuration and set
ANPFUEL_STRIPE_PORTAL_CONFIGURATION_ID(bpc_*). Empty keeps the portal unavailable without affecting anything else. - Pix Automático: merchant eligibility is an external Asaas gate; the
service stays unavailable (
MerchantEligiblefalse) until the authorized eligibility proof lands. Conventional Pix needs no eligibility. - Notifications: provider email/SMS/WhatsApp and application notifications are configured explicitly and never duplicated automatically; Asaas customers are created with notifications disabled.
- Fiscal: provider invoices/receipts are billing references only. No tax engine, fiscal document or CNPJ flow exists — fiscal issuance is a named owner workflow, not a code path.
Startup logs a redacted preflight (api.payments): per channel,
maintenance/new-sales readiness plus blocking reasons
(disabled-by-flag, provider-not-configured, mode-mismatch,
missing-credentials, missing-return-origin, missing-catalog,
maintenance-disabled, invalid-configuration). Preflight performs no
writes and creates no provider resources. Release criteria:
- Every channel reports a reason (never silently ready).
- Test/staging shows
testmodes only;live/productionmodes refuse outside production (mode-mismatch). -
NewSalesReadyis false on every channel until sandbox proof.
- Stripe webhook secret: rotate in the Dashboard, run both secrets through the overlap window (the verifier accepts old+new signatures), then retire the old one. Old-only signatures are refused.
- Asaas webhook token: set the new token while keeping the previous one configured; the handler accepts either during overlap, then clear the previous value. The API key is never accepted as the webhook token.
- API keys (
sk_*/rk_*, Asaas key): replace, restart API/worker, confirm preflight stays ready and the old key is revoked at the provider. Rotation never drops durable inbox rows or paid-through access.
Set <channel>_MAINTENANCE_ENABLED=false and restart. The channel goes
dark: webhook intake answers 503, providers stay unbuilt, inbox rows stay
pending, refunds/switches/portal for that channel refuse. Already-granted
access, free reads and the sibling channel are unaffected. Re-enable by
flipping the flag back; pending rows drain on the next worker tick. Sales
switches (*_NEW_SALES_ENABLED) only stop new checkout and never strand
existing subscriptions.
-
payment-inboxjobs are wake-ups: the router drains bounded pending rows per configured channel. Missed, reordered or duplicate deliveries converge through the same drain — never per-read provider polling. - Unknown authenticated events are retained minimally with no effect;
conflicting deliveries are marked
CONFLICT, never reprocessed. - Stuck
PENDINGrows: inspectpayment_inbox(state,attempts,last_error,received_at); fix the blocking cause (credentials, mode, provider outage), then wait for the next tick. Never mark rows processed by hand and never delete them: deletion destroys the exactly-once guards. - Dead letters follow the standard job policy (bounded retries with backoff, then park for audited replay).
- Financial tables (
payment_*) ride the standard encrypted backup (backup.md) with the same RPO/RTO; billing exits and operator actions are retained across account erasure by policy. - Restore into an isolated database first: stale outbox/operation rows cannot replay a charge or refund (lease, generation and idempotency fences), and replayed settlement or refund intents converge without a second provider write.
- Rollback is forward-only: no destructive migration exists in the payment range. Restoring an older binary over newer rows is refused by the migration ledger; roll forward instead.
- After restore, reconcile each channel (drain + settlement/refund reconcile paths) before opening the edge.
- Never load-test provider public endpoints and never simulate sandbox cases in production.
- Synthetic journeys run against disposable PostGIS with fixture verifiers; provider business logic (fees, MED names, retry windows) is proven only with real sandbox accounts (PAY-21).
- Callback budget reference (disposable PostGIS, PAY-18): 200 intakes total 174.76 ms, mean 873.80 µs, p95 1.12 ms; hot inbox/grants/orders queries use indexes with no sequential scan.
Checkout/admission/error rates, provider latency/429/outage, ambiguous writes, financial/access mismatch census, oldest inbox/job age, dead letters, webhook rejections/retries, mandate eligibility, pending refunds, unknown disputes and last reconciliation success. Logs carry correlation IDs, codes and counts only — never payment URLs, QR data, tokens, signatures, CPF/CNPJ or customer email.
- Home
- Roadmap
- docs-README
- docs-android-build
- docs-android-design-system
- docs-android-forum
- docs-android-games
- docs-android-map-engine
- docs-android-navigation
- docs-android-ocr-image
- docs-android-ocr-live-framing
- docs-android-premium-area
- docs-android-premium-integration
- docs-android-release
- docs-android-ui-containers
- docs-architecture-android-stack
- docs-architecture-android
- docs-architecture-backend
- docs-architecture-data-sources
- docs-architecture-overview
- docs-architecture-sources-ev-research
- docs-architecture-sources-national-limits
- docs-architecture-sources-national-stations
- docs-architecture-sources-register
- docs-assets-app-tutorial-CAPTURE_CONTRACT
- docs-assets-app-tutorial-FABLE_LANDING_POLISH_PROMPT
- docs-assets-app-tutorial-README
- docs-assets-attribution
- docs-assets-brand-README
- docs-assets-flags-ATTRIBUTION
- docs-assets-fuel-icons-README
- docs-assets-games-fuel-v1-README
- docs-assets-home-icons-README
- docs-assets-landing-fleet-android-20261012-BRIEF
- docs-assets-landing-hero-20261011-BRIEF
- docs-assets-landing-illustrated-20261012-BRIEF
- docs-assets-landing-illustrated-20261012-README
- docs-assets-landing-minimal-20261012-BRIEF
- docs-assets-landing-open-data-20261026-BRIEF
- docs-assets-landing-redesign-20261011-PREPARATION_EVIDENCE
- docs-assets-landing-redesign-20261011-README
- docs-assets-landing-redesign-20261011-REFERENCE_BRIEF
- docs-assets-landing-sync-20261012-BRIEF
- docs-assets-map-icons-README
- docs-backend-anp-ingestion
- docs-backend-api
- docs-backend-community-pricing
- docs-backend-data-model
- docs-backend-domain-model
- docs-backend-driver-private-data
- docs-backend-forum-architecture
- docs-backend-forum-bulletins
- docs-backend-forum-sources
- docs-backend-payments-provider-admission
- docs-backend-payments-provider-register
- docs-backend-photos-capture
- docs-backend-photos-subset-submission
- docs-backend-premium-api
- docs-backend-premium-cloud-protocol
- docs-backend-testing
- docs-backend-toolchain
- docs-brand-app-icons
- docs-brand-identity
- docs-decisions-001-kotlin-compose-stack
- docs-decisions-002-price-import-immutability
- docs-decisions-003-nominatim-reverse-geocode
- docs-decisions-005-modular-monolith-and-postgresql
- docs-decisions-006-official-catalog-and-exact-contracts
- docs-decisions-007-anonymous-proof-of-possession
- docs-decisions-008-privacy-and-retention
- docs-decisions-009-community-consensus-and-projections
- docs-decisions-010-private-object-evidence
- docs-decisions-012-licensing-and-hosted-business
- docs-decisions-015-kotlin-multiplatform-shared-domain
- docs-decisions-016-android-commercial-community-ios-deferred
- docs-decisions-017-station-profile-and-verified-representation
- docs-decisions-021-community-first-contribution
- docs-decisions-022-comaps-derived-native-map-engine
- docs-decisions-023-admin-suite-granted-tiers-contributors
- docs-decisions-025-private-abastevo-empresas-organization-boundary
- docs-decisions-026-multilingual-public-site
- docs-decisions-README
- docs-enterprise-README
- docs-enterprise-architecture
- docs-enterprise-backlog-INDEX
- docs-enterprise-backlog-ep00-governance
- docs-enterprise-backlog-ep01-platform
- docs-enterprise-backlog-ep02-organizations
- docs-enterprise-backlog-ep03-identity-access
- docs-enterprise-backlog-ep04-sync
- docs-enterprise-backlog-ep05-fleet-meters
- docs-enterprise-backlog-ep06-trips
- docs-enterprise-backlog-ep07-gps-navigation
- docs-enterprise-backlog-ep08-fuelings
- docs-enterprise-backlog-ep09-documents
- docs-enterprise-backlog-ep10-expenses-finance
- docs-enterprise-backlog-ep11-maintenance
- docs-enterprise-backlog-ep12-fuel-stock
- docs-enterprise-backlog-ep13-intelligence
- docs-enterprise-backlog-ep14-station-claims
- docs-enterprise-backlog-ep15-station-commerce
- docs-enterprise-backlog-ep16-subscriptions
- docs-enterprise-backlog-ep17-data
- docs-enterprise-backlog-ep18-imports-notifications-integrations
- docs-enterprise-backlog-ep19-back-office
- docs-enterprise-backlog-ep20-release
- docs-enterprise-business-rules
- docs-enterprise-contract
- docs-enterprise-conventions
- docs-enterprise-data-offering
- docs-enterprise-decisions
- docs-enterprise-domain-model
- docs-enterprise-glossary
- docs-enterprise-journeys
- docs-enterprise-modules-back-office
- docs-enterprise-modules-data
- docs-enterprise-modules-documents
- docs-enterprise-modules-expenses-finance
- docs-enterprise-modules-fleet
- docs-enterprise-modules-fuel-stock
- docs-enterprise-modules-fuelings
- docs-enterprise-modules-gps-navigation
- docs-enterprise-modules-identity
- docs-enterprise-modules-imports-notifications-integrations
- docs-enterprise-modules-intelligence
- docs-enterprise-modules-maintenance
- docs-enterprise-modules-organizations
- docs-enterprise-modules-station-claims
- docs-enterprise-modules-station-commerce
- docs-enterprise-modules-subscriptions
- docs-enterprise-modules-trips
- docs-enterprise-offline-sync
- docs-enterprise-permissions
- docs-enterprise-portal-routes
- docs-enterprise-privacy-security
- docs-enterprise-product-vision
- docs-enterprise-source-admission
- docs-enterprise-state-model
- docs-enterprise-testing
- docs-enterprise-ux-app
- docs-enterprise-ux-web
- docs-operations-README
- docs-operations-backup
- docs-operations-deploy-agent
- docs-operations-dou-editions
- docs-operations-edge-cache
- docs-operations-enterprise-activation
- docs-operations-map-static-overlay
- docs-operations-moderation-feedback
- docs-operations-moderation-profiles
- docs-operations-monitoring
- docs-operations-operator-access
- docs-operations-payments
- docs-operations-premium-billing
- docs-operations-recovery
- docs-operations-registry-daily-sync
- docs-operations-registry-runs
- docs-product-README
- docs-product-admin-tiers
- docs-product-community-community-first
- docs-product-community-experience
- docs-product-community-metrics
- docs-product-community-moderation
- docs-product-community-safety
- docs-product-community-terms-pt-br
- docs-product-driver-suite-README
- docs-product-driver-suite-android-state
- docs-product-driver-suite-cloud-sync
- docs-product-driver-suite-cost-profiles-and-maintenance
- docs-product-driver-suite-driver-model-and-earnings
- docs-product-driver-suite-foundation-decisions
- docs-product-driver-suite-gps-lifecycle
- docs-product-driver-suite-mobile-hub
- docs-product-driver-suite-odometer-review
- docs-product-driver-suite-outbox-wire
- docs-product-driver-suite-quick-refuel
- docs-product-driver-suite-reports
- docs-product-driver-suite-shifts-and-distance
- docs-product-driver-suite-signed-commands
- docs-product-ev-README
- docs-product-ev-charging-stop-planner
- docs-product-ev-energy-model
- docs-product-ev-financial-method
- docs-product-ev-journey-ui
- docs-product-ev-preparation
- docs-product-ev-typed-data
- docs-product-exploration
- docs-product-forum-contract
- docs-product-forum-policies
- docs-product-glossary
- docs-product-landing-content
- docs-product-landing-guides
- docs-product-landing-organic-growth-i18n-plan
- docs-product-licensing
- docs-product-map-discovery
- docs-product-map-favorites-and-trips
- docs-product-map-reports-routing-guidance
- docs-product-notification-content
- docs-product-official-prices
- docs-product-open-source-business
- docs-product-overview
- docs-product-payments-README
- docs-product-payments-offer-policy
- docs-product-premium-README
- docs-product-premium-financial-method
- docs-product-premium-source-policy
- docs-product-stations-catalog
- docs-product-stations-fuel-feedback
- docs-product-stations-fuel-quality
- docs-product-stations-identity-and-ev-catalog
- docs-product-stations-profile-contract
- docs-product-stations-profile-representation
- docs-product-stations-registry-sources
- docs-product-vehicle-registration
- docs-product-vehicles-and-occurrences
- docs-security-android-terms-acceptance
- docs-security-free-account-access
- docs-security-identity-profile
- docs-security-media-location-policy
- docs-security-privacy-notice
- docs-security-privacy-policy
- docs-security-retention
- docs-security-risks
- docs-security-security-privacy
- docs-store-README
- docs-store-play-readiness
- docs-store-play-store-listing
- docs-store-ugc-safety
Source: AlexandreZanata/Abastevo @ e4a67580fc368a59bc1c0f1e0466fc011313f330