Estornos

Use os estornos para devolver todo ou parte do valor de um pagamento Pix recebido. A devolução usa a cobrança original e retorna o dinheiro à conta que fez o pagamento; não é necessário informar outro cliente, conta de destino ou chave Pix.

Quando solicitar um estorno

A cobrança precisa ter um pagamento Pix recebido e confirmado. Em Produção, a transferência original deve estar identificada. No Sandbox, use um pagamento confirmado pela simulação da Raims. Uma cobrança parcialmente devolvida pode receber outro pedido pelo valor restante, depois da conclusão do anterior. O valor precisa ser coberto pelo saldo disponível da conta.

Os estados aceitos são 4 (paid) e 5 (partially_refunded). Estar em um desses estados não dispensa as demais condições, como pagamento Pix identificado, valor restante e saldo disponível.

Uma cobrança aceita somente uma devolução em andamento. Se já houver um pedido pendente ou sem resultado confirmado, acompanhe essa solicitação antes de tentar outra. A consulta de elegibilidade informa o impedimento atual.

Uma contestação em análise também pode impedir o pedido. Nesse caso, consulte as contestações da cobrança; pode não existir um estorno em andamento no histórico.

Este recurso devolve pagamentos Pix. Cobranças ainda não pagas seguem a revogação. O endpoint de estorno não devolve pagamentos de boleto e não recebe instruções de transferência para outra conta.

Consultar o valor devolvível

Use Consultar elegibilidade para estorno, com GET /v1/charges/{id}/refund_eligibility, antes de oferecer a devolução. Informe o identificador da cobrança, com prefixo ch_.

eligible indica se as condições atuais permitem um pedido. O campo refundable_amount_cents informa quanto ainda resta para devolver na cobrança. max_refund_amount_cents informa o máximo que pode ser solicitado agora, considerando esse restante e o saldo disponível, e fica em zero quando houver um impedimento. pending_amount_cents informa o valor dos pedidos que aguardam resultado. Quando houver impedimento, reason informa seu código e uma explicação em inglês. Use reason.code para decidir o tratamento; o texto de reason.message serve ao diagnóstico e pode ser melhorado. Sem impedimento, reason é null.

Se restarem R$ 100,00 na cobrança e houver R$ 40,00 disponíveis para a devolução, refundable_amount_cents será 10000 e max_refund_amount_cents será 4000. Nesse momento, é possível solicitar até R$ 40,00. Esse campo não informa o saldo integral da conta.

Envie um amount_cents positivo, até o máximo informado. Para devolver todo o restante, o máximo disponível precisa cobrir o valor restante da cobrança. A consulta não separa esse dinheiro nem garante a aceitação: as condições podem mudar, e são conferidas novamente no envio do estorno.

Devolver um pagamento Pix pela API

Use Solicitar estorno, com POST /v1/charges/{id}/refunds, e envie amount_cents. O valor usa centavos inteiros: por exemplo, 2500 representa R$ 25,00. description permite registrar uma descrição opcional da solicitação.

{
  "amount_cents": 2500,
  "description": "Devolução parcial do serviço"
}

Para devolver tudo, envie o valor restante em amount_cents. Omitir esse campo é inválido. Para devolver uma parte, envie o valor parcial na mesma requisição. O cliente e a conta de destino vêm do pagamento original; não envie dados bancários nem uma chave Pix.

Em Produção, uma resposta 202 confirma que a solicitação foi aceita para acompanhamento. No Sandbox, a simulação conclui na própria requisição e retorna 200 com status: completed. Guarde o id do estorno, com prefixo rf_, para consultar seu resultado. Ele é diferente do identificador ch_ da cobrança.

Se perder a resposta, consulte o histórico da cobrança antes de repetir o pedido. Um novo pedido pode representar outra devolução parcial.

Acompanhar o resultado

Use Recuperar um estorno, com GET /v1/refunds/{id}, para consultar a mesma solicitação. A resposta informa a cobrança vinculada, o valor, a descrição, o estado atual e as datas disponíveis. Quando o estado for failed, failure_reason explica a falha confirmada com um código e uma mensagem em inglês.

O pedido pendente ainda não confirma que o dinheiro voltou ao pagador. Considere a devolução concluída somente quando o estado retornado confirmar a conclusão. Quando houver falha, consulte a solicitação e a elegibilidade da cobrança antes de decidir sobre um novo pedido.

created_at, completed_at e failed_at usam segundos Unix UTC. As datas de conclusão e falha ficam null enquanto o respectivo resultado não estiver confirmado. Consultas repetidas não iniciam nem aceleram a devolução.

