API reference

defineConfig({
  default?: string
  providers?: Record<string, PaymentsDriverFactory>
  methods?: Partial<Record<PaymentMethodName, string>>
  allowUnverifiedWebhooks?: boolean | string[]

  invoice?: {
    default?: string
    providers?: Record<string, InvoiceProviderFactory>
    defaults?: { service?: {...}; tax?: Record<string, unknown> }
  }

  billing?: {
    enabled?: boolean
    autoCreateSchema?: boolean
    dispatcher?: 'auto' | 'durable' | 'in-process'
    role?: 'all' | 'api' | 'worker'
    store?: BillingStoreFactory
    durable?: 'auto' | boolean       // legacy alias for dispatcher
    handlers?: Record<string, WebhookHandler | WebhookHandlerService>
    passthroughEvents?: string[]
  }
})

// Brazil-first
payments.abacate({ apiKey?, publicKey?, webhookSecret? })
payments.asaas({ apiKey?, sandbox?, webhookToken? })
payments.efi({ clientId?, clientSecret?, pixKey?, sandbox?, certificate?,
               certificatePassphrase?, expirationSeconds?, fetch? })
payments.infinitepay({ handle?, baseUrl?, webhookUrl? })
payments.pagarme({ secretKey?, baseUrl?, webhookUser?, webhookPassword?, pixExpiresIn? })
payments.pagbank({ token?, sandbox?, webhookToken?, verifyWebhooks?, notificationUrls? })
payments.woovi({ appId?, baseUrl?, webhookSecret?, webhookPublicKey? })

// Multi-currency — `currency` is required on every one of these
payments.stripe({ currency, apiKey?, webhookSecret? })
payments.adyen({ currency, apiKey?, merchantAccount?, hmacKey?, liveUrlPrefix?,
                 environment?, captureMode? })
payments.mercadopago({ currency, accessToken?, webhookSecret? })
payments.mollie({ currency, apiKey?, webhookSecret? })
payments.paypal({ currency, clientId?, clientSecret?, sandbox?, webhookId? })
payments.razorpay({ currency, keyId?, keySecret?, webhookSecret? })
payments.square({ currency, accessToken?, locationId?, sandbox?,
                  webhookSignatureKey?, notificationUrl?, apiVersion? })

// Merchant of record
payments.dodo({ currency, apiKey?, sandbox?, billingCountry?, webhookKey? })
payments.lemonsqueezy({ storeId, apiKey?, webhookSecret? })
payments.paddle({ currency, apiKey?, sandbox?, productId?, webhookSecret?,
                  webhookMaxAgeSeconds? })
payments.polar({ currency, accessToken?, sandbox?, webhookSecret? })

invoice.focus({ token?, baseUrl? })
invoice.enotas({ apiKey?, baseUrl? })
invoice.plugnotas({ apiKey?, baseUrl? })
invoice.asaas({ apiKey?, sandbox? })
invoice.tecnospeed({ token?, baseUrl? })

import { getPayments } from '@adonis-agora/payments/services/main'

const payments = getPayments()

import {
  getPayments, findPayments,
  getBillingStore, findBillingStore,
  getWebhookDispatcher, findWebhookDispatcher,
  lazyPayments, lazyBillingStore, lazyPaymentsDriver,
} from '@adonis-agora/payments/services/main'

export default class GrantAccess {
  #payments = lazyPayments()          // safe in a field initializer
  #store = lazyBillingStore()
  #pix = lazyPaymentsDriver('pix')    // routing resolved lazily too
}

interface PaymentsDriver {
  readonly provider: string
  readonly supportedMethods: readonly PaymentMethodName[]
  readonly capabilities?: {
    refunds?: boolean; invoices?: boolean; subscriptions?: boolean; disputes?: boolean
  }
  /** 'configured' | 'unconfigured' | 'unsupported'. Absent reads as 'unsupported'. */
  readonly webhookVerification?: WebhookVerificationState

  createCustomer(input: CreateCustomerInput): Promise<Customer>
  findCustomer(customerId: string): Promise<Customer | null>
  updateCustomer(customerId: string, input: UpdateCustomerInput): Promise<Customer>

  charge(input: ChargeInput): Promise<Payment>
  findPayment(gatewayId: string): Promise<Payment | null>
  refund(paymentGatewayId: string, amount?: Money, options?: { idempotencyKey?: string }): Promise<Refund>

  createCheckout(input: CheckoutInput): Promise<CheckoutSession>

