# AI Agent Payment Flow

> Complete sequence diagram for AI agent payments via the SatsRail MCP server. Agent-initiated invoicing, programmatic payment creation, and agent-to-agent Bitcoin transactions.

Source: https://www.satsrail.com/developers/guides/flows/ai-agent/

MCP server + Lightning — AI agents that create invoices and process payments programmatically.

## Flow Overview

This diagram shows how AI agents (Claude, GPT, custom agents) use the SatsRail MCP server to programmatically create orders, generate Lightning invoices, and process payments — no browser, no forms, no redirects. The MCP server wraps the SatsRail REST API and exposes it as tool calls that any MCP-compatible agent can invoke.

## MCP Tools Available

| Tool | Description | Used In |
| --- | --- | --- |
| `create_order` | Create a payment order with optional auto-generated Lightning invoice | Phase 2 |
| `get_order` | Get order details by ID (expandable: invoice, payment, merchant) | Phase 2 |
| `list_orders` | List orders with optional status filter | Phase 4 |
| `cancel_order` | Cancel a pending order | Error recovery |
| `get_invoice` | Get invoice details including bolt11 Lightning string | Phase 2 |
| `check_invoice_status` | Real-time payment status check against the Lightning node | Phase 2, 3 |
| `generate_invoice` | Generate a new invoice for an existing order (on expiry) | Error recovery |
| `list_payments` | List confirmed payments with optional date range filter | Phase 4 |
| `get_payment` | Get payment details | Phase 4 |
| `create_checkout_session` | Create a hosted checkout session with redirect URL | Phase 3 |
| `get_merchant` | Get the current merchant's profile and settings | Phase 1 |
| `list_wallets` | List connected wallets | Phase 1 |

## Step-by-Step Detail

#### Phase 1: Setup

##### 1. Configure MCP Server

Add the SatsRail MCP server to your AI agent's configuration:

```
{
  "mcpServers": {
    "satsrail": {
      "type": "http",
      "url": "https://app.satsrail.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_live_your_key_here" }
    }
  }
}
```

The hosted server authenticates every request with the `sk_live_` key and exposes 45 tools to the agent.

##### 2. Agent Discovers Tools

When the MCP server starts, it connects to the SatsRail API, validates the key, and advertises all available tools (create_order, check_invoice_status, etc.) to the agent. The agent can now invoke any tool as part of a conversation.

---

#### Phase 2: Agent-Initiated Payment

##### 3. Create Order + Invoice

The agent determines a payment is needed (based on conversation context or autonomous task) and calls:

```
create_order({
  amount_cents: 2500,
  currency: "usd",
  description: "Monthly subscription",
  generate_invoice: true,
  payment_method: "lightning"
})
```

SatsRail creates an Order, converts USD → sats, generates a BOLT-11 Lightning invoice from the merchant's node (non-custodial), and returns the order with the bolt11 string.

##### 4. Present Invoice to Payer

The agent now has a BOLT-11 invoice string. Three paths:

- **Path A — Human user:** Agent presents the bolt11 string (and optionally a QR code) in the conversation. User scans with their Lightning wallet.
- **Path B — Another agent:** Agent passes the bolt11 string to another AI agent that has Lightning wallet access. The second agent pays programmatically.
- **Path C — Auto-pay:** If the agent itself has wallet access (via another MCP server or API), it pays the invoice automatically.

##### 5. Verify Payment

After payment, the agent calls `check_invoice_status` to verify:

- **completed:** Agent proceeds — confirms to user, activates service, delivers product
- **pending:** Agent waits and re-polls (e.g., every 5 seconds)
- **expired:** Agent calls `generate_invoice` to create a new invoice for the same order at the current BTC rate

---

#### Phase 3: Agent-Managed Product Sales

##### 6. Checkout Session for Products

For more complex sales, the agent calls `create_checkout_session` to generate a hosted checkout URL. The agent shares this link with the customer (in chat, email, Slack, etc.). The customer completes the payment through the standard SatsRail checkout flow. The agent polls for completion using `check_invoice_status` and confirms when paid.

---

#### Phase 4: Monitoring

##### 7. Transaction Reconciliation

The agent can query transaction history for reporting:

- `list_payments` — retrieve all payments with date range filters
- `list_orders` — check order statuses
- `get_merchant` — get merchant profile and settings

All MCP-initiated transactions are also visible in the SatsRail Dashboard, where the merchant can see agent-initiated vs manual transactions side by side.

## Error Paths

| Error | Trigger | Agent Behavior | Recovery |
| --- | --- | --- | --- |
| MCP Connection Failure | MCP server process crashes or fails to start | Agent detects tool unavailability | Retry MCP connection or fall back to direct REST API calls |
| Invalid Tool Parameters | Agent passes wrong types or missing required fields | MCP server returns structured error with field details | Agent corrects parameters and retries the tool call |
| 429 Rate Limited | Too many API calls per minute | Agent receives rate limit error | Agent implements exponential backoff before retrying |
| Invoice Expired | BOLT-11 invoice TTL exceeded (typically 1 hour) | check_invoice_status returns "expired" | Agent calls `generate_invoice` for a new invoice at current rate |
| Lightning Routing Failure | No route found to recipient node | Payer's wallet returns routing error | Retry later (channel liquidity may change) |
| Invalid API Key | sk_live_ key is wrong or revoked | MCP server answers 401 Unauthorized | Developer checks the Authorization header in the MCP config |

## Example Agent Conversation

User "Charge me $25 for the monthly subscription"

Agent *→ calls create_order(amount_cents: 2500, generate_invoice: true)*

Agent "Here's your Lightning invoice. Scan this QR code or copy the payment string:"

lnbc250u1pj...kqq5yxmetu

User "Paid!"

Agent *→ calls check_invoice_status(invoice_id: "inv_...")*

Agent "Payment confirmed! 25,000 sats received. Your subscription is now active."

User "Show me all payments this month"

Agent *→ calls list_payments(from_date: "2024-01-01")*

Agent "You received 3 payments totaling 75,000 sats ($75.00) this month."

## Build the future of AI payments

Give your AI agents the power to create invoices and process Bitcoin payments.

[AI Agents Docs →](https://www.satsrail.com/developers/guides/ai-agents/) [MCP Server](https://www.satsrail.com/mcp/)