申请退款

概述

PUT /api/pix/:e2eid/devolucao/:id 端点用于申请退还已收到的 PIX。您需要提供原始 PIX 的 End to End ID（e2eid）以及由您的系统生成的退款标识符。

退款可以是全额或部分。所有退款的总和不能超过原始 PIX 的金额。

端点

PUT https://api.fypay.me/api/pix/{e2eid}/devolucao/{id}

认证

stringobrigatorio

通过 POST https://api.fypay.me/api/auth/token 获取的 Bearer 令牌。此路由不使用客户端证书。

URL 参数

e2eidstringobrigatorio

要退还的已收 PIX 的标识符。接受 End to End ID（RECEIVE Webhook 中的 data.endToEndId）或 FyPay 中的数字交易 ID（收款的 loc.id 或 Webhook 的 data.id）。

示例：E12345678202401151030abcdefghijk

idstringobrigatorio

由您的系统生成、用于表示该笔退款的标识。最多 100 个字符，且在账户内唯一：重复使用已用过的 id 会返回 400，错误码为 PIX_DUPLICATE_EXTERNAL_ID。

示例：D123456789

请求体

stringobrigatorio

申请退款的金额。字符串，十进制格式，恰好 2 位小数（^\d{1,10}\.\d{2}$）。

所有退款金额之和不能超过原始 PIX 的金额。

示例："7.89"

string

退款性质：ORIGINAL 或 RETIRADA。为兼容巴西央行标准而接受，并在响应中返回。目前无论该字段取值如何，所有退款都按普通退款处理。

string

向付款人展示的退款说明文本。

最多：140 个字符。

请求

curl -X PUT https://api.fypay.me/api/pix/E12345678202401151030abcdefghijk/devolucao/D123456789 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": "7.89",
    "descricao": "Devolução solicitada pelo recebedor"
  }'

const e2eid = 'E12345678202401151030abcdefghijk';
const devolucaoId = 'D123456789';

const response = await fetch(
  `https://api.fypay.me/api/pix/${e2eid}/devolucao/${devolucaoId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      valor: '7.89',
      descricao: 'Devolução solicitada pelo recebedor',
    }),
  }
);

const devolucao = await response.json();

import requests

e2eid = 'E12345678202401151030abcdefghijk'
devolucao_id = 'D123456789'

response = requests.put(
    f'https://api.fypay.me/api/pix/{e2eid}/devolucao/{devolucao_id}',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
    },
    json={
        'valor': '7.89',
        'descricao': 'Devolução solicitada pelo recebedor',
    }
)

devolucao = response.json()

响应

{
  "id": "D123456789",
  "rtrId": "00000000000000000000000000000789",
  "valor": "7.89",
  "natureza": "ORIGINAL",
  "descricao": "Devolução solicitada pelo recebedor",
  "horario": {
    "solicitacao": "2024-01-15T10:30:00.000Z"
  },
  "status": "EM_PROCESSAMENTO"
}

{
  "statusCode": 400,
  "code": "PIX_REFUND_EXCEEDS_AVAILABLE",
  "message": "Refund value (R$ 25.00) exceeds available amount to refund (R$ 20.00)",
  "userMessage": "Valor do reembolso excede o valor disponível.",
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

{
  "statusCode": 404,
  "code": "PIX_TRANSACTION_NOT_FOUND",
  "message": "Transaction with e2eId E12345678202401151030abcdefghijk not found",
  "userMessage": "Transação não encontrada.",
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

响应字段

idstring

退款标识（与 URL 中发送的值相同）。

rtrIdstring

FyPay 中的退款标识符：退款交易的内部 ID，左侧补零至 32 个字符。它不是退款的 End to End ID；后者会在 REFUND Webhook 的 data.refunds[0].endToEndId 中返回。

valorstring

退款金额，2 位小数的字符串。

naturezastring

发送的 natureza 值（ORIGINAL 或 RETIRADA），省略时为 ORIGINAL。

descricaostring

发送的 descricao 文本（如有）。

horarioobject

statusstring

响应时的退款状态：

EM_PROCESSAMENTO：退款处理中（正常情况）
DEVOLVIDO：退款已结算
NAO_REALIZADO：退款失败

motivostring

仅当 status = NAO_REALIZADO 时返回，文本为 Erro ao processar devolução。

退款的最终结果通过 REFUND Webhook 送达，发送到在 refund_in 事件下以 PIX BACEN 格式登记的 URL。

退款 Webhook

退款处理完成后，您会收到 REFUND 类型的 Webhook（节选）：

{
  "data": {
    "id": 12345,
    "txId": "7978c0c97ea847e78e8849634473c1f1",
    "status": "REFUNDED",
    "payment": {
      "amount": "100",
      "currency": "BRL"
    },
    "refunds": [
      {
        "status": "LIQUIDATED",
        "payment": {
          "amount": 7.89,
          "currency": "BRL"
        },
        "errorCode": null,
        "eventDate": "2024-01-15T10:30:00.000Z",
        "endToEndId": "D12345678202401151030abcdefghijk",
        "information": "Devolução solicitada pelo recebedor"
      }
    ],
    "endToEndId": "E12345678202401151030abcdefghijk",
    "creditDebitType": "DEBIT"
  },
  "type": "REFUND"
}

await solicitarDevolucao(e2eid, 'DEV001', '30.00');

await solicitarDevolucao(e2eid, 'DEV002', '50.00');

await solicitarDevolucao(e2eid, 'DEV003', '25.00');

如果原始 PIX 为 R$ 100.00，前两次合计 R$ 80.00，第三次会以 400 PIX_REFUND_EXCEEDS_AVAILABLE 失败，因为仅剩 R$ 20.00 可退。

常见错误

HTTP 状态码	`code`	原因
400	`PUB_REQUEST_BODY_INVALID`	`valor` 格式错误、`natureza` 无效或 `descricao` 超过 140 个字符
400	`PIX_DUPLICATE_EXTERNAL_ID`	该账户已使用过此退款 `id`
400	`PIX_REFUND_EXCEEDS_AVAILABLE`	金额超过剩余可退余额
400	`PIX_REFUND_DEADLINE_EXCEEDED`	距原始 PIX 已超过 89 天
400	`PIX_INVALID_TRANSACTION_TYPE_FOR_REFUND`	该交易不是已收到的 PIX
400	`PIX_INVALID_TRANSACTION_STATE`	原始交易所处状态不允许退款
400	`PIX_TRANSACTION_ACCOUNT_MISMATCH`	该交易属于其他账户
401		令牌缺失、无效或已过期
404	`PIX_TRANSACTION_NOT_FOUND`	未找到与所提供 `e2eid` 对应的 PIX

申请退款

概述

端点

认证

URL 参数

请求体

请求

响应

响应字段

退款 Webhook

REFUND Webhook

退款期限

部分退款

常见错误

下一步

PIX 转账

REFUND Webhook

本页目录

申请退款

属性

REFUND Webhook

PIX 转账

REFUND Webhook

本页目录