  createSubscription(input: CreateSubscriptionInput): Promise<Subscription>
  cancelSubscription(gatewayId: string, options?: { atPeriodEnd?: boolean }): Promise<Subscription>
  updateSubscription(gatewayId: string, input: UpdateSubscriptionInput): Promise<Subscription>
  findSubscription(gatewayId: string): Promise<Subscription | null>

  listInvoices(customerId: string): Promise<Invoice[]>

  // Optional. A gateway with no dispute API declares `capabilities.disputes: false` and omits
  // both, rather than inventing a Dispute it cannot read back.
  findDispute?(disputeGatewayId: string): Promise<Dispute | null>
  submitDisputeEvidence?(disputeGatewayId: string, evidence: DisputeEvidence): Promise<Dispute>

  parseWebhook(
    rawBody: string,
    headers: Record<string, string | string[] | undefined>,
  ): WebhookEvent | WebhookEvent[] | Promise<WebhookEvent | WebhookEvent[]>
}

{
  amount: Money                       // required — integer cents
  customerId?: string
  currency?: string
  description?: string
  method?: string
  paymentMethodId?: string
  card?: CardInput
  customer?: { name?: string; taxId?: string; email?: string }   // the payer's fiscal data
  idempotencyKey?: string             // guards the OUTBOUND call
  externalReference?: string          // routes the INBOUND webhook to your row
  split?: Array<{ walletId: string; percentualValue?: number; fixedValue?: number }>
  invoice?: boolean | string | InvoiceOptions
  metadata?: Record<string, unknown>
}

{
  customerId: string
  planId: string
  amount?: Money                      // required by the BR gateways
  idempotencyKey?: string
  cycle?: 'WEEKLY' | 'BIWEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUALLY' | 'YEARLY'
  method?: string
  description?: string
  trialDays?: number
  startDate?: string                  // ISO date — required by Asaas
  card?: CardInput
  customer?: { name?: string; email?: string; taxId?: string }
  externalReference?: string
  invoice?: boolean | string | InvoiceOptions
  metadata?: Record<string, unknown>
}

interface CardInput {
  token: string                       // tokenized in the browser
  holder?: { name; email; cpfCnpj; postalCode; addressNumber; phone }
  remoteIp?: string
}

interface CheckoutInput {
  amount: Money
  successUrl: string
  customerId?: string
  currency?: string
  description?: string
  cancelUrl?: string
  planId?: string
  trialDays?: number
  idempotencyKey?: string
  externalReference?: string          // matters MORE here — see below
  customer?: { name?: string; taxId?: string; email?: string }
  invoice?: boolean | string | InvoiceOptions
  metadata?: Record<string, unknown>
}

type Money = number         // integer, smallest currency unit
type Currency = string      // lowercase ISO 4217
interface MoneyAmount { amount: Money; currency: Currency }

// 'authorized' = funds held, nothing captured. Money has NOT moved.
type BillingStatus =
  | 'pending' | 'authorized' | 'paid' | 'failed' | 'refunded' | 'canceled' | 'disputed'

// 'paused' is not a flavour of 'active': it exists, it will bill again, it must not entitle.
type SubscriptionStatus =
  | 'trialing' | 'active' | 'paused' | 'past_due' | 'incomplete' | 'canceled' | 'ended'

// Categories, not brands. 'wallet' covers PayPal/Apple Pay/Google Pay, 'bank_transfer' the
// push-from-your-bank methods (iDEAL, Bancontact, Multibanco), 'bank_debit' the pull ones
// (SEPA Direct Debit, ACH). The brand goes in the gateway's own field, via metadata.
type PaymentMethodType =
  | 'card' | 'pix' | 'boleto' | 'debit_card' | 'wallet' | 'bank_transfer'
  | 'bank_debit' | 'upi' | 'bnpl' | 'voucher' | 'unknown'
type PaymentMethodName =
  | 'pix' | 'credit_card' | 'debit_card' | 'boleto' | 'wallet' | 'bank_transfer'
  | 'bank_debit' | 'upi' | 'bnpl' | 'voucher' | 'undefined'

interface Payment {
  id: string
  gatewayId: string
  provider: string
  amount: MoneyAmount
  status: BillingStatus
  customerId?: string
  method?: PaymentMethodType
  payload: Record<string, unknown>    // the untouched gateway response
  createdAt: string
  paidAt?: string
  pixQrCodeImage?: string             // base64 PNG of the Pix QR code
  pixCode?: string                    // the BR Code (EMV payload) the customer copies
  pixQrCode?: string                  // @deprecated alias of pixQrCodeImage
  pixCopiaECola?: string              // @deprecated alias of pixCode
  hostedUrl?: string
  subscriptionId?: string
  invoice?: Invoice
}

