Quickstart

Three copy-paste recipes that cover the most common integrations: accept a payment, sign in with RBS, and issue a CFDI. Each recipe is self-contained and links to the full API reference for the owning app.

Before you begin

• Obtain an ecosystem API key for the app(s) you integrate. Contact api-support@redbroomsoftware.com.
• Export it so the snippets below resolve: export API_KEY="col_<app_slug>_<32_hex>".
• All amounts are MXN. All timestamps are ISO-8601 UTC.
• Webhook signing (HMAC-SHA256) and the full auth flow are documented separately — see Integration → Auth and Integration → Webhooks.

---

Recipe 1 — Accept an MXN payment (Colectiva)

Create a payment. Colectiva auto-routes small amounts to the user's Red Wallet, and larger amounts to CoDi (Banxico QR) or MercadoPago (card, OXXO). You do not pick the rail — Colectiva does.

Prerequisites

• Ecosystem API key with payments:create permission.
• An internal reference_id you can correlate when the webhook fires.
• A public HTTPS endpoint to receive payment.completed — see Webhooks.

Create the payment

curl -s -X POST https://colectiva.redbroomsoftware.com/api/payments \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "firebase_uid_abc123",
    "amount": 1500,
    "currency": "MXN",
    "concept": "Professional services — April 2026",
    "reference_id": "order_0001",
    "reference_type": "order",
    "prefer_wallet": true,
    "customer_info": {
      "email": "cliente@example.com"
    }
  }'

Expected response (new CoDi payment)

{
  "success": true,
  "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
  "status": "pending",
  "payment_method": "codi",
  "gateway_provider": "codi_banxico",
  "amount": 1500,
  "expires_at": "2026-04-17T18:00:00.000Z",
  "qr_string": "0002010212...",
  "qr_image_url": "https://banxico.redbroomsoftware.com/qr/...",
  "folio_codi": "20260417ABC",
  "banxico_transaction_id": "txn_..."
}

If the user's wallet covers the amount and prefer_wallet is true, you will instead receive { "success": true, "status": "completed", "payment_method": "wallet", ... } synchronously.

Webhook receiver (on your side)

On payment.completed, Colectiva POSTs a signed ecosystem event to the URL you registered. Verify and fulfill:

# Your endpoint receives a POST with headers:
#   X-Webhook-Signature: sha256=<hex>
#   X-Webhook-Timestamp: <unix_seconds>
# Body: { "event": "payment.completed", "data": { "payment_id": "...", "amount": 1500, ... } }

Use the createWebhookHandler factory from @r-bsoftware/ecosystem-sdk — see Webhooks for the full verify recipe.

Full API reference: Apps → Colectiva.

---

Recipe 2 — Sign in with RBS (Camino OAuth2 + PKCE)

Camino is the ecosystem identity provider. Use the OAuth2 authorization-code flow with PKCE to authenticate end users into your app.

Prerequisites

• A registered OAuth client at Camino (client_id, one or more redirect_uris). Contact api-support@redbroomsoftware.com to register.
• Ability to store a PKCE code_verifier in the user's server-side session.

Step 1 — Redirect the user to Camino

Generate a PKCE verifier and challenge, then redirect the browser to /oauth/authorize.

# Pseudo-shell — run these in your app server, not at the CLI.
CODE_VERIFIER=$(openssl rand -base64 48 | tr -d '=+/' | cut -c1-43)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" \
  | openssl dgst -binary -sha256 \
  | openssl base64 \
  | tr '+/' '-_' | tr -d '=')

# Redirect the user-agent to:
echo "https://camino.redbroomsoftware.com/oauth/authorize\
?response_type=code\
&client_id=$CAMINO_CLIENT_ID\
&redirect_uri=https%3A%2F%2Fmyapp.com%2Fauth%2Fcallback\
&scope=openid%20profile%20email\
&state=$STATE\
&code_challenge=$CODE_CHALLENGE\
&code_challenge_method=S256"

After the user consents, Camino redirects back to redirect_uri with ?code=...&state=....

Step 2 — Exchange the code for tokens

curl -s -X POST https://camino.redbroomsoftware.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$CODE" \
  -d "redirect_uri=https://myapp.com/auth/callback" \
  -d "client_id=$CAMINO_CLIENT_ID" \
  -d "code_verifier=$CODE_VERIFIER"

Expected response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_...",
  "id_token": "eyJhbGciOi..."
}

The id_token is a JWT with the user's claims (sub, email, name). Call GET /oauth/userinfo with the access token if you need the canonical profile. Persist refresh_token — refresh tokens rotate on use.

Full API reference: Apps → Camino. Full flow (discovery, scopes, refresh, revoke): Integration → Auth.

---

Recipe 3 — Stamp a CFDI 4.0 (Constanza)

Constanza is the ecosystem CFDI issuer. Partner apps POST receptor + conceptos; Constanza handles the emisor CSD, PAC routing, and returns the stamped XML, PDF, and UUID.

Prerequisites

• A Constanza API key with cfdi:stamp permission, scoped to an organization that has an active invoicing profile (CSD uploaded, PAC configured).
• A valid SAT RFC, regimenFiscalReceptor, and domicilioFiscalReceptor (postal code) for the receiver. Send receiver fiscal data via /api/ecosystem/fiscal-data ahead of time if you do not already have it.

Request

curl -s -X POST https://constanza.redbroomsoftware.com/api/external/cfdi/stamp \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receptor": {
      "rfc": "XAXX010101000",
      "nombre": "PUBLICO EN GENERAL",
      "domicilioFiscalReceptor": "06600",
      "regimenFiscalReceptor": "616",
      "usoCFDI": "S01"
    },
    "conceptos": [{
      "claveProdServ": "80101500",
      "cantidad": 1,
      "claveUnidad": "E48",
      "descripcion": "Servicios de software",
      "valorUnitario": 1293.10,
      "importe": 1293.10
    }],
    "metodoPago": "PUE",
    "formaPago": "03",
    "moneda": "MXN",
    "referenceId": "order_0001",
    "referenceType": "order"
  }'

Expected response (HTTP 201)

{
  "success": true,
  "uuid": "A1B2C3D4-E5F6-7890-ABCD-EF0123456789",
  "xmlBase64": "PD94bWwgdmVyc2lvbj0iMS4wIi4uLg==",
  "pdfBase64": "JVBERi0xLjQKJeLjz9MK...",
  "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUg...",
  "fechaTimbrado": "2026-04-17T15:30:00"
}

On validation errors (invalid RFC, missing regime, unbalanced amounts) you receive HTTP 422 with { "success": false, "error": "...", "errorCode": "STAMP_FAILED" }. Constanza also emits a cfdi.stamped webhook to the originating app on success — consume it to update your local order or invoice record.

Full API reference: Apps → Constanza.

---

Next steps

Topic	Link
Full OAuth2 / PKCE reference	Integration → Auth
Webhook signing + replay protection	Integration → Webhooks
Typed event payloads	Reference → Events Registry
TypeScript SDK factories	Reference → SDK