Documentação da API do Vmix Pay

O Vmix Pay é um gateway financeiro que permite a integradores receber por PIX, emitir boletos, processar devoluções (refunds) e acompanhar pagamentos em tempo real via webhooks assinados.

A API é REST + JSON sobre HTTPS, versionada por URL (/v1), com idempotência em toda operação financeira e respostas/erros padronizados.

URL base

Todas as chamadas usam a base de produção:

https://api.vmixpay.com.br

Não há ambiente de sandbox

A API do Vmix Pay é de produção. Não existe um ambiente de teste separado: cobranças PIX e boletos criados são reais.

• Para testar a integração, use valores pequenos (ex.: "1.00") e cancele as cobranças de teste que criar.
• Trate o client_secret como uma senha — nunca o exponha em código client-side.

Autenticação em uma frase

Você troca suas credenciais (client_id + client_secret) por um access_token de curta duração no endpoint OAuth2 e usa esse token como Bearer nas chamadas. Veja o passo a passo em Autenticação.

Escopos (scopes)

Cada credencial recebe um conjunto de scopes. Toda rota de negócio exige o scope correspondente — sem ele, a resposta é 403.

Scope	Permite
charges:create	Criar cobranças PIX (POST /v1/charges/pix) e emitir boletos (POST /v1/charges/boleto).
charges:read	Consultar/listar cobranças e baixar o PDF do boleto.
payments:read	Listar pagamentos e eventos, consultar refunds, e ler saldo/extrato da conta.
refunds:create	Criar devoluções (POST /v1/refunds).
webhooks:manage	Gerir endpoints de webhook no painel (não há endpoint público para isso).

Consulta de refund usa payments:read

O scope refunds:create autoriza criar devoluções. Para consultar uma devolução (GET /v1/refunds/{id}) o scope necessário é payments:read — não refunds:create. Veja Refunds.

Por onde começar

AutenticaçãoObter o access_token via OAuth2 client_credentials.

Receber por PIXCriar cobranças e receber pagamentos instantâneos.

Emitir boletoBoleto, boleto híbrido e boleto + PIX avulso.

RefundsDevolver, total ou parcialmente, uma cobrança paga.

WebhooksReceber notificações assinadas (HMAC) de pagamento.

Erros & IdempotênciaIdempotency-Key, envelope de erro e status.

Referência da APIExplorador interativo (OpenAPI) de todos os endpoints.

PostmanCollection para testar a API.