Aparência

Módulo: Cartão de Crédito ​

Documentação completa do módulo de controle e liquidação de pagamentos via cartão de crédito.

Sumário ​

  1. Visão Geral
  2. Arquitetura e Fluxo
  3. Regras de Negócio
  4. Tabelas
  5. Endpoints
  6. Job D+1 (Automático)
  7. Glossário de Status

Visão Geral ​

O módulo de Cartão de Crédito implementa um ledger segregado para pagamentos realizados via cartão, separado do ledger financeiro global (transactions).

O fluxo possui dois momentos distintos:

  1. Entrada — Quando uma cobrança é paga via cartão, o valor é registrado em card_transactions com status PENDING. O saldo global ainda não é afetado.
  2. Saída / Retirada — Quando um card_withdrawal é criado (manual ou automaticamente via job D+1), os valores pendentes são consolidados, uma transaction global é gerada e os registros são marcados como WITHDRAWN.

Arquitetura e Fluxo ​

Cobrança paga via CREDIT_CARD
        │
        ▼ [ChargeObserver — automático]
   card_transactions
   (status: PENDING)
        │
        ├─── Job D+1 ────────────────────────────── diário, 06:00, dias úteis
        │
        └─── POST /card-withdrawals ─────────────── manual, acionado pelo operador
                     │
                     ▼
     card_withdrawals (tipo: AUTOMATIC | MANUAL)
                     │
                     ▼
     transactions (ledger global, tipo: credit-card-settlement)

Separação de responsabilidades:

TabelaResponsabilidade
card_transactionsRegistra cada pagamento recebido via cartão. Valores bruto, taxa e líquido segregados.
card_withdrawalsConsolida N transações de cartão em uma única retirada.
transactionsLedger global do sistema. Recebe o valor líquido da retirada.

Regras de Negócio ​

RN-01 — Criação automática de card_transaction ​

Quando uma Charge tem seu status_id atualizado para paid e o campo payment_method for CREDIT_CARD, CARD ou DEBIT_CARD, o ChargeObserver cria automaticamente um registro em card_transactions.

  • O gross_amount é o valor pago (amount_paid da cobrança).
  • O fee_amount é calculado com base na taxa do gateway (por padrão 0 até integração completa).
  • O net_amount = gross_amount − fee_amount.
  • O expected_settlement_date é calculado como D+1 útil a partir do payment_date.
  • O status inicial é sempre PENDING.

RN-02 — Validação de idempotência ​

Antes de criar qualquer transaction global durante uma retirada, o sistema verifica se há registros PENDING no período solicitado. Se não houver, retorna 200 OK sem criar registros.

RN-03 — Retirada Manual (tipo MANUAL) ​

Acionada via POST /consolidation/card-withdrawals. O operador pode opcionalmente:

  • Definir payment_date_until para retirar apenas pagamentos até uma data específica.
  • Adicionar uma notes explicativa.

Todos os card_transactions com status = PENDING e payment_date <= payment_date_until da conta autenticada são incluídos.

RN-04 — Liquidação Automática D+1 (tipo AUTOMATIC) ​

O job ConsolidateCardTransactionsJob é agendado para rodar todo dia útil às 06:00.

  • Agrupa card_transactions com status = PENDING e payment_date <= ontem.
  • Processa cada conta em transação de banco separada (DB::transaction).
  • Falhas em uma conta não afetam as demais.
  • Logs são gravados em canal daily.

RN-05 — Imutabilidade após retirada ​

Uma vez que um card_transaction é marcado como WITHDRAWN, ele não pode mais ser incluído em novas retiradas. O card_withdrawal_id é usado para rastreabilidade completa.

RN-06 — Geração da transaction global ​

A Transaction global criada na retirada segue os mesmos padrões do ledger existente:

  • type_id → TransactionType com slug credit-card-settlement (criado automaticamente na primeira vez).
  • value → net_amount total da retirada.
  • balance → calculado como saldo_atual + net_amount.
  • sequence → incrementa o último sequence da conta.
  • txid → gerado com prefixo CC-SETTLE- (automático) ou CC-WITHDRAW- (manual).

RN-07 — Acesso por conta ​

Todos os endpoints são protegidos pelo middleware auth:sanctum + SetActiveAccountMiddleware + InjectAccountIntoRequest. Cada conta só enxerga seus próprios registros.

Tabelas ​

card_transactions ​

