MCP tool

top_up_wallet

Create a prepaid-wallet top-up in GBP. Offline sandbox credits immediately; live and isolated Stripe-test modes create a Stripe Checkout session whose URL must be opened and whose eventual credit must be verified with get_topup_status. This is a consequential money operation: quote the exact amount and obtain explicit user approval immediately before calling. idempotencyKey is mandatory here; reuse it after timeouts. New live/Stripe-test funding intents require a funding-v2: prefix and unique opaque suffix. Existing keys must retain their exact value; a legacy key with no durable history or an uncertain provider outcome requires human operator reconciliation, never a replacement key or blind retry. Changed funding details fail.

Input

Pass fields from this schema as the tool arguments. Runtime ownership, product scope and readiness checks still apply.

Input JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "amountPounds": {
      "type": "number",
      "minimum": 100,
      "maximum": 21474836.47,
      "description": "top-up amount in GBP pounds; minimum £100"
    },
    "agentStepId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "pending execute-step id that consumed the exact approved action"
    },
    "expectedActionDigest": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "SHA-256 digest returned for the exact approved action"
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 200,
      "description": "Retain this exact key for retries. For a genuinely new live/Stripe-test intent use funding-v2: plus a unique opaque suffix; unrecorded legacy keys require operator reconciliation."
    },
    "poNumber": {
      "description": "optional buyer purchase-order reference for reconciliation",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    }
  },
  "required": [
    "amountPounds",
    "agentStepId",
    "expectedActionDigest",
    "idempotencyKey"
  ]
}

REST mapping and authority

The tool wraps this REST endpoint. The mapping identifies path/query/body transformations and approval or idempotency headers.

Request contract

{
  "method": "POST",
  "path": "/api/v1/billing/topup",
  "pathFields": [],
  "pathSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  },
  "pathEncoding": "encodeURIComponent for each path field",
  "governedAction": "billing.topup",
  "headers": {
    "x-chorus-agent-step-id": "agentStepId",
    "x-chorus-agent-action-digest": "expectedActionDigest"
  },
  "bodySchema": {
    "type": "object",
    "properties": {
      "idempotencyKey": {
        "type": "string",
        "minLength": 8,
        "maxLength": 200,
        "description": "Retain this exact key for retries. For a genuinely new live/Stripe-test intent use funding-v2: plus a unique opaque suffix; unrecorded legacy keys require operator reconciliation."
      },
      "poNumber": {
        "description": "optional buyer purchase-order reference for reconciliation",
        "type": "string",
        "minLength": 1,
        "maxLength": 64
      },
      "amountMinor": {
        "type": "integer",
        "minimum": 10000,
        "maximum": 2147483647
      }
    },
    "additionalProperties": false,
    "required": [
      "idempotencyKey",
      "amountMinor"
    ]
  },
  "bodyMapping": {
    "passthroughOtherFields": true,
    "amountMinor": {
      "from": "amountPounds",
      "transform": "Math.round(value * 100)"
    },
    "constants": {}
  },
  "responseMapping": "REST JSON is returned as MCP structuredContent and a compatibility text block; privacy-sensitive tools validate their output schema."
}

Output

This is the registered MCP output envelope. Nested fields are only modeled where the schema explicitly defines them.

Output JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "sandbox": {
      "type": "boolean"
    },
    "checkout": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "url": {
          "anyOf": [
            {
              "type": "string",
              "format": "uri"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "url"
      ],
      "additionalProperties": false
    },
    "creditedMinor": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "stripeTest": {
      "type": "boolean"
    },
    "requestId": {
      "type": "string",
      "minLength": 1
    },
    "idempotentReplay": {
      "type": "boolean"
    },
    "creditConfirmed": {
      "type": "boolean"
    },
    "checkoutUrl": {
      "anyOf": [
        {
          "type": "string",
          "format": "uri"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "sandbox",
    "checkout"
  ],
  "additionalProperties": {}
}

Safety annotations

MCP annotations

{
  "readOnlyHint": false,
  "destructiveHint": true,
  "idempotentHint": true,
  "openWorldHint": true
}

Annotations help a client present the tool. The API independently enforces authorization and exact action approvals. Error and retry guidance →