What happens after an agent sends a payment? Receipts, webhooks, and settlement

The lifecycle

• The bot submits a payment command.
• The API validates auth, limits, token, amount, and recipient.
• The ledger records the debit and credit or queues external settlement.
• The API returns a payment ID and status.
• A webhook notifies the product when the status changes.
• The product issues a receipt or unlocks the next workflow step.

Receipt model

type PaymentReceipt = {
  paymentId: string;
  status: "pending" | "completed" | "failed";
  fromWalletId: string;
  toWalletId?: string;
  toAddress?: string;
  token: string;
  amount: number;
  signature?: string;
  createdAt: string;
};

Create a user-facing receipt

A receipt should be understandable without exposing internal implementation details. Show amount, token, status, recipient, memo, time, and signature when the payment settled on-chain.

Webhook-driven state transitions

async function applyPaymentWebhook(event: {
  type: string;
  data: { payment_id: string; status: string };
}) {
  if (event.type !== "payment.updated") return;

  await updateLocalPaymentStatus(event.data.payment_id, event.data.status);

  if (event.data.status === "completed") {
    await unlockPurchasedWorkflow(event.data.payment_id);
  }
}

Internal versus external payments

Internal transfers can complete quickly because they move inside the ledger. External Solana sends may have a pending period while the transaction is broadcast and confirmed. Your product should reflect that difference instead of pretending every payment has the same lifecycle.

Production checklist

• Store payment ID immediately.
• Show pending status when settlement is not final.
• Use webhooks to update local state.
• Give users a receipt page or receipt message.
• Expose on-chain signatures when available.
• Do not unlock irreversible goods until the payment is confirmed.