Skip to main content
P

PicPay

@codespar/mcp-picpay · v0.2.0-alpha.3

🇧🇷 BrazilPaymentsAuth · API Keybeta20 tools3 env varsprerelease

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.

Get started · freeView docs

MIT · runs locally with your own credentials

Limitations

  • v0.2.0-alpha.3 is a prerelease; npm has no stable release of this package.
  • Hosted calls with a test key are not available: the runtime has not recorded this provider's test behaviour (test venue unclassified).
Package
@codespar/mcp-picpay
Version
0.2.0-alpha.3 · prerelease
npm dist-tag
latest
Category
Payments
Auth
API Key
Country
🇧🇷 Brazil
License
MIT
Transport
stdio · streamable-http

Quickstart

Install, set the credentials, make the first call.

Pick your client. The server runs locally over stdio, with your own credentials.

Add the server to your clientOne config entry. No build step, no SDK required.
Set the environment variables3 variables read by this server's code, listed below.
Restart and make the first callThe agent can call any of the 20 tools. Try create_payment first.
terminal
# Claude Code claude mcp add picpay -e PICPAY_BASE_URL=… -e PICPAY_SELLER_TOKEN=… -e PICPAY_TOKEN=… -- npx -y @codespar/mcp-picpay@0.2.0-alpha.3 # then: /mcp to confirm the server is connected
Environment variables3 variables
PICPAY_BASE_URLPicPay ecommerce API base URL. Defaults to https://appws.picpay.com/ecommerce/public.optional
PICPAY_SELLER_TOKENPicPay seller token used to validate webhook callbacks (x-seller-token header)requiredsecret
PICPAY_TOKENPicPay merchant integration token (sent as x-picpay-token header)requiredsecret

Names read from the package code (@codespar/mcp-picpay@0.2.0-alpha.3). Descriptions and flags come from its manifest. Self-hosted, you hold the credentials.

First call democreate_payment

"Create a PicPay checkout payment. Returns paymentUrl"

tools/callcreate_paymentresult returned

Tools

What your agent can call.

20 tools, as the package's tools/list returns them.

create_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).

get_payment_status

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

cancel_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).

create_plan

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

list_plans

List all subscription plans registered for this merchant.

update_plan

Update an existing subscription plan.

delete_plan

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

create_subscription

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

get_subscription

Retrieve a subscription by id.

cancel_subscription

Cancel an active subscription. Future recurring charges are stopped; past charges are not refunded automatically.

validate_notification

Verify that an incoming webhook callback came from PicPay by comparing the x-seller-token header against PICPAY_SELLER_TOKEN. Use this in your callback handler before trusting the payload, then call get_payment_status to fetch the authoritative status.

refund_payment

Refund a paid PicPay order, optionally partially. Unlike cancel_payment, this is the explicit refund endpoint and accepts a custom amount for partial refunds. The merchant wallet must have enough balance to cover the refund.

Names and descriptions come from the package's tools/list (@codespar/mcp-picpay@0.2.0-alpha.3). A kind (read, write, delete) is shown only when the package annotates its tools or each tool was verified one by one; neither exists for this server yet.

Compatibility

MCP is a protocol. Any client that speaks it can mount this server.

codespar_discover lists this server's tools, but a project with a test key cannot call them yet: the runtime has not recorded what this provider does in test mode, and refuses rather than guess.

Protocol

Any MCP client

stdio · streamable-http

Questions

Before you install.

How do I install the PicPay MCP server?

Run npx -y @codespar/mcp-picpay@0.2.0-alpha.3 and add the config block above to your MCP client: Claude Code, Cursor, Claude Desktop, VS Code, or any MCP-compatible client. No build step, no SDK required.

What can my agent do with PicPay?

PicPay exposes 20 tools for payments. Your agent calls them directly; the full list is above.

How does PicPay authenticate, and how are credentials stored?

PicPay uses API Key. Self-hosted, you hold the credentials: the server reads them from its environment variables.

How does PicPay handle upstream API changes?

Every server is versioned independently on npm. The command on this page pins 0.2.0-alpha.3, the version whose tools are listed here; your agent keeps running it until you change the version.

Is PicPay open source? How do I report a bug?

Yes. PicPay is MIT-licensed and published on npm as @codespar/mcp-picpay, source on GitHub (link in the Details panel). Report issues on the package repository; security issues go to security@codespar.dev, and we respond within 24 hours.

Start in seconds.

Add the config above, set the variables, and your agent calls the tools.

Start in seconds demo
Add the server to your client with the config above.
Set the environment variables listed above.
Ask your agent for the first call.
PicPay — MCP server · 20 tools | CodeSpar