About mcp-picpay
mcp-picpay is an MCP server for PicPay Business, a Brazilian digital wallet. It is aimed at merchants and agent developers who need checkout, Pix-style QR codes, subscriptions and transfers. Tools cover payments, recurring plans and wallet balance.
Key features
- 01Create, query and refund payments
- 02Generate static and dynamic PicPay QR codes
- 03Manage subscription plans and subscriptions
- 04Send B2P transfers to PicPay users
- 05Validate webhook callbacks with the seller token
Use cases
- 01Generate payment links or QR codes and track order status
- 02Manage recurring plans and enroll buyers in subscriptions
- 03Send batch transfers to PicPay users and review transaction history
- 04Verify notification origin before processing callbacks
MCP support
The server exposes PicPay checkout, subscription, transfer and wallet endpoints as MCP tools for MCP clients to call.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @codespar/mcp-picpayPICPAY_TOKENSecretPicPay merchant integration token (sent as x-picpay-token header)PICPAY_SELLER_TOKENSecretPicPay seller token used to validate webhook callbacks (x-seller-token header)PICPAY_BASE_URLPicPay ecommerce API base URL. Defaults to https://appws.picpay.com/ecommerce/public.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
20Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| buyer | object | No | Buyer identity. document (CPF) is required by BCB rules. |
| buyer.email | string | No | |
| buyer.phone | string | No | E.164 or BR format (e.g. +55 11 91234-5678) |
| buyer.document | string | Yes | CPF, digits only or formatted |
| buyer.lastName | string | Yes | |
| buyer.firstName | string | Yes | |
| value | number | Yes | Amount in BRL, decimal (e.g. 100.50). Not cents. |
| expiresAt | string | No | ISO-8601 expiration timestamp (e.g. 2026-12-31T23:59:59-03:00) |
| returnUrl | string | Yes | URL the buyer is redirected to after completing payment in the PicPay app. |
| callbackUrl | string | Yes | HTTPS endpoint PicPay POSTs to on status changes. Validate via x-seller-token header. |
| referenceId | string | Yes | Merchant-side unique identifier for this order. Used in subsequent status/cancel calls. |
Details
From the project README@codespar/mcp-picpay
MCP server for PicPay Business — Brazilian digital wallet with 60M+ users.
PicPay's Checkout API lets merchants create a payment intent that the buyer completes inside the PicPay app, returning a redirect URL plus a Pix-style QR code. The Recurrency API adds subscription plans on top.
Tools (20)
| Tool | Purpose |
|---|---|
create_payment | Create a PicPay checkout payment. |
get_payment_status | Get the status of a payment by referenceId. |
cancel_payment | Cancel a PicPay order. |
create_plan | Create a subscription plan (Recurrency API). |
list_plans | List all subscription plans registered for this merchant. |
update_plan | Update an existing subscription plan. |
delete_plan | Delete a subscription plan. |
create_subscription | Enroll a buyer in a subscription plan. |
get_subscription | Retrieve a subscription by id. |
cancel_subscription | Cancel an active subscription. |
validate_notification | Verify that an incoming webhook callback came from PicPay by comparing the x-seller-token header against PI... |
refund_payment | Refund a paid PicPay order, optionally partially. |
create_b2p_transfer | Create a Business-to-Person (B2P) transfer: push funds from the merchant wallet to a PicPay user identified... |
get_b2p_transfer | Get the status of a B2P transfer by referenceId. |
create_batch_payment | Submit a batch of B2P transfers in a single request. |
list_transactions | List merchant transactions (payments and transfers) within a date range. |
get_wallet_balance | Retrieve the merchant's current PicPay wallet balance (available and blocked amounts in BRL). |
generate_static_qrcode | Generate a static PicPay Pay QR code for in-store / reusable use. |
generate_dynamic_qrcode | Generate a dynamic PicPay Pay QR code with a fixed amount and optional expiration. |
create_payment_link | Create a shareable PicPay payment link. |
Install
npm install @codespar/mcp-picpay@alpha
Environment
PICPAY_TOKEN="..." # Merchant integration token (x-picpay-token header)
PICPAY_SELLER_TOKEN="..." # Seller token used to validate webhook callbacks
PICPAY_BASE_URL="..." # Optional. Defaults to https://appws.picpay.com/ecommerce/public
Authentication
Every request sends:
Content-Type: application/json
x-picpay-token: <PICPAY_TOKEN>
PicPay webhook callbacks carry x-seller-token: <PICPAY_SELLER_TOKEN>. Use the validate_notification tool (or compare the header yourself) before trusting a payload, then fetch the authoritative status with get_payment_status.
Run
# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-picpay
# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-picpay
Status
0.1.0-alpha.1. Core checkout endpoints (/payments, /payments/{ref}/status, /payments/{ref}/cancellations) are verified against PicPay's public docs. Recurrency (plans + subscriptions) endpoints come from the documented path shape but field-level schemas (frequency enum values, subscription response) should be confirmed against the live API before production use.
Enterprise
Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.
License
MIT
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.