interface Subscription {
  id: string; gatewayId: string; provider: string; customerId: string
  status: SubscriptionStatus; planId: string; amount?: MoneyAmount
  trialEndsAt?: string; endsAt?: string
  currentPeriodStart?: string; currentPeriodEnd?: string
  payload: Record<string, unknown>; createdAt: string
}

interface Invoice {
  id: string; gatewayId: string; provider: string
  status: 'draft' | 'open' | 'paid' | 'void' | 'uncollectible'
        | 'issued' | 'pending' | 'failed' | 'canceled'
  amount: MoneyAmount; createdAt: string
  customerId?: string; subscriptionId?: string
  number?: string; key?: string; hostedPdfUrl?: string; issuedAt?: string
  payload: Record<string, unknown>
}

interface WebhookEvent<T = unknown> {
  id: string                          // stable — the idempotency key
  provider: string
  type: string
  createdAt?: string
  data: T                             // normalized
  raw: Record<string, unknown>        // untouched
}

interface Customer { id: string; email?: string; name?: string; taxId?: string; metadata?: Record<string, unknown> }
interface Refund { id: string; gatewayId: string; provider: string; amount: MoneyAmount; status: 'succeeded' | 'pending' | 'failed'; createdAt: string }
interface CheckoutSession { id: string; gatewayId: string; provider: string; url: string; status: 'open' | 'complete' | 'expired'; amount?: MoneyAmount; subscriptionId?: string; customerId?: string; pixCode?: string; pixCopiaECola?: string }

// 'warning' is not a dispute yet — it is the pre-chargeback alert the networks relay (Stripe's
// early fraud warning, Adyen's NOTIFICATION_OF_FRAUD), where a refund inside the window stops
// the chargeback from ever being filed. Worth taking even on a dispute you would have won: a
// chargeback counts against the ratio that puts a merchant into a network monitoring programme.
type DisputeStatus =
  | 'warning' | 'open' | 'under_review' | 'won' | 'lost' | 'canceled' | 'expired'

interface Dispute {
  id: string                          // the DISPUTE's own gateway id, not the payment's
  provider: string
  paymentGatewayId: string
  status: DisputeStatus
  amount?: MoneyAmount                // not always the whole payment — partials are normal
  reason?: string                     // the gateway's own code, verbatim; the vocabulary is per-network
  evidenceDueBy?: string              // past it the dispute is lost by default, and nothing can be done
  canSubmitEvidence?: boolean         // most gateways accept evidence ONCE
  createdAt?: string
  payload: Record<string, unknown>
}

interface DisputeEvidence {
  explanation?: string                // most gateways weigh this heavily
  shippingCarrier?: string; shippingTrackingNumber?: string; shippingDate?: string
  serviceDate?: string
  termsAcceptedAt?: string
  customerName?: string; customerEmail?: string; customerIpAddress?: string
  priorUndisputedPayments?: PriorUndisputedPayment[]
  documents?: DisputeDocument[]
  metadata?: Record<string, unknown>
}

// What a document proves, which is what every gateway files it by. Stripe has nine separate
// file fields and Adyen a defenseDocumentTypeCode; neither is reachable with "here are some files".
type DisputeDocumentKind =
  | 'receipt' | 'invoice' | 'customer_communication' | 'customer_signature' | 'shipping'
  | 'service' | 'refund_policy' | 'cancellation_policy' | 'terms' | 'duplicate_charge' | 'other'

// A file id, never a URL: the banks reviewing a dispute do not follow links, and no gateway
// here accepts one. The bytes have to be at the gateway already.
interface DisputeDocument { kind: DisputeDocumentKind; id: string }

// The transactions themselves, not a count — Visa's Compelling Evidence 3.0 wants the charges,
// each with the account, device and IP they were made from. A number is not evidence of anything.
interface PriorUndisputedPayment {
  paymentGatewayId: string
  customerAccountId?: string
  customerIpAddress?: string
  customerDeviceId?: string
}

{
  provider?: string
  service?: { description?: string; code?: string; cityServiceCode?: string }
  tax?: Record<string, unknown>
  customer?: { name?: string; taxId?: string; email?: string; address?: Record<string, unknown> }
  metadata?: Record<string, unknown>
}

class WebhookProcessor {
  constructor(options: {
    store: BillingStore
    driver?: PaymentsDriver
    handlers?: Record<string, WebhookHandler>
  })

  /** false ⇒ redelivery, nothing ran. Throws ⇒ ledger marked failed. */
  process(event: WebhookEvent): Promise<boolean>
}

type WebhookHandler = (event: WebhookEvent) => void | Promise<void>

