Refund Guide (PIX Refund)

This guide explains how to request a refund for a received PIX payment.

Overview

The PIX refund allows you to fully or partially reverse a received payment. You can request the refund using:

• E2E (End-to-End ID) - Unique transaction identifier in the PIX system
• Identifier - Internal charge ID at CorpX

When to Use

• Duplicate payment - Customer paid twice
• Order cancellation - Order cancelled after payment
• Incorrect amount - Customer paid a different amount than expected
• Operational error - Payment received incorrectly

Deadlines

Type	Deadline
Normal refund	Up to 90 days after payment
Fraud refund	Up to 90 days after payment

warning

After 90 days, PIX refunds are no longer possible. Use other means.

Request Refund by E2E (End-to-End ID)

The E2E is the unique transaction identifier in the Brazilian PIX system. Format: 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"
  }'

Body Parameters

Field	Type	Required	Description
accountId	string	Yes	UUID of the account that received the original PIX
originalEndToEnd	string	Yes	E2E ID of the original transaction to be refunded
amount	number	Yes	Amount to refund in BRL
currency	string	Yes	Always BRL
reason	string	Yes	Refund reason code (see table below)

reason Values

Value	Description
USER_REQUESTED	Refund requested by user/integrator
FRAUD	Fraudulent transaction
BANK_ERROR	Bank/partner processing error
CASHIER_ERROR	Cashier/operator error
CUSTOMER_REQUEST	End-customer request

Success Response (202 Accepted)

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

Field	Description
refundId	Internal refund ID
status	PROCESSING, COMPLETED, REJECTED
amount	Refund amount

Partial Refund

You can refund only part of the amount by specifying an amount smaller than the original value:

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"
  }'

Response

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

info

You can make multiple partial refunds until the total amount of the original transaction is reached.

Possible Statuses

Status	Description
PROCESSING	Refund in progress
COMPLETED	Refund completed successfully
REJECTED	Refund rejected

Refund Webhook

When the refund is processed, you receive a 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"
    }
  }
}

Full Example: Refund Script

#!/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"

Where to Find the E2E

The E2E can be found in:

1. Payment received webhook response
2. Charge lookup after payment
3. Account statement (Statement)
4. Payer's receipt

Example: Extract E2E from Webhook

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

Example: Extract E2E from Charge (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 this value
  }
}

Common Errors

Error	Cause	Solution
transaction_not_found	E2E or Identifier not found	Check the identifier
already_refunded	Transaction has already been refunded	Check the history
refund_amount_exceeded	Amount exceeds the available balance	Reduce the refund amount
refund_expired	90-day deadline exceeded	Use another reversal method
insufficient_balance	Insufficient balance for refund	Deposit funds into the account

Best Practices

1. Save the E2E of all received transactions
2. Use Idempotency Key to avoid duplicate refunds
3. Validate the amount before requesting (cannot exceed the original)
4. Document the reason for auditing purposes
5. Configure webhooks to track the status
6. Keep a history of refunds for reconciliation

Next Steps

• Authentication Guide - Obtain access tokens
• QR Code Guide - Create charges
• Webhooks - Receive notifications