> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# 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 um pagamento recebido, **no todo ou em parte**. A transação original é sempre identificada pelo **E2E (End-to-End ID)** — não existe devolução por `identifier` da cobrança. Se você só tem o `identifier`, consulte o QR ou o pagamento primeiro para obter o E2E (ver [Onde Encontrar o E2E](#onde-encontrar-o-e2e)).

## 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

O prazo para devolução PIX é definido pelo BACEN e aplicado pelo liquidante:
**90 dias** contados do pagamento original, tanto para devolução comum quanto
para os casos de fraude.

> **Warning**
>
> Passado esse prazo, o liquidante recusa a devolução — a API repassa a recusa
> como `partner_rejected` (422), com o motivo informado no bloco `partner`. Não
> há um código de erro específico para "prazo expirado". Nesse cenário, use
> outros meios de estorno.

## 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

```bash
curl -X POST "https://tenant.api.corpx.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 '{
    "originalEndToEnd": "E36741675202601281435001234567",
    "amount": 150.00,
    "reason": "user-requested",
    "identifier": "refund-order-12345"
  }'
```

### Parâmetros do Body

A conta que recebeu o PIX original vem do path (`{accountId}`) e a moeda é
sempre BRL — nenhum dos dois é lido do body.

| Campo              | Tipo   | Obrigatório | Descrição                                                                                                               |
| ------------------ | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
| `originalEndToEnd` | string | Sim         | ID E2E da transação original a ser devolvida                                                                            |
| `amount`           | number | Sim         | Valor a devolver em BRL — igual ao valor do PIX original (estorno total) ou menor (estorno parcial). Não pode excedê-lo |
| `reason`           | string | Sim         | Motivo da devolução em **kebab-case** (ver tabela abaixo)                                                               |
| `identifier`       | string | Não         | Identificador da devolução (máx. 38 chars `[A-Za-z0-9._-]`). Gerado automaticamente se omitido                          |
| `description`      | string | Não         | Descrição livre (máx. 140 caracteres)                                                                                   |

### Valores de `reason`

A lista é **fechada**: qualquer valor fora desta tabela é rejeitado com HTTP 400. Os slugs são repassados literalmente ao liquidante, sem tradução.

| Slug                       | Quando usar                                                        |
| -------------------------- | ------------------------------------------------------------------ |
| `user-requested`           | Cliente final solicitou a devolução (caso mais comum)              |
| `transaction-error`        | Erro genérico na transação (valor incorreto, dados inconsistentes) |
| `unauthorized-transaction` | Transação não autorizada pelo titular                              |
| `fraud`                    | Fraude comprovada/em investigação                                  |
| `trade-disagreement`       | Desacordo comercial (bem/serviço não entregue)                     |
| `withdrawal-purchase`      | Operação envolvendo PIX Saque/Troco                                |
| `contractual-divergence`   | Divergência contratual entre as partes                             |
| `operational-error`        | Erro operacional/processamento bancário                            |
| `duplicate-payment`        | Pagamento duplicado                                                |

### Resposta de Sucesso

A devolução usa o **mesmo pipeline (e shape) do PIX out**. O status HTTP
reflete o desfecho: **200** (`COMPLETED`), **422** (`FAILED`), **202**
(`TIMEOUT`/`PENDING`).

```json
{
  "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "transactionId": "txn-refund-abc123",
  "endToEndId": "D12345678202301011500009876543",
  "status": "COMPLETED",
  "completedAt": "2026-01-28T15:00:03Z",
  "identifier": "refund-order-12345"
}
```

| Campo                       | Descrição                                                 |
| --------------------------- | --------------------------------------------------------- |
| `paymentId`                 | ID interno da intenção (rastreio/conciliação)             |
| `endToEndId`                | D-code/E2E da devolução (após registrada)                 |
| `status`                    | `COMPLETED`, `FAILED`, `TIMEOUT`, `PENDING`, `PROCESSING` |
| `errorCode` / `errorReason` | preenchidos quando `FAILED`                               |

> Não há campo `refundId`/`amount`/`currency` na resposta — use `paymentId`
> e acompanhe o desfecho final pelo extrato ou webhook.

## Estorno parcial

O campo `amount` é obrigatório e define quanto volta ao pagador: envie o
valor integral do PIX original para estornar tudo, ou um valor menor para
estornar em parte. Acima do original, a API responde
`400 refund_amount_exceeded` e não inicia a devolução.

Um mesmo PIX pode ser devolvido em mais de uma parcela, até somar o valor
original. Duas regras importam aqui:

* **Cada devolução precisa de `Idempotency-Key` e `identifier`
  próprios.** Repetir um dos dois faz a API tratar a chamada como
  retentativa da devolução anterior e devolver o resultado dela — a
  segunda parcela nunca sai.
