Integración MED

Visión General

Esta guía muestra cómo integrar el flujo de MED en su aplicación. Usted aprenderá a:

Configurar webhooks para recibir notificaciones de MED
Consultar la lista de MEDs de su cuenta
Tratar cada tipo de evento (creación, aprobación, rechazo)

Antes de comenzar, lea la visión general del MED para entender el ciclo de vida y los conceptos involucrados.

1. Configurar los webhooks de MED

Registre un endpoint para cada tipo de evento MED que desee recibir en el panel https://banking.fypay.me, en Configuración → Webhooks. La URL debe ser HTTPS; cada evento acepta hasta 3 URLs y hasta 5 headers personalizados. Vea el paso a paso en Configurar Webhooks.

Evento	Descripción
`med_created`	Notificación de un nuevo MED recibido contra su cuenta.
`med_accepted`	Notificación de MED aprobado (devolución aceptada — el valor será devuelto al pagador).
`med_rejected`	Notificación de MED rechazado (devolución denegada — el saldo permanece con el beneficiario).

Recomendamos configurar los tres tipos de webhook (med_created, med_accepted, med_rejected) para tener visibilidad completa del ciclo de vida del MED.

2. Consultar MEDs

Use GET /api/med para listar los MEDs de su cuenta con filtros y paginación.

Parámetro	Tipo	Descripción
`status`	string	`OPEN`, `RECEIVED`, `CANCELLED` o `ANALYZED` (`CANCELED` también se acepta)
`isReconciled`	boolean	`true` para MEDs vinculados a una transacción de su cuenta
`startDate`	string	Fecha inicial (ISO 8601)
`endDate`	string	Fecha final (ISO 8601)
`page`	integer	Página (predeterminado: 1)
`pageSize`	integer	Elementos por página (predeterminado: 20, máximo: 100)

Listar todos los MEDs

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

Filtrar por estado

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

Filtrar por período

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"

Ejemplo de respuesta

{
  "data": [
    {
      "id": 42,
      "endToEnd": "E12345678202604101030abcdef123456",
      "status": "RECEIVED",
      "reason": "REFUND_REQUEST",
      "cause": "UNAUTHORIZED_TRANSACTION",
      "description": "El cliente alega no haber realizado la transacción",
      "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
  }
}

El campo isReconciled indica si el MED fue vinculado automáticamente a una transacción local de su cuenta. Cuando es true, el campo originalTransactionId contiene el ID de la transacción PIX original.

Detallar un MED

Use GET /api/med/\{id\} (el id numérico del MED) para obtener todos los campos, incluido el historial de estados (statusHistory), la transacción original detallada, el identificador regulatorio idSolicitacaoDevolucao y los datos de bloqueo (blockStatus, blockAmount). Si el MED no pertenece a su cuenta, la API responde 404.

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

3. Tratar los webhooks de MED

Ejemplo de handler (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':
      // Nuevo MED recibido — notificar al equipo y/o bloquear operaciones del beneficiario
      await notifyTeam({
        message: `MED #${medId} recibido — causa: ${cause}`,
        amount: originalTransaction?.amount,
        endToEndId: originalTransaction?.endToEndId,
      });
      break;

    case 'MedAccepted':
      // Devolución aprobada — el valor será devuelto al pagador
      await updateTransaction({
        medId,
        status: 'DEVOLVIDO',
        note: 'MED aprobado — valor devuelto al pagador original',
      });
      break;

    case 'MedRejected':
      // Devolución rechazada — el saldo permanece con el beneficiario
      await updateTransaction({
        medId,
        status: 'MANTIDO',
        note: 'MED rechazado — saldo desbloqueado',
      });
      break;
  }

  // Devuelva siempre 200 para confirmar la recepción
  res.status(200).json({ received: true });
});

Ejemplo de handler (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} (causa: {cause})")

    if event == 'MedCreated':
        # Nuevo MED — alertar al equipo
        notify_team(med_id, cause, data.get('originalTransaction'))

    elif event == 'MedAccepted':
        # Devolución aprobada
        update_transaction(med_id, 'DEVOLVIDO')

    elif event == 'MedRejected':
        # Devolución rechazada
        update_transaction(med_id, 'MANTIDO')

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

4. Flujo recomendado

┌─────────────────────────────────────────────────────────────┐
│                   SU APLICACIÓN                              │
│                                                              │
│  Webhook MedCreated ──────▶ Alertar al equipo de riesgo     │
│       │                     Marcar transacción "en MED"     │
│       │                     (Opcional) Bloquear beneficiario │
│       │                                                      │
│       ▼                                                      │
│  Consultar GET /api/med ──▶ Verificar detalles y causa      │
│       │                     Seguir el estado                 │
│       │                                                      │
│       ▼                                                      │
│  Webhook MedAccepted ─────▶ Registrar devolución            │
│       O                     Actualizar saldo del cliente     │
│  Webhook MedRejected ─────▶ Desbloquear beneficiario        │
│                              Mantener saldo                  │
└─────────────────────────────────────────────────────────────┘

Mejores Prácticas

Configure los 3 webhooks

Configure siempre med_created, med_accepted y med_rejected para tener visibilidad completa del ciclo de vida.

Devuelva 200 rápidamente

Procese el webhook de forma asíncrona. La entrega tiene un timeout de 10 segundos y solo las respuestas 2xx cuentan como éxito; de lo contrario, el sistema intenta reenviarlo.

Use idempotencia

Use la combinación medId + event como clave de idempotencia (el mismo medId aparece en MedCreated y luego en MedAccepted o MedRejected). El mismo webhook puede reenviarse en caso de falla de entrega.

Monitoree MEDs abiertos

Consulte periódicamente GET /api/med?status=RECEIVED para garantizar que ningún MED quedó sin tratar.