Guia de Devolução (PIX Refund)

Este guia explica como solicitar a devolução de um pagamento PIX recebido.

Visão Geral

A devolução PIX permite estornar total ou parcialmente um pagamento recebido. Você pode solicitar a devolução usando:

• E2E (End-to-End ID) - Identificador único da transação no sistema PIX
• Identifier - ID interno da cobrança na CorpX

Quando Utilizar

• Pagamento duplicado - Cliente pagou duas vezes
• Cancelamento de pedido - Pedido cancelado após o pagamento
• Valor incorreto - Cliente pagou um valor diferente do esperado
• Erro operacional - Pagamento recebido incorretamente

Prazos

Tipo	Prazo
Devolução normal	Até 90 dias após o pagamento
Devolução por fraude	Até 90 dias após o pagamento

aviso

Após 90 dias, devoluções PIX não são mais possíveis. Utilize outros meios.

Solicitar Devolução por E2E (End-to-End ID)

O E2E é o identificador único da transação no sistema PIX brasileiro. Formato: E{ISPB}{DATE}{SEQUENTIAL}.

Request

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/pix/out/refund" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-e2e-12345" \
  -d '{
    "accountId": "{accountId}",
    "originalEndToEnd": "E36741675202601281435001234567",
    "amount": 150.00,
    "currency": "BRL",
    "reason": "USER_REQUESTED"
  }'

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
accountId	string	Sim	UUID da conta que recebeu o PIX original
originalEndToEnd	string	Sim	ID E2E da transação original a ser devolvida
amount	number	Sim	Valor a devolver em BRL
currency	string	Sim	Sempre BRL
reason	string	Sim	Motivo da devolução (ver tabela abaixo)

Valores de reason

Valor	Descrição
USER_REQUESTED	Devolução solicitada pelo usuário/integrador
FRAUD	Transação fraudulenta
BANK_ERROR	Erro do banco/parceiro
CASHIER_ERROR	Erro operacional/caixa
CUSTOMER_REQUEST	Solicitação do cliente final

Resposta de Sucesso (202 Accepted)

{
  "refundId": "ref-abc123-def456",
  "status": "PROCESSING",
  "amount": 150.00,
  "currency": "BRL"
}

Campo	Descrição
refundId	ID interno da devolução
status	PROCESSING, COMPLETED, REJECTED
amount	Valor da devolução

Devolução Parcial

Você pode devolver apenas parte do valor especificando um amount menor que o valor original:

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/pix/out/refund" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-partial-12345" \
  -d '{
    "accountId": "{accountId}",
    "originalEndToEnd": "E36741675202601281435001234567",
    "amount": 50.00,
    "currency": "BRL",
    "reason": "CUSTOMER_REQUEST"
  }'

Resposta

{
  "refundId": "ref-partial-123",
  "status": "PROCESSING",
  "amount": 50.00,
  "currency": "BRL"
}

informação

Você pode realizar múltiplas devoluções parciais até atingir o valor total da transação original.

Status Possíveis

Status	Descrição
PROCESSING	Devolução em andamento
COMPLETED	Devolução concluída com sucesso
REJECTED	Devolução rejeitada

Webhook de Devolução

Quando a devolução for processada, você receberá um webhook:

{
  "event": "pix.refund.completed",
  "timestamp": "2026-01-28T15:00:03Z",
  "data": {
    "refundId": "ref_abc123xyz789",
    "status": "COMPLETED",
    "originalEndToEndId": "E36741675202601281435001234567",
    "refundEndToEndId": "D36741675202601281500009876543",
    "originalValue": 150.00,
    "refundedValue": 150.00,
    "recipient": {
      "name": "John Smith",
      "document": "12345678901"
    }
  }
}

Exemplo Completo: Script de Devolução

#!/bin/bash

# Configuration
API_URL="https://api.corpxapi.com"
TOKEN="your_token_here"
TENANT_ID="tenant-suaempresa"
ACCOUNT_ID="your_account"

# Refund by E2E function
refund_by_e2e() {
  local e2e=$1
  local amount=$2
  local reason=$3
  
  echo "Requesting refund..."
  echo "E2E: $e2e"
  echo "Amount: R$ $amount"
  echo "Reason: $reason"
  echo ""
  
  IDEMPOTENCY_KEY="refund-$(date +%s)-$RANDOM"
  
  response=$(curl -s -X POST "$API_URL/v1/accounts/{accountId}/pix/out/refund" \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Tenant-Id: $TENANT_ID" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
    -d "{
      \"accountId\": \"$ACCOUNT_ID\",
      \"originalEndToEnd\": \"$e2e\",
      \"amount\": $amount,
      \"currency\": \"BRL\",
      \"reason\": \"$reason\"
    }")
  
  echo "$response" | jq
}

# Usage
echo "=== PIX REFUND ==="
echo ""
read -p "E2E (End-to-End ID): " e2e
read -p "Amount to refund: " amount
read -p "Reason: " reason

refund_by_e2e "$e2e" "$amount" "$reason"

Onde Encontrar o E2E

O E2E pode ser encontrado em:

1. Webhook de pagamento recebido
2. Consulta da cobrança após o pagamento
3. Extrato da conta (Statement)
4. Comprovante do pagador

Exemplo: Extrair E2E do Webhook

{
  "event": "pix.in.completed",
  "data": {
    "identifier": "cob_abc123def456",
    "endToEndId": "E36741675202601281435001234567",  // <-- Use este valor
    "value": 150.00
  }
}

Exemplo: Extrair E2E da Cobrança (QR Code)

curl -X GET "https://api.corpxapi.com/v1/accounts/{accountId}/pix/qr-code?identifier=order-12345" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"

{
  "statusCode": 200,
  "data": {
    "identifier": "order-12345",
    "status": "PAID",
    "endToEndId": "E36741675202601281435001234567"  // <-- Use este valor
  }
}

Erros Comuns

Erro	Causa	Solução
transaction_not_found	E2E ou Identifier não encontrado	Verifique o identificador
already_refunded	Transação já foi devolvida	Verifique o histórico
refund_amount_exceeded	Valor excede o saldo disponível	Reduza o valor da devolução
refund_expired	Prazo de 90 dias excedido	Utilize outro método de estorno
insufficient_balance	Saldo insuficiente para devolução	Deposite fundos na conta

Boas Práticas

1. Salve o E2E de todas as transações recebidas
2. Use Idempotency Key para evitar devoluções duplicadas
3. Valide o valor antes de solicitar (não pode exceder o original)
4. Documente o motivo para fins de auditoria
5. Configure webhooks para acompanhar o status
6. Mantenha um histórico de devoluções para conciliação

Próximos Passos

• Guia de Autenticação - Obter tokens de acesso
• Guia de QR Code - Criar cobranças
• Webhooks - Receber notificações