Colectiva Payment API

Colectiva is the central payment and billing hub for the RBS ecosystem.

Base URL: https://colectiva.redbroomsoftware.com

---

Overview

Colectiva provides:

• Payment Processing: Cards, OXXO, SPEI via MercadoPago
• Subscription Management: Recurring billing, trials, upgrades
• Wallet System: MXC credits for ecosystem services
• Trust Accounts: Segregated client funds (law firms)
• AI Billing: Usage-based AI service metering
• Ecosystem Registry: Organization and API key management

---

Authentication

Authorization: Bearer <api_key>
Content-Type: application/json

API Key Permissions

Permission	Access
payments:read	View payment status
payments:write	Create payments
subscriptions:*	Full subscription management
wallet:*	Wallet operations
trust:*	Trust account management
ecosystem:*	Organization management
developer_access	Generate support access tokens
*	Full access (admin)

---

Key Endpoints

Payments

Endpoint	Method	Description
/api/payments	POST	Create payment
/api/payments/:id	GET	Get payment status
/api/payments/:id/refund	POST	Refund payment

Subscriptions

Endpoint	Method	Description
/api/subscriptions	POST	Create subscription
/api/subscriptions/:id	GET	Get subscription
/api/subscriptions/:id	PUT	Update (upgrade/downgrade)
/api/subscriptions/:id/cancel	POST	Cancel subscription
/api/subscriptions/:id/pause	POST	Pause billing

Wallet

Endpoint	Method	Description
/api/wallet/balance	GET	Get current balance
/api/wallet/credit	POST	Add credits
/api/wallet/debit	POST	Deduct credits
/api/wallet/transactions	GET	Transaction history

Trust Accounts

Endpoint	Method	Description
/api/trust	GET	List trust accounts
/api/trust/:id	GET	Account details
/api/trust/:id/deposit	POST	Client deposit
/api/trust/:id/withdraw	POST	Authorized withdrawal
/api/trust/:id/statement	GET	Generate statement

Ecosystem

Endpoint	Method	Description
/api/ecosystem/orgs	GET	List organizations
/api/ecosystem/orgs/:id	GET	Organization details
/api/developer-access	POST	Generate dev access token

---

Code Examples

Create a Card Payment

const response = await fetch('https://colectiva.redbroomsoftware.com/api/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1500.00,
    currency: 'MXN',
    method: 'card',
    description: 'Monthly subscription - Pro Plan',
    customer: {
      email: 'cliente@example.com',
      name: 'María García'
    },
    metadata: {
      subscription_id: 'sub_123',
      plan: 'pro'
    },
    return_url: 'https://myapp.com/payment/complete',
    webhook_url: 'https://myapp.com/api/webhooks/colectiva'
  })
});

const { payment_id, status, checkout_url } = await response.json();

if (status === 'pending') {
  // Redirect customer to checkout
  window.location.href = checkout_url;
}

Create OXXO Payment

const response = await fetch('https://colectiva.redbroomsoftware.com/api/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 500.00,
    currency: 'MXN',
    method: 'oxxo',
    description: 'Order #12345',
    customer: {
      email: 'cliente@example.com',
      name: 'Juan Pérez'
    },
    expires_in_hours: 72  // OXXO voucher expiry
  })
});

const { payment_id, oxxo_reference, oxxo_barcode, expires_at } = await response.json();
// Display OXXO reference number to customer

Create Subscription

const response = await fetch('https://colectiva.redbroomsoftware.com/api/subscriptions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    plan_id: 'plan_pro_monthly',
    customer: {
      email: 'business@example.com',
      name: 'Empresa ABC',
      rfc: 'EAB123456789'
    },
    billing_cycle: 'monthly',
    trial_days: 14,
    payment_method_id: 'pm_card_xxx',  // From saved card
    metadata: {
      org_id: 'org_123',
      app: 'cosmos-pet'
    }
  })
});

const { subscription_id, status, trial_end, next_billing_date } = await response.json();

Wallet Operations

// Check balance
const balanceRes = await fetch('https://colectiva.redbroomsoftware.com/api/wallet/balance', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'X-Ecosystem-Org-ID': 'eco_123'
  }
});
const { balance, currency, pending } = await balanceRes.json();

// Add credits (after receiving payment)
const creditRes = await fetch('https://colectiva.redbroomsoftware.com/api/wallet/credit', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    org_id: 'eco_123',
    amount: 1000,  // MXC credits
    reference: 'payment_xyz',
    description: 'Credit top-up'
  })
});

// Debit for service usage
const debitRes = await fetch('https://colectiva.redbroomsoftware.com/api/wallet/debit', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    org_id: 'eco_123',
    amount: 50,
    service: 'ai_classification',
    reference: 'txn_abc123',
    description: 'AI expense classification (10 items)'
  })
});

AI Service Billing

// Record AI usage
const response = await fetch('https://colectiva.redbroomsoftware.com/api/ai/usage', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    org_id: 'eco_123',
    service: 'expense_classification',
    units: 25,  // Number of classifications
    model: 'gemini-1.5-flash',
    tokens_used: 15000,
    metadata: {
      batch_id: 'batch_xyz'
    }
  })
});

// Check quota
const quotaRes = await fetch('https://colectiva.redbroomsoftware.com/api/ai/quota?org_id=eco_123', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const { used, limit, remaining, resets_at } = await quotaRes.json();

---

Webhooks Sent

Colectiva sends webhooks for payment and subscription events:

Event	Trigger
payment.created	Payment initiated
payment.completed	Payment successful
payment.failed	Payment failed
payment.refunded	Refund processed
subscription.created	New subscription
subscription.activated	Trial ended, billing started
subscription.renewed	Successful renewal
subscription.payment_failed	Renewal payment failed
subscription.cancelled	Subscription cancelled
wallet.credited	Credits added
wallet.debited	Credits deducted
wallet.low_balance	Balance below threshold

Webhook Payload Example

{
  "event": "payment.completed",
  "timestamp": "2026-01-26T12:00:00Z",
  "data": {
    "payment_id": "pay_abc123",
    "amount": 1500.00,
    "currency": "MXN",
    "method": "card",
    "customer_email": "cliente@example.com",
    "metadata": {
      "subscription_id": "sub_123"
    }
  },
  "signature": "sha256=abc123..."
}

Verify Webhook Signature

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature.replace('sha256=', '')),
    Buffer.from(expected)
  );
}

---

Error Responses

{
  "error": "insufficient_funds",
  "message": "Wallet balance insufficient for this operation",
  "details": {
    "required": 500,
    "available": 350
  }
}

Error Code	HTTP Status	Description
invalid_request	400	Malformed request
authentication_failed	401	Invalid API key
permission_denied	403	Missing required permission
not_found	404	Resource doesn't exist
insufficient_funds	402	Wallet balance too low
payment_declined	402	Card/payment declined
rate_limited	429	Too many requests

---

Rate Limits

Endpoint Type	Limit
Payment creation	100/min
Read operations	300/min
Wallet operations	60/min

---

Related

• Full OpenAPI Spec
• Webhook Documentation
• Colectiva Project README