Error Handling

class PaymentError extends Error {
  code: PaymentErrorCode;
  details?: Record<string, unknown>;
}

import { PaymentError, PaymentErrorCode } from '@payo/mcp';

try {
  // Tool call that might fail
} catch (error) {
  if (error instanceof PaymentError) {
    switch (error.code) {
      case PaymentErrorCode.INSUFFICIENT_BALANCE:
        console.log('Agent needs more credits');
        break;
      case PaymentErrorCode.TOKEN_INVALID:
        console.log('Agent token is invalid');
        break;
    }
  }
}

enum PaymentErrorCode {
  TOKEN_MISSING = 'TOKEN_MISSING',
  TOKEN_INVALID = 'TOKEN_INVALID',
  INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE',
  PLATFORM_UNAVAILABLE = 'PLATFORM_UNAVAILABLE',
  CHARGE_FAILED = 'CHARGE_FAILED',
}

Payment required. [Provider] has enabled Payo micropayments for '[tool]' ($X.XX).

To use this tool:
1. Get your agent token at https://payo.dev/agent/api-keys
2. Add the token to your MCP client's Authorization header
3. Documentation: https://docs.payo.dev/quickstart-agent

Questions? Contact cheng@payo.dev

Invalid or expired agent token. Get a new one at https://payo.dev/agent/api-keys

Insufficient balance for '[tool]' (requires $X.XX, current balance: $Y.YY).

To add funds:
1. Visit https://payo.dev/agent/wallet
2. Top up your account balance

Documentation: https://docs.payo.dev/guides/agent/deposits

{
  required: 0.05,      // Price of the tool
  available: 0.02,     // Agent's current balance
  tool: 'get_weather'
}

Payment service temporarily unavailable. Please try again shortly.
Status: https://status.payo.dev

Payment processing failed. Please try again or contact support.

Agent calls paid tool
         │
         ▼
   Extract token ─────────────────────┐
         │                            │
         │ No token                   │
         ▼                            │
   TOKEN_MISSING ◄────────────────────┘
         │
         │ Has token
         ▼
   Call /api/v1/charge
         │
    ┌────┴────┬─────────┬──────────────┐
    │         │         │              │
    ▼         ▼         ▼              ▼
 Success   Invalid   Balance      Network
           Token     Too Low      Error
    │         │         │              │
    │         ▼         ▼              ▼
    │   TOKEN_INVALID  INSUFFICIENT  PLATFORM_
    │                  _BALANCE      UNAVAILABLE
    │
    ▼
Execute tool
    │
    ▼
Return result

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Payment required for 'get_weather' ($0.01). Get your token at https://payo.dev/agent/api-keys"
  }
}

import { LogLevel } from '@payo/mcp';

const paidServer = withPayments(server, {
  apiKey: process.env.PAYO_API_KEY!,
  pricing: { 'my_tool': 0.01 },
  logLevel: LogLevel.DEBUG,
});

[2024-01-15T10:30:45Z] [payo:info] Charge failed {
  "code": "INSUFFICIENT_BALANCE",
  "tool": "get_weather",
  "agentToken": "sk_l****xyz9",
  "required": 0.01
}