Payments

@adonis-agora/payments brings multi-gateway payments and Cashier-style billing to AdonisJS. One contract — charge, refund, createSubscription, parseWebhook — normalized across every supported gateway, so your services talk to one interface instead of one SDK per provider.

Nothing in the contract is region-specific: money is an integer in the currency's smallest unit, a payment method is a name the driver either supports or refuses, and a webhook is a signature to verify and an event to normalize. What differs between a card charge in the euro area and a Pix charge in Brazil is which driver you route to — not the code that calls it. A charge can go out through one gateway and emit its invoice through a completely different provider, in a single call.

The problem it solves

Payment integrations are usually a mess of gateway SDKs, hand-rolled status mirrors, and webhook controllers that duplicate each other. @adonis-agora/payments collapses that into four guarantees:

• One driver contract, every gateway. Every gateway normalizes onto the same PaymentsDriver. Adding a gateway is a config entry, not a code change — and a driver declares which methods it supports, so routing a card to a Pix-only gateway fails at the manager, not at the gateway.
• Money moves only on confirmation. The idempotent webhook processor (a gateway-event ledger written before any work runs) makes redeliveries no-ops. Your business logic — grant credits, activate a subscription — runs at the right moment, exactly once. And the endpoint that receives it will not boot unverified: a driver that can authenticate a delivery and was given no credential refuses to start.
• Billing mirrors the gateway. Subscriptions, payments, disputes and trials sync into Lucid tables automatically, Cashier-style, with billable mixins on your models — and the library creates those tables itself, so adopting it is a config file, not a migration.
• Invoices are a separate concern. Pay through one provider, emit the invoice through another — the invoice option on the charge call joins them.

Quickstart

The minimal loop — install, configure a gateway, charge — with one provider and no invoice provider:

node ace add @adonis-agora/payments

ASAAS_API_KEY=your-asaas-api-key

import env from '#start/env'
import { defineConfig, payments } from '@adonis-agora/payments'

export default defineConfig({
  default: 'asaas',
  providers: {
    asaas: payments.asaas({ apiKey: env.get('ASAAS_API_KEY') }),
  },
  methods: {
    pix: 'asaas',
    credit_card: 'asaas',
  },
})

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

const customer = await getPayments().driver('pix').createCustomer({
  name: 'Jane Doe',
  email: 'jane@example.com',
  taxId: '123.456.789-00',
})

// charge via Pix — the customer scans the QR, then the webhook confirms
const payment = await getPayments().driver('pix').charge({
  customerId: customer.id,
  amount: 1990, // R$ 19,90 — integer cents, never floats
})
// `driver('pix')` binds the method: the charge goes out as Pix without repeating it.

node ace payments:webhook   # prints the URL + event list per provider
node ace make:webhook-handler payment.succeeded

@inject()
export default class PaymentSucceededHandler {
  static readonly eventType = 'payment.succeeded'
  async handle(event: WebhookEvent): Promise<void> {
    // dispatch a durable workflow — durable owns retry + exactly-once
  }
}

The happy path, end to end