---
title: "Gerar cobrança PIX para custódia BRL ou entrega de cripto"
method: POST
path: "/cashin/charge"
tags: ["Cash-in"]
---

# Gerar cobrança PIX para custódia BRL ou entrega de cripto

`POST /cashin/charge`

## Request

- Base URL: `https://api.luniumpay.com`
- URL: `https://api.luniumpay.com/cashin/charge`
- Auth: API key in header `X-API-Key`

Gera PIX para custódia BRL (destino=saldo, sem carteira) ou entrega direta de cripto (destino=cripto, padrão). Informe o documento de quem pagará. Consulte GET /cashin/limits e as condições da chave. Limites, taxas e provedor determinam o mínimo efetivo; a criação revalida. Retenção pode ocorrer no provedor (held_hours/delay_until) ou localmente (hold_hours/liberar_em). PIX paid não significa entrega/crédito concluído: acompanhe settlement_status e o extrato. Sandbox cria QR nao pagavel; confirme com POST /sandbox/cashin/{cashin_id}/pay. Nao ha transacao bancaria.

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).

## Request body

- object
  - `amount_cents` integer, required: Valor da cobrança em CENTAVOS de real, inteiro (ex.: 15000 = R$ 150,00). Consulte GET /cashin/limits antes de criar; ele publica as faixas sem retenção e com retenção vigentes para o pagador.
  - `chain` string: Rede da rota de entrega. Use o network do catálogo neste campo chain.
  - `asset` string: Ativo da rota entregável em GET /cashin/catalog; não limitado a stablecoins.
  - `payout_address` string: Carteira por cobrança para destino=cripto; se omitida, pode usar settlement_address da chave. Omitir para destino=saldo. Endereço deve corresponder à rede escolhida.
  - `payer_tax_number` string, required: CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, somente números. Identifica o pagador e alimenta os limites e retenções anti-fraude publicados por GET /cashin/limits.
  - `external_id` string: 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.
  - `destino` 'cripto' | 'saldo': saldo credita custódia BRL líquida das taxas, sem carteira. cripto (padrão) entrega na carteira informada ou configurada. Consulte taxas/carência em GET /saldo e retenção na cobrança/status.
  - `customer_ref` string: Optional sub-account of the balance (your end customer id). With `destino: "saldo"`, the credit lands on this sub-account; GET /saldo?customer_ref= reads it and POST /payouts with the same `customer_ref` spends it. Omit to use the key's main balance.
  - `allow_hold` boolean: Legado: campo ignorado. A retenção exigida pela faixa do pagador é automática, inclusive com false. Não bloqueie a criação pelo limite sem retenção; consulte max_amount_cents/held_qr e mostre held_hours e hold_hours/liberar_em antes do pagamento.
  - `payout_tag` string: Memo/tag do destino. OBRIGATORIO nas redes coletivas — XRP, XLM, TON, ATOM, HBAR, ALGO, EOS, KAVA, LUNA — onde a carteira de destino e compartilhada e o memo e quem identifica o dono. Sem ele a API responde 400 `memo_obrigatorio` antes de criar qualquer cobranca. Em XRP e a destination tag: inteiro de 0 a 4294967295. Aliases aceitos: `memo`, `tag`, `destination_tag`. O catalogo marca essas rotas com `memoRequired: true`. Aliases aceitos: memo, tag, destination_tag.
  - `payer_name` string: Nome do pagador, quando informado.
  - `sandbox_scenario` 'success' | 'delayed' | 'held' | 'expired' | 'refunded' | 'failed' | 'payer_mismatch' | 'settlement_failed' | 'settlement_uncertain' | 'route_unavailable' | 'provider_unavailable': Only for a sandbox key. GET /sandbox provides the scenario matrix by flow. Omit in production. All prices, payments and withdrawals remain fictitious.
  - `delivery_mode` 'full' | 'split': Somente para chain="liquid" (DePix). "full" (padrão) entrega o DePix direto na carteira informada, com o valor cheio — a taxa da chave não é descontada. "split" faz o caminho receber-e-repassar: a Lunium recebe o DePix, desconta a taxa da chave (fixa + percentual) e envia o líquido para payout_address; net_cents na resposta é exatamente o que o destinatário recebe. Em split, payout_address é obrigatório. Sem o campo, vale o padrão da sua chave.

## Response `200`

Cobrança criada: qr_copypaste é o PIX a mostrar.

