Get Payment Notifications

Once payments start flowing through your wallets, you need to know when money arrives. Traditional payment systems scatter this information across batch files, polling endpoints, and network-specific notification formats — each with its own schedule, its own format, and its own failure modes.

The ledger gives you two ways to track payments, and you can use both together:

This guide walks you through both, building on the store wallet from Create a Wallet.

Approach 1: Query intents

The simplest way to check for payments — ask the ledger what happened. Every payment is an intent, and the ledger keeps a complete, queryable record of every intent that has touched your wallets.

curl "https://{ledger-host}/v2/intents?filter[data.claims.target.handle]=store1@greatcoffee.co" \
  -H "Authorization: Bearer {your-token}" \
  -H "x-ledger: {your-ledger}"

curl "https://{ledger-host}/v2/intents?filter[data.claims.target.handle]=store1@greatcoffee.co&filter[meta.status]=completed" \
  -H "Authorization: Bearer {your-token}" \
  -H "x-ledger: {your-ledger}"

Available filters

The intents endpoint supports filtering on any combination of these fields:

This approach is ideal for building dashboards, running reconciliation checks, or generating end-of-day reports.

Approach 2: Register an effect

Querying works for on-demand checks, but if you need to react the moment a payment lands — update a POS screen, send a receipt, trigger a downstream process — you want the ledger to call you. That's what an effect does.

An effect is a subscription: you tell the ledger which event to watch for and where to send the notification. The ledger handles delivery, retries, and ordering.

curl -X POST "https://{ledger-host}/v2/effects" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your-token}" \
  -H "x-ledger: {your-ledger}" \
  -d '{
    "data": {
      "handle": "greatcoffee-payment-received",
      "signal": "balance-received",
      "filter": {
        "wallet.data.handle": "store1@greatcoffee.co"
      },
      "action": {
        "schema": "webhook",
        "endpoint": "https://greatcoffee.co/api/webhooks/payment-received"
      }
    }
  }'

// Your server — Express, Fastify, or any HTTP framework
app.post('/api/webhooks/payment-received', async (req, res) => {
  // Acknowledge immediately — the ledger retries if it doesn't get a 2xx
  res.status(202).send()

  const event = req.body
  const { signal, wallet, symbol, intent, amount } = event.data

  // Check idempotency — the handle uniquely identifies this event
  if (await isAlreadyProcessed(event.data.handle)) return

  console.log(`Received ${amount} ${symbol.data.handle} on ${wallet.data.handle}`)
  console.log(`Intent: ${intent.data.handle}`)

  // Your business logic — update POS, send receipt, trigger payout
  await processPayment(event)
})

curl "https://{ledger-host}/v2/effects/greatcoffee-payment-received" \
  -H "Authorization: Bearer {your-token}" \
  -H "x-ledger: {your-ledger}"

Built-in reliability

Effects aren't fire-and-forget. The ledger guarantees delivery with automatic retries:

If your server is down for maintenance, the ledger queues events and delivers them when your endpoint comes back. No need for a separate dead-letter queue or reconciliation process for missed notifications.

End-to-end flow

With both approaches set up, here is the complete flow when a customer pays the store:

The effect gives you the real-time notification. The intent query gives you the on-demand audit trail. Together they cover both the "something just happened" and the "show me everything that happened" use cases.

What you learned

• How to query intents by wallet, status, and currency using filters
• How to register a webhook effect that fires when a wallet receives a payment
• How to handle webhook calls with idempotency and immediate acknowledgment
• How the ledger guarantees delivery with automatic retries

Next steps

• About Intents — how the two-phase commit protocol guarantees every payment is atomic
• About Anchors — how simple identifiers like QR codes and phone numbers resolve to wallets
• Get Notifications — advanced effect configuration including bridge effects and additional signals