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.loco.ltd/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",
"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. |
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.loco.ltd/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_payed_at": null,
"refunds": [],
"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). |
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.
Consultar uma cobrança
GET /api/charges/{pix_txid}
Shell
curl https://marx.loco.ltd/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.