Payments

Provides a centralized MCP server exposing payment tools for Pagar.me and Woovi/OpenPix via stdio or HTTP.
  • typescript

0

GitHub Stars

typescript

Language

2 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

You run a Model Context Protocol (MCP) server focused on payments integrations. It centralizes Pagar.me and Woovi/OpenPix capabilities, exposing a set of MCP tools that a client can call via stdio or MCP over HTTP. This lets you manage customers, recipients, charges, proofs of payment, refunds, and webhooks from a single, consistent interface.

How to use

You interact with the MCP server using a client that speaks the MCP protocol. You can run the server locally in stdio mode or expose it over HTTP for remote clients. In stdio mode, you start the server and communicate through standard input and output. In HTTP mode, the server provides a dedicated MCP endpoint you can call over the network. The server handles tools for Pagar.me and Woovi/OpenPix, so you can orchestrate payments, Pix charges, card tokenization, and refunds from one place.

How to install

Prerequisites: Node.js 18+ and npm installed on your system. You also need credentials for Pagar.me and/or Woovi/OpenPix.

Install dependencies and build the project, then run in the desired mode.

npm install

Build:

npm run build

Run in stdio mode:

npm start

Development mode:
npm run dev

> Observação: the build process clears dist/ before compiling.

Configuration and running modes

Environment variables configure connections to Pagar.me and Woovi/OpenPix. Create a .env file at the project root or export variables in your environment.

cp env.example .env

Running with MCP over HTTP (optional)

If you want to expose MCP over HTTP, set MCP_HTTP_PORT to the port you want to use. The server will then expose MCP endpoints over HTTP in addition to stdio.

export MCP_HTTP_PORT=3001
npm start

Docker usage

You can build and run the MCP server inside Docker. Health checks and E2E tests are supported.

# Build the image
docker build -t payments-mcp:local .

# Run with MCP over HTTP
docker run --rm -p 3001:3001 --env-file .env -e MCP_HTTP_PORT=3001 payments-mcp:local

Pagar.me — functionalities (tools MCP)

Manage customers, recipients, orders, charges, and tokenization for card payments. The following tools are available.

Pagar.me — customers and recipients

  • pagarme_create_customer
  • pagarme_get_customer
  • pagarme_update_customer_metadata
  • pagarme_create_recipient
  • pagarme_update_recipient_default_bank_account
  • pagarme_get_recipients

Pagar.me — Orders, Pix and Card splits

  • pagarme_get_order
  • pagarme_create_order_pix_split
  • pagarme_create_order_credit_card_split Split 100%: the personal recipient receives 100% of the order amount and bears the processing fees (configured as liable=true and chargeProcessingFee=true in the split).

Pagar.me — Charges

  • pagarme_get_charge
  • pagarme_get_charge_transactions (useful for Pix; the QRCode comes from the transactions)
  • pagarme_capture_charge (when a card was created with capture=false)
  • pagarme_cancel_charge

Pagar.me — Card tokenization

  • pagarme_create_card_token (uses PAGARME_PUBLIC_KEY or publicKey in payload)
  • pagarme_get_token

Woovi/OpenPix — functionalities (tools MCP)

Tools follow OpenPix (Woovi) documentation, including charges, refunds, and webhook verification.

Woovi/OpenPix — Charges (Pix)

- woovi_create_charge (POST /api/v1/charge)
- woovi_get_charge (GET /api/v1/charge/{id})
- woovi_list_charges (GET /api/v1/charge with filters)
- woovi_delete_charge (DELETE /api/v1/charge/{id})

Output is normalized for frontend with fields like brCode, qrCodeImage, paymentLinkUrl, expiresDate, status, plus raw payload.

Woovi/OpenPix — Refunds

- woovi_create_refund (POST /api/v1/refund)
- woovi_list_refunds (GET /api/v1/refund)
- woovi_get_refund (GET /api/v1/refund/{id})
- woovi_get_charge_refunds (GET /api/v1/charge/{id}/refund)
- woovi_create_charge_refund (POST /api/v1/charge/{id}/refund)

