退款指南（PIX 退款）

本指南说明如何为已收到的 PIX 付款申请退款。

概述

PIX 退款允许您全额或部分撤销已收到的付款。您可以通过以下方式申请退款：

• E2E (End-to-End ID) - PIX 系统中的唯一交易标识符
• Identifier - CorpX 内部的收款 ID

使用场景

• 重复付款 - 客户付款两次
• 订单取消 - 付款后取消订单
• 金额错误 - 客户支付的金额与预期不符
• 操作失误 - 错误地收到付款

期限

类型	期限
普通退款	付款后 90 天内
欺诈退款	付款后 90 天内

注意

超过 90 天后，PIX 退款将不再可用。请使用其他方式处理。

通过 E2E (End-to-End ID) 申请退款

E2E 是巴西 PIX 系统中的唯一交易标识符。格式：E{ISPB}{DATE}{SEQUENTIAL}。

请求

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

请求体参数

字段	类型	必填	描述
accountId	string	是	收到原始 PIX 的账户 UUID
originalEndToEnd	string	是	要退款的原始交易的 E2E ID
amount	number	是	退款金额（BRL）
currency	string	是	固定为 BRL
reason	string	是	退款原因代码（见下表）

reason 值

值	描述
USER_REQUESTED	用户/集成方申请的退款
FRAUD	欺诈交易
BANK_ERROR	银行/合作伙伴处理错误
CASHIER_ERROR	收银员/操作员失误
CUSTOMER_REQUEST	终端客户请求

成功响应 (202 Accepted)

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

字段	描述
refundId	内部退款 ID
status	PROCESSING、COMPLETED、REJECTED
amount	退款金额

部分退款

您可以通过指定小于原始金额的 amount 来仅退还部分金额：

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

响应

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

信息

您可以进行多次部分退款，直到达到原始交易的总金额。

可能的状态

状态	描述
PROCESSING	退款处理中
COMPLETED	退款成功完成
REJECTED	退款被拒绝

退款 Webhook

当退款处理完成后，您会收到一个 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"
    }
  }
}

完整示例：退款脚本

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

如何找到 E2E

E2E 可以在以下位置找到：

1. 收款 webhook 响应中
2. 收款查询 在付款后
3. 账户对账单（Statement）
4. 付款方的收据

示例：从 Webhook 中提取 E2E

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

示例：从收款（QR Code）中提取 E2E

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

常见错误

错误	原因	解决方案
transaction_not_found	未找到 E2E 或 Identifier	检查标识符
already_refunded	交易已退款	检查历史记录
refund_amount_exceeded	金额超过可用余额	减少退款金额
refund_expired	超过 90 天期限	使用其他撤销方式
insufficient_balance	退款余额不足	向账户充值

最佳实践

1. 保存所有已收交易的 E2E
2. 使用 Idempotency Key 以避免重复退款
3. 在申请前验证金额（不能超过原始金额）
4. 记录退款原因 以便审计
5. 配置 webhooks 以跟踪状态
6. 保留退款历史 用于对账

后续步骤

• 认证指南 - 获取访问令牌
• QR Code 指南 - 创建收款
• Webhooks - 接收通知