Criar depósito Pix

#Crie a cobrança

A rota de depósito é POST /payments. O cliente recebe o código Pix e o QR Code; a criação da cobrança não credita a carteira. O crédito só é registrado quando o backend confirma o pagamento.

# Gere e guarde este UUID antes da primeira tentativa.
export MIVY_REQUEST_ID="$(node -p 'require("node:crypto").randomUUID()')"

curl --fail-with-body "https://api.mivy.com.br/api/v1/payments" \
  -X POST \
  -H "Authorization: Bearer $MIVY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $MIVY_REQUEST_ID" \
  --data '{"amount":100,"currency":"BRL","description":"Pedido 123","passFee":false,"validityMinutes":30}'

#Campos da solicitação

#Resposta e dados do Pix

Uma nova cobrança retorna 201. Repetir a mesma solicitação retorna 200 e a cobrança existente. pixCode é o código copia e cola; qrCode pode conter a imagem em data URL ou null. Em caso de null, gere o QR Code a partir de pixCode.

{
  "data": {
    "id": "ID_DO_PAGAMENTO",
    "status": "PENDING",
    "amount": 100,
    "requestedAmount": 100,
    "fee": 1.35,
    "netAmount": 98.65,
    "currency": "BRL",
    "description": "Pedido 123",
    "passFee": false,
    "pixCode": "CODIGO_PIX_RETORNADO_PELA_API",
    "qrCode": "data:image/png;base64,...",
    "validityMinutes": 30,
    "expiresAt": "2026-10-17T22:30:00.000Z",
    "paidAt": null,
    "createdAt": "2026-10-17T22:00:00.000Z"
  }
}

#Repita sem duplicar cobranças

Guarde o UUID junto do pedido no seu banco antes de chamar a API. Após timeout ou falha de rede, repita o mesmo corpo com o mesmo UUID. Usar outro UUID representa outra cobrança. O UUID é reservado para a loja inteira, inclusive se você trocar de chave de API.

Alterar valor, descrição, repasse ou validade mantendo o UUID retorna 409. O servidor nunca aceita storeId, taxa manual, beneficiário, dados de saque ou campos adicionais no corpo.

import { MivyClient } from './mivy-client.mjs';

const mivy = new MivyClient(process.env.MIVY_API_KEY);
// MIVY_REQUEST_ID deve ser o UUID já salvo no seu pedido.
const payment = await mivy.createDeposit(
  { amount: 100, description: 'Pedido 123', validityMinutes: 30 },
  { idempotencyKey: process.env.MIVY_REQUEST_ID }
);
console.log(payment.id, payment.status);

#Consulte um pagamento

Substitua ID_DO_PAGAMENTO pelo id recebido ao gerar o Pix. Você só pode consultar recebimentos da API da sua loja. Pagamentos do formulário da carteira ficam no histórico de depósitos do painel.

curl --fail-with-body "https://api.mivy.com.br/api/v1/payments/ID_DO_PAGAMENTO" \
  -H "Authorization: Bearer $MIVY_API_KEY"

#Liste seus recebimentos

Use page de 1 a 1000 e limit de 1 a 100. Os padrões são page=1 e limit=50. A resposta traz data e pagination com page, limit e total; a lista não inclui a imagem qrCode.

curl --fail-with-body "https://api.mivy.com.br/api/v1/payments?page=1&limit=50" \
  -H "Authorization: Bearer $MIVY_API_KEY"

#Receba a confirmação

Cadastre payment.approved em Webhooks ou na sua conexão WebSocket. Os eventos identificam o recebimento por data.paymentId e data.source=api. Consulte GET /payments/{id} quando precisar confirmar o estado atual. O processamento da cobrança continua mesmo se a chave que a criou for excluída.