StatusCobranca

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/luniumpay-com/json-schema/luniumpay-com-status-cobranca-schema.json",
  "title": "StatusCobranca",
  "description": "Estado da cobrança; GET pode acrescentar trilho, timeline e tempos_tipicos. Lista e webhook usam o objeto-base.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/luniumpay-com-openapi.json#/components/schemas/StatusCobranca",
  "type": "object",
  "properties": {
    "cashin_id": {
      "type": "string",
      "description": "Identificador da cobrança (ci_…)."
    },
    "status": {
      "type": "string",
      "description": "Estado do PIX. paid não comprova sozinho crédito/entrega; leia settlement_status.",
      "enum": [
        "pending",
        "delayed",
        "under_review",
        "paid",
        "expired",
        "refunded",
        "failed"
      ]
    },
    "settlement_status": {
      "type": [
        "string",
        "null"
      ],
      "description": "Estado do crédito/entrega: sent concluiu; incerto exige conciliação. PIX pago e entrega são estados distintos.",
      "enum": [
        "pending",
        "sending",
        "entregando",
        "sent",
        "incerto",
        "failed",
        null
      ]
    },
    "amount_cents": {
      "type": "integer",
      "description": "Valor do PIX em centavos."
    },
    "depix_received_cents": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Valor recebido do liquidante antes da dedução das taxas de depósito da chave; não é o crédito líquido de custódia."
    },
    "usdt_amount": {
      "type": [
        "string",
        "null"
      ],
      "description": "Campo legado de quantidade retornado pela liquidação; interprete junto de asset e dos campos específicos da rota."
    },
    "settlement_tx_hash": {
      "type": [
        "string",
        "null"
      ],
      "description": "Hash on-chain da entrega (ou id interno quando a entrega é pela corretora)."
    },
    "settlement_tx_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Link do explorador para o hash acima, quando existe."
    },
    "payout_address": {
      "type": [
        "string",
        "null"
      ],
      "description": "Carteira que recebe a cripto (destino=cripto)."
    },
    "payout_tag": {
      "type": [
        "string",
        "null"
      ],
      "description": "Memo/tag da carteira de destino em redes coletivas (destino=cripto)."
    },
    "chain": {
      "type": "string",
      "description": "Rede de entrega (id de GET /cashin/catalog)."
    },
    "asset": {
      "type": "string",
      "description": "Ativo entregue (usdt, usdc, btc, …)."
    },
    "payer_tax_number": {
      "type": "string",
      "description": "CPF/CNPJ do pagador — quem deve pagar o QR. PIX de outro documento é devolvido (refund_reason PAYER_MISMATCH)."
    },
    "external_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
      "maxLength": 64
    },
    "expires_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Validade da própria cobrança; leia este timestamp, inclusive para validade estendida pelo bot."
    },
    "paid_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "settled_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "destino": {
      "type": "string",
      "description": "cripto (entrega on-chain) ou saldo (credita a custódia BRL da chave, usável em POST /payouts e POST /saldo/sacar-cripto).",
      "enum": [
        "cripto",
        "saldo"
      ]
    },
    "held_hours": {
      "type": "integer",
      "description": "Retenção solicitada ao provedor. Pode ser zero enquanto existe retenção local (hold_hours/liberar_em)."
    },
    "held": {
      "type": "boolean",
      "description": "true quando held_hours > 0. Isoladamente não revela retenção local."
    },
    "delay_until": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Instante de liberação informado para retenção do provedor, quando disponível."
    },
    "liberar_em": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Quando o crédito no saldo sai da carência. null quando já entra disponível (padrão desde 16/09/2026)."
    },
    "e2e": {
      "type": [
        "string",
        "null"
      ],
      "description": "EndToEndId do PIX recebido (Banco Central)."
    },
    "payer_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Nome do pagador quando informado ou identificado pelo banco."
    },
    "customer_ref": {
      "type": [
        "string",
        "null"
      ],
      "description": "Sua referência do cliente final (subconta no saldo).",
      "maxLength": 80
    },
    "refund_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Motivo da devolução quando status=refunded (ex.: PAYER_MISMATCH = pagou outro documento; TEST_AMOUNT = valor de teste; PROVIDER_REJECTED)."
    },
    "refund_reason_detail": {
      "type": [
        "string",
        "null"
      ],
      "description": "Explicação legível do motivo da devolução."
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "trilho": {
      "type": "string",
      "description": "Trilho desta operação: casa, corretora, saldo ou liquid. Não é promessa de prazo."
    },
    "timeline": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "tempos_tipicos": {
      "type": "object",
      "description": "Mediana medida (segundos) de cada etapa, por trilho — para mostrar ao cliente quanto costuma demorar.",
      "additionalProperties": true
    },
    "sandbox": {
      "type": "boolean",
      "description": "True for fictitious sandbox operations."
    },
    "simulation": {
      "type": "object",
      "additionalProperties": true
    },
    "delivery_mode": {
      "type": "string",
      "enum": [
        "full",
        "split"
      ],
      "description": "Só em chain=\"liquid\": como o DePix foi entregue. Ausente nas outras redes."
    },
    "net_cents": {
      "type": "integer",
      "description": "Só em chain=\"liquid\" com delivery_mode=\"split\": quanto o destinatário recebe em DePix, já sem a taxa. É este valor que a Lunium envia on-chain."
    },
    "fee_total_cents": {
      "type": "integer",
      "description": "Só em chain=\"liquid\" com delivery_mode=\"split\": tudo que saiu do bruto (taxa fixa + percentual). net_cents + fee_total_cents == amount_cents."
    },
    "settlement_proof": {
      "type": "string",
      "enum": [
        "none",
        "broadcast",
        "confirmed",
        "reported",
        "simulated"
      ],
      "description": "Evidência de entrega separada do PIX: none=sem envio concluído; broadcast=tx informada sem confirmação registrada; confirmed=recibo confirmado registrado; reported=conclusão reportada sem prova on-chain (inclui custódia/transferência interna); simulated=teste sem dinheiro real. Ausência de confirmação não prova falha; a cobertura do verificador depende da rede e do período."
    },
    "settlement_confirmed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Quando a confirmação on-chain foi registrada. Só preenchido em settlement_proof=confirmed."
    },
    "settlement_block": {
      "type": [
        "string",
        "null"
      ],
      "description": "Número do bloco confirmado como string, preservando precisão."
    },
    "lunium_fee_cents": {
      "type": "integer",
      "minimum": 0,
      "description": "Parte da taxa em centavos para depósito Pix em saldo BRL; calculada com os valores congelados da cobrança."
    },
    "partner_fee_cents": {
      "type": "integer",
      "minimum": 0,
      "description": "Parte da taxa em centavos para depósito Pix em saldo BRL; calculada com os valores congelados da cobrança."
    }
  }
}