Pular para o conteúdo
m MARX / docs

/ Recorrência

Pix Automático

O Pix Automático é a recorrência oficial do Pix: o cliente autoriza uma vez no app do banco e as cobranças seguintes são debitadas automaticamente em cada vencimento, sem boleto, cartão ou ação do pagador.

Importante

Disponível sob liberação. Sem ela, todos os endpoints respondem 403 com "Pix Automático is not enabled for this company".

Como funciona

  1. Você cadastra o cliente pagador (nome e CPF/CNPJ).
  2. Cria uma assinatura: periodicidade, valor (fixo ou mínimo), data de início.
  3. O cliente autoriza no app do banco (lendo um QR Code ou recebendo uma notificação).
  4. A cada ciclo, a marx gera a cobrança do ciclo com antecedência e o banco debita no vencimento.
  5. Você recebe webhooks a cada mudança de status da assinatura e das cobranças.

Base dos endpoints: https://marx.loco.ltd/api/pix_automatico. Todos aceitam Idempotency-Key em POST e PATCH.

Clientes

Método Caminho Descrição
POST /customers Cria o cliente (ou devolve o existente com o mesmo documento: 200).
GET /customers Lista (?document=, ?external_id=, paginação page/per_page).
GET /customers/{id} Detalhe.
PATCH /customers/{id} Atualiza (o documento não muda).
JSON
{ "customer": { "external_id": "c_871", "name": "Maria Souza", "document": "12345678909",
                "email": "maria@example.com", "cep": "01310100", "cidade": "São Paulo", "logradouro": "Av. Paulista, 1000", "uf": "SP" } }

name (até 140) e document (CPF com 11 ou CNPJ com 14 dígitos) são obrigatórios; external_id e document são únicos na sua empresa.

Assinaturas

Criar

POST /subscriptions

Shell
curl -X POST https://marx.loco.ltd/api/pix_automatico/subscriptions \
  -H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
  -H "Idempotency-Key: assinatura-c_871-plano-pro" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "subscription": {
      "reference": "assinatura-c_871-pro",
      "customer_id": "0b8f6c1e-2d4a-4b7f-9e13-5a6c7d8e9f01",
      "journey": "qrcode",
      "object": "Plano Pro mensal",
      "periodicity": "MENSAL",
      "start_date": "2026-11-05",
      "amount": "59.90",
      "retry_policy": "PERMITE_3R_7D"
    }
  }'
Campo Regra
reference Seu identificador, único. Repetir devolve a assinatura existente (200).
customer_id ou customer ID de um cliente ou o objeto do cliente (criado na hora).
journey Como o cliente autoriza (abaixo). Padrão qrcode.
periodicity SEMANAL, MENSAL, TRIMESTRAL, SEMESTRAL ou ANUAL.
start_date / end_date Início obrigatório; fim opcional (≥ início).
amount ou min_amount Valor fixo por ciclo, ou valor mínimo (o valor de cada ciclo é informado na cobrança). Não envie os dois.
initial_amount Valor cobrado na hora da adesão (obrigatório na jornada qrcode_with_payment).
retry_policy NAO_PERMITE (padrão) ou PERMITE_3R_7D (até 3 novas tentativas em 7 dias após uma falha).
auto_charge true (padrão): a marx cria as cobranças de cada ciclo sozinha.
contract, object Identificação do contrato e descrição exibidas ao pagador (até 35 caracteres).
metadata Dados livres seus.

Jornadas de autorização

journey Como o cliente autoriza
qrcode Você mostra o QR Code / copia e cola (pix_copia_e_cola da resposta) e o cliente autoriza no app.
qrcode_with_payment Igual, mas o cliente já paga initial_amount no mesmo passo.
push O pedido de autorização chega direto no app do banco do cliente. Envie destinatario com agencia, conta e ispb_participante (ou chame request_authorization depois).

Status da assinatura

status lifecycle_status Significado
CRIADA pending Aguardando o cliente autorizar.
APROVADA approved Autorizada: os ciclos serão cobrados.
REJEITADA failed O cliente recusou.
EXPIRADA expired O prazo para autorizar acabou.
CANCELADA cancelled Cancelada por você ou pelo cliente.

Outras ações

Método Caminho Descrição
GET /subscriptions Lista (?reference=, ?status=, ?customer_id=).
GET /subscriptions/{id} Detalhe, com pix_copia_e_cola, next_due_date e cliente.
POST /subscriptions/{id}/request_authorization Reenvia o pedido de autorização (jornada push), com destinatario.
POST /subscriptions/{id}/cancel Cancela a assinatura e as cobranças futuras ainda não enviadas.
POST /subscriptions/{id}/sync Atualiza o status agora (normalmente não é necessário).

Cobranças do ciclo

Com auto_charge: true a marx cria a cobrança de cada ciclo entre 2 e 10 dias antes do vencimento. Você também pode criar manualmente (obrigatório quando a assinatura usa min_amount):

POST /subscriptions/{subscription_id}/charges

JSON
{ "charge": { "due_date": "2026-12-05", "amount": "72.40", "reference": "ciclo-2026-12", "info_adicional": "Consumo de novembro" } }

Regras: a assinatura precisa estar APROVADA; due_date deve estar no período da assinatura e pelo menos 2 dias à frente; com valor fixo, amount precisa ser igual a ele; com mínimo, maior ou igual. Já existindo cobrança para a data, ela é devolvida (200).

Método Caminho Descrição
GET /subscriptions/{id}/charges Cobranças da assinatura.
GET /charges/{id} Detalhe de uma cobrança do ciclo.
POST /charges/{id}/cancel Cancela antes do débito.
POST /charges/{id}/retry Nova tentativa após falha ({"date": "AAAA-MM-DD"}), só com PERMITE_3R_7D.
POST /charges/{id}/refund Devolução (veja abaixo).
POST /charges/{id}/sync Atualiza o status agora.
status lifecycle_status Significado
CRIADA / ATIVA pending Agendada, aguardando o débito.
CONCLUIDA settled Paga.
REJEITADA failed O débito falhou (ex.: saldo insuficiente).
EXPIRADA expired Venceu sem pagamento.
CANCELADA cancelled Cancelada.
(qualquer, com devolução concluída) reversed Houve devolução.

Devoluções

POST /charges/{id}/refund com {"refund": {"amount": "72.40", "refund_id": "DEVCICLO12"}}. Só para cobranças CONCLUIDA. amount é opcional (padrão: valor total) e refund_id é gerado se você não enviar. Funciona como em Devoluções: várias parciais até o valor pago.

Webhooks

Evento Quando
event_type_pix_automatico_subscription A assinatura muda de status (autorizada, recusada, expirada, cancelada).
event_type_pix_automatico_charge Uma cobrança do ciclo muda de status, ou uma devolução termina.

O payload traz o mesmo objeto da API (assinatura ou cobrança). Veja Webhooks.

Erros específicos

Status Corpo Quando
422 { "error": "...", "details": { "campo": ["mensagem"] } } Validação.
422 / 502 { "error": "...", "details": { … } } Recusa (details traz o motivo informado pela rede Pix) ou indisponibilidade. 502 é temporário: tente de novo.
404 { "error": "Not found" } Recurso inexistente ou de outra empresa.

Dúvidas sobre a integração? Fale com o time marx pelo seu canal de suporte.

© 2026 marx