Cash-out (pagamento)

Pix Cash-out

Pagamentos Pix por chave ou payload (QR Code) na conta titular.

Objetivo

Transferir recursos para fora da conta via Pix (cash-out).

Pré-requisito: Login da conta. Scope baas.pix-payments.write. Rate limit típico: 30 req/min (confirmar no ambiente).

Regras gerais

value em centavos inteiros.
idempotency_key obrigatório e único por intenção (UUID v4). Reenvio com a mesma chave não deve duplicar débito.
Saldo disponível e limites devem cobrir o valor.
Conta em análise ou inativa pode retornar 400 (invalid_user, saldo insuficiente, limite Pix).
Não é permitido pagar para a própria conta (422).
Resposta do POST traz movimentação: end_to_end_id, internal_id_request (eco do idempotency_key), receiver_account, payer_account, transaction_type (pix ou 1/2).

Fluxo completo (app Minha Conta)

Modo	Campos além do mínimo HTTP
Por chave	`favorite`, `appointment_date`, `schedule_months` quando o usuário agenda ou recorre
Por payload	`value` sempre no fluxo; obrigatório em QR estático sem valor; `valorMaximo` se QR aberto

A API pode aceitar requisição parcial; para espelhar o app, envie o pacote completo da Referência.

Por chave vs por payload

Modo	Path	Quando usar
Chave	`POST …/payments/key`	Após consultar a chave no DICT (`POST …/key-managements/consult`). Use `type_initiation: 1` e dados do favorecido sem alterar o retorno da consulta.
Payload	`POST …/payments/payload`	QR Code EMV copia-e-cola (estático ou dinâmico). `valorMaximo` opcional limita valor em QR aberto.

Contrato HTTP: Pagamento por chave.

Endpoints

Chave


Método	`POST`
Path	`/api/v2/baas/pix/payments/key`

Contrato: Pagamento por chave.

Autenticação

Bearer da conta, HMAC. Corpo JSON idêntico na assinatura.

Corpo mínimo (fluxo por chave)

Campo	Regra
`idempotency_key`	UUID único
`type_initiation`	`1` após consulta DICT; `0` manual
`value`	Centavos
`key`, `name`, `ispb`, `agency`, `account`, `account_type`, `document`, `person_type`	Alinhados à consulta DICT
`favorite`	Opcional no HTTP; app envia preferência do usuário

account_type: 0 corrente, 1 salário, 2 poupança, 3 pagamento, 4 PI.

Regras de negócio

Chave inválida ou dados divergentes da consulta tendem a 422.
appointment_date (futuro) agenda o pagamento; schedule_months para recorrência (1 a 12).

Payload


Método	`POST`
Path	`/api/v2/baas/pix/payments/payload`

Contrato: Pagamento por payload.

Autenticação

Bearer da conta, HMAC.

Corpo mínimo

Campo	Regra
`payload`	String EMV do QR (não use QR real de produção com titular verdadeiro em exemplos públicos)
`idempotency_key`	UUID único
`value`	Centavos; obrigatório no fluxo completo (QR estático sem valor)
`description`	Opcional, até 60 caracteres
`valorMaximo`	Opcional; teto em reais para QR dinâmico aberto
`appointment_date`	Opcional; agendamento (`Y-m-d`)

Regras de negócio

QR inválido ou expirado falha na decodificação.
Idempotência igual ao fluxo por chave.

Pix Cash-out por Chaves Pix

Realize pagamentos Pix instantâneos utilizando uma chave Pix do beneficiário. As chaves podem ser CPF, CNPJ, email, telefone ou chave aleatória (EVP).

Pix Cash-out por QR Code Dinâmico

Realize pagamentos Pix instantâneos utilizando um QR Code dinâmico (payload). O QR Code dinâmico contém todas as informações necessárias para o pagamento, incluindo valor, beneficiário e descrição.