CashOut

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/luniumpay-com/json-schema/luniumpay-com-cash-out-schema.json",
  "title": "CashOut",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/luniumpay-com-openapi.json#/components/schemas/CashOut",
  "type": "object",
  "properties": {
    "cashout_id": {
      "type": "string",
      "description": "Identificador opaco da ordem. Em produção pode ser UUID; em sandbox começa com sbx_. Preserve sem converter."
    },
    "state": {
      "type": "string",
      "enum": [
        "QUOTE_CREATED",
        "AWAITING_DEPOSIT",
        "DEPOSIT_DETECTED",
        "DEPOSIT_CONFIRMED",
        "SELLING",
        "SOLD",
        "FORWARDING",
        "PAYING_OUT",
        "COMPLETED",
        "MANUAL_REVIEW",
        "REFUNDING_CRYPTO",
        "REFUNDED",
        "EXPIRED",
        "FAILED",
        "DELAYED",
        "AWAITING_REFUND_ADDRESS",
        "PROCESSING",
        "REFUNDING"
      ],
      "description": "Estado da ordem. COMPLETED confirma PIX. Etapas intermediárias variam por trilho. DELAYED pertence ao cenário de sandbox. AWAITING_REFUND_ADDRESS: a ordem precisa devolver e não tem carteira de retorno; informe-a em POST /cash-outs/{cashout_id}/refund-address (venda de cripto e, desde a 1.44.0, venda de DePix). Venda de DePix: QUOTE_CREATED → AWAITING_DEPOSIT → DEPOSIT_DETECTED → PROCESSING → COMPLETED; se o Pix não puder ser pago, REFUNDING → REFUNDED, ou AWAITING_REFUND_ADDRESS quando falta a carteira. DePix que já tinha sido repassado ao provedor só é devolvido depois que o retorno é confirmado: até lá a ordem fica em MANUAL_REVIEW, e a devolução é de no máximo o que voltou."
    },
    "path": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "FAST",
        "DEX",
        "CONVERT",
        null,
        "depix_liquid"
      ],
      "description": "Trilho FAST, DEX ou CONVERT. Prazos dependem da rota, confirmações e processamento. DePix/Liquid usa depix_liquid."
    },
    "asset": {
      "type": "string",
      "description": "Ativo vendido. Use o id EXATO do GET /catalog (ex.: \"usdt\"). Combine com network — o par (asset, network) precisa existir no catálogo."
    },
    "network": {
      "type": "string",
      "description": "Rede blockchain do depósito, como listada no catálogo (ex.: \"polygon\"). O endereço de depósito devolvido só vale nesta rede."
    },
    "amount": {
      "type": "string",
      "description": "Quantidade de cripto, em string decimal. Nunca float."
    },
    "brl_amount": {
      "type": [
        "string",
        "null"
      ],
      "description": "Amount in Brazilian reais (BRL) the PIX key will receive.\n\n(pt) Reais que a chave PIX vai receber."
    },
    "pix_key": {
      "type": "string",
      "description": "Chave PIX mascarada do destinatario na resposta. A entrada aceita a chave completa; não compare literalmente a resposta mascarada com a entrada."
    },
    "pix_key_type": {
      "type": "string",
      "enum": [
        "cpf",
        "cnpj",
        "phone",
        "email",
        "random"
      ],
      "description": "Usually omit it: the type is inferred from the key for e-mails, CNPJs, random keys and phones written with the +55 country code. Only required when the key is 11 bare digits, because a CPF and a phone number are the same length and guessing would pay the wrong person. An explicit type always wins over inference."
    },
    "deposit_address": {
      "type": [
        "string",
        "null"
      ],
      "description": "Para onde o cliente envia a cripto. Só existe depois do accept. Em sandbox DePix é um marcador não pagável SANDBOX:LIQUID:NAO_ENVIAR:...; não envie moedas."
    },
    "deposit_tag": {
      "type": [
        "string",
        "null"
      ],
      "description": "Memo/tag que deve acompanhar o depósito quando retornado pelo aceite. Use apenas redes presentes em GET /catalog."
    },
    "external_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Identificador persistente por intenção, até 64 caracteres. Repetir o mesmo corpo reutiliza a ordem. Mudanca de rede, ativo, token, destino, tipo PIX, valor ou carteira de retorno e conflito 409; recuperar a original antes de decidir nova operação. Ordens antigas sem identidade verificavel podem exigir recuperacao por cashout_id/external_id.",
      "maxLength": 64
    },
    "refund_address": {
      "type": [
        "string",
        "null"
      ],
      "description": "Carteira de retorno confirmada pelo cliente. Ausência não autoriza usar deposit_from; a ordem pode pedir endereço em AWAITING_REFUND_ADDRESS. Vale também para a venda de DePix (endereço Liquid lq1…) desde a 1.44.0."
    },
    "refund_tx_hash": {
      "type": [
        "string",
        "null"
      ],
      "description": "Hash da devolução quando concluída; não implica valor/prazo fixo de estorno para todos os casos."
    },
    "deposit_from": {
      "type": [
        "string",
        "null"
      ],
      "description": "Origem on-chain do deposito, apenas informativa. Pode ser carteira compartilhada de exchange; nunca a escolher automaticamente como destino de devolução."
    },
    "br_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "Copia e cola informado na cotação (cobrança), quando houve. brl_amount é o valor do QR.\n\n(en) Copy-paste string given at quote time (charge), if any. brl_amount is the QR amount."
    },
    "merchant_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Nome do recebedor lido do QR (cobrança).\n\n(en) Receiver name read from the QR (charge)."
    },
    "copia_e_cola_buffer_usd": {
      "type": [
        "string",
        "null"
      ],
      "description": "Equivalente em USDT da reserva operacional de R$1, convertido na cotacao e ja incluido no total; nao somar novamente. Ordens antigas mantem seu valor original. / USDT equivalent of the BRL 1 operational reserve, converted at quote time and already included in the total; do not add it again. Existing orders retain their original value."
    },
    "expires_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Instante em que a cotação expira, ISO 8601 em UTC (ex.: 2026-09-02T14:03:00Z). Aceites após esse instante falham com erro=cotacao_expirada — recote em vez de insistir."
    },
    "pix_e2e": {
      "type": [
        "string",
        "null"
      ],
      "description": "Central Bank end-to-end identifier of the completed PIX. Anyone can verify it at GET /v1/verificar/{e2e}, no key required.\n\n(pt) Identificador oficial do PIX no Banco Central. É a prova — devolva ao seu cliente final. Em sandbox é fictício, com ISPB 00000000; não comprova pagamento bancário."
    },
    "pix_paid_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "receipt_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Página compartilhavel do comprovante, quando pronta. Pode permanecer null no evento cashout.completed; cashout.receipt_ready e a consulta da mesma ordem entregam o link depois."
    },
    "receipt_pdf_url": {
      "type": [
        "string",
        "null"
      ],
      "nullable": true,
      "format": "uri",
      "description": "Receipt as a PDF FILE: attach to a ticket, send over WhatsApp, keep for accounting. Does not depend on our page being up on the day someone checks. Carries recipient name, tax number, institution, amount, date, E2E and the verification link.\n\n(pt) Comprovante em ARQUIVO PDF. E o que se anexa em chamado, manda no WhatsApp do cliente final e guarda na contabilidade -- nao depende de a pagina estar no ar no dia da conferencia. Traz nome, documento e instituicao do recebedor, valor, data, E2E e o link de verificacao. Gerado da MESMA fonte de dados da pagina: os dois nunca divergem. Vem `null` enquanto a ordem nao chegou no estado que o preenche.\n\nComprovante oficial — o que contém e por onde chega (API, webhook, painel do parceiro, Telegram): https://docs.luniumpay.com/manual#comprovante"
    },
    "verify_url": {
      "type": [
        "string",
        "null"
      ],
      "nullable": true,
      "format": "uri",
      "description": "Direct link to the OPEN verification (no key). Hand it to your counterparty so they can confirm the payment themselves, without trusting you or us. Never exposes PIX key, full name or tax number.\n\n(pt) Link direto da verificacao ABERTA (sem chave). Entregue ao seu contraparte para ele mesmo confirmar o pagamento, sem precisar confiar em voce nem em nos. Nao expoe chave PIX, nome completo nem documento. Vem `null` enquanto a ordem nao chegou no estado que o preenche."
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "timeline": {
      "type": "array",
      "description": "Linha do tempo carimbada pelo SERVIDOR a cada transição (hora do gateway, não do seu polling): AWAITING_DEPOSIT → DEPOSIT_DETECTED → DEPOSIT_CONFIRMED → (SELLING → SOLD → FORWARDING, só na corretora) → PAYING_OUT → COMPLETED. Use para o rastreador do cliente.",
      "items": {
        "type": "object",
        "properties": {
          "state": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "confirmations": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Confirmações do depósito já observadas, AO VIVO. Aparece só enquanto a ordem está confirmando e não é persistido — o número muda a cada bloco. Use com confirmations_required para desenhar o progresso em vez de um \"aguardando\" sem fim."
    },
    "confirmations_required": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Confirmações que a corretora exige antes de creditar o depósito desta rede."
    },
    "failure_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Motivo de falha quando retornado, inclusive nos cenários de sandbox."
    },
    "sandbox": {
      "type": "boolean",
      "description": "True for fictitious sandbox operations."
    },
    "simulation": {
      "type": "object",
      "additionalProperties": true
    },
    "partner_fee_bps": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Sub fee do parceiro congelada nesta venda (bps); null em ordem anterior ao campo ou venda DePix."
    },
    "partner_fee_brl_cents": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Fatia do parceiro em centavos, fechada na confirmacao do PIX; e o valor creditado no razao de comissao."
    },
    "refund_address_required": {
      "type": "boolean",
      "description": "true em AWAITING_REFUND_ADDRESS: consultar os dados da devolução e informar carteira confirmada pelo cliente em POST /cash-outs/{cashout_id}/refund-address."
    },
    "refund_amount": {
      "type": [
        "string",
        "null"
      ],
      "description": "Quantidade efetiva a devolver, quando apurada; não presumir quantidade original. Venda de DePix: com o DePix inteiro com a Lunium, refund_amount, refund_asset (DEPIX) e refund_network (liquid) já vêm preenchidos em AWAITING_REFUND_ADDRESS. Se o DePix já tinha sido repassado ao provedor, esses campos ficam null em MANUAL_REVIEW até o retorno ser confirmado; depois, refund_amount é de no máximo o que voltou (mais a parte que não chegou a ser repassada, até o valor da ordem)."
    },
    "refund_asset": {
      "type": [
        "string",
        "null"
      ],
      "description": "Ativo efetivo da devolução; pode diferir do ativo depositado."
    },
    "refund_network": {
      "type": [
        "string",
        "null"
      ],
      "description": "Rede efetiva da devolução; usar carteira compatível confirmada pelo cliente."
    },
    "provider_return_txid": {
      "type": [
        "string",
        "null"
      ],
      "description": "Referência da devolução do parceiro para a Lunium; não e prova de estorno ao cliente."
    },
    "fee_bps": {
      "type": "integer",
      "description": "Percentual da venda de DePix em pontos-base."
    },
    "fee_fixed_cents": {
      "type": "integer",
      "description": "Parcela fixa da venda de DePix, em centavos."
    },
    "fee_total_cents": {
      "type": "integer",
      "description": "Taxa total, em centavos; disponível na cotação DePix e na ordem simulada."
    },
    "net_cents": {
      "type": "integer",
      "description": "PIX líquido, em centavos; disponível na cotação DePix e na ordem simulada."
    },
    "pix_key_reserve_usd": {
      "type": [
        "string",
        "null"
      ],
      "description": "Equivalente em USDT da reserva operacional de R$1, convertido na cotacao e ja incluido no total; nao somar novamente. Ordens antigas mantem seu valor original. / USDT equivalent of the BRL 1 operational reserve, converted at quote time and already included in the total; do not add it again. Existing orders retain their original value."
    },
    "reserve_brl": {
      "type": [
        "string",
        "null"
      ],
      "description": "Reserva operacional fixa de R$1 nas novas ordens, ja incluida no total. Legado preserva a reserva original. / Fixed BRL 1 operational reserve on new orders, already included in the total; existing orders keep their original reserve."
    }
  }
}