ColunaTipoDescrição
idbigintPK
account_idFKConta proprietária
charge_idFK (nullable)Cobrança que originou o pagamento
acquirerstringGateway: pagmaxx, stripe, cielo
acquirer_tidstringID da venda no gateway
acquirer_nsustringNSU da transação
brandstringBandeira: visa, mastercard, elo
installmentstinyintNúmero de parcelas (padrão: 1)
payer_namestringNome do pagador
payer_documentstringCPF/CNPJ do pagador
gross_amountdecimalValor bruto cobrado
fee_amountdecimalTaxa do gateway
net_amountdecimalValor líquido (gross − fee)
statusenumPENDING | WITHDRAWN
payment_datedateData do pagamento
expected_settlement_datedateD+1 útil previsto
card_withdrawal_idFK (nullable)Retirada que liquidou este registro
metadatajsonResposta bruta do gateway

card_withdrawals ​

ColunaTipoDescrição
idbigintPK
account_idFKConta
transactions_countintQuantidade de card_transactions incluídos
gross_amountdecimalSoma dos valores brutos
fee_amountdecimalSoma das taxas
net_amountdecimalValor líquido transferido
period_startdateMenor payment_date incluído
period_enddateMaior payment_date incluído
typeenumAUTOMATIC | MANUAL
statusenumCOMPLETED
transaction_idFK (nullable)Transaction global gerada
requested_byFK (nullable)Usuário que solicitou (retiradas manuais)
notestextObservações

Endpoints ​

URL base: \{base_url\}/consolidation
Autenticação: Bearer Token (Sanctum)
Headers obrigatórios: Authorization: Bearer \{token\}, X-Account-Id: \{account_id\}

Transações de Cartão ​

GET /consolidation/card-transactions ​

Lista paginada das transações de cartão da conta autenticada.

Query Params

ParâmetroTipoObrigatórioDescrição
statusstringNãoPENDING ou WITHDRAWN
payment_date_startdate (Y-m-d)NãoData inicial do pagamento
payment_date_enddate (Y-m-d)NãoData final do pagamento
per_pageintegerNãoItens por página (padrão: 15, máx: 500)
pageintegerNãoPágina atual

Response 200 OK

json
{
  "success": true,
  "message": "Transações de cartão recuperadas com sucesso.",
  "data": {
    "data": [
      {
        "id": 1,
        "acquirer": "pagmaxx",
        "acquirer_tid": "TID_ABC123",
        "acquirer_nsu": "NSU_001",
        "brand": "visa",
        "installments": 1,
        "payer": {
          "name": "João Silva",
          "document": "12345678900"
        },
        "amounts": {
          "gross": 150.00,
          "fee": 4.50,
          "net": 145.50
        },
        "status": "PENDING",
        "payment_date": {
          "raw": "2026-04-05",
          "formatted": "05/04/2026",
          "iso": "2026-04-05T00:00:00.000Z"
        },
        "expected_settlement_date": {
          "raw": "2026-04-06",
          "formatted": "06/04/2026",
          "iso": "2026-04-06T00:00:00.000Z"
        },
        "card_withdrawal_id": null,
        "charge_id": 501
      }
    ],
    "current_page": 1,
    "per_page": 15,
    "total": 42
  }
}

GET /consolidation/card-transactions/summary ​

Totalizador do período: valores brutos, taxas e líquidos separados por status.

Query Params

ParâmetroTipoObrigatórioDescrição
payment_date_startdate (Y-m-d)NãoData inicial
payment_date_enddate (Y-m-d)NãoData final

Response 200 OK

json
{
  "success": true,
  "message": "Resumo das transações de cartão.",
  "data": {
    "total": {
      "count": 18,
      "gross": 3200.00,
      "fee": 96.00,
      "net": 3104.00
    },
    "pending": {
      "count": 5,
      "net": 725.50
    },
    "withdrawn": {
      "count": 13,
      "net": 2378.50
    }
  }
}

Retiradas (Withdrawals) ​

GET /consolidation/card-withdrawals ​

Histórico de retiradas realizadas pela conta.

Query Params

ParâmetroTipoObrigatórioDescrição
created_at_startdate (Y-m-d)NãoData inicial de criação
created_at_enddate (Y-m-d)NãoData final de criação
per_pageintegerNãoItens por página (padrão: 15)

Response 200 OK

