Guias

Devolução de Pix recebido

A devolução reverte, total ou parcialmente, um Pix já recebido. É a forma correta de reembolsar um pedido — não use Pix Out.

Referência de conta e headers

Toda request sobre uma conta identifica a conta por header: envie account-id (o accountId recebido no onboarding), wallet-id ou tax-identifier — precedência wallet-id > tax-identifier > account-id. Some a isso Authorization e tenantid; em DEV, também hostdevelop: apiapp.dev.ideabank.com.br. Sem nenhum header de conta a API responde 422 (account, wallet or tax-identifier header is required); se a integração não estiver vinculada à conta, 403.

POST/integration/v1/pix/refund/{id}

Campos

Campo	Tipo	Descrição
amount*	number	Valor a devolver. Igual ao valor original = devolução total; menor = parcial.
reason	string	Motivo — exibido no extrato.

curl -X POST "https://apiapp.dev.ideabank.com.br/integration/v1/pix/refund/7f1d664d-73c7-4cbf-a984-2d0ec9c2ba81" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenantid: $TENANT_ID" -H "account-id: $ACCOUNT_ID" -H "hostdevelop: apiapp.dev.ideabank.com.br" -H "Content-Type: application/json" \
  -d '{ "amount": 150.00, "reason": "Reembolso do pedido 12345" }'

Prazo regulatório

A janela para devolução operacional segue as regras do BACEN. Após o prazo, o caminho é o MED (Mecanismo Especial de Devolução) — coordene com o time Idea+Cash.