canonical: https://jentic.com/apis/mupag.com.br/mupag # MuPag Public API The MuPag Public API lets Brazilian merchants charge customers by PIX or credit card, open hosted PIX checkout sessions, and run subscriptions on a plan with optional trial days and coupons. Charges carry amount_cents, a customer, optional split rules, and an external reference, and can be listed by status, customer, payment method, and creation date with keyset pagination, cancelled while pending, or refunded in full or in part. Customers are created and updated with name, email, and CPF or CNPJ tax id. Every write takes an Idempotency-Key, and sandbox-only routes simulate a paid or failed charge, advance a subscription's billing cycle, and seed test data. ## For AI agents Create PIX and credit card charges, hosted PIX checkout sessions, subscriptions, customers, and refunds for a Brazilian merchant on MuPag, and simulate payment outcomes in the sandbox. ## Scope Does not issue boletos, handle payouts to bank accounts, or file taxes. Use for PIX and credit card charges, hosted checkout, subscriptions, and refunds for a MuPag merchant only. ## Capabilities - Create a PIX or credit card charge in amount_cents for a new or existing customer, with optional split_rules - Open a hosted checkout session for up to 100 items with success_url and cancel_url - Start a subscription on a plan_id with trial_days, and cancel it immediately or at the end of the period - Refund a charge in full or in part and look up the refund's status - List charges filtered by status, customer_id, payment_method, and a created_at window - Create and update customers with name, email, tax_id, and phone - Simulate a sandbox charge as paid or failed and advance a sandbox subscription's billing ## Use cases ### AI sales agent issuing a PIX charge An AI agent closing a sale in chat needs to hand the buyer a way to pay without the developer building a PIX integration. Through Jentic the agent searches for 'create a PIX charge', loads the MuPag charge operation with its input schema, and sends amount_cents, payment_method pix, and the customer, with a fresh Idempotency-Key and the merchant key injected at call time. It returns the charge to the buyer and later checks the charge list for its status. Example prompt: Call POST `/v1/charges` with amount_cents 15000, payment_method pix, a customer object, and an Idempotency-Key, then read GET `/v1/charges` filtered by customer_id to confirm it ### Hosted checkout for a small online store A store that does not want to collect payment details itself can redirect buyers to a MuPag-hosted checkout. A checkout session takes the items, a success_url, and a cancel_url, plus an optional customer, coupon, UTM parameters, and an expiry of up to 1440 minutes, defaulting to 30. Hosted checkout sessions currently accept PIX as the allowed payment method. Example prompt: Call POST `/v1/checkout-sessions` with two items, success_url and cancel_url on the store domain, and expires_in_minutes 60, and return the session ### Recurring billing for a membership A membership business bills customers each cycle. A subscription is created from a customer_id, a plan_id, and a payment method of PIX or credit card, with optional trial_days and coupon. Cancelling takes a required mode of immediate or end_of_period, so a member who quits keeps access until the period ends. Example prompt: Call POST `/v1/subscriptions` with customer_id, plan_id, payment_method credit_card, and trial_days 7; later call POST `/v1/subscriptions/{id}/cancel` with mode end_of_period ### Testing payment flows in the sandbox Before going live, a developer needs paid and failed outcomes without real money. MuPag's sandbox routes seed minimal merchant test data, mark a sandbox charge as paid or failed through the canonical flow, and bring forward a subscription's next billing cycle, so webhook handlers and reconciliation can be exercised end to end. Example prompt: Call POST `/v1/_test/data/seed`, create a charge, then call POST `/v1/_test/charges/{id}/simulate-paid` with an Idempotency-Key and confirm the status in GET `/v1/charges` ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/v1/charges` | Create a PIX or card charge | | GET | `/v1/charges` | List charges | | POST | `/v1/charges/{chargeId}/refunds` | Request a full or partial refund | | POST | `/v1/checkout-sessions` | Create a hosted checkout session | | POST | `/v1/subscriptions` | Create a subscription | | POST | `/v1/subscriptions/{id}/cancel` | Cancel a subscription | | POST | `/v1/customers` | Create a customer | | POST | `/v1/_test/charges/{id}/simulate-paid` | Simulate a paid sandbox charge | ## Key resources - **Charges** — Create PIX or credit card charges, list them, cancel pending ones, and manage their refunds - **Checkout sessions** — Hosted checkout with items, return URLs, coupons, and expiry - **Subscriptions** — Create a subscription on a plan and cancel it immediately or at period end - **Customers** — Create, list, and update customers with tax id and contact details - **Production activation** — Dashboard-authenticated journey to submit the legal profile and start provider KYC - **Sandbox tools** — Simulate paid or failed charges, advance subscription billing, seed test data, and simulate PSP decisions ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 69 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 85 / 100 - Developer Experience & Jentic Compatibility: 64 / 100 - AI-Readiness & Agent Experience: 67 / 100 - Agent Usability: 94 / 100 - Security: 60 / 100 - AI Discoverability: 49 / 100 - **View full report:** https://jentic.com/apis/mupag.com.br/mupag/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring MuPag by hand means telling sk_test_ and sk_prd_ bearer keys apart, sending an Idempotency-Key on every write, and switching between the sandbox and production hosts. Through Jentic you install once, import MuPag from the API Directory, store the merchant key once, and your agent calls it. - **Permission scoping:** MuPag carries the customer and amount for a new charge in the request body, so rules bound which operations your agent may call, not which customer it bills. You choose the operations it may call, so money-moving ones like refunds and subscription cancellation are not included unless you add them. - **Credential handling:** Your MuPag merchant key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a PIX charge' or 'refund a payment', and Jentic returns the matching MuPag operation with its input schema, including required fields like amount_cents and the Idempotency-Key header, so the agent builds a valid request. ## Related APIs - **Cielo E-commerce API** — Brazilian card acquirer API for online card and PIX payments - **NuPay for Business Checkout API** — Nubank's checkout API for paying with a NuPay account - **Stripe** — Global payments API for cards, wallets, and subscriptions ## FAQ ### What authentication does the MuPag Public API use? The MuPag OpenAPI spec declares two bearer schemes. The merchant API key, sk_test_ for sandbox or sk_prd_ for production, is the default for charges, refunds, checkout sessions, subscriptions, customers, and the sandbox tools. A dashboard session JWT is used instead on the production-activation routes and the CEP lookup. The influencer pre-registration route declares no auth, and the Woovi and Asaas provider webhook receivers check an x-webhook-signature or asaas-access-token header instead of a bearer token. Through Jentic your merchant key is held by your own instance and injected at call time. ### Which payment methods does the MuPag API support? Per the spec, a charge's payment_method is pix or credit_card, and subscriptions take the same two. Hosted checkout sessions accept pix in allowed_payment_methods. Credit card charges use a card_token or saved card_token_id and require payer_ip, and the spec says never to send the raw card number or CVV. ### What are the rate limits for the MuPag Public API? The OpenAPI spec does not state a numeric limit, but it documents HTTP 429 responses for over-limit calls. Check the published spec at https://api.mupag.com.br/openapi.yaml and your merchant dashboard for current limits. ### Which host should I call for the MuPag API? The spec lists https://api.sandbox.mupag.com.br for testing with sk_test_ keys and https://api.mupag.com.br for production, which the spec marks as reserved until your merchant account completes production activation. ### How do I create a PIX charge through Jentic? Search Jentic for 'create a PIX charge', load POST `/v1/charges`, and execute it with amount_cents, payment_method set to pix, a customer, and an Idempotency-Key header. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the MuPag API? Yes. Write a rule that allows only POST `/v1/charges` and GET `/v1/charges`, and the agent can issue and check charges but cannot refund, cancel subscriptions, or edit customers. Keep it on an sk_test_ key while you watch the log of every call it makes.