payment.refunded

A payment was refunded by Colectiva — voluntary refund initiated by a tenant app or by Colectiva ops, OR an involuntary MP-platform-side refund. Receivers branch on paymentReferenceType. For voluntary refunds with proration, isPartial=true and proration block carries period bounds. paymentLayer is the primary routing discriminator; receivers MUST check it before paymentReferenceType.

Senders

• colectiva
• comal

Receivers

• baul
• mancha
• servilleta
• agora
• constanza
• cosmos-pet
• caracol

Data schema

Each field maps to a type hint. | null indicates an optional field.

{
  "paymentId": "string (Firestore payments doc id, or empty string when refund is sub-only and no Colectiva payment exists)",
  "amount": "number (refunded amount, currency-native MP minor units / cents)",
  "currency": "string (ISO 4217)",
  "referenceId": "string | null (Colectiva-internal earnings reference)",
  "referenceType": "string | null (Colectiva-internal earnings type)",
  "refundedAt": "string (ISO datetime)",
  "reason": "string | null (free-form ops/merchant-supplied)",
  "refundId": "string (Colectiva refunds doc id; idempotency key for receivers)",
  "mpRefundId": "string | null (MercadoPago refund id when applicable)",
  "isPartial": "boolean (true when refund.amount < originalAmount)",
  "originalAmount": "number | null (original payment amount, currency-native cents)",
  "paymentMethod": "string | null (mercadopago | codi | ...)",
  "paymentReferenceId": "string | null (application-level reference set by source app, e.g. agora invoice id, caracol tenantId, servilleta task id)",
  "paymentReferenceType": "string | null (application-level reference type — same enum vocabulary as chargeback: 'subscription' | 'task_escrow' | 'legal_invoice' | 'reservation_deposit' | 'pos_transaction' | 'order' | 'trial_conversion' | 'implementation' | 'shipment' | ...)",
  "originalCfdiUuid": "string | null (best-effort lookup; same query path as chargeback)",
  "refundReason": "'voluntary_cancellation' | 'merchant_correction' | 'duplicate_charge' | 'goodwill' | 'mp_platform' | 'other'",
  "initiatedBy": "'merchant' | 'colectiva_ops' | 'mp_platform' | 'tenant_self_service'",
  "proration": "{ periodStart: string (ISO date), periodEnd: string (ISO date), cancellationDate: string (ISO date), unusedDays: number, totalDays: number, computedAt: 'colectiva' | 'app' } | null",
  "paymentLayer": "'L1_brillo_platform' | 'L2_tenant_saas' | 'L3_tenant_sale' | 'L4_tenant_subscription' (sender-asserted; receivers branch on this BEFORE paymentReferenceType)"
}

Example payload

The following is a synthetic payload that matches the schema. Production payloads are signed with HMAC-SHA256 and delivered to each receiver's registered webhook endpoint.

{
  "paymentId": "example-paymentId",
  "amount": 10000,
  "currency": "example-currency",
  "referenceId": "example-referenceId",
  "referenceType": "example-referenceType",
  "refundedAt": "2026-04-17T12:00:00.000Z",
  "reason": "example-reason",
  "refundId": "example-refundId",
  "mpRefundId": "example-mpRefundId",
  "isPartial": true,
  "originalAmount": 10000,
  "paymentMethod": "mercadopago",
  "paymentReferenceId": "example-paymentReferenceId",
  "paymentReferenceType": "application-level reference type — same enum vocabulary as chargeback: 'subscription'",
  "originalCfdiUuid": "example-originalCfdiUuid",
  "refundReason": "example-refundReason",
  "initiatedBy": "example-initiatedBy",
  "proration": "example-proration",
  "paymentLayer": "example-paymentLayer"
}

See also

• Events registry index
• Webhooks integration guide
• Errors & retries

---

Generated from ecosystem-sdk/packages/mcp-server/src/registry/events.json. Do not edit by hand.