Woovi/OpenPix — Webhook verification

  • woovi_verify_webhook_hmac validates webhook HMAC using sha1, base64, and header X-OpenPix-Signature.

Recommended flows

Pix via Pagar.me is the current preferred flow. Create a customer (optional), set up a personal recipient, create a Pix split order, and poll for status. For alternatives, use Woovi/OpenPix to create and monitor charges, then apply refunds if needed.

Card payments via Pagar.me involve optionally creating a card token first, then creating a credit card split order. If you set capture to false, capture later, and you can cancel as needed.

Payload examples (paste-ready)

Pagar.me Pix with 100% split, tokenization example, card-based flow, and Woovi/OpenPix charge examples are provided to help you build requests.

{
  "recipientId": "rp_xxxxxxxxxx",
  "items": [
    { "amount": 15000, "description": "Mensalidade", "quantity": 1 }
  ],
  "customer": {
    "name": "Aluno Exemplo",
    "email": "aluno@exemplo.com",
    "document": "98765432100",
    "type": "individual",
    "address": {
      "street": "Rua Exemplo",
      "number": "100",
      "zipCode": "01001000",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    }
  },
  "pix": { "expiresIn": 3600 },
  "idempotencyKey": "order-pix-pay_001"
}

Woovi/OpenPix — criar charge Pix

{
  "correlationID": "pay_123",
  "value": 15000,
  "comment": "Mensalidade",
  "customer": {
    "name": "Aluno Exemplo",
    "email": "aluno@exemplo.com",
    "phone": "+5511999999999",
    "taxID": "471.737.080-52"
  }
}

Exemplos de verificação de webhook (HMAC)

{
  "secret": "hmac-secret-key",
  "signature": "jgR2XF0PKDiAwHP1s+TryvxMySQ=",
  "body": "{\"event\":\"OPENPIX:CHARGE_COMPLETED\"}"
}

Available tools

pagarme_create_customer

Create a customer in Pagar.me and store reference for future operations.

pagarme_get_customer

Retrieve customer details from Pagar.me.

pagarme_update_customer_metadata

Update customer metadata in Pagar.me.

pagarme_create_recipient

Create a recipient (personal) for split payments.

pagarme_update_recipient_default_bank_account

Update the default bank account for a recipient.

pagarme_get_recipients

List recipients for a given account.

pagarme_get_order

Fetch an orderPix/order details.

pagarme_create_order_pix_split

Create an order with a 100% split to a recipient for Pix.

pagarme_create_order_credit_card_split

Create an order with a 100% split to a recipient for card payments.

pagarme_get_charge

Get details of a charge.

pagarme_get_charge_transactions

List transactions related to a charge, useful for Pix.

pagarme_capture_charge

Capture a charge created with capture=false for card payments.

pagarme_cancel_charge

Cancel an existing charge.

pagarme_create_card_token

Tokenize a card using a public key to obtain card_token.

pagarme_get_token

Retrieve a stored card token.

woovi_create_charge

Create a Pix charge via Woovi/OpenPix.

woovi_get_charge

Get details of a Woovi/OpenPix charge.

woovi_list_charges

List Woovi/OpenPix charges with optional filters.

woovi_delete_charge

Delete a Woovi/OpenPix charge.

woovi_create_refund

Create a refund for a Woovi/OpenPix transaction.

woovi_list_refunds

List refunds for Woovi/OpenPix transactions.

woovi_get_refund

Get details of a Woovi/OpenPix refund.

woovi_get_charge_refunds

List refunds for a specific Woovi/OpenPix charge.

woovi_create_charge_refund

Create a refund for a specific Woovi/OpenPix charge.

woovi_verify_webhook_hmac

Validate webhook HMAC using sha1 and base64 with the X-OpenPix-Signature header.

Built by
VeilStrat
AI signals for GTM teams
© 2026 VeilStrat. All rights reserved.All systems operational