Cobranças Pix

Uma cobrança gera um Pix com valor definido. Você mostra o QR Code ou o código copia e cola ao cliente (ou envia o link de pagamento pronto), e a marx avisa por webhook quando o pagamento cair.

Criar uma cobrança

POST /api/charges

Shell

curl -X POST https://marx.locosrv.com/api/charges \
  -H "X-Client-Id: $MARX_CLIENT_ID" \
  -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "charge": {
      "amount": "149.90",
      "reference": "pedido-1001",
      "pix_info1_name": "Pedido",
      "pix_info1_value": "#1001 - 2 camisetas",
      "pix_expires_in": 1800,
      "metadata": { "customer_id": "c_871", "channel": "app" }
    }
  }'

Campo	Tipo	Obrigatório	Descrição
`amount`	texto	sim	Valor em reais, até 6 dígitos inteiros e 2 decimais (`"149.90"`). Vírgula também é aceita.
`reference`	texto	não	Seu identificador (pedido, fatura). Volta em todas as respostas e webhooks.
`pix_info1_name` / `pix_info1_value`	texto	não	Informação extra exibida no app do banco do pagador (ex.: "Pedido" / "#1001").
`metadata`	objeto ou texto	não	Dados livres seus; voltam nas respostas e webhooks.
`pix_expires_in`	número	não	Por quantos segundos o Pix aceita pagamento, de `60` (1 minuto) a `2592000` (30 dias). Sem o campo, vale o padrão da sua conta (veja abaixo).
`request_ip`, `lat`, `lng`	texto	não	Dados do pagador para antifraude, se você tiver.

Resposta `201`

JSON

{
  "id": "0f6e2a3c-7c1d-4f43-9b2f-5e8d9a4b1c22",
  "pix_txid": "0f6e2a3c7c1d4f439b2f5e8d9a4b1c22",
  "amount": "149.9",
  "amount_system": "2.25",
  "amount_to_pay": "147.65",
  "pix_status": "ATIVA",
  "status": "ATIVA",
  "lifecycle_status": "pending",
  "pix_qrcode": "00020101021226...6304A1B2",
  "payment_url": "https://marx.locosrv.com/pay/kJ8sQ2xYvL0pWm3n",
  "payment_token": "kJ8sQ2xYvL0pWm3n",
  "reference": "pedido-1001",
  "metadata": { "customer_id": "c_871", "channel": "app" },
  "pix_created_at": "2026-10-06T14:03:22-03:00",
  "pix_expires_in": 1800,
  "pix_expires_at": "2026-10-06T14:33:22-03:00",
  "pix_payed_at": null,
  "refunds": [],
  "split": [],
  "created_at": "2026-10-06T14:03:21-03:00"
}

Campo	Significado
`pix_txid`	Identificador do Pix. Use-o para consultar e devolver.
`pix_qrcode`	Código copia e cola (EMV). Para exibir o QR Code, gere a imagem a partir deste texto com qualquer biblioteca de QR.
`payment_url`	Página de pagamento pronta (QR, copia e cola e confirmação automática). Ótima para WhatsApp, e-mail e SMS.
`amount`	Valor cobrado do pagador.
`amount_system`	Taxa da marx (quando o seu contrato define percentual).
`amount_to_pay`	Quanto fica para você: `amount − amount_system`.
`pix_status` / `lifecycle_status`	Situação da cobrança (tabela abaixo).
`pix_expires_in` / `pix_expires_at`	Validade registrada no banco, em segundos, e o horário em que o Pix deixa de aceitar pagamento.
`split`	Recebedores e valores do split. Lista vazia quando não há split.

Validade do Pix

O padrão da conta aparece no painel, em Integração → Validade do Pix, e pode ser alterado lá. Ele vale para as cobranças e os links de pagamento criados sem pix_expires_in. O valor enviado em pix_expires_in vale só para aquela cobrança ou link. Mudar o padrão não altera cobranças já criadas.

Nota

Se a cobrança não puder ser gerada (valor inválido, instabilidade bancária), a resposta é 422 com error e nenhuma cobrança fica criada. É seguro tentar de novo.

Dividir o pagamento (split)

Com o split, parte de cada Pix pago vai direto para a conta de um parceiro quando o pagamento cai, sem passar pelo seu saldo. Você define quanto vai para cada parceiro em cada cobrança, e o restante fica com você.

Importante

O split é liberado por contrato. Os recebedores são cadastrados pelo time marx: cada um precisa ter conta na instituição de pagamento que processa os seus Pix. No cadastro você recebe o recipient_id de cada recebedor.

