docs planning STRIPE_ASAAS_PROVIDER_REGISTER

Stripe and Asaas provider admission register

Status: PROVIDER_CONTRACTS_ADMITTED / ACCOUNT_PROOF_OWED. Date: 2026-10-24. Owner: payment plan, PAY-01/02/21.

PAY-02 froze the local provider contracts in provider admission v1, with synthetic fixtures for Stripe v87 and Asaas v3. Selected: Stripe Go v87.0.0/API 2026-09-30.endive and an Asaas v3 net/http client (no vendor Go SDK). No provider account, credential, actual webhook, eligibility or live transaction was configured/validated; account-specific proof remains PAY-21. Recheck before activation.

Primary public documentation was inspected in this conversation. Distinguish the documented contract above from availability in the maintainer's merchant account.

PAY-02 admission record

Item	Stripe	Asaas
Contract	API 2026-09-30.endive; hosted Checkout, Billing, Refunds, Disputes	REST v3; conventional Pix and Pix Automático
Client	github.com/stripe/stripe-go/v87 v87.0.0, stripe.NewClient + webhook	net/http thin client; no vendor Go SDK
License/toolchain	MIT; Go 1.24+	Go standard library; no new module
Auth	API key + SDK Stripe-Signature raw-body verification	access_token header; webhook asaas-access-token
Idempotency	Idempotency-Key, retained at least 24h; reconcile ambiguity	No provider key; externalReference/contractId correlation only
Cycle owner	Stripe subscription	Asaas provider-owned SUBSCRIPTION for Pix Automático
Current status	Local contract admitted; account/catalog/webhook proof owed	Local contract admitted; account/eligibility/sandbox proof owed

backend/go.mod/go.sum were not changed by PAY-02. Add the Stripe SDK at PAY-06 after a coordinated head and dependency/license/vulnerability review; Asaas needs no new module. All sale channels remain disabled.

Stripe card billing

• Checkout subscriptions is the selected hosted-payment direction. The documentation exposes multiple UI variants; the hosted variant could not be extracted fully in the planning browser. PAY-02 must inspect its exact applicable version and API reference. Restrict to admitted card payment methods; no raw card form or Connect/splits.
• Webhook security requires unmodified raw request bytes for signature verification. Pin event/API versions and account/ livemode expectations; test rotation, time tolerance, duplicates and disorder.
• Subscription events expose payment failure, action-required and lifecycle changes. Define which invoice/settlement facts fund a grant; do not grant merely because checkout completed, an invoice exists or an operator marked it paid manually.
• Idempotent requests describes provider key semantics and pruning after at least 24 hours for API v1. Local durable operation/cycle records must outlive remote dedupe. Reusing an old key after provider pruning is not proof of safe retry; reconcile uncertain writes.
• Subscription object documents provider lifecycle and collection modes. Do not flatten incomplete, past-due, active, paused collection, canceled and refunded into a single paid Boolean.

Admission record to finish: actual merchant/country/currency/account ownership, test/live scope, catalog Price IDs and intervals, webhook endpoint/events/version, API permissions and rotation, SCA/3DS/test cases, checkout/portal return origins, tax/notices/refund settings and rate-limit/retry behavior. SDK selection requires license, maintenance/security, Go-version compatibility and pinned dependency review. No fee, approval or availability claim is made here.

Asaas conventional Pix

• Charge reference and charge guidance define the provider resource. PAY-02 freezes supported amount/date/QR/status/expiry fields and actual settlement mapping for Pix; do not reuse card-only state semantics.
• Retries and idempotency directs checking uncertain outcomes before retrying. externalReference is a correlation field, not an assumed unique constraint or universal idempotency key. Persist and serialize intent, search/reconcile, and quarantine ambiguous creation when remote absence cannot be proved safely. Verify each write endpoint.
• Webhook receipt uses an authToken sent as asaas-access-token; it must differ from the API key. Persist before HTTP 200 and process later. This is shared-secret authentication, not a per-body asymmetric/HMAC signature.
• Webhook FAQ states at-least-once delivery and HTTP 200 success. It describes interrupted delivery after repeated failures and a limited retained-event window. Include queue-health detection and resource reconciliation rather than relying forever on event redelivery.
• Charge events describe receipts/refunds and other method-specific events. Admit only the selected event mappings; preserve unknown additions without financial effects.
• Pix refund supports full/partial refunds with a cumulative principal limit. Fees may leave available balance insufficient. Model requested, failed, pending and completed separately.
• Balance-block events can include MED-related holds; some blocks have no associated charge. Such a hold cannot identify every affected subscription or prove customer fraud.

Admission record to finish: actual merchant identity/account approval, supported Pix receipt/QR flow, sandbox/live base origins, API key and User-Agent contract, minimum required billing data, QR expiration/late-payment behavior, reference query completeness, webhook token/events and IPs if used as supplemental control, refund constraints and operator permissions. Do not provision split/subaccounts, transfers, outgoing Pix or arbitrary beneficiary payments for subscription sales.

Asaas Pix Automático — separately enabled

The maintainer selected this as well as conventional Pix; neither replaces the other. Overview, implementation, authorization reference and webhook flow describe payer authorization, initial payment and later recurring collection.

Select one cycle owner at PAY-01/02. Recommended provider-generated SUBSCRIPTION mode reduces application scheduling if its actual account/API contract meets requirements. MANUAL means the application creates authorized debit instructions; it is not the conventional customer-paid Pix mode. Never run both schedulers. Provider retries must be admitted with the relevant supported retry policy.

PAY-13 keeps the provider-owned SUBSCRIPTION flow: instructions and received payments are reconciled locally, never re-created; cancellation/expiry and eligibility loss stop future authority while verified paid periods remain. PAY-14 fences source changes: Stripe renewal is stopped with a confirmed cancel_at_period_end; Pix Automático mandates are confirmed canceled before a new source may start; immediate/prorated plan changes are refused.

FAQ describes merchant eligibility requirements and loss of eligibility. Initial payment can succeed even when authorization is refused. Verify the actual merchant's eligibility before enabling this channel. Cancellation reasons distinguishes canceled authorization from expiry; preserve native reasons and reconcile already scheduled instructions. Payment receipt alone never activates future debit authority.

Sandbox and distribution gates

• Asaas sandbox FAQ and supported tests describe available simulation paths and limitations. No dedicated Pix Automático sandbox proof was obtained here; PAY-21 must establish supported cases with the actual test account. Unsupported simulations remain PROOF_OWED, not production tests.
• Google Play payments policy applies to digital-feature sales in Play-distributed apps and permits alternative arrangements only under applicable requirements/programs. Web billing backend work may proceed; embedding checkout or purchase steering in Android needs its own verified distribution decision. Google provider activation remains LATER.
• OWASP webhook guidance supports authenticated bounded intake, durable acknowledgement and idempotent handling. Source-specific provider behavior takes precedence over invented common signatures. Follow the project's existing auth/privacy/SQL contracts.

Required merchant configuration beyond secrets

Record nonsecret merchant IDs, exact test/live environment, product/price mapping, BRL amounts/terms/capabilities, allowed checkout/portal origins, webhook URLs and event/version settings, channel switches, Pix readiness/mandate eligibility, retention/refund/cancellation policies, operational limits and alert routing. Provider customer notifications must be configured to avoid duplicate/unwanted email/SMS/WhatsApp and unapproved messaging costs. A billing invoice is not automatically a Brazilian fiscal document; freeze the required issuance workflow. No account setup, fiscal decision or real sandbox acceptance is replaced by inserting an API key.