Payout Lifecycle

This document maps every step of the payout lifecycle, showing exactly where the system touches our database (Drizzle/Supabase) versus the Pagar.me API.

Legend

• DB = Our database (Drizzle ORM / Supabase)
• PAGAR.ME = Pagar.me REST API (https://api.pagar.me/core/v5/)

0. Seller eligibility: can_sell vs can_withdraw

Two separate capabilities, both DERIVED from live DB state by deriveEligibility immediately before the mutation they gate. They are not JWT claims — the access-token hook actively strips can_sell / can_withdraw, because a token can be an hour stale and must never gate money:

can_sell — can list items for sale

Computed as:

user_can_sell := (
  user_cpf IS NOT NULL
  AND user_seller_id IS NOT NULL
  AND has_shipping_address = true
  AND user_account_status = 'active'
);

Requires: CPF + Pagar.me seller (any status). The seller must also have a shipping address and good account standing.

can_withdraw — can request payouts

Computed as:

user_can_withdraw := (
  user_can_sell
  AND user_seller_status = 'active'
  AND NULLIF(BTRIM(user_payout_destination_id), '') IS NOT NULL
  AND user_payout_destination_status = 'active'
);

Requires: sell eligibility + a Pagar.me recipient with status exactly "active" + an active provider-owned payout destination.

The gap between selling and withdrawing

A seller can list items (can_sell = true) before they can withdraw, because:

1. The Pagar.me recipient starts in "pending" status after creation — this is enough for can_sell but not for can_withdraw (needs "active").
2. Pagar.me owns the bank credentials. Cüte retains only the returned provider reference and safe masked metadata.
3. The recipient transitions pending → active asynchronously on Pagar.me's side (KYC approval).

So the full onboarding timeline looks like:

User provides CPF and bank details in Cüte's payout form
    ↓
Server sends the bank details transiently to Pagar.me while creating the recipient
    ↓
Pagar.me stores the bank account; Cüte stores providerSellerId plus safe destination metadata
    ↓
can_sell = true ✅  (can list items)
can_withdraw = false ❌  (payment account is not active yet)
    ↓
Pagar.me KYC approves → recipient status changes to "active"
    ↓
can_sell = true ✅
can_withdraw = true ✅  (all conditions met)

What each step stores in the DB

Full branch/account numbers and holder documents are never persisted in Cüte's database. They exist only in the transient server request to the payment gateway and in Pagar.me's vault.

Key files:

• packages/commerce/onboarding/onboarding.eligibility.ts — deriveEligibility, the canonical capability predicate
• packages/features/payments/actions/ensure-seller-payment-account.action.ts — payment account creation
• packages/features/payments/actions/configure-payout-destination.action.ts — payout-destination update
• packages/payments/providers/pagarme/adapter.ts — provider mapping and custody boundary
• packages/db/schema/seller-payment-accounts.ts — payment account schema

1. Seller onboarding (seller creation)

Before a seller can receive payouts, they need a Pagar.me seller.

Note: can_withdraw remains false until both the payment account and its provider-owned payout destination have normalized status "active".

Key files:

• packages/features/payments/actions/ensure-seller-payment-account.action.ts
• packages/payments/providers/pagarme/adapter.ts

2. Order payment → seller balance credit

When a buyer pays, Pagar.me processes the payment and notifies us via webhook.

Funds stay in the held bucket until the order reaches completed. On completion, the order workflow calls releaseHold() to move them held → available.

Key files:

• apps/web/app/api/v1/webhooks/pagarme/route.ts
• packages/features/payments/actions/webhook-handlers.action.ts → handlePaymentPaid()
• packages/commerce/wallet/wallet-service.ts → creditBucket(), releaseHold()

3. Withdrawal request

The seller requests a withdrawal from their available balance. This has the most guards of any flow.

Guard chain (all must pass)

Flow (after guards pass)

Key files:

• apps/web/app/api/v1/withdraw/route.ts — rate limiting, schema validation
• packages/features/payments/actions/request-withdrawal.action.ts — all business logic guards + gateway calls
• packages/commerce/wallet/wallet.service.ts → debitBucket(), creditBucket()
• packages/features/payments/queries/update-payout.query.ts

4. Transfer settlement (webhook)

Pagar.me settles the transfer (typically 1-2 business days) and notifies us.

4a. Transfer succeeded (transfer.paid)

4b. Transfer failed (transfer.failed)

Key files:

• packages/features/payments/actions/webhook-handlers.action.ts → handleTransferPaid(), handleTransferFailed()
• packages/commerce/wallet/wallet-service.ts → completeWithdrawal(), creditBucket()

5. Payout status machine

pending ──→ processing ──→ completed
  │              │
  └──→ failed ←──┘
  │
  └──→ cancelled

Balance buckets

The wallet uses two buckets (collapsed from the earlier 5-bucket shape). Standing is not on the wallet: a suspended member is stopped by deriveEligibility (reading users.account_status) before the wallet is asked to move anything.

In-flight withdrawals are not a bucket. The payouts row (with status in pending / processing) is the source of truth for money en route to the seller's bank.

All Pagar.me API touchpoints (summary)

Safeguards

• Atomic DB transactions for all balance movements — funds never "disappear"
• Compensating transactions on API failure — if Pagar.me rejects, funds are immediately unreserved
• Idempotent webhooks via webhook_logs — duplicate deliveries won't double-credit
• Environment-aware provider gateway — sandbox/live endpoints and credentials are selected inside the gateway while application data remains canonical
• Rate limiting on withdrawal endpoint via Upstash Redis
• RLS policies — users can only view their own payouts and balances