Ir para o conteúdo
Docs

Cobranças

Crie cobranças PIX com copia e cola e imagem do QR Code, consulte o status e liste com filtros e paginação por cursor.

O objeto cobrança

Uma cobrança representa um PIX a receber. Ela nasce pending com o código copia e cola e a imagem do QR Code, e passa para paid quando o pagador paga.

Campos

  • idstring

    Identificador da cobrança na MaxxiPay.

  • objectstring
    sempre "charge"
  • statusenum

    Situação atual da cobrança.

    pendingpaidexpiredcanceledrefundedfailed
  • amountCentsinteger

    Valor cobrado em centavos.

  • feeCentsinteger · pode ser nulo

    Tarifa da MaxxiPay em centavos. Preenchida quando a cobrança é paga.

  • netCentsinteger · pode ser nulo

    Valor líquido creditado no saldo, em centavos. Preenchido quando a cobrança é paga.

  • currencystring
    sempre "BRL"
  • descriptionstring
  • payerNamestring
  • payerDocumentstring

    CPF ou CNPJ do pagador, só dígitos.

  • pixCopyPastestring · pode ser nulo

    Código PIX copia e cola.

  • pixQrCodestring · pode ser nulo

    Imagem PNG do QR Code em base64, gerada a partir de pixCopyPaste. Nula quando não há código. Exiba com data:image/png;base64,{pixQrCode}.

  • endToEndIdstring · pode ser nulo

    Identificador da transação no PIX, presente depois do pagamento.

  • externalIdstring · pode ser nulo
  • metadataobject · texto → texto
  • failureReasonstring · pode ser nulo
  • expiresAtstring · ISO 8601 · pode ser nulo
  • paidAtstring · ISO 8601 · pode ser nulo
  • createdAtstring · ISO 8601
  • updatedAtstring · ISO 8601
ExemploJSON
{
  "id": "6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
  "object": "charge",
  "status": "paid",
  "amountCents": 4990,
  "feeCents": 99,
  "netCents": 4891,
  "currency": "BRL",
  "description": "Pedido 1042",
  "payerName": "Cliente Exemplo",
  "payerDocument": "52998224725",
  "pixCopyPaste": "00020101021226870014br.gov.bcb.pix2565pix.exemplo.com.br/qr/v2/6f0c1a521d7e4b8a9f432c5e8d9b7a1052040000530398654044.905802BR6304B7C1",
  "pixQrCode": "iVBORw0KGgoAAAANSUhEUgAA…",
  "endToEndId": "E18236120202611021813s0a1b2c3d4e",
  "externalId": "pedido-1042",
  "metadata": {
    "canal": "checkout"
  },
  "failureReason": null,
  "expiresAt": "2026-11-02T19:12:00.000Z",
  "paidAt": "2026-11-02T18:13:41.000Z",
  "createdAt": "2026-11-02T18:12:00.000Z",
  "updatedAt": "2026-11-02T18:13:41.000Z"
}

Criar uma cobrança

POST/v1/charges

Gera uma cobrança PIX com validade de 1 hora e devolve o copia e cola e a imagem do QR Code.

Escopo
charges:write
Idempotency-Key
Obrigatório
Sucesso
201

A empresa precisa estar com a verificação aprovada. Repetir a chamada com a mesma Idempotency-Key devolve a mesma cobrança, com o cabeçalho Idempotent-Replayed: true.

pixQrCode é o PNG do QR Code em base64. Mostre com <img src="data:image/png;base64,...">.

Corpo da requisição

  • amountCentsintegerobrigatório

    Valor da cobrança em centavos. 4990 equivale a R$ 49,90.

    maior que 0máximo 5.000.000.000
  • descriptionstringobrigatório

    Texto exibido ao pagador no app do banco.

    1 a 140 caracteres
  • payerNamestringobrigatório

    Nome completo ou razão social de quem paga.

    3 a 120 caracteres
  • payerDocumentstringobrigatório

    CPF ou CNPJ de quem paga, com ou sem pontuação.

  • externalIdstringopcional

    Identificador do seu sistema, como o número do pedido. Serve para conciliação e para filtrar listas.

    1 a 100 caracteres
  • metadataobject · texto → textoopcional

    Pares chave e valor de texto guardados com o recurso e devolvidos nas respostas e webhooks. Até 20 chaves.

    chaves até 40 caracteresvalores até 500 caracteres

Resposta

Devolve o objeto cobrança com status pending.

Erros desta rota

  • 400idempotency_key_requiredFaltou o cabeçalho Idempotency-Key ou ele tem menos de 8 ou mais de 120 caracteres.
  • 422invalid_bodyUm campo do corpo não passou na validação. O campo vem em error.field.
  • 403account_not_verifiedA conta ainda não foi verificada. Cobranças e saques ficam bloqueados até a aprovação.
  • 403merchant_blockedA conta está bloqueada. Cobranças e saques estão suspensos.
  • 422limit_per_chargeO valor passa do máximo por cobrança da conta. O padrão é R$ 10.000,00 e o valor em vigor vem em error.message.
  • 409idempotency_conflictA Idempotency-Key já foi usada com outro conteúdo.
  • 502processing_failedO processamento PIX recusou a operação. O motivo vem em error.message e em failureReason.

Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.

const response = await fetch("https://api.maxxipay.com/v1/charges", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
    "Idempotency-Key": "pedido-1042",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amountCents: 4990,
    description: "Pedido 1042",
    payerName: "Cliente Exemplo",
    payerDocument: "529.982.247-25",
    externalId: "pedido-1042",
    metadata: {
      canal: "checkout"
    }
  }),
});

