Guia de Devoluções Pix

Este guia detalha a devolução de um Pix recebido, com foco em regras, implementação e conciliação.

Regras importantes

Antes de implementar, considere:

• A soma das devoluções não pode ultrapassar o valor original;
• A devolução deve ocorrer em até 30 dias da liquidação original;
• Cada devolução gera um return_identification próprio.

Fluxo de devolução (visão rápida)

Pré-requisitos

1. Token JWT válido (veja Guia de Autenticação);
2. Identificador original_end_to_end_id da transação original;
3. Valor da devolução em centavos;
4. external_id único por devolução.

Passo 1 - Iniciar devolução

Endpoint de referência: Iniciar uma devolução

POST /v1/connect/refund HTTP/1.1
Host: api.qesh.ai
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount": 1000,
  "original_end_to_end_id": "E318188732025073114206r8iSU2Swrt",
  "external_id": "refund-pedido-2026-03-001"
}

Campos obrigatórios:

• amount
• original_end_to_end_id

Passo 2 - Acompanhar status da devolução

Endpoints de consulta:

• Consultar devolução por ID
• Consultar devolução por ID externo
• Consultar devolução por Return Identification
• Consultar devoluções por End To End original

Status possíveis:

• PROCESSING
• RETURNED
• ERROR

Persista em sua base:

• id
• external_id
• return_identification
• original_end_to_end_id
• status

Cenários comuns

• Devolução parcial: devolver parte do valor original;
• Devoluções múltiplas: várias devoluções parciais, respeitando o limite total;
• Falha na devolução (ERROR): tratar com monitoramento e suporte.

Eventos de webhook relacionados

• refund.in.processing: devolução de um pagamento feito, mas ainda não liquidada;

• refund.in.returned: devolução concluída, valor retornado ao pagador;

• refund.in.error: falha na devolução, possível necessidade de ação manual.

• refund.out.processing: devolução de um pagamento recebido, mas ainda não liquidada;

• refund.out.returned: devolução concluída, valor retornado ao pagador;

• refund.out.error: falha na devolução, possível necessidade de ação manual.

Payload de webhooks relacionados a devoluções:

{
    "id": 12345678, // ID interno do evento
    "name": "refund.in.processing", // Nome do evento
    "payload": { // Dados específicos da devolução
        "id": 12345678,
        "external_id": "refund_12345678",
        "return_identification": "D318188732025073114206r8iSU2Swrt", // Identificador de retorno da transação de devolução
        "original_end_to_end_id": "E318188732025073114206r8iSU2Swrt", // Identificador da transação original que está sendo devolvida
        "correlation_id": "correlation_12345678",
        "amount": 1000,
        "status": "PROCESSING",
        "flow": "IN",
        "create_timestamp": "2024-06-01T12:00:00Z"
    },
    "create_timestamp": "2024-06-01T12:00:00Z"
}