Devolver QrCode de Cobrança

Este endpoint realiza a devolução de um QrCode de cobrança PIX. Para fazê-lo deve ser efetuada a chamada para a API, como especificado abaixo.

aviso

Esta funcionalidade faz a devolução do valor TOTAL do qrcode.

Request

A chamada deverá ser feita utilizando o método POST.

URL

{BaseUrl}/api/v1/pix/collections/:transaction_id/refund

HTTP Headers - Exemplo:

Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/json

Exemplo cURL - bash:

curl -X POST https://api.moneyguard.com.br/api/v1/pix/collections/QR-abc123def456/refund \
    -H "Authorization: Bearer seu_access_token" \
    -H "User-Agent: seu_user_agent"

Response

Em caso de sucesso, será retornado uma mensagem HTTP 200 – OK, contendo os dados, conforme apresentado abaixo:

HTTP 200 Response Body - Exemplo

{
    "success": true,
    "data": {
        "id": 123,
        "reference_code": "9403d9b8-fc83-4ec0-8c8f-0a05990c7c44",
        "status": "pending",
        "request_date": "2026-02-09T11:50:25.673-03:00",
        "value": 150.0
    }
}

Descrição dos Atributos

ATRIBUTO	DESCRIÇÃO	TIPO
success (Obrigatório)	Indica que a devolução foi solicitada com sucesso.	BOOLEAN
data.id (Obrigatório)	Identificador numérico da devolução.	INTEGER
data.reference_code (Obrigatório)	Identificador único da devolução.	STRING limite de 36 caracteres
data.status (Obrigatório)	Status da devolução. Na resposta desta chamada será sempre pending.	ENUM pending (Devolução solicitada) reversed (Devolução concluída) error (Devolução falhou)
data.request_date (Obrigatório)	Data/hora da solicitação da devolução.	STRING formato datetime ISO 8601
data.value (Obrigatório)	Valor devolvido, em reais.	DECIMAL Maior que zero

informação

A devolução é processada de forma assíncrona. A confirmação (ou falha) será comunicada através da notificação collection.reversed, enviada ao webhook do tipo pix_in cadastrado.

Error

Em caso de erros, será retornado um json com o atributo error especificando o motivo de a operação ter sido rejeitada.

HTTP 422 Response Body - Exemplos

{ "error": "QR code ainda não foi pago" }
{ "error": "Já existe uma devolução pendente para este QR code" }
{ "error": "Saldo insuficiente para a devolução" }

HTTP 404 Response Body - Exemplo

{
    "error": "Couldn't find PixQrcode"
}