* **O controle do quanto ainda resta devolvível é do banco liquidante.**
  A CorpX não soma parciais: uma devolução que estoure o saldo devolvível
  é recusada pelo liquidante e volta como `refund_amount_exceeded`.

Para saber quanto de um PIX já foi devolvido, consulte o extrato da
conta: as linhas de devolução referenciam o E2E da transação original.

## Webhook de Devolução

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

```json
{
  "id": "pix-refund-pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "type": "pix.refund.completed",
  "occurredAt": "2026-01-28T15:00:03.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "{accountId}",
  "data": {
    "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
    "tenantId": "tenant-suaempresa",
    "accountId": "{accountId}",
    "status": "SUCCESS",
    "endToEnd": "D36741675202601281500009876543",
    "transactionId": "txn-refund-abc123",
    "amount": 150.00,
    "currency": "BRL",
    "identifier": "refund-order-12345",
    "description": "",
    "originalTransactionId": "E36741675202601281435001234567",
    "initiatedAt": "2026-01-28T15:00:01.000000000Z",
    "completedAt": "2026-01-28T15:00:03.000000000Z",
    "payee": {
      "name": "John Smith",
      "document": "12345678901"
    }
  }
}
```

Uma devolução recusada emite `pix.refund.failed` com `status: "FAILED"` e os
campos `errorCode`/`errorReason`/`error` no `data`. Devolução em `TIMEOUT`
**não** emite webhook — consulte o extrato.

## Exemplo Completo: Script de Devolução

```bash
#!/bin/bash

# Configuration
API_URL="https://tenant.api.corpx.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/$ACCOUNT_ID/pix/out/refund" \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Tenant-Id: $TENANT_ID" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
    -d "{
      \"originalEndToEnd\": \"$e2e\",
      \"amount\": $amount,
      \"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

```json
{
  "id": "evt_in_123",
  "type": "pix.in.completed",
  "occurredAt": "2026-01-28T14:35:00.000Z",
  "schemaVersion": "1.0",
  "tenantId": "tenant-suaempresa",
  "accountId": "{accountId}",
  "data": {
    "identifier": "cob_abc123def456",
    "endToEnd": "E36741675202601281435001234567",
    "amount": 150.00
  }
}
```

O campo a guardar é `data.endToEnd`.

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

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

```json
{
  "identifier": "order-12345",
  "status": "PAID",
  "endToEndId": "E36741675202601281435001234567"
}
```

A resposta do lookup de QR é um objeto **plano** (sem envelope `data`); o
campo a guardar é `endToEndId`.

## Erros Comuns

| Erro                             | HTTP | Causa                                                                    | Solução                                                                               |
| -------------------------------- | ---- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `missing_fields`                 | 400  | `originalEndToEnd` ou `amount` ausente                                   | Envie os dois campos                                                                  |
| `invalid_payload`                | 400  | `reason` fora da lista fechada, ou JSON malformado                       | Use um dos slugs da tabela acima                                                      |
| `refund_amount_exceeded`         | 400  | `amount` maior que o PIX original, ou maior que o saldo ainda devolvível | Confira no extrato quanto já foi devolvido                                            |
| `original_transaction_not_found` | 404  | E2E não encontrado no liquidante                                         | Verifique o `originalEndToEnd`                                                        |
| `conflict`                       | 409  | Transação já devolvida integralmente                                     | Verifique o histórico no extrato                                                      |
| `insufficient_funds`             | 422  | Saldo insuficiente para a devolução                                      | Deposite fundos na conta                                                              |
| `policy_denied`                  | 422  | Uma regra de política do tenant/conta recusou a devolução                | Veja `violations` no corpo — [Políticas e Regras](/baas/guias/autenticacao/politicas) |
| `partner_rejected`               | 422  | Recusa do liquidante (inclui prazo de 90 dias vencido)                   | Veja o bloco `partner` com o motivo                                                   |
| `partner_error`                  | 502  | Falha ao consultar a transação original no liquidante                    | Tente novamente; se persistir, acione o suporte                                       |

A lista completa está em [Erros](/baas/guias/referencia/erros).

## Boas Práticas

1. **Salve o E2E** de todas as transações recebidas
2. **Use Idempotency Key** para evitar devoluções duplicadas — e uma chave (e `identifier`) diferente a cada parcial do mesmo PIX
3. **Confira no extrato** quanto de um PIX já foi devolvido antes de pedir uma nova parcial
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](/baas/guias/autenticacao/oauth2) - Obter tokens de acesso
* [Guia de QR Code](/baas/guias/receber/qr-code-dinamico) - Criar cobranças
* [Webhooks](/baas/guias/conta/webhooks) - Receber notificações