Solicitar estorno
Solicite a devolução integral ou parcial de um pagamento Pix recebido.
Solicita a devolução de um pagamento Pix recebido pela cobrança informada. O dinheiro retorna à conta de origem do pagamento. Envie o valor que deseja devolver; a mesma requisição atende devoluções integrais e parciais.
Em Produção, o aceite do pedido ainda não confirma a devolução. No Sandbox, a simulação conclui na própria requisição. Guarde o identificador retornado e confira o estado da mesma solicitação.
Consulte Estornos para conhecer as condições de uso e o acompanhamento do resultado.
Parâmetros de caminho
Identificador da cobrança que recebeu o pagamento Pix.
Até 100 caracteres
Cabeçalhos
Chave única escolhida pelo seu sistema para identificar esta requisição. Ao repetir a tentativa, envie a mesma chave e os mesmos parâmetros. Sem este header, a requisição é processada normalmente. Consulte o guia de idempotência para os prazos e o tratamento de respostas pendentes ou incertas.
1 a 255 caracteres
Parâmetros do corpo
Usar exemplo substitui os campos do corpo.
Valor solicitado para devolução, em centavos de real. Para devolver tudo, informe o valor restante mostrado na consulta de elegibilidade.
Mínimo 1
Descrição da solicitação de devolução. Você pode deixar este campo vazio.
Até 200 caracteres
Respostas
Corpo da resposta
Devolução concluída no Sandbox ou resultado de uma solicitação já processada, sem repetir seu efeito. Confira o status retornado.
Solicitação de devolução Pix vinculada a uma cobrança.
Identificador público da solicitação de estorno.
Identificador da cobrança que recebeu o pagamento original.
Valor solicitado para devolução, em centavos de real.
Descrição da solicitação, ou null quando não informada.
Estado atual: reserved para solicitação em preparação, accepted para pedido aceito e aguardando confirmação, completed para devolução concluída, failed para falha confirmada e unknown para resultado ainda não confirmado. Consulte a mesma solicitação enquanto não houver resultado confirmado.
Data da solicitação, em segundos Unix UTC.
Data da confirmação da devolução, em segundos Unix UTC, ou null.
Data da falha confirmada, em segundos Unix UTC, ou null.
Motivo disponível quando o estado é failed, ou null nos demais estados. Uma falha sem causa registrada usa REFUND_FAILURE_REASON_UNAVAILABLE; não presuma que o pedido foi rejeitado.
Código da causa confirmada. REFUND_FAILURE_REASON_UNAVAILABLE informa que a causa não está disponível.
Explicação em inglês e orientação para acompanhamento. Use code para tratar a causa; não dependa do texto literal.
Corpo da resposta
Solicitação aceita e pendente de confirmação. Guarde o id e acompanhe a mesma solicitação pelo GET de estornos. O valor ainda não deve ser considerado devolvido.
Solicitação de devolução Pix vinculada a uma cobrança.
Identificador público da solicitação de estorno.
Identificador da cobrança que recebeu o pagamento original.
Valor solicitado para devolução, em centavos de real.
Descrição da solicitação, ou null quando não informada.
Estado atual: reserved para solicitação em preparação, accepted para pedido aceito e aguardando confirmação, completed para devolução concluída, failed para falha confirmada e unknown para resultado ainda não confirmado. Consulte a mesma solicitação enquanto não houver resultado confirmado.
Data da solicitação, em segundos Unix UTC.
Data da confirmação da devolução, em segundos Unix UTC, ou null.
Data da falha confirmada, em segundos Unix UTC, ou null.
Motivo disponível quando o estado é failed, ou null nos demais estados. Uma falha sem causa registrada usa REFUND_FAILURE_REASON_UNAVAILABLE; não presuma que o pedido foi rejeitado.
Código da causa confirmada. REFUND_FAILURE_REASON_UNAVAILABLE informa que a causa não está disponível.
Explicação em inglês e orientação para acompanhamento. Use code para tratar a causa; não dependa do texto literal.
Corpo da resposta
Há um campo ou parâmetro inválido, ou a origem da requisição não pôde ser identificada. Confira error.code e error.message. Quando error.details estiver presente, corrija os campos indicados antes de tentar novamente.
Código e explicação do erro retornado pela API.
Código estável do erro.
Explicação do erro em inglês. Em validações, resume a categoria; os detalhes identificam as correções. Use os códigos para tratar a resposta.
Falhas em campos recebidos ou referências enviadas no corpo, com campo, código e explicação. Omitido em erros gerais e quando não há correção de campo a indicar.
Nome público do campo JSON, parâmetro de consulta, parâmetro de rota ou header relacionado ao erro. Campos aninhados e listas preservam o caminho e o índice. $ representa a raiz do corpo JSON.
Motivo do erro no campo, como REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD ou INVALID_TYPE.
Explicação em inglês sobre o problema nesse campo ou parâmetro e a correção disponível. Não use o texto para decidir o fluxo da integração.
Corpo da resposta
Cobrança não encontrada na empresa e no ambiente autenticado.
Código e explicação do erro retornado pela API.
Código estável do erro.
Explicação do erro em inglês. Em validações, resume a categoria; os detalhes identificam as correções. Use os códigos para tratar a resposta.
Falhas em campos recebidos ou referências enviadas no corpo, com campo, código e explicação. Omitido em erros gerais e quando não há correção de campo a indicar.
Nome público do campo JSON, parâmetro de consulta, parâmetro de rota ou header relacionado ao erro. Campos aninhados e listas preservam o caminho e o índice. $ representa a raiz do corpo JSON.
Motivo do erro no campo, como REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD ou INVALID_TYPE.
Explicação em inglês sobre o problema nesse campo ou parâmetro e a correção disponível. Não use o texto para decidir o fluxo da integração.
Corpo da resposta
A devolução não pode ser solicitada nas condições atuais. A mensagem identifica a causa; quando for o estado, informa o estado atual da cobrança e os estados aceitos. Confira o código e consulte o histórico ou a elegibilidade antes de outro pedido. Retry-After, quando presente, informa o prazo de espera para um impedimento temporário.
Código e explicação do erro retornado pela API.
Código estável do erro.
Explicação do erro em inglês. Em validações, resume a categoria; os detalhes identificam as correções. Use os códigos para tratar a resposta.
Falhas em campos recebidos ou referências enviadas no corpo, com campo, código e explicação. Omitido em erros gerais e quando não há correção de campo a indicar.
Nome público do campo JSON, parâmetro de consulta, parâmetro de rota ou header relacionado ao erro. Campos aninhados e listas preservam o caminho e o índice. $ representa a raiz do corpo JSON.
Motivo do erro no campo, como REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD ou INVALID_TYPE.
Explicação em inglês sobre o problema nesse campo ou parâmetro e a correção disponível. Não use o texto para decidir o fluxo da integração.
Para os erros gerais, consulte Códigos HTTP das respostas.