Colectiva (Payments)
Payments, wallets, subscriptions, and escrow for the RBS ecosystem. Accept MXN via CoDi or card, pay out to bank accounts, and consume typed payment events on your side.
URL: colectiva.redbroomsoftware.comStatus: LIVE Tier: T1 SDK: @r-bsoftware/ecosystem-sdk — createWebhookHandler, createWebhookSender, signPayload, verifySignature, createEcosystemAuth
What you can integrate
- Accept MXN payments via MercadoPago (cards) or Banxico CoDi (QR, bank transfer)
- Subscribe tenants to recurring plans with retry + dunning handled server-side
- Trigger escrow holds and release funds when a deal milestone closes
- Pay out to Red Wallet balances and settle to bank accounts (SPEI)
- Consume payment events — get notified when money moves, fails, refunds, or is disputed
Authentication
Partner apps authenticate with an ecosystem API key per source app:
X-API-Key: col_<app_slug>_<32_hex>Keys are hashed at rest in the ecosystem_api_keys collection. User-facing flows use Camino SSO — see Auth.
Inbound webhooks to /api/ecosystem/webhooks require HMAC-SHA256 signatures — see Webhooks.
Endpoints
| Method | Path |
|---|---|
| POST | /api/acorde/split-sheet |
| GET, PATCH | /api/acorde/split-sheet/:id |
| GET | /api/acorde/split-sheet/:id/paquete |
| POST | /api/acorde/split-sheet/:id/seal |
| POST | /api/acorde/split-sheet/:id/sign |
| GET, POST | /api/acuerdos |
| GET, PATCH, DELETE | /api/acuerdos/:id |
| GET, POST, PUT | /api/acuerdos/:id/distributions |
| GET | /api/ai/billing |
| GET, POST | /api/ai/chat |
219 total — 34 admin/cron/internal (hidden) — +175 more primary endpoints not shown. Source: src/routes/api/**/+server.{ts,js} in the colectiva-RBS/colectiva repo.
Events emitted
| Event | Receivers | Description |
|---|---|---|
ai_cost.recorded | constanza | Monthly AI cost aggregate recorded by Colectiva for an org — carries provider, token totals, and MXN spend for the period. Sent to Constanza for bookkeeping. |
brain.signal | camino, colectiva | Cross-brain intelligence signal. Emitted by Camino (marketing/fiscal intelligence) and Colectiva (operational/financial intelligence) to share insights bidirectionally. Carries a typed signal with severity, priority, and actionable context. |
cpi.investor_update_posted | camino | A CPI investor update was posted on a Colectiva offering — Camino sends email to each investor who purchased this offering. |
cpi.purchased | camino, constanza | A CPI (Colectiva Participation Instrument) was purchased — Camino creates/updates contact with cpi_holder tag + logs purchase timeline; Constanza records sale for accounting. |
cpi.transfer_completed | camino | A CPI secondary market transfer completed — Camino sends buyer receipt + seller sale confirmation emails. |
deal.billed | constanza | [auto-derived] deal.billed event |
distribution.completed | camino | A participation distribution completed in Colectiva — Camino logs investor activity + sends confirmation email. |
employee.created | hoja | [auto-derived] employee.created event |
employee.terminated | hoja | [auto-derived] employee.terminated event |
employee.updated | hoja | [auto-derived] employee.updated event |
escrow.released | constanza | An escrow hold was released in Colectiva — Constanza books the escrow release as a poliza entry for fiscal reconciliation. |
investor.nda_signed | camino | An investor signed an NDA for a CPI offering in Colectiva — Camino creates/updates contact with investor tags + logs timeline event. |
invoice.paid | agora, camino | An invoice was paid — Camino marks the cobranza receivable as paid and logs the payment event on the CRM contact timeline. |
labor_costs.monthly_report | hoja | [auto-derived] labor_costs.monthly_report event |
labor_costs.updated | camino, hoja | [auto-derived] labor_costs.updated event |
payment.chargeback_resolved | constanza, agora, mancha, servilleta, cosmos-pet, caracol | A MercadoPago chargeback reached a terminal state. Colectiva emits this when verdict.terminal && outcome ∈ {lost, won, coverage}. Constanza uses it to post a counter-póliza and (on lost + originalCfdiUuid present) cancel the original CFDI. Canonical contract is whatever colectiva/src/lib/services/ecosystem-webhook.service.js notifyPaymentChargebackResolved emits. |
payment.completed | baul, constanza, cosmos-pet, mancha | A payment transaction was fully completed in Colectiva — source apps confirm the payment for delivery orders, subscriptions, or escrow. Used by baul to confirm delivery payment, mancha for reservation payment, constanza for accounting, and cosmos-pet for vet clinic subscription payments. |
payment.expired | cosmos-pet, mancha | A pending payment expired without being completed — Colectiva notifies the originating app to cancel the pending reservation or order. cosmos-pet uses it to mark vet-clinic subscription payments as expired. |
payment.failed | baul, mancha | A payment attempt failed in Colectiva — notifies source apps (baul, mancha) to surface the failure to the user and offer retry. |
payment.received | agente, continua, cosmos-pet, garita, goodbay, hoja, madriguera, patadas | A payment has been processed via Colectiva |
payment.refunded | baul, mancha, servilleta, agora, constanza, cosmos-pet, caracol | 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. |
payment.released | servilleta | An escrow payment was released from hold by Colectiva — Servilleta marks the task payment as released and triggers tasker payout. |
payment.status_changed | colectiva, mancha, plenura, servilleta | [auto-derived] payment.status_changed event |
payroll.calculated | constanza, hoja | [auto-derived] payroll.calculated event |
payroll.disbursed | colectiva | [auto-derived] payroll.disbursed event |
payroll.processed | constanza | [auto-derived] payroll.processed event |
subscription.activated | agente, agora, camino, caracol, colectiva, comal, constanza, continua, cosmos-pet, garita, hoja, madriguera, mancha, patadas, plenura, rito, servilleta | A subscription plan has been activated for a tenant — all apps that gate features behind the subscription tier update their local tier state. |
subscription.cancelled | agente, agora, camino, caracol, colectiva, comal, constanza, continua, cosmos-pet, garita, hoja, madriguera, mancha, patadas, plenura, rito, servilleta | A subscription has been cancelled — all apps that gate features behind the subscription tier update their local tier state to free/cancelled. |
subscription.created | baul | A new subscription record was created in Colectiva — baul receives this to link delivery service with the tenant's subscription. Distinct from subscription.activated (which fires after first payment succeeds). |
subscription.payment_failed | agora, baul, camino, plenura, servilleta | A subscription payment attempt failed — receiver apps surface a payment-failed banner to the tenant operator and may restrict feature access. |
subscription.renewed | camino, constanza, mancha, plenura, servilleta | A subscription was successfully renewed for a new billing period — receiver apps update the subscription period end date and resume any paused features. |
tips.processed | caracol | Tips collected via Colectiva have been processed and distributed to staff — Caracol POS records the tip distribution for shift reports and labor analytics. |
wallet.deposit_completed | camino | A CPI wallet deposit completed in Colectiva — Camino logs activity and sends deposit receipt email to the user. |
wallet.deposited | colectiva | [auto-derived] wallet.deposited event |
wallet.payout_completed | comal | [auto-derived] wallet.payout_completed event |
wallet.spent | colectiva | [auto-derived] wallet.spent event |
wallet.withdrawal_completed | camino | A CPI wallet SPEI withdrawal completed in Colectiva — Camino logs activity and sends withdrawal receipt email to the user. |
wallet.withdrawn | colectiva | [auto-derived] wallet.withdrawn event |
workflow.action | constanza, hoja, camino | Colectiva dispatches a workflow action to a target app — instructs the receiver to perform a specific operation (create employee, generate poliza, update record). Payload includes the action type and data needed by the receiver. |
Events consumed
| Event | Senders | Description |
|---|---|---|
account.deletion_requested | camino | A user has submitted an account deletion request (soft-delete). Subscribers mark local user records with deletion_requested_at and notify their local operators — they do NOT auto-delete data. Actual anonymization is gated behind a separate 'account.deletion_approved' event (Phase 4). |
ai.usage | caracol, mancha, plenura, rito | AI token usage report for metering |
appointment.completed | cosmos-pet, plenura | A therapy or veterinary appointment has been completed and paid |
booking.cancelled | plenura, goodbay | A booking has been cancelled. PD-115 (S178-inverse fingerprint): goodbay added as sender — Colectiva's handleBookingCancelled handler at /api/ecosystem/webhooks/+server.js:960 was wired end-to-end but no goodbay producer fired the event, surfacing as a dormant emitter in the S327 audit. Goodbay emits from /api/bookings/[id]/+server.ts after the cancel batch commits. |
booking.created | goodbay, plenura | A new booking was created in a hospitality or pet-care app — Colectiva records it for revenue tracking and occupancy analytics. |
booking.reserved | goodbay | A booking has been reserved/created (coins/funds deducted, status='pending'). PD-073 Slice 1 (S317) — semantic-corrected rename of the previous goodbay booking.completed-at-creation emit. Settlement signal moves to the new booking.completed once Slice 2 lands. Colectiva wired as receiver in Slice 3. |
brain.signal | camino, colectiva | Cross-brain intelligence signal. Emitted by Camino (marketing/fiscal intelligence) and Colectiva (operational/financial intelligence) to share insights bidirectionally. Carries a typed signal with severity, priority, and actionable context. |
capital_call.created | rito | [auto-derived] capital_call.created event |
capital_call.payment_requested | rito | Rito requested Colectiva to process a capital call payment from an LP — triggers the payment flow for the specified capital event. |
constanza.partner_billing_period | constanza | [auto-derived] constanza.partner_billing_period event |
customer.updated | camino, constanza, caracol | A customer/contact record was updated in Camino — receiver apps sync the changed fields to their local customer records for display and invoicing accuracy. |
deal.commission_ready | camino | Camino has processed a deal billing record and calculated commission splits. Colectiva uses this to route payouts to developer/provider wallets. S125 Gap #18. |
deal.stage_changed | rito | A real estate deal has advanced to a new pipeline stage |
deposit.completed | baul | Cash deposit completed at bank with proof (photo of slip, GPS). Baul physical layer event. Triggers expense creation in Constanza and agreement reconciliation in Colectiva. |
distribution.created | rito | A distribution record was created in Rito — sent to Colectiva to initiate the payment to the LP wallet. The type field distinguishes capital_call vs distribution. |
distribution.payment_requested | rito | Rito requested Colectiva to process a distribution payment to an LP — triggers the payout flow. |
donation.completed | continua | A blood donation has been completed and the donor rewarded with MXC coins |
employee.missing_data | constanza | Constanza detected an employee with missing fiscal data (RFC/CURP/etc.) — routed back to the source app that created the employee so the missing fields can be completed. |
fiscal.anomaly_detected | constanza | Constanza AI detected an unusual pattern in an organization's financial data (z-score outlier, Benford violation, duplicate transaction, timing anomaly, etc.). Routed to Camino for CRM health alerts and to Colectiva so the Brain can factor fiscal anomalies into business intelligence. |
fiscal.deadline_reminder | constanza | Constanza detected an upcoming tax deadline (3/7/30 days out) — notifies Colectiva so the Brain can surface the deadline as a priority. |
fiscal.health_score_updated | constanza | [auto-derived] fiscal.health_score_updated event |
fiscal.resico_warning | constanza | Constanza detected an organization whose RESICO income utilization crossed the warning threshold (>=90%). Routed to accounting-sensitive apps so they can surface limit warnings in POS/invoice flows. |
garita.access.denied | garita | A person was denied access to a property |
garita.access.granted | garita | A person was granted access to a property (check-in) |
garita.reservation.cancelled | garita | A reservation was cancelled |
garita.reservation.completed | garita | A reservation was completed (amenity used) |
garita.reservation.created | garita | A reservation for an amenity was created |
garita.reservation.no_show | garita | A resident did not show up for their reservation |
garita.resident.onboarded | garita | A new resident or member was registered in a property |
garita.visitor.checked_in | garita | A visitor checked into a property |
handoff.completed | baul | Generic physical handoff completed with proof. Covers document delivery, product returns, sample collection, key handoff, equipment transfer. Baul physical layer event. |
inventory.low | caracol, comal, hoja | A product inventory fell below the low-stock threshold — Colectiva records the alert for analytics; Camino logs it as a TenantIntelligence signal in organization_activity_log. |
invoice.issued | constanza | Constanza issued and stamped an invoice — Colectiva syncs the CFDI to the workspace invoices collection for the business owner's records. |
invoice.queued | constanza | Constanza accepted a deal-billing póliza and queued the invoice for CFDI stamping — notifies Colectiva so the deal-billing pipeline can track the pending invoice. |
order.completed | comal, mancha | An e-commerce order has been completed (paid + fulfilled) |
order.refunded | comal | An e-commerce order has been refunded |
owner.registered | madriguera | A property or pet owner was registered in Madriguera — Camino creates a CRM contact, Colectiva records the new account for revenue tracking. |
payment.status_changed | colectiva | [auto-derived] payment.status_changed event |
payroll.disbursed | colectiva | [auto-derived] payroll.disbursed event |
pet.registered | madriguera | [auto-derived] pet.registered event |
project.completed | patadas | A Patadas marketplace project has been completed and accepted — triggers final escrow release, platform fee deduction, and invoice generation |
report_card.generated | madriguera | [auto-derived] report_card.generated event |
reservation.checked_out | madriguera | [auto-derived] reservation.checked_out event |
reservation.completed | mancha | A restaurant reservation was completed (the party finished dining) — Colectiva records for revenue analytics, Caracol POS releases the table, La Hoja POS mirrors the timeline. |
reservation.created | madriguera, mancha | A restaurant reservation has been created |
sale.completed | caracol, hoja, cosmos-pet | A POS sale has been completed |
shipment.closed | agente | [auto-derived] shipment.closed event |
shipment.created | agente | [auto-derived] shipment.created event |
subscription.activated | camino, colectiva | A subscription plan has been activated for a tenant — all apps that gate features behind the subscription tier update their local tier state. |
subscription.cancelled | camino, colectiva | A subscription has been cancelled — all apps that gate features behind the subscription tier update their local tier state to free/cancelled. |
subscription.trial_expiring | camino | A trial subscription is expiring soon — receiver apps surface an upgrade prompt to the tenant operator. |
subscription.trial_started | camino | A trial subscription was started — receiver apps activate trial-tier features for the new tenant. |
task.completed | servilleta | A gig task has been completed and accepted by the client on Servilleta — triggers payment release from escrow to tasker wallet |
timesheet.approved | patadas | A developer's timesheet has been approved by the client on Patadas — triggers escrow payment release to developer wallet |
walk.completed | madriguera | [auto-derived] walk.completed event |
wallet.deposited | colectiva | [auto-derived] wallet.deposited event |
wallet.spent | colectiva | [auto-derived] wallet.spent event |
wallet.withdrawn | colectiva | [auto-derived] wallet.withdrawn event |
Sandbox vs production
| Env | MercadoPago token prefix | CoDi endpoint |
|---|---|---|
| Sandbox | TEST-<chars> | Banxico CoDi Beta |
| Production | APP_USR-<chars> | Banxico CoDi Prod |
Swap by environment variable — the code path is identical. Always test against sandbox first; provider state transitions differ in edge cases (e.g., CoDi timeouts).
Webhook signature
Ecosystem HMAC-SHA256 over raw body, 5-minute timestamp window, replay protection via X-Webhook-Id. Failed deliveries are retried with exponential backoff and moved to a dead-letter queue after N attempts. See Webhooks.
Gotchas
- All amounts are integer cents (e.g.,
12345= 123.45 MXN). Never pass floats — financial math in this system is cents-based everywhere. - Idempotency is enforced via
X-Idempotency-Keyon POST/api/payments. Replaying the same key returns the original payment, not a duplicate. - Webhook receivers must return
2xxwithin 10 seconds. Anything slower triggers a retry — make your handler idempotent. payment.receivedfires on authorization,payment.completedfires on settlement. For high-risk integrations, wait for.completed.