Moonip Integration Guide

Welcome. This guide is everything you need to accept payments through Moonip — from your first API call to receiving signed webhooks in production.

#What Moonip gives you

Moonip is a Pix-first payment gateway. You create a Cobrança (charge) through a single canonical API and we route it to the right PSP/adquirente behind the scenes; the response gives you a BR Code and QR Code ready to render in your checkout. Card, MB WAY, Multibanco and crypto rails exist on the same account when enabled, but PIX is the entry point for every new integration.

Your application never talks to the PSP directly, never holds card data, and never has to change when we add or rotate underlying providers — the provider field and any PSP identifier are stripped by the serializer before the response reaches you (see API conventions §3).

┌────────────┐               ┌──────────┐                ┌─────────────┐
│            │ POST /charges │          │   routing      │  PSP/       │
│  Your app  ├──────────────▶│  Moonip   ├───────────────▶│  adquirente │
│            │◀──────────────┤          │◀───────────────┤  (interno)  │
└──────┬─────┘  BR Code / QR └────┬─────┘   status       └─────────────┘
       │                          │
       │     signed webhook       │
       │◀─────────────────────────┘
       │   charge.paid
       ▼
   Order fulfilled

#Supported payment methods

PIX is the primary rail for Brazilian merchants and the flow every new integration should start with.

Availability is per account. The methods above are enabled individually for your account — a method you have not been enabled for is rejected at charge creation, not at checkout. Ask your Moonip contact which rails are active before building against one.

#Read these in order

1. Getting Started — Auth, environments, conventions, your first call
2. PIX — End-to-end PIX flow with code samples
3. Webhooks — Register endpoints, verify signatures, handle retries
4. Errors — Error shape, status code map, retry strategies
5. API Reference — Every endpoint, every field, every status

Once you have PIX working end-to-end with webhooks, the other methods are tiny variations of the same flow:

• Card payments
• MB WAY
• Multibanco

Receiving payments is half the system. The other half is moving balance out:

• Payouts / Withdrawals — PIX out, TED (Saque)
• Payout failures — the refusal contract: INSUFFICIENT_BALANCE, the failure_code values, and processor liquidity
• Disputes and MED — Pix chargeback (BACEN MED): hold, MED case API and webhooks, appeal, evidence upload and outcomes

Refunds are not part of the API: they are issued from the Moonip admin panel (POST /v1/payments/{id}/refund answers 403 to every API key — error.code "forbidden", message prefixed with the REFUND_ADMIN_ONLY marker).

Operating your account:

• API Keys — Issue, list, rotate, and revoke keys via dashboard or HTTP API
• Official SDKs — Node.js, Python, PHP and .NET

#The contract you build against

This guide documents the Moonip v1 public contract: the Authorization: Bearer header with ak_test_* / ak_live_* keys (the legacy apikey header is still accepted), POST /v1/charges returning a ch_… id, and X-Moonip-* webhook headers. That is the surface — there is nothing older you need to know about.

A couple of resource paths are worth noting: payouts live at /v1/withdrawals, your balance at /v1/wallets, and the list of charges with cursor pagination at /v1/charges. Should a canonical /v1/payouts alias land later, the current path keeps working and ships Deprecation / Sunset headers well before any removal.

#Sandbox

• Sandbox — same host and contract as production, with a ak_test_* key: the charge goes to the simulator, artifacts carry the SANDBOX marker, and POST /v1/payments/{id}/confirm-sandbox forces PAID so you can test webhooks end to end.

#Need help?

Email suporte@moonip.io with your request_id — every API error carries one, and it locates the exact request in our logs.

• Polling and limits