Skip to main content
OID4Pay
Theme: System
Getting started

Agent quickstart (5 minutes)

Build an agent that makes a test payment against a sandbox 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 sandbox.oid4pay.com.

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 oid4pay-mcp register \
  --setup-token <code-from-wallet-portal> \
  --as-url https://sandbox.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