Receber por PIX

Uma cobrança PIX gera um QR Code e um código copia-e-cola que o seu cliente usa para pagar. Quando o pagamento é confirmado, a cobrança muda para paid e você é notificado por webhook (ou pode consultar o status por pull).

Criar uma cobrança

POST /v1/charges/pix — exige o scope charges:create e o header Idempotency-Key (obrigatório por ser uma operação financeira; veja Erros & Idempotência).

O amount é uma string decimal em reais ("199.90") — nunca um número — para não perder precisão. O account_id é a conta do merchant onde a cobrança é emitida.

curl
Node.js

curl -X POST https://api.vmixpay.com.br/v1/charges/pix \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f2a9c1e-8b7d-4e6f-9a1b-2c3d4e5f6a7b" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "external_id": "pedido-123",
    "amount": "199.90",
    "description": "Mensalidade junho",
    "expires_in": 3600,
    "payer": {
      "name": "Cliente Exemplo",
      "document": "00000000000",
      "email": "cliente@email.com",
      "phone": "44999999999"
    }
  }'

import { randomUUID } from "node:crypto";

const res = await fetch("https://api.vmixpay.com.br/v1/charges/pix", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    account_id: "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    external_id: "pedido-123",
    amount: "199.90",
    description: "Mensalidade junho",
    expires_in: 3600,
    payer: {
      name: "Cliente Exemplo",
      document: "00000000000",
      email: "cliente@email.com",
      phone: "44999999999",
    },
  }),
});

const charge = await res.json();

A resposta é 201 para uma cobrança nova (ou 200 num replay com a mesma Idempotency-Key). O amount volta como string:

{
  "charge_id": "9b2f1c7a-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "external_id": "pedido-123",
  "public_id": "pub_AbC123XyZ",
  "status": "pending",
  "amount": "199.90",
  "pix": {
    "txid": "abc123",
    "qr_code": "00020126...5204000053039865802BR...6304ABCD",
    "qr_code_image": "data:image/png;base64,iVBORw0KGgo..."
  },
  "payment": null,
  "created_at": "2026-06-22T12:00:00.000Z",
  "due_date": null,
  "expires_at": "2026-06-22T13:00:00.000Z"
}

qr_code — o payload copia-e-cola (BR Code) que o cliente cola no app do banco.
qr_code_image — uma imagem PNG do QR em data URI (data:image/png;base64,...).
public_id — token opaco da página pública de pagamento.
payment — null enquanto a cobrança está pending; vira o comprovante quando paid.

Erro	Quando
`400` `IDEMPOTENCY_KEY_REQUIRED`	Header `Idempotency-Key` ausente.
`400` `AMOUNT_INVALID`	`amount` malformado (não é string decimal > 0).
`409` `IDEMPOTENCY_KEY_REUSED`	Mesma `Idempotency-Key` com corpo diferente.
`404` `CHARGE_NOT_FOUND`	`account_id` inexistente ou de outro merchant.
`403`	Token sem o scope `charges:create`.

Consultar uma cobrança

GET /v1/charges/{charge_id} — exige charges:read. Devolve a mesma projeção da criação, com o status e (quando paga) o bloco payment.

curl https://api.vmixpay.com.br/v1/charges/9b2f1c7a-3d4e-4f5a-8b6c-7d8e9f0a1b2c \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Uma cobrança de outro merchant (ou inexistente) retorna 404 CHARGE_NOT_FOUND (genérico, tenant-safe).

Cancelar uma cobrança

POST /v1/charges/{charge_id}/cancel — exige charges:create. Só funciona enquanto a cobrança está pending; uma cobrança já paga/expirada retorna 409 CHARGE_NOT_PENDING.

curl -X POST \
  https://api.vmixpay.com.br/v1/charges/9b2f1c7a-3d4e-4f5a-8b6c-7d8e9f0a1b2c/cancel \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Página pública de pagamento

Cada cobrança tem um public_id que monta uma página hospedada onde o pagador paga, sem login:

https://app.vmixpay.com.br/pagar/{public_id}

Compartilhe esse link com o cliente (por e-mail, WhatsApp etc.). A página mostra o QR Code, o copia-e-cola e o valor.

Como saber que a cobrança foi paga

Há duas formas (combine-as para robustez):

Webhook (push): configure um endpoint no painel e receba o evento payment.received assim que a cobrança for paga. Veja Webhooks.
Consulta (pull): chame GET /v1/charges/{charge_id} e verifique se o status virou paid. Útil como reconciliação caso um webhook se perca (o transporte é at-least-once).