PIX cash-out

Estas rotas não estão montadas na superfície atual e respondem 404. Elas dependem da liberação comercial de pagamentos e do escopo payments:create, que é recusado na criação da credencial. A página descreve o contrato para você planejar a integração.

Rotas

Método	Rota	Debita de
`POST`	`/v1/pix/cashout`	conta raiz
`POST`	`/v1/accounts/{accountId}/pix/cashout`	conta gerenciada

Escopo payments:create. Idempotency-Key obrigatório nas duas.

Corpo

Envie exatamente um entre pixKey e qrCode. Os dois juntos, ou nenhum dos dois, resultam em 422 invalid_request.

Campo	Tipo	Regra
`amountCents`	inteiro	obrigatório, positivo, em centavos
`pixKey`	string	chave PIX de destino
`qrCode`	string	BR Code até 1024 caracteres, com CRC válido
`description`	string	opcional, até 140 caracteres, sem caracteres de controle

Enviar para uma chave

{
  "amountCents": 5000,
  "pixKey": "financeiro@example.com",
  "description": "Pagamento do pedido 1234"
}

Pagar um QR Code

{
  "amountCents": 5000,
  "qrCode": "00020126580014br.gov.bcb.pix...",
  "description": "Pagamento do pedido 1234"
}

Pagar uma cobrança pelo QR Code não é a mesma coisa que transferir para a chave dela. Só o caminho do QR Code carrega o identificador que o sistema do lojista usa para dar a venda por paga. Se você recebeu um QR Code, pague pelo QR Code.

Com qrCode, o servidor decodifica o BR Code de novo e usa amountCents como conferência:

Situação	Comportamento
QR com valor definido e `amountCents` diferente	`422 amount_mismatch`
QR estático de valor aberto	`amountCents` é o valor pago
BR Code com CRC inválido	`422 invalid_request`

Exemplo

curl -X POST https://api.prismapay.com.br/v1/pix/cashout \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b2e8f6e-4f4d-4f93-b8d3-9c2f2c32e2b1" \
  -H "X-Api-Key: pk_live_seu_key_id" \
  -H "X-Timestamp: 1767000000" \
  -H "X-Signature: assinatura_hex" \
  -d '{"amountCents":5000,"pixKey":"financeiro@example.com"}'

Tetos de valor

Cada credencial tem um teto por transação acordado com a PrismaPay. A verificação falha fechada:

Situação	Resposta
Valor acima do teto por transação	`422 per_tx_limit_exceeded`
Credencial sem teto configurado	`422 cashout_limit_not_configured`
Teto diário configurado, mas ainda não somado automaticamente	`422 daily_cashout_limit_not_enforced`

“Falha fechada” significa que a ausência de configuração recusa a operação, em vez de liberar. Se você recebeu cashout_limit_not_configured, não é bug do seu lado: peça a configuração do teto à PrismaPay.

Resultado incerto

409 payment_pending_confirmation significa que o resultado do pagamento ainda não foi confirmado.

Nunca reenvie automaticamente depois desse erro. O pagamento pode ter saído. Esse caso exige conferência operacional. Consulte GET /v1/accounts/{accountId}/transactions/{transactionId} e, na dúvida, fale com a PrismaPay antes de tentar de novo.

Antes de enviar

Confira o saldo disponível

Use o campo available de GET /v1/accounts/{accountId}/balance. Ele já está líquido das tarifas em aberto.

Gere e guarde a chave de idempotência

Uma chave por pagamento, persistida antes da primeira chamada. Ver Idempotência.

Trate o 409 request_in_progress esperando, não trocando a chave

Trocar a chave nesse momento é o caminho para pagar duas vezes.

Comece aqui

Fundamentos

Contas

Movimentação

Rotas

Corpo

Enviar para uma chave

Pagar um QR Code

Exemplo

Tetos de valor

Resultado incerto

Antes de enviar

​Rotas

​Corpo

​Enviar para uma chave

​Pagar um QR Code

​Exemplo

​Tetos de valor

​Resultado incerto

​Antes de enviar

Rotas

Corpo

Enviar para uma chave

Pagar um QR Code

Exemplo

Tetos de valor

Resultado incerto

Antes de enviar