PicPay

v0.2.0-alpha.1API Keyalpha

Brazilian digital wallet with 60M+ users. Merchant checkout API for payments, recurrency plans, and subscriptions. Alpha release on npm — core payments verified, recurrency payload shapes pending sandbox validation.

20 tools3 env vars🇧🇷 Brazilalpha — pending validation

Install

terminal

$ npm install @codespar/mcp-picpay@alpha

Quickstart

Add this entry to your claude_desktop_config.json (or any MCP-compatible client config).

claude_desktop_config.json

{
  "mcpServers": {
    "picpay": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-picpay@alpha"
      ],
      "env": {
        "PICPAY_TOKEN": "<your_picpay_token>",
        "PICPAY_SELLER_TOKEN": "<your_picpay_seller_token>"
      }
    }
  }
}

After restart, your agent can call any of the 20 tools below — try create_payment first.

Environment variables · 3

Required to authenticate the server. Stored encrypted when using CodeSpar managed hosting.

PICPAY_TOKEN

requiredsecret

PicPay merchant integration token (sent as x-picpay-token header)

PICPAY_SELLER_TOKEN

requiredsecret

PicPay seller token used to validate webhook callbacks (x-seller-token header)

PICPAY_BASE_URL

optional

PicPay ecommerce API base URL. Defaults to https://appws.picpay.com/ecommerce/public.

Available tools · 20

Each tool is independent — your agent loads only what it needs to reduce context and response time.

WRITEcreate_payment

Create a PicPay checkout payment. Returns paymentUrl (redirect the buyer to the PicPay app / web) and qrcode (content + base64 image). The buyer pays inside PicPay; your callbackUrl receives the status update. value is in BRL as a decimal number (e.g. 20.50).

WRITEget_payment_status

Get the status of a payment by referenceId. Typical statuses: created, expired, analysis, paid, completed, refunded, chargeback.

DELETEcancel_payment

Cancel a PicPay order. If the order is unpaid, it is voided. If already paid, this triggers a refund (requires merchant account balance to cover).

WRITEcreate_plan

Create a subscription plan (Recurrency API). Plans define the recurring amount, frequency, and trial.

READlist_plans

List all subscription plans registered for this merchant.

WRITEupdate_plan

Update an existing subscription plan.

DELETEdelete_plan

Delete a subscription plan. Fails if the plan has active subscriptions.

WRITEcreate_subscription

Enroll a buyer in a subscription plan. Returns the subscription record and the buyer-facing authorization URL.

Compatible frameworks

MCP is a protocol — any framework that speaks it can mount this server.

Claude Agent SDKAnthropic

OpenAI AgentsOpenAI

Vercel AI SDKVercel

LangChainLangChain

LlamaIndexLlamaIndex

CrewAICrewAI

MastraMastra

Any MCP clientProtocol

Frequently asked questions

All credentials are encrypted at rest in an isolated vault scoped per organization. OAuth2 tokens are automatically refreshed before expiry. Your agent code never sees raw secrets — it receives scoped, short-lived session tokens.