API da Mivy
Conecte seu servidor à Mivy para receber Pix, consultar o saldo da loja e acompanhar eventos em tempo real.
#Endereço da API
As chamadas são enviadas ao backend oficial da Mivy. A documentação descreve a API de recebimentos já utilizada pela carteira do painel. O endereço da documentação não recebe cobranças nem substitui a API.
https://api.mivy.com.br/api/v1#Crie sua chave de acesso
- Entre na Mivy e selecione a loja que receberá os valores.
- Abra Integrações → API e clique em Criar chave.
- Selecione payments:create, payments:read e/ou balance:read, conforme sua integração.
- Copie a chave exibida uma única vez e salve como MIVY_API_KEY no ambiente do seu servidor.
O token mivy_live_ identifica a loja. Não envie storeId, conta bancária ou chave Pix no corpo da cobrança. Guarde o token no servidor; os exemplos não exigem login do comprador nem credenciais do provedor.
#Rotas e permissões
| Método e rota | Permissão | Uso |
|---|---|---|
| GET /status | Chave válida | Verificar autenticação e permissões. |
| POST /payments | payments:create | Gerar um Pix para depositar na carteira da loja. |
| GET /payments | payments:read | Listar recebimentos da API desta loja. |
| GET /payments/{id} | payments:read | Consultar o status e os dados de um Pix. |
| GET /balance | balance:read | Ler o saldo disponível da carteira. |
#Verifique a conexão
/api/v1/statusBearer tokenInclua Authorization: Bearer em todas as chamadas. Este teste só consulta a autenticação; não cria cobrança e não altera saldo.
curl --fail-with-body "https://api.mivy.com.br/api/v1/status" \
-H "Authorization: Bearer $MIVY_API_KEY"{
"data": {
"authenticated": true,
"permissions": [
"payments:create",
"payments:read",
"balance:read"
],
"withdrawalsEnabled": false
}
}#Respostas e limites
A API aceita até 120 chamadas por minuto por chave. Ao receber 429, aguarde o número de segundos informado em Retry-After. A resposta usa data para resultados e error para falhas.
| HTTP | Significado | Ação |
|---|---|---|
| 200 / 201 | Consulta concluída / Pix criado. | Use os dados da resposta. |
| 400 | Dados, UUID ou campos inválidos. | Corrija a solicitação. |
| 401 | Chave inválida, excluída, revogada ou expirada. | Confira o token no painel. |
| 403 | Permissão insuficiente ou conta indisponível. | Confira os escopos da chave e a loja. |
| 404 / 405 | Recurso não encontrado / método incorreto. | Confira a rota, o ID e o método HTTP. |
| 409 | UUID de idempotência já usado com outros dados. | Reenvie os mesmos dados ou use outro UUID para uma nova cobrança. |
| 413 | Corpo maior que 8 KiB. | Reduza o JSON. |
| 429 | Limite de chamadas por chave. | Respeite Retry-After. |
| 500 / 502 / 503 | Falha interna ou indisponibilidade do processamento. | Consulte o pagamento ou repita com o mesmo UUID. |
#Arquivos para integrar
Importe o contrato OpenAPI em sua ferramenta de API. O cliente Node.js usa os mesmos endpoints desta referência e lê sua chave pelo construtor. Nenhum arquivo contém uma credencial real.
import { MivyClient } from './mivy-client.mjs';
const mivy = new MivyClient(process.env.MIVY_API_KEY);
const status = await mivy.getStatus();
console.log(status.authenticated);