Skip to main content
OID4Pay
Theme: System
Getting started

Agent quickstart (5 minutes)

Build an agent that makes a test payment against a test-mode merchant. By the end you have the OID4Pay MCP server registered, running, and wired into your MCP client, with the model driving a signed-Offer + PAR + token + KB-JWT round trip against as.oid4pay.com in test mode. Connecting an agent is open to design partners during the developer preview.

Not published yet. The packages are not on npm, PyPI or the Go module proxy yet, so the install commands on this page do not work today. They show the names the packages will ship under.

Prerequisites

Step 1: install the MCP server

npm install -g @oid4pay/oid4pay-mcp

The MCP server wraps the wire shapes so you do not need to implement DPoP proof generation, KB-JWT minting, or PAR posting yourself. It exposes the OID4AC flow as a set of tools your model invokes over the MCP protocol. The same verify-only merchant SDK is available standalone at @oid4pay/oid4ac-merchant; see node.

Step 2: register the agent

Registration mints the agent's DPoP and private_key_jwt keypairs (if not already present), calls the Authorization Server's registration endpoint, and persists the issued client_id locally. Pass the one-shot setup token from your Wallet Portal session.

npx -y @oid4pay/oid4pay-mcp register \
  --setup-token <code-from-wallet-portal> \
  --as-url https://as.oid4pay.com

On success the CLI prints OK registered client_id=... and the state directory holding your keys and registration. The --redirect-uri and --client-name options are available; defaults are applied when omitted.

Step 3: run the server

The server speaks MCP over stdio. Start it with:

oid4pay-mcp serve

The serve subcommand takes no options; it runs the stdio server.

Step 4: wire it into your MCP client

Point your MCP client at the serve command. For example, in a Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "oid4pay": {
      "command": "oid4pay-mcp",
      "args": ["serve"]
    }
  }
}

Restart the client so it picks up the server. The OID4Pay tools become available to the model.

Step 5: let the model call the agent_payment_initiate tool

With the server wired in, the model invokes the agent_payment_initiate tool through the MCP protocol; it is not a JavaScript method you call directly. Prompt the model toward a payment and it supplies the tool arguments. The tool input shape is:

{
  "merchant_url": "https://shop.alpacanica.com",
  "amount": { "currency": "EUR", "amount_minor": 1500 },
  "line_items": [{ "sku": "test-pinata", "qty": 1 }],
  "redirect_uri": "http://127.0.0.1:8765/oid4ac/callback",
  "offer_id": "<offer id from the merchant catalog>",
  "offer_digest": "<offer digest from the merchant catalog>"
}

The tool drives the full OID4AC path: it posts a PAR, runs authorize and token exchange to obtain a JWT-AT and SD-JWT VC mandate, mints the KB-JWT, and presents the mandate to the merchant. When the merchant requires human scan-consent, the tool polls until the principal approves (or returns step_up_required on timeout). The token exchange and any settlement happen at the Authorization Server, reached over HTTP; the tool itself never charges.

Step 6: read the result

The tool returns the payment result. The shape:

{
  "status": "paid",
  "mandate_id": "mandate_test_xyz",
  "receipt_jws": "<compact JWS receipt>",
  "payment_provider_ref": "<provider reference>",
  "order_id": "<merchant order id>"
}

status is one of paid, step_up_required, setup_required, or declined. On a non-paid status the result carries a step_up_url or an error object instead of the receipt fields.

Next steps