const charge = await response.json();
RespostaJSON201 Created
{
  "id": "6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
  "object": "charge",
  "status": "pending",
  "amountCents": 4990,
  "feeCents": null,
  "netCents": null,
  "currency": "BRL",
  "description": "Pedido 1042",
  "payerName": "Cliente Exemplo",
  "payerDocument": "52998224725",
  "pixCopyPaste": "00020101021226870014br.gov.bcb.pix2565pix.exemplo.com.br/qr/v2/6f0c1a521d7e4b8a9f432c5e8d9b7a1052040000530398654044.905802BR6304B7C1",
  "pixQrCode": "iVBORw0KGgoAAAANSUhEUgAA…",
  "endToEndId": null,
  "externalId": "pedido-1042",
  "metadata": {
    "canal": "checkout"
  },
  "failureReason": null,
  "expiresAt": "2026-11-02T19:12:00.000Z",
  "paidAt": null,
  "createdAt": "2026-11-02T18:12:00.000Z",
  "updatedAt": "2026-11-02T18:12:00.000Z"
}

Consultar uma cobrança

GET/v1/charges/{id}

Busca uma cobrança pelo identificador.

Escopo
charges:read
Idempotency-Key
Não se aplica
Sucesso
200

Se a cobrança ainda estiver pending, a consulta confere a situação na rede PIX e já devolve o status atualizado. O webhook continua sendo o jeito recomendado de saber do pagamento.

Enquanto houver código, pixQrCode traz o PNG em base64 para <img src="data:image/png;base64,...">.

Parâmetros de caminho

  • idstringobrigatório

    Identificador da cobrança.

Resposta

Devolve o objeto cobrança.

Erros desta rota

  • 404not_foundO recurso não existe ou pertence a outra empresa.

Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.

const response = await fetch("https://api.maxxipay.com/v1/charges/6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10", {
  headers: {
    Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
  },
});

const charge = await response.json();
RespostaJSON200 OK
{
  "id": "6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
  "object": "charge",
  "status": "paid",
  "amountCents": 4990,
  "feeCents": 99,
  "netCents": 4891,
  "currency": "BRL",
  "description": "Pedido 1042",
  "payerName": "Cliente Exemplo",
  "payerDocument": "52998224725",
  "pixCopyPaste": "00020101021226870014br.gov.bcb.pix2565pix.exemplo.com.br/qr/v2/6f0c1a521d7e4b8a9f432c5e8d9b7a1052040000530398654044.905802BR6304B7C1",
  "pixQrCode": "iVBORw0KGgoAAAANSUhEUgAA…",
  "endToEndId": "E18236120202611021813s0a1b2c3d4e",
  "externalId": "pedido-1042",
  "metadata": {
    "canal": "checkout"
  },
  "failureReason": null,
  "expiresAt": "2026-11-02T19:12:00.000Z",
  "paidAt": "2026-11-02T18:13:41.000Z",
  "createdAt": "2026-11-02T18:12:00.000Z",
  "updatedAt": "2026-11-02T18:13:41.000Z"
}

Listar cobranças

GET/v1/charges

Lista as cobranças da empresa da mais recente para a mais antiga, com filtros e paginação por cursor.

Escopo
charges:read
Idempotency-Key
Não se aplica
Sucesso
200

Parâmetros de consulta

  • limitintegeropcional

    Quantidade de itens por página, de 1 a 100. Padrão 20.

    mínimo 1máximo 100padrão 20
  • cursorstringopcional

    Valor de nextCursor da página anterior. Omita para começar do item mais recente.

    1 a 200 caracteres
  • statusenumopcional

    Filtra pelo status da cobrança.

    pendingpaidexpiredcanceledrefundedfailed
  • externalIdstringopcional

    Filtra pelo externalId informado na criação.

    1 a 100 caracteres
  • createdFromstring · ISO 8601opcional

    Inclui só itens criados a partir deste instante (ISO 8601).

  • createdTostring · ISO 8601opcional

    Inclui só itens criados antes deste instante (ISO 8601).

Resposta

Devolve uma lista paginada de objetos cobrança.

Erros desta rota

  • 422invalid_queryUm parâmetro de consulta é inválido. O parâmetro vem em error.field.
  • 422invalid_cursorO cursor não foi gerado pela API.

Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.

const response = await fetch("https://api.maxxipay.com/v1/charges?status=paid&limit=20", {
  headers: {
    Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
  },
});

const page = await response.json();
RespostaJSON200 OK
{
  "object": "list",
  "data": [
    {
      "id": "6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
      "object": "charge",
      "status": "paid",
      "amountCents": 4990,
      "feeCents": 99,
      "netCents": 4891,
      "currency": "BRL",
      "description": "Pedido 1042",
      "payerName": "Cliente Exemplo",
      "payerDocument": "52998224725",
      "pixCopyPaste": "00020101021226870014br.gov.bcb.pix2565pix.exemplo.com.br/qr/v2/6f0c1a521d7e4b8a9f432c5e8d9b7a1052040000530398654044.905802BR6304B7C1",
      "pixQrCode": "iVBORw0KGgoAAAANSUhEUgAA…",
      "endToEndId": "E18236120202611021813s0a1b2c3d4e",
      "externalId": "pedido-1042",
      "metadata": {
        "canal": "checkout"
      },
      "failureReason": null,
      "expiresAt": "2026-11-02T19:12:00.000Z",
      "paidAt": "2026-11-02T18:13:41.000Z",
      "createdAt": "2026-11-02T18:12:00.000Z",
      "updatedAt": "2026-11-02T18:13:41.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJjIjoiMjAyNi0xMS0wMlQxODoxMjowMC4wMDBaIiwiaSI6IjZmMGMxYTUyIn0"
}
esc