Use failure_reason.code para tratar a causa conhecida. A mensagem serve ao diagnóstico e pode ser melhorada sem mudar o significado do código. Nos demais estados, failure_reason é null. Uma falha antiga sem causa registrada pode apresentar um motivo desconhecido; isso não autoriza presumir rejeição bancária nem criar automaticamente outro pedido.

Consultar o histórico

Use Listar estornos, com GET /v1/refunds, para consultar as solicitações de todas as cobranças da empresa e do ambiente da chave. Cada item informa charge_id, permitindo associar a devolução à cobrança no seu sistema.

Para acompanhar devoluções parciais de uma cobrança específica, use Listar estornos de uma cobrança, com GET /v1/charges/{id}/refunds. As duas listas apresentam as solicitações mais recentes primeiro e incluem pedidos pendentes, concluídos e com falha.

Nas duas listagens, use created_gte e created_lte para filtrar o período em que o estorno foi solicitado. Informe segundos Unix UTC; os limites são inclusivos. Esse período considera created_at e não a data de pagamento da cobrança nem a conclusão da devolução. Você pode informar somente um dos limites ou os dois, com o final igual ou posterior ao início.

A resposta usa list e page. Comece sem cursor, processe list e copie page.next_after para after enquanto page.has_next for verdadeiro. Mantenha a mesma chave, os filtros e a mesma listagem durante a navegação; na lista por cobrança, mantenha também o mesmo id. Para consultar outro período, comece sem cursor. Não interprete nem altere o cursor recebido, nem troque cursores entre as duas listas.

Para consultar uma página anterior, use page.previous_before em before. Não envie after e before juntos. Veja Listagem e paginação para as regras gerais.

Comprovante de estorno

Use Baixar comprovante de estorno, com GET /v1/refunds/{id}/receipt, para guardar o documento ou disponibilizá-lo ao cliente. Informe o identificador do estorno, com prefixo rf_, recebido na solicitação ou na consulta do histórico.

O comprovante exige status: completed, valor positivo e data de conclusão registrada. Pedidos pendentes, com falha ou sem confirmação não têm comprovante de conclusão. Nesses casos, acompanhe o mesmo estorno em Recuperar um estorno.

O PDF informa o valor daquela devolução. Se uma cobrança tiver dois estornos parciais, cada solicitação tem seu próprio comprovante; o documento não soma o histórico nem substitui o valor original da cobrança.

O endpoint retorna JSON com url e expires_at. Consulte-o pelo servidor da sua integração com a chave de API. Faça um GET na url completa para baixar o PDF em files.raims.com, sem enviar Authorization ou a chave de API nesse download. expires_at informa a expiração em segundos Unix UTC. Depois dela, consulte novamente o endpoint autenticado para obter outro link. Um link inválido ou expirado pode receber HTTP 403 no download, sem o envelope JSON de erros da API. A URL pode ser reutilizada até expirar e permite acesso a quem a possuir. Compartilhe-a somente com pessoas autorizadas e não a registre em logs. O documento é emitido pela Raims e não substitui uma nota fiscal ou um comprovante bancário. Um comprovante de Sandbox identifica a devolução como simulação, sem movimentação de dinheiro real.

Estorno Pix na API: Sandbox e Produção

O Sandbox permite testar devoluções integrais e parciais com o mesmo endpoint e os mesmos campos de Produção. Primeiro, confirme um pagamento Pix por Confirmar pagamento ou pela simulação do Dashboard. Use uma chave Sandbox da mesma empresa para consultar a elegibilidade e solicitar o estorno.

A simulação considera o saldo disponível e o valor restante, conclui na própria requisição e retorna 200 com status: completed. A cobrança, o histórico de estornos, o saldo e o extrato do Sandbox refletem a devolução simulada. Nenhum dinheiro real é movimentado. O console desta documentação aceita somente chaves Sandbox.

Para testar um pedido que aguarda resultado, use Simular estorno pendente. Depois, escolha entre concluir a devolução e simular uma falha usando o mesmo ID do estorno. Assim você pode conferir o acompanhamento, o saldo e a disponibilidade do comprovante. Veja Estorno Pix pendente e com falha.

Os estados aceitos e as demais condições continuam valendo; boleto não permite estorno por este endpoint. As mudanças confirmadas geram eventos para os webhooks do Sandbox cadastrados para esses tipos. Em Produção, uma solicitação aceita pode retornar 202 enquanto aguarda a confirmação, que deve ser acompanhada pela consulta do estorno.

As requisições usam https://api.raims.com e exigem uma chave de API. Não é necessário habilitar uma permissão adicional de estorno nessa chave. A permissão Devolver Pix dos colaboradores autoriza a ação no Dashboard; ela não é exigida nas requisições da API.

A empresa e o ambiente vêm da chave; um identificador de outra empresa ou ambiente não concede acesso à cobrança nem ao estorno.