json
{
  "success": true,
  "message": "Retiradas de cartão recuperadas com sucesso.",
  "data": {
    "data": [
      {
        "id": 3,
        "type": "MANUAL",
        "status": "COMPLETED",
        "transactions_count": 5,
        "amounts": {
          "gross": 850.00,
          "fee": 25.50,
          "net": 824.50
        },
        "period": {
          "start": { "raw": "2026-04-01", "formatted": "01/04/2026" },
          "end":   { "raw": "2026-04-04", "formatted": "04/04/2026" }
        },
        "transaction_id": 9012,
        "transaction": {
          "id": 9012,
          "txid": "CC-WITHDRAW-A1B2C3D4",
          "description": "Retirada de Cartão Manual — 5 transação(ões)...",
          "value": 824.50,
          "balance": 10824.50
        },
        "notes": "Retirada quinzenal",
        "created_at": { "raw": "2026-04-06", "formatted": "06/04/2026" }
      }
    ],
    "total": 3
  }
}

POST /consolidation/card-withdrawals ​

Cria uma retirada manual. Consolida todos os card_transactions com status = PENDING e payment_date <= payment_date_until.

Importante: Esta operação é atômica. Cria o CardWithdrawal, a Transaction global e marca as transações como WITHDRAWN em uma única transação de banco. Em caso de erro, tudo é revertido.

Request Body

CampoTipoObrigatórioDescrição
payment_date_untildate (Y-m-d)NãoInclui transações até esta data (padrão: ontem)
notesstringNãoObservação sobre a retirada (máx. 500 caracteres)

Exemplo

json
{
  "payment_date_until": "2026-04-05",
  "notes": "Retirada quinzenal de cartão"
}

Response 201 Created

json
{
  "success": true,
  "message": "Retirada realizada com sucesso! Saldo transferido para o ledger global.",
  "data": {
    "id": 4,
    "type": "MANUAL",
    "status": "COMPLETED",
    "transactions_count": 7,
    "amounts": {
      "gross": 1200.00,
      "fee": 36.00,
      "net": 1164.00
    },
    "period": {
      "start": { "raw": "2026-03-30", "formatted": "30/03/2026" },
      "end":   { "raw": "2026-04-05", "formatted": "05/04/2026" }
    },
    "transaction_id": 9100,
    "transaction": {
      "id": 9100,
      "txid": "CC-WITHDRAW-F5E4D3C2",
      "value": 1164.00,
      "balance": 12988.00
    }
  }
}

Erro — Sem saldo pendente (200 OK)

json
{
  "success": true,
  "message": "Não há transações de cartão pendentes para retirada neste período.",
  "data": null
}

GET /consolidation/card-withdrawals/\{id\} ​

Detalhe de uma retirada específica, incluindo a lista de card_transactions liquidadas.

Path Params

ParâmetroTipoDescrição
idintegerID da retirada

Response 200 OK — igual ao POST, com cardTransactions adicionado.

POST /consolidation/card-withdrawals/run-d1-job ​

Dispara manualmente o job D+1 de liquidação automática. Uso administrativo.

Não requer body. O job é enfileirado na fila padrão do sistema.

Response 200 OK

json
{
  "success": true,
  "message": "Job de liquidação D+1 disparado com sucesso.",
  "data": null
}

Job D+1 Automático ​

ConsolidateCardTransactionsJob ​

Arquivo: app/Jobs/ConsolidateCardTransactionsJob.php
Agendamento: Todo dia útil às 06:00 (configurado em routes/console.php)
Fila: padrão
Tentativas: 3 (backoff: 60 segundos)

Processo:

1. Define `until` = ontem (Carbon::yesterday())
2. Busca account_ids com card_transactions PENDING até `until`
3. Para cada conta:
   a. Inicia DB::transaction
   b. Coleta os IDs dos card_transactions a liquidar
   c. Cria Transaction global (tipo: credit-card-settlement)
   d. Cria CardWithdrawal (tipo: AUTOMATIC)
   e. Atualiza card_transactions → status=WITHDRAWN, card_withdrawal_id=N
   f. Commit
4. Erros por conta são logados no canal `daily` sem interromper as demais

TransactionType criado automaticamente:

SlugName
credit-card-settlementLiquidação Cartão de Crédito

Glossário de Status ​

card_transactions.status ​

ValorDescrição
PENDINGRecebido, aguardando retirada. Não impacta o saldo global.
WITHDRAWNLiquidado e incluído em um card_withdrawal.

card_withdrawals.type ​

ValorDescrição
AUTOMATICGerado pelo job D+1
MANUALCriado via endpoint pelo operador

card_withdrawals.status ​

ValorDescrição
COMPLETEDRetirada concluída e Transaction global criada

FastGivr API Documentation

Copyright © 2026 FASTGIVR. Todos os direitos reservados.