Cash-in (cobrança)
Pix Cash-in
Cobranças Pix (QR Code) para recebimento na conta titular.
Objetivo
Gerar QR Code Pix para receber pagamentos na conta (cash-in). O crédito só ocorre quando o pagador efetiva o Pix.
Pré-requisito: Login da conta. Scopes baas.pix-cash-in.write (criar) e baas.pix-cash-in.read (consultar).
Tipos (type)
| Valor | Uso |
|---|---|
static | QR reutilizável |
dynamic | QR dinâmico com valor fixo (value) |
dynamicWithExpiration | Com vencimento; exige expiration (YYYY-MM-DD) e objeto debtor |
Regras
keydeve ser chave Pix ativa da própria conta.valueem centavos (máx.1000000000). O app bloqueiavalue = 0.cityaté 15 caracteres; no app costuma ser valor fixo curto (ex.:TUBARAO).descriptionopcional, até 60.- Guarde o
txIddo POST para consultar status (ATIVA,CONCLUIDA, etc.). - Novo QR = novo POST (novo
txId). Webhookpix-receivedpode notificar liquidação se cadastrado. - Consulta (
GET) retorna cobrança no formato COB (calendario,valor,pix[]). Ver Consultar cobrança. - Após a liquidação, se o contrato da conta tiver percentual de reserva, parte do valor bruto do Pix é retida automaticamente em
reserved_balance. A requisição de cash-in não inclui campo de reserva. O efeito aparece em Consultar saldo e no extrato como movimento Reserva de valor.
Contrato HTTP: Criar cobrança.
Endpoints
Criar
| Método | POST |
| Path | /api/v2/baas/pix/cash-in |
Contrato: Criar cobrança Pix.
Autenticação
Bearer da conta, HMAC.
Corpo mínimo
| Campo | Regra |
|---|---|
value | Centavos, obrigatório |
key | Chave de recebimento da conta |
city | Máx. 15 caracteres |
type | static, dynamic ou dynamicWithExpiration |
Para dynamicWithExpiration, inclua expiration e debtor (name, cpf ou cnpj, endereço opcional).
Resposta
Retorna payload (EMV para exibir ou gerar imagem) e txId para consulta.
Consultar
| Método | GET |
| Path | /api/v2/baas/pix/cash-in/{txid} |
Contrato: Consultar cobrança.
Autenticação
Bearer da conta, HMAC. Corpo [] na assinatura.
Path
txid alfanumérico, 25 a 35 caracteres (o txId retornado no POST).
Regras de negócio
- Formato inválido de
txid→422. - Resposta no formato COB Pix:
status,valor.original,chave,pix[]com pagamentos e devoluções quando liquidada.