Shell

curl -X POST https://marx.locosrv.com/api/charges \
  -H "X-Client-Id: $MARX_CLIENT_ID" \
  -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "charge": {
      "amount": "113.50",
      "reference": "pedido-1002",
      "split": [
        { "recipient_id": "8d2f6b1e-4c3a-4e0f-9a7b-1c5d2e3f4a6b", "amount": "3.50" }
      ]
    }
  }'

Campo	Tipo	Obrigatório	Descrição
`split`	lista	não	Recebedores desta cobrança, até 20.
`split[].recipient_id`	texto	sim	ID do recebedor, informado pelo time marx.
`split[].amount`	texto	sim	Quanto vai para esse recebedor, em reais com ponto e até 2 decimais (`"3.50"`), maior que zero.

Regras

Valores fixos, por cobrança. Você calcula a parte de cada recebedor ao criar a cobrança. Exemplo: um pedido de R$ 100,00 com 13,5% de taxa vira uma cobrança de R$ 113,50, com R$ 3,50 para o parceiro e R$ 110,00 para você.
O recebedor recebe exatamente o valor informado.
A soma do split precisa ser menor que amount e deixar com você pelo menos a taxa da marx (amount_system).
O split não muda depois que a cobrança é criada. Para mudar, crie outra cobrança.
Links de pagamento não aceitam split.

A resposta e as consultas trazem split com os recebedores e valores (lista vazia nas cobranças sem split):

JSON

{
  "pix_txid": "5b1c9e7a2d4f4a3e8c6b0d9f1e2a3b4c",
  "amount": "113.5",
  "split": [
    { "recipient_id": "8d2f6b1e-4c3a-4e0f-9a7b-1c5d2e3f4a6b", "amount": "3.5" }
  ]
}

A cobrança com split responde 422, sem criar nada, quando:

o recebedor não existe, está inativo ou é de outra empresa;
o split não está liberado para a sua conta;
a soma não deixa nada para você, ou deixa menos que a taxa da marx;
há mais de 20 recebedores, ou um valor é zero, negativo ou tem mais de 2 decimais.

Atenção

Devoluções de cobranças com split são descontadas integralmente de você: o recebedor fica com a parte dele. O mesmo vale para disputas MED. Combine com seus parceiros como acertar esses casos.

Consultar uma cobrança

GET /api/charges/{pix_txid}

Shell

curl https://marx.locosrv.com/api/charges/0f6e2a3c7c1d4f439b2f5e8d9a4b1c22 \
  -H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" -H "Accept: application/json"

Responde 200 com o mesmo formato da criação. Cobrança inexistente (ou de outra empresa) responde 404.

Dica

Prefira os webhooks à consulta repetida. Use a consulta para conciliar ou quando um webhook não chegar.

Status

`pix_status`	`lifecycle_status`	Significado
`ATIVA`	`pending`	Aguardando pagamento.
`CONCLUIDA`	`settled`	Paga. `pix_payed_at` traz o horário.
`REMOVIDA_PELO_USUARIO_RECEBEDOR`	`removed_by_receiver`	Cancelada antes do pagamento.
`REMOVIDA_PELO_PSP`	`removed_by_psp`	Expirada ou removida pela instituição.
`DEVOLVIDO`	`reversed`	Houve devolução (total ou parcial). Veja `refunds`.

Use lifecycle_status nas suas regras: ele é estável e igual para cobranças, repasses e Pix Automático.

Exibindo o QR Code

JavaScript

import QRCode from 'qrcode'

const charge = await criarCobranca()           // resposta do POST /api/charges
const dataUrl = await QRCode.toDataURL(charge.pix_qrcode, { width: 320, margin: 1 })
document.querySelector('#qr').src = dataUrl     // e um botão "copiar" com charge.pix_qrcode

Próximos passos

Devoluções: devolver total ou parcialmente uma cobrança paga.
Links de pagamento: quando o cliente escolhe a forma de pagamento.
Webhooks: receber a confirmação.

#Cobranças Pix

#Criar uma cobrança

#Resposta 201

#Validade do Pix

#Dividir o pagamento (split)

#Consultar uma cobrança

#Status

#Exibindo o QR Code

#Próximos passos

Cobranças Pix

Criar uma cobrança

Resposta `201`

Validade do Pix

Dividir o pagamento (split)

Consultar uma cobrança

Status

Exibindo o QR Code

Próximos passos