Cobranca

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/luniumpay-com/json-schema/luniumpay-com-cobranca-schema.json",
  "title": "Cobranca",
  "description": "Resposta de criação da cobrança, com QR. Para status/lista/webhook veja StatusCobranca.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/luniumpay-com-openapi.json#/components/schemas/Cobranca",
  "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"
      ]
    },
    "amount_cents": {
      "type": "integer",
      "description": "Valor do PIX em centavos."
    },
    "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"
      ]
    },
    "fonte": {
      "type": "string",
      "enum": [
        "pix",
        "saldo"
      ],
      "description": "Fonte do valor na criação: PIX ou saque do saldo."
    },
    "customer_ref": {
      "type": [
        "string",
        "null"
      ],
      "description": "Sua referência do cliente final (subconta no saldo).",
      "maxLength": 80
    },
    "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, …)."
    },
    "lunium_fee_bps": {
      "type": "integer",
      "description": "Taxa percentual congelada na cobrança, em bps."
    },
    "lunium_fee_fixed_cents": {
      "type": "integer",
      "description": "Parcela fixa congelada na cobrança, em centavos."
    },
    "partner_fee_bps": {
      "type": "integer",
      "description": "Subfee exclusiva do depósito Pix em saldo BRL, em basis points (100 = 1%). Padrão 0, máximo 1000. Aplicada ao valor recebido após a taxa fixa Lunium, descontada antes do crédito no saldo. Independente de compra, venda e saque. Congelada na criação; comissão creditada somente após liberação e crédito concluído (paid/sent). Para compra direta, este campo congela partner_fee_bps."
    },
    "qr_copypaste": {
      "type": [
        "string",
        "null"
      ],
      "description": "PIX copia e cola na criação; null no saque custodial."
    },
    "qr_image_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Imagem do QR (PNG) — só na resposta da criação."
    },
    "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
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "expires_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Validade da própria cobrança; leia este timestamp, inclusive para validade estendida pelo bot."
    },
    "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)."
    },
    "hold_hours": {
      "type": "integer",
      "description": "Retenção local da cobrança em horas. Não é alias de held_hours nem da carência geral do 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."
    },
    "sandbox": {
      "type": "boolean",
      "description": "True for fictitious sandbox operations."
    },
    "simulation": {
      "type": "object",
      "additionalProperties": true
    },
    "sandbox_payment": {
      "type": "object",
      "properties": {
        "method": {
          "const": "POST"
        },
        "path": {
          "type": "string"
        }
      }
    },
    "timeline": {
      "type": "array",
      "items": {
        "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."
    },
    "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."
    }
  }
}