io.github.codespar/mcp-picpay — Model Context Protocol (MCP) Server

MCP server for PicPay Business, a BR digital wallet with 60M+ users. It provides tools for checkout payments and Pix-style QR flows via PicPay’s Checkout API, and supports subscriptions on top of checkout using the Recurrency API.

🛠️ Key Features

Tools are centered on payment checkout: create payments, query status, and cancel orders
Supports a redirect URL plus a Pix-style QR code for buyers completing payments in the PicPay app
Includes subscription plan creation using Recurrency

🚀 Use Cases

Build agent-driven payment checkout flows for Brazilian merchants
Generate Pix-style QR payments and track payment outcomes by referenceId
Add recurring subscription payments using plans

⚡ Developer Benefits

Exposes MCP tools for create_payment, get_payment_status, and cancel_payment
Enables subscription management via create_plan from the Recurrency API

⚠️ Limitations

Available tool details beyond the tool list excerpt are not fully provided in the source data

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.

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:

code

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.

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.

Install

Configuration

Environment variables

PICPAY_TOKENrequiredsecret

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

PICPAY_SELLER_TOKENrequiredsecret

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

PICPAY_BASE_URL

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

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp-picpay": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-picpay@0.2.0-alpha.3"
      ],
      "env": {
        "PICPAY_TOKEN": "<YOUR_PICPAY_TOKEN>",
        "PICPAY_SELLER_TOKEN": "<YOUR_PICPAY_SELLER_TOKEN>",
        "PICPAY_BASE_URL": "<YOUR_PICPAY_BASE_URL>"
      }
    }
  }
}

io.github.codespar/mcp-picpay