Skip to content

charge.mdx

Latest commit

 

History

History
80 lines (61 loc) · 3.28 KB

charge.mdx

File metadata and controls

80 lines (61 loc) · 3.28 KB
title Charge intent for one-time payments
imageDescription Immediate one-time payments where the full amount is collected in a single request-response cycle

import { Cards } from 'vocs' import { MermaidDiagram } from '../../components/MermaidDiagram' import { TempoChargeCard, StripeMethodCard, LightningMethodCard, SolanaChargeCard, CardMethodCard } from '../../components/cards' import { SpecCard } from '../../components/SpecCard'

Charge [Immediate one-time payments]

The charge intent requests an immediate one-time payment. The client pays a fixed amount and the server settles the transaction before returning the response. This is the simplest MPP payment pattern—one request, one payment, one receipt.

How it works

<MermaidDiagram chart={sequenceDiagram participant Client participant Server participant Network as Payment Network Client->>Server: (1) GET /resource Server-->>Client: (2) 402 + Challenge Note over Client: (3) Fulfill payment Client->>Server: (4) GET /resource + Credential Server->>Network: (5) Settle payment Network-->>Server: (6) Confirmed Server-->>Client: (7) 200 OK + Receipt } />

  1. Client: requests a paid resource
  2. Server: responds with 402 and a Challenge specifying the payment requirements—amount, currency, and recipient
  3. Client: fulfills the payment using the method specified in the Challenge
  4. Client: retries the request with the payment proof as a Credential
  5. Server: verifies the Credential and settles the payment on the underlying network
  6. Network: confirms the payment
  7. Server: returns the resource with a Receipt

When to use charge

Charge is the best intent when each request maps to a single payment with a known cost:

  • Paid API endpoints—Charge per request for data, compute, or content
  • Content access—Pay-per-article, pay-per-query, or pay-per-download
  • Tool calls—MCP tool invocations where each call has a fixed price
  • Simple integrations—No channel setup, no state management, no storage backend

For metered billing, high volume flows such as scraping, or usage-based billing where the total cost isn't known upfront, use the session intent instead.

Request schema

The charge intent defines the following request fields:

Field Type Required Description
amount string Required Payment amount in base units
currency string Required Currency identifier (token address, currency code)
description string Optional Human-readable description of the payment
expires string Optional ISO 8601 expiry timestamp
externalId string Optional Server-defined idempotency key
recipient string Optional Recipient identifier (address, account ID)

Payment methods extend this schema with method-specific fields through methodDetails. For example, Tempo adds chainId and feePayer.

Method integrations

Each payment method defines how charge is fulfilled, verified, and settled on its underlying network.

Specification