MED 集成

概览

本指南展示如何将 MED 流程集成到您的应用中。您将了解如何：

配置 webhook 以接收 MED 通知
查询账户中的 MED 列表
处理各类事件（创建、批准、拒绝）

开始之前，请先阅读 MED 概览以了解涉及的生命周期和概念。

1. 配置 MED webhook

在控制台 https://banking.fypay.me 的 设置 → Webhooks 中，为您希望接收的每种 MED 事件类型注册一个端点。URL 必须为 HTTPS；每个事件最多接受 3 个 URL 和最多 5 个自定义 header。详细步骤请参阅配置 Webhooks。

事件	描述
`med_created`	针对您账户接收到新 MED 的通知。
`med_accepted`	MED 已批准的通知（退款被接受 — 金额将退还给付款人）。
`med_rejected`	MED 被拒绝的通知（退款被拒绝 — 余额保留在受益人处）。

我们建议配置全部三种 webhook（med_created、med_accepted、med_rejected），以完整掌握 MED 的生命周期。

2. 查询 MED

使用 GET /api/med 结合筛选和分页列出您账户中的 MED。

参数	类型	描述
`status`	string	`OPEN`、`RECEIVED`、`CANCELLED` 或 `ANALYZED`（也接受 `CANCELED`）
`isReconciled`	boolean	`true` 表示已关联到您账户交易的 MED
`startDate`	string	开始日期（ISO 8601）
`endDate`	string	结束日期（ISO 8601）
`page`	integer	页码（默认：1）
`pageSize`	integer	每页条数（默认：20，最大：100）

列出所有 MED

curl -X GET "https://api.fypay.me/api/med" \
  -H "Authorization: Bearer $TOKEN"

按状态筛选

curl -X GET "https://api.fypay.me/api/med?status=RECEIVED" \
  -H "Authorization: Bearer $TOKEN"

按时间段筛选

curl -X GET "https://api.fypay.me/api/med?startDate=2026-01-01T00:00:00.000Z&endDate=2026-01-31T23:59:59.999Z&page=1&pageSize=50" \
  -H "Authorization: Bearer $TOKEN"

响应示例

{
  "data": [
    {
      "id": 42,
      "endToEnd": "E12345678202604101030abcdef123456",
      "status": "RECEIVED",
      "reason": "REFUND_REQUEST",
      "cause": "UNAUTHORIZED_TRANSACTION",
      "description": "客户声称未发起该交易",
      "analysisResult": null,
      "analysisDetails": null,
      "requestingBank": {
        "ispb": "00000000",
        "name": "BANCO SOLICITANTE S.A."
      },
      "contestedBank": {
        "ispb": "11111111",
        "name": "INSTITUICAO CONTESTADA S.A."
      },
      "originalTransaction": {
        "amount": 1500.00,
        "type": "PIX",
        "transactionType": "CASH_IN",
        "name": "João da Silva",
        "document": "***456789**",
        "dateTime": "2026-04-05T14:30:00.000Z"
      },
      "isReconciled": true,
      "originalTransactionId": 78432,
      "createdAt": "2026-04-10T10:00:00.000Z",
      "updatedAt": "2026-04-10T10:00:00.000Z"
    }
  ],
  "metadata": {
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1
  }
}

isReconciled 字段表示该 MED 是否已自动关联到您账户中的本地交易。为 true 时，originalTransactionId 字段包含原始 PIX 交易的 ID。

查看 MED 详情

使用 GET /api/med/\{id\}（MED 的数字 id）获取全部字段，包括状态历史（statusHistory）、原始交易详情、监管标识符 idSolicitacaoDevolucao 以及锁定数据（blockStatus、blockAmount）。如果该 MED 不属于您的账户，API 返回 404。

curl -X GET "https://api.fypay.me/api/med/42" \
  -H "Authorization: Bearer $TOKEN"

3. 处理 MED webhook

处理器示例（Node.js）

import express from 'express';
const app = express();
app.use(express.json());

app.post('/webhooks/med', async (req, res) => {
  const { event, medId, status, cause, originalTransaction } = req.body;

  console.log(`MED ${medId}: ${event} (status: ${status})`);

  switch (event) {
    case 'MedCreated':
      // 收到新的 MED — 通知团队和/或锁定受益人的操作
      await notifyTeam({
        message: `MED #${medId} 已收到 — 原因：${cause}`,
        amount: originalTransaction?.amount,
        endToEndId: originalTransaction?.endToEndId,
      });
      break;

    case 'MedAccepted':
      // 退款已批准 — 金额将退还给付款人
      await updateTransaction({
        medId,
        status: 'DEVOLVIDO',
        note: 'MED 已批准 — 金额已退还给原付款人',
      });
      break;

    case 'MedRejected':
      // 退款被拒绝 — 余额保留在受益人处
      await updateTransaction({
        medId,
        status: 'MANTIDO',
        note: 'MED 被拒绝 — 余额已解锁',
      });
      break;
  }

  // 始终返回 200 以确认接收
  res.status(200).json({ received: true });
});

处理器示例（Python）

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/med', methods=['POST'])
def handle_med_webhook():
    data = request.json
    event = data.get('event')
    med_id = data.get('medId')
    cause = data.get('cause')

    print(f"MED {med_id}: {event} (原因: {cause})")

    if event == 'MedCreated':
        # 新的 MED — 提醒团队
        notify_team(med_id, cause, data.get('originalTransaction'))

    elif event == 'MedAccepted':
        # 退款已批准
        update_transaction(med_id, 'DEVOLVIDO')

    elif event == 'MedRejected':
        # 退款被拒绝
        update_transaction(med_id, 'MANTIDO')

    return jsonify({'received': True}), 200

4. 推荐流程

┌─────────────────────────────────────────────────────────────┐
│                        您的应用                              │
│                                                              │
│  MedCreated webhook ──────▶ 提醒风控团队                     │
│       │                     将交易标记为"MED 处理中"          │
│       │                     （可选）锁定受益人                │
│       │                                                      │
│       ▼                                                      │
│  查询 GET /api/med ───────▶ 核实详情和原因                    │
│       │                     跟踪状态                          │
│       │                                                      │
│       ▼                                                      │
│  MedAccepted webhook ─────▶ 记录退款                         │
│       或                    更新客户余额                      │
│  MedRejected webhook ─────▶ 解锁受益人                       │
│                              保留余额                         │
└─────────────────────────────────────────────────────────────┘

最佳实践

配置全部 3 个 webhook

始终配置 med_created、med_accepted 和 med_rejected，以完整掌握生命周期。

快速返回 200

以异步方式处理 webhook。投递超时时间为 10 秒，且只有 2xx 响应才算成功；否则系统会尝试重新发送。

使用幂等性

使用 medId + event 的组合作为幂等键（同一个 medId 会先出现在 MedCreated 中，之后出现在 MedAccepted 或 MedRejected 中）。投递失败时，同一个 webhook 可能会被重新发送。

监控未结 MED

定期查询 GET /api/med?status=RECEIVED，确保没有遗漏未处理的 MED。