Repasses (Pix de saída)
Com repasses a sua empresa envia Pix para qualquer chave: pagar parceiros, sacar saldo, reembolsar fora de uma cobrança.
Importante
Repasses são liberados por contrato. Se a sua empresa ainda não tem a função, POST /api/payouts responde 403 com "Payouts are not enabled for this company". Peça a liberação ao time marx.
Enviar um Pix
POST /api/payouts
Shell
curl -X POST https://marx.loco.ltd/api/payouts \
-H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{
"payout": {
"amount_payout": "250.00",
"pix_key": "financeiro@parceiro.com.br",
"pix_key_type": "EMAIL",
"pix_info": "Comissão outubro",
"reference": "comissao-2026-10-parceiro-12",
"metadata": { "partner_id": "p_12" }
}
}'
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount_payout |
texto | sim | Valor maior que zero, até 2 casas decimais. |
pix_key |
texto | sim | Chave Pix de destino. |
pix_key_type |
texto | recomendado | EVP (aleatória), EMAIL, TELEFONE, CPFCNPJ ou NAO_INFORMADO. Valor diferente → 422. |
pix_info |
texto | não | Mensagem ao recebedor (até 30 caracteres recomendado). |
reference |
texto | recomendado | Seu identificador, único por empresa. Garante que uma nova tentativa não envia o dinheiro duas vezes. |
metadata |
objeto | não | Dados livres seus. |
Atenção
Sempre envie reference. Se a requisição cair por timeout e você repetir com o mesmo reference, a marx devolve o repasse existente (200) em vez de criar outro. Sem reference, cada chamada envia um novo Pix.
Respostas
| Status | Quando |
|---|---|
201 |
Repasse criado e enviado para processamento. |
200 |
Já existia um repasse com esse reference: ele é devolvido, sem novo envio. |
403 |
Repasses não liberados para a sua empresa, ou o Pix foi recusado pela instituição (chave inexistente, limite). O corpo traz o motivo. |
422 |
Campos inválidos. |
JSON
{
"id": "4a5d2c8e-91b7-4f0a-8e3c-6d1b2a9f7e40",
"amount_payout": "250.0",
"pix_key": "financeiro@parceiro.com.br",
"pix_key_type": "EMAIL",
"pix_info": "Comissão outubro",
"reference": "comissao-2026-10-parceiro-12",
"pix_status": "EM_PROCESSAMENTO",
"lifecycle_status": "pending",
"pix_endtoend": "E1234567820261006171512345678901",
"paid_at": null,
"metadata": { "partner_id": "p_12" },
"created_at": "2026-10-06T17:15:12-03:00"
}
Consultar
GET /api/payouts/{id} devolve o mesmo formato (404 se não existir).
Status
pix_status |
lifecycle_status |
Significado |
|---|---|---|
EM_PROCESSAMENTO |
pending |
Enviado, aguardando liquidação. |
REALIZADO |
settled |
Dinheiro entregue. paid_at traz o horário. |
NAO_REALIZADO |
failed |
Não foi possível concluir o envio. |
Você recebe um webhook event_type_payout quando o repasse é realizado ou não realizado.