// Typed authoring — `event.data` inferred from the event type.
defineWebhookHandler<T>(type: T, handle: TypedWebhookHandler<T>): WebhookHandlerDefinition<T>

interface WebhookEventDataMap { 'payment.succeeded': PaymentWebhookData; /* … */ }
type WebhookEventDataFor<T> = T extends WebhookEventType ? WebhookEventDataMap[T] : unknown
type WebhookEventFor<T>     = WebhookEvent<WebhookEventDataFor<T>> & { type: T }
type TypedWebhookHandler<T> = (event: WebhookEventFor<T>) => void | Promise<void>

// Boot-time validation. The provider calls this; it is exported for a custom bootstrap.
assertWebhookHandlerTypes(
  registrations: readonly { type: string; source: string }[],
  options?: { passthroughEvents?: readonly string[] },
): void

interface BillingStore {
  saveCustomer(customer): Promise<CustomerRow>
  findCustomerByGatewayId(gatewayId): Promise<CustomerRow | null>
  findCustomerByOwner(ownerType, ownerId, provider): Promise<CustomerRow | null>
  listCustomers(query: CustomerListQuery): Promise<CustomerListItem[]>
  listCustomersByGatewayIds(gatewayIds): Promise<CustomerListItem[]>   // a page of owners in one read

  saveSubscription(sub): Promise<SubscriptionRow>
  findSubscriptionByGatewayId(gatewayId): Promise<SubscriptionRow | null>
  listSubscriptions(query): Promise<SubscriptionListItem[]>
  countSubscriptions(query): Promise<number>
  countActiveSubscriptions(): Promise<number>

  savePayment(payment): Promise<PaymentRow>
  findPaymentByGatewayId(gatewayId): Promise<PaymentRow | null>
  findPaymentByExternalReference(reference): Promise<PaymentRow | null>
  listPayments(query: PaymentListQuery): Promise<PaymentListItem[]>
  countPayments(query): Promise<number>
  revenue(query: { from?: Date; to?: Date }): Promise<number>     // GROSS — sums `amount`
  netRevenue(query: { from?: Date; to?: Date }): Promise<number>  // NET   — minus refunded_amount

  saveDispute(dispute): Promise<DisputeRow | null>             // null ⇒ no billing_disputes table
  findDisputeByGatewayId(gatewayId): Promise<DisputeRow | null>
  findOpenDisputeByPayment(paymentGatewayId): Promise<DisputeRow | null>
  listDisputes(query): Promise<DisputeListItem[]>
  countDisputes(query): Promise<number>
  listDisputesDueWithin(query: DisputeDeadlineQuery): Promise<DisputeListItem[]>
  countDisputesDueWithin(query): Promise<number>
  listOpenDisputes(query: OpenDisputeQuery): Promise<DisputeListItem[]>   // oldest first
  countOpenDisputes(query: { provider?: string }): Promise<number>

  recordWebhookEvent(event): Promise<WebhookEventRow | null>   // null ⇒ redelivery
  markWebhookProcessed(id): Promise<void>
  markWebhookFailed(id, error): Promise<void>
  findWebhookEventByGatewayEventId(gatewayEventId): Promise<WebhookEventListItem | null>
  listWebhookEvents(query: WebhookEventListQuery): Promise<WebhookEventListItem[]>
  listWebhookEventsForPayment(paymentGatewayId, query?): Promise<WebhookEventListItem[]>
  countWebhookEvents(query): Promise<number>
  webhookEventBreakdown(query): Promise<WebhookEventBreakdownLine[]>

  recordAuditEvent(event): Promise<AuditEventListItem | null>  // null ⇒ no billing_audit_events table
  listAuditEvents(query: AuditEventQuery): Promise<AuditEventListItem[]>
  countAuditEvents(query: AuditEventCountQuery): Promise<number>

  recordUsage(event): Promise<UsageEventRow>
  usageReport(query): Promise<Array<{ meter: string; quantity: number }>>
}

const AUDIT_ACTIONS = {
  refund: 'payment.refunded',
  disputeResolved: 'dispute.resolved',
  webhookRejected: 'webhook.rejected',
}

interface PaymentListQuery extends BillingListQuery {
  externalReference?: string   // the app's own id for the charge
  gatewayId?: string           // the gateway's payment id
  customerId?: string          // the gateway's customer id
}
interface WebhookEventListQuery extends BillingListQuery { type?: string }
interface CustomerListQuery    extends BillingListQuery { ownerType?, ownerId?, gatewayId? }

interface DisputeDeadlineQuery {
  withinHours: number      // 72 = "everything due in the next three days"
  now?: Date               // overridable clock
  provider?: string
  page?: number           // 1-based, like every other list read
  size?: number
}

