Emitir boleto

Emitir um boleto é a mesma capacidade de criar uma cobrança PIX — por isso usa o mesmo scope charges:create. O Vmix Pay registra o boleto no banco e devolve a linha digitável, o código de barras, o nosso número e (nos tipos com PIX) o QR Code copia-e-cola.

Antes de começar

Obtenha um access_token Bearer com o scope charges:create (Autenticação). A conta operada é a vinculada ao seu token; emitir boleto não exige KYC aprovado.

Os 3 tipos de boleto

tipo	O que é
boleto	Boleto bancário tradicional (sem PIX). O campo qr_code da resposta vem null.
boleto_hibrido	Boleto com PIX embutido — o pagador pode quitar o mesmo documento por boleto ou lendo o QR Code.
boleto_pix	Boleto + PIX — combina o boleto com um QR Code PIX para pagamento.

Criar um boleto

POST /v1/charges/boleto — exige charges:create e o header Idempotency-Key (obrigatório). O corpo:

• tipo — um dos três tipos acima.
• valorCents — apesar do nome, é uma string decimal em reais ("199.90"), como o amount do PIX. Nunca um número.
• dataVencimento — string no formato YYYY-MM-DD (data válida e futura).
• pagador — dados do cliente final (PII). Endereço obrigatório para o registro no banco; numero é opcional.
• descricao — texto livre, opcional.
• account_id — opcional; se presente, deve bater com a conta do seu token (senão 403).

curl

curl -X POST https://api.vmixpay.com.br/v1/charges/boleto \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Idempotency-Key: 7d8e9f0a-1b2c-4d3e-8f9a-0b1c2d3e4f5a" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "boleto_hibrido",
    "valorCents": "199.90",
    "dataVencimento": "2026-07-15",
    "descricao": "Mensalidade junho",
    "pagador": {
      "nome": "Cliente Exemplo",
      "documento": "00000000000",
      "tipoPessoa": "PESSOA_FISICA",
      "cep": "85000000",
      "cidade": "Guarapuava",
      "logradouro": "Rua Exemplo",
      "numero": "123",
      "uf": "PR"
    }
  }'

Node.js

import { randomUUID } from "node:crypto";

const res = await fetch("https://api.vmixpay.com.br/v1/charges/boleto", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tipo: "boleto_hibrido",
    valorCents: "199.90",
    dataVencimento: "2026-07-15",
    descricao: "Mensalidade junho",
    pagador: {
      nome: "Cliente Exemplo",
      documento: "00000000000",
      tipoPessoa: "PESSOA_FISICA",
      cep: "85000000",
      cidade: "Guarapuava",
      logradouro: "Rua Exemplo",
      numero: "123",
      uf: "PR",
    },
  }),
});

const boleto = await res.json();

A resposta é 201 para um boleto novo (ou 200 num replay idempotente):

{
  "charge_id": "9b2f1c7a-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "public_id": "pub_AbC123XyZ",
  "payment_method": "boleto_hibrido",
  "status": "pending",
  "amount": "199.90",
  "boleto": {
    "nosso_numero": "000000012345678",
    "seu_numero": "pedido-123",
    "linha_digitavel": "00190.00009 01234.567890 12345.678901 2 99990000019990",
    "codigo_barras": "00192999900000199900000001234567891234567890",
    "qr_code": "00020126...5204000053039865802BR...6304ABCD",
    "tipo_cobranca": "boleto_hibrido",
    "data_vencimento": "2026-07-15"
  },
  "created_at": "2026-06-22T12:00:00.000Z"
}

• linha_digitavel — a linha digitável (para digitação no app do banco).
• codigo_barras — o código de barras numérico.
• nosso_numero — o identificador do boleto no banco.
• qr_code — o copia-e-cola PIX nos tipos boleto_hibrido/boleto_pix; null no boleto tradicional.
• public_id — token da página pública de pagamento (/pagar/{public_id}).

Sem PII na resposta

A projeção nunca devolve o pagador nem o beneficiário (PII). Os dados do pagador que você envia são usados só para o registro no banco.

Erro	Quando
400 IDEMPOTENCY_KEY_REQUIRED	Header Idempotency-Key ausente.
400 AMOUNT_INVALID	valorCents malformado.
400 INVALID_DUE_DATE	dataVencimento impossível (ex.: 2026-13-40).
403 ACCOUNT_MISMATCH	account_id informado não bate com a conta do token.
409 IDEMPOTENCY_KEY_REUSED	Mesma Idempotency-Key com corpo diferente.
422 MERCHANT_ADDRESS_REQUIRED	O endereço do beneficiário (sua empresa) está incompleto no cadastro.
502 BANK_UNAVAILABLE	Falha ao registrar no banco; re-tentável.

Baixar o PDF do boleto

GET /v1/charges/boleto/{id}/pdf — exige charges:read. Responde application/pdf como anexo (attachment).

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

Um id que não exista, seja de outro merchant, ou não corresponda a um boleto, retorna 404 genérico (tenant-safe).

Como saber que o boleto foi pago

Igual ao PIX: receba o evento payment.received por webhook ou consulte o status da cobrança com GET /v1/charges/{charge_id} (scope charges:read) até virar paid.