Woovi (OpenPix)

• Methods: pix, undefined — Pix only.
• Setup: payments.woovi({ appId, webhookPublicKey }) — WOOVI_APP_ID.
• Webhooks: two signing schemes. The recommended one is RSA-SHA256 in x-webhook-signature, verified against webhookPublicKey (the account public key from GET /api/v1/webhook/public-keys, PEM or base64-PEM). The deprecated per-webhook HMAC (X-OpenPix-Signature, HMAC-SHA1 base64) is supported via webhookSecret and takes a back seat when both are set.
• externalReference: maps to Woovi's correlationID — the id you pass comes back on the charge and its webhook, so it's your routing key. It reaches subscriptions too: it is sent on create and echoed at the ROOT of every PIX_AUTOMATIC_COBR_* delivery, so a renewal routes like any other payment.
• Subscriptions: Pix Automático (type: 'PIX_RECURRING') — recurring Pix authorized once at the payer's bank, no card. The payer's customer.address is required: a recurring mandate carries it, and the gateway refuses the subscription without one. Journey and retry default to PAYMENT_ON_APPROVAL / NON_PERMITED; override with metadata.journey, metadata.retryPolicy, metadata.minimumValue, metadata.dayDue. description becomes the subscription name and, truncated to 30 characters, the adoption-contract comment shown in the bank app. Pass metadata.pixAutomatic: false for the ordinary subscription that mails a payment link each cycle instead. Pass startDate to set the monthly charge day (dayGenerateCharge) — with the default pay-on-approval journey the gateway requires it to be today. They are write-once: the API creates and reads them and nothing else, so both updateSubscription and cancelSubscription throw instead of pretending. Cancel in the Woovi dashboard and reconcile your own record — the payer can also revoke a Pix Automático authorization at their own bank, which arrives as a webhook. To change an amount, cancel and create a new subscription.
• Invoices: no invoice concept — a charge is the billing record; use an invoice provider with invoice: true if you need an invoice.
• Disputes: Pix MED, all four events mapped — see Disputes.

await payments.driver('pix').charge({
  customerId: 'your-correlation-id',
  amount: 1990,
  externalReference: 'payment_local_1',
  invoice: true,
})

Disputes are Pix MED, not chargebacks

A Pix cannot be charged back. What Woovi calls a disputa is the Banco Central's MED — Mecanismo Especial de Devolução — a payer reporting fraud or a scam, which Woovi's own dispute payload types as "MED" | "CHARGEBACK". Four events, and the driver maps all four:

DISPUTE_CREATED is a warning, not a payment.disputed, and the distinction is Woovi's own: while a dispute is under analysis, "o saldo relacionado a transação será bloqueado no saldo da empresa". A block is not a withdrawal — the money is still yours if the dispute is rejected — so nothing is written to the payment row. What you get is the alert, and Woovi's published window to answer it: three days to send evidence, after which the bank has up to seven to decide.

reason comes from dispute.disputeReason (Woovi's example is "Golpe") and disputeId from dispute.id — the id you upload evidence against.

The dispute events carry no actionableUntil — the payload has no date field at all, and the three-day window is Woovi's policy rather than something it sends, so the driver does not compute a deadline it was never given. They carry no amount either: the dispute payload's value is the disputed figure rather than the charge's, and the row the processor moves already knows what it was charged. event.raw.dispute.value has it if you want it.