const OPEN_DISPUTE_STATUSES = ['warning', 'open', 'under_review']

createBillingTables(db: LucidDatabase): Promise<void>   // idempotent; also carries later columns
dropBillingTables(db: LucidDatabase): Promise<void>     // for a migration's down() and for tests
truncateBillingTables(db: LucidDatabase): Promise<void> // empties the rows, keeps the schema
BILLING_TABLES  // ['billing_customers', 'billing_subscriptions', 'billing_payments',
                //  'billing_webhook_events', 'billing_disputes', 'billing_usage_events',
                //  'billing_audit_events']

billingOverview(store, { from: Date; to: Date }): Promise<BillingOverview>
// → { period, metrics: [{ key, label, value }] }
//   revenue (cents, GROSS) · net_revenue (cents, minus refunded_amount)
//   · active_subscriptions · meter:<name> per meter

meteredBill(usage, rates): MeteredBill
meteredBillForSubscription(store, { subscriptionId, from, to, rates }): Promise<MeteredBill>

interface MeterRate     { meter: string; rate: number; included?: number }
interface MeteredBillLine { meter: string; quantity: number; billable: number; amount: number }
interface MeteredBill   { lines: MeteredBillLine[]; total: number }

billingHealth(store, options?: BillingHealthOptions): Promise<BillingHealth>

interface BillingHealthOptions {
  stuckAfter?: number         // ms an event may sit in `received`.  Default 15 min
  unconfirmedAfter?: number   // ms a `pending` payment may age.     Default 2 h
  failedWithin?: number       // the window failures are counted over. Default 24 h
  disputeDueWithin?: number   // ms ahead to look for a closing evidence window. Default 72 h
  rejectedWithin?: number     // the window rejected deliveries are counted over. Default 24 h
  now?: Date
}

interface BillingHealth {
  healthy: boolean            // false when ANY check is non-zero — the command's exit code
  checkedAt: Date
  checks: BillingHealthCheck[]
  failures: WebhookEventBreakdownLine[]   // which provider/event pairs make up failed_webhooks
  deadlines: DisputeListItem[]            // WHICH windows are closing, soonest first, capped at 20
  openDisputes: DisputeListItem[]         // WHICH are unanswered, OLDEST first, capped at 20
}

interface BillingHealthCheck {
  key: 'stuck_webhooks' | 'failed_webhooks' | 'unconfirmed_payments'
     | 'disputes_due' | 'open_disputes' | 'rejected_deliveries'
  label: string
  count: number
  healthy: boolean            // true when count is zero — every check is a "should be nothing" check
  hint: string
}

httpRequest<T>(path, options: HttpRequestOptions): Promise<T>
headerValue(headers, name): string | undefined
isNotFound(error): boolean

// All four take the currency, because the exponent is not always 2: JPY and KRW have none,
// KWD and BHD have three. Omitting it assumes 2. `formatDecimal` builds the wire string by
// shifting the integer's digits rather than dividing — (x/100).toFixed(2) routes through a
// binary float, which is the classic way to ship "19.89".
currencyExponent(currency?: Currency): number
toDecimal(amount: Money, currency?: Currency): number
fromDecimal(value: number, currency?: Currency): Money
formatDecimal(amount: Money, currency?: Currency): string

ensureCustomer(driver, existingId, input, options?): Promise<Customer>
//   options: { store?: BillingStore; owner?: { type: string; id: string | number } }
emitInvoice(ctx, options): Promise<Invoice>
emitInvoiceIfRequested(ctx, input, payment, driver): Promise<void>

PAYMENTS_DIAGNOSTIC_EVENTS          // the runtime catalog
publishPayments(event, payload)
claimPaymentsDiagnostics()
isPaymentsDiagnosticClaimed(event)
tracePayments(...)

import {
  FakePaymentsDriver, InMemoryBillingStore, MutableClock,
  fakePayments, swapPayments, swapBillingStore, flushWebhooks,
} from '@adonis-agora/payments/testing'

new FakePaymentsDriver({ provider?, webhookEvents? })
//   .chargeCalls, .refundCalls, … — every call recorded
new InMemoryBillingStore()
new MutableClock()   // .advance(ms)

fakePayments(driver?: FakePaymentsDriver): PaymentsManager   // a REAL manager over the fake
swapPayments(manager: PaymentsManager): () => void           // returns the restore
swapBillingStore(store: BillingStore): () => void            // same, for the store
flushWebhooks(options?: { timeoutMs?: number }): Promise<void>

{ "received": true, "processed": 3, "failed": ["evt_4"], "error": "…" }