Getting started

node ace add @adonis-agora/payments

The configure command does five things:

1. registers three providers in adonisrc.ts — payments_provider, dashboard_provider and payments_client_provider (the last two read their own config file and the client one is off unless you enable it), plus the Assembler init hook that generates the app/payment_handlers/ barrel;
2. registers the ace commands (make:billable, make:webhook-handler, payments:webhook, payments:sync, payments:health);
3. publishes config/payments.ts, config/payments_dashboard.ts and config/payments_client.ts;
4. publishes one Lucid migration for the billing tables — which most apps can delete, see the next step;
5. registers the payment env validations.

Credentials are wired through config/payments.ts — you name your .env variables however you like and reference them with env.get(...). The library's built-in fallbacks (ASAAS_API_KEY, STRIPE_KEY, …) are a convenience when you don't pass a value, not a contract.

The configuration below is for the gateway picked in the sidebar — Asaas until you pick one. Every gateway's own options are on its provider page.

Showing Asaas — pick your gateway in the sidebar to see yours.

PAYMENTS_ASAAS_KEY=your-asaas-api-key
PAYMENTS_ASAAS_WEBHOOK_TOKEN=your-asaas-webhook-token

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

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

Asaas takes Pix, boleto and cards from one account, so routing both methods to it is the whole map. Outside production the driver talks to the sandbox host on its own (sandbox defaults to NODE_ENV !== 'production').

Or pass values from anywhere — the driver configs are plain objects, so an API key can come from a vault, another config file, or a literal (not recommended for secrets).

There isn't one to run. The billing layer owns seven tables — customers, subscriptions, payments, disputes, usage events, the audit trail and the webhook idempotency ledger — and it creates them itself on first use, the same convention @adonis-agora/durable and @adonis-agora/authz follow. Nothing to publish, nothing to run, nothing to remember when you upgrade.

The DDL is idempotent, so it costs one round trip on the first query of a process and nothing afterwards. Columns added to the library in later versions are carried to a database that already has the tables, which is what makes this an upgrade path rather than a first-install convenience.

If you would rather own the DDL — a shared database, a team that reviews every schema change, a deploy that runs migrations as their own step — turn it off and run the published migration instead:

billing: { autoCreateSchema: false }

node ace migration:run

configure publishes that one file for exactly this case. It calls the same createBillingTables the library does, so the two cannot drift. Leaving both on is harmless — whichever runs second finds the tables already there — but "who creates this table" is worth having one answer to.

If you want the gateways and none of the persistence, set billing: { enabled: false } and delete the published migration. The drivers work standalone; what you give up is everything the tables carry — the idempotency ledger included, so the mounted webhook route will verify a delivery and then do nothing with it.

Each gateway dashboard needs the endpoint URL and event list. Print them for every configured provider:

node ace payments:webhook

The provider mounts POST /payments/webhook/:provider automatically — register it in each gateway's dashboard and point it at /payments/webhook/<provider> (e.g. https://you.app/payments/webhook/asaas).

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

const payments = getPayments()

// Your own row, created before the money is asked for.
const order = await Order.create({ total: 1990, status: 'awaiting_payment' })

// A customer at the routed provider for `pix`
const customer = await payments.driver('pix').createCustomer({
  name: 'Jane Doe',
  email: 'jane@example.com',
  taxId: '123.456.789-00',
})

// Charge via Pix. `driver('pix')` threads the method into the charge, so you do not
// repeat `method: 'pix'` here.
const payment = await payments.driver('pix').charge({
  customerId: customer.id,
  amount: order.total, // 1990 is R$ 19,90 — integer cents, never floats
  externalReference: order.id, // comes back on every webhook for this charge
})

// payment.pixCode → the copy-paste BR code to show the customer

Add invoice: true to that call to emit a fiscal note with it — it needs an invoice section in the config first, or the charge throws. See Invoices.