- Cobranca: Resposta de criação da cobrança, com QR. Para status/lista/webhook veja StatusCobranca.
  - `cashin_id` string: Identificador da cobrança (ci_…).
  - `status` 'pending' | 'delayed' | 'under_review' | 'paid' | 'expired' | 'refunded' | 'failed': Estado do PIX. paid não comprova sozinho crédito/entrega; leia settlement_status.
  - `amount_cents` integer: Valor do PIX em centavos.
  - `destino` 'cripto' | 'saldo': cripto (entrega on-chain) ou saldo (credita a custódia BRL da chave, usável em POST /payouts e POST /saldo/sacar-cripto).
  - `fonte` 'pix' | 'saldo': Fonte do valor na criação: PIX ou saque do saldo.
  - `customer_ref` string, nullable: Sua referência do cliente final (subconta no saldo).
  - `payout_address` string, nullable: Carteira que recebe a cripto (destino=cripto).
  - `payout_tag` string, nullable: Memo/tag da carteira de destino em redes coletivas (destino=cripto).
  - `chain` string: Rede de entrega (id de GET /cashin/catalog).
  - `asset` string: Ativo entregue (usdt, usdc, btc, …).
  - `lunium_fee_bps` integer: Taxa percentual congelada na cobrança, em bps.
  - `lunium_fee_fixed_cents` integer: Parcela fixa congelada na cobrança, em centavos.
  - `partner_fee_bps` integer: 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` string, nullable: PIX copia e cola na criação; null no saque custodial.
  - `qr_image_url` string, nullable: Imagem do QR (PNG) — só na resposta da criação.
  - `external_id` string, nullable: 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.
  - `created_at` string, date-time, nullable
  - `expires_at` string, date-time, nullable: Validade da própria cobrança; leia este timestamp, inclusive para validade estendida pelo bot.
  - `delay_until` string, date-time, nullable: Instante de liberação informado para retenção do provedor, quando disponível.
  - `liberar_em` string, date-time, nullable: Quando o crédito no saldo sai da carência. null quando já entra disponível (padrão desde 16/09/2026).
  - `hold_hours` integer: Retenção local da cobrança em horas. Não é alias de held_hours nem da carência geral do saldo.
  - `held_hours` integer: Retenção solicitada ao provedor. Pode ser zero enquanto existe retenção local (hold_hours/liberar_em).
  - `held` boolean: true quando held_hours > 0. Isoladamente não revela retenção local.
  - `sandbox` boolean: True for fictitious sandbox operations.
  - `simulation` object
  - `sandbox_payment` object
    - `method` 'POST'
    - `path` string
  - `timeline` object[]
  - `delivery_mode` 'full' | 'split': Só em chain="liquid": como o DePix foi entregue. Ausente nas outras redes.
  - `net_cents` integer: 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` integer: 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` integer: Parte da taxa em centavos para depósito Pix em saldo BRL; calculada com os valores congelados da cobrança.
  - `partner_fee_cents` integer: Parte da taxa em centavos para depósito Pix em saldo BRL; calculada com os valores congelados da cobrança.

## Other responses

- `400`: Parametros invalidos, valor fora dos limites, ou cash-in indisponivel para esta chave. · `valor_abaixo_do_minimo` — a moeda/rede escolhida tem mínimo próprio; a resposta traz `minimo_estimado_cents` (a partir de quanto dá). Conferido ANTES de tocar no dinheiro. · `memo_obrigatorio` — a rede exige memo/tag e ele nao veio (ou veio invalido).
- `401`: X-API-Key ausente, desconhecida ou incorreta.
- `403`: Limite do pagador excedido (limite_do_pagador) ou pagador bloqueado pela Lunium para esta integração (pagador_bloqueado: nenhuma cobrança é criada; não repita com o mesmo CPF/CNPJ).
- `409`: external_id divergente.
- `502`: provedor_indisponivel (acao: repetir) — o provedor de liquidação PIX não gerou o QR. NENHUMA cobrança foi criada: repita a MESMA chamada (mesmo external_id) em alguns minutos. Dois erros distintos usam este status e exigem acoes opostas: `provedor_indisponivel` (acao `repetir` ou `esperar`) e instabilidade do liquidante, passa sozinha; `config_provedor` (acao `falar_com_suporte`) e uma configuracao invalida do nosso lado — a chave PIX, a credencial ou a conta do provedor — e NAO se resolve esperando nem repetindo. Nenhuma cobranca e criada em nenhum dos dois casos.
- `503`: catalogo_indisponivel / cotacao_indisponivel — corretora sem cotação neste instante; repita.

## Changes

- **2026-10-20** `0b5a340fa9dd`: 1 info
  - request property `allow_hold` deprecated
- **2026-10-19** `fc06c3b824b1`: 2 info
  - added the optional property `lunium_fee_cents` to the response with the `200` status
  - added the optional property `partner_fee_cents` to the response with the `200` status

[Operation history](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/changes/cashin/charge/post.md)

---

[API](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil.md) · [All operations](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/llms.txt) · [OpenAPI document](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/revisions/0b5a340fa9dd?raw)