Get started with Cosmo

This guide walks you through integrating your application with the Cosmo API — how to authenticate, work with partner programs, and issue points using the core endpoints.

Cosmo follows a simple flow: sign up, authenticate, retrieve your partnerships, and start issuing points. Sandbox mode lets you build and test safely before you connect to real partner programs in production.

Account setup

There are two paths to getting set up with Cosmo, depending on your organization's needs.

Sign up

To begin using Cosmo, your team creates an organization and completes identity verification.

Sandbox integration

Sandbox mode lets you build and test without affecting live partner programs. All Sandbox transactions are isolated from production systems.

Sandbox matches production logic as closely as possible, so your integration behaves identically when you switch environments.

User flow

The complete flow your system follows to issue points through Cosmo. Each step maps to a specific API endpoint.

Key API endpoints

All paths below are relative to the base URL: https://api.cosmopoints.com for production, https://api.sandbox.cosmopoints.com for sandbox.

Error handling

Sandbox supports deterministic error simulation via predefined destinationUserId values — no dedicated endpoint, triggered through the normal issue-points flow. Use it to test backend error handling, frontend messaging, and retry / reconciliation flows.

All errors follow a structured response format for consistent handling.

Production integration

Once you've completed your sandbox testing, switching to production takes two changes: point your base URL from api.sandbox.cosmopoints.com to api.cosmopoints.com, and swap in your production client_secret (your client_id stays the same). No code changes — the API structure and endpoints are identical.

Production credentials are issued after your KYB is approved and at least one partner program is enabled. Store them securely; never expose them client-side.

Going live

Going live means issuing real points to real accounts. Final checks before launch:

After launch, monitor failed attempts, token-expiry errors, missing destination fields, traffic spikes, and reconciliation mismatches. All production transactions are permanent and billable — keep logs of validation, preview, and issue calls for downstream audits.

Point Exchange widget

A ready-made UX for point purchases and exchanges — embed it in your web or mobile app while your backend keeps all sensitive logic (auth, debits, reconciliation). Your backend obtains a short-lived access token (valid 10 minutes, server-side only — never expose clientId or clientSecret in the frontend):

{
  "clientId": "string",         // from the Cosmo Portal
  "clientSecret": "string",     // from the Cosmo Portal
  "userId": "string",           // any unique user identifier
  "amount": number,             // in your chosen currency
  "referenceNumber": "string",  // your internal reference
  "currency": "string",         // USD / SAR / AED
  "description": "string | null"
}
→ response: { "accessToken": "string" }

Then launch the widget with the token — in a web app (iFrame / WebView) or a mobile in-app browser:

<iframe
  src="https://purchase.cosmopoints.com?token=ACCESS_TOKEN"
  style="width: 100%; height: 600px; border: 0;"
></iframe>

The widget displays available options, collects required inputs, and sends the transaction to Cosmo. On completion, Cosmo sends a Transaction Webhook — verify it, confirm the transactionId, value, and destination, and only then apply post-completion logic like debiting the user's balance.

Multibrand widget

Lets users manage reward preferences for a Multibrand card — select and edit programs, decide how rewards are allocated, and update preferences over time. Same pattern as Point Exchange: your backend obtains a short-lived token (valid 1 minute) and your frontend launches the widget with it.

{
  "clientId": "string",
  "clientSecret": "string",
  "userId": "string"            // your unique user ID (can be opaque)
}
→ response: { "accessToken": "string" }

<iframe
  src="https://multibrand.cosmopoints.com/?token=ACCESS_TOKEN"
  style="width: 100%; height: 600px; border: 0;"
></iframe>

Webhooks

Cosmo notifies your backend of important events, like completed transactions. Configure endpoints in the Cosmo Portal → Developers → Webhooks. Three authentication modes are supported:

Transaction webhook

Sent when a transaction (API or widget) completes. Process the transaction only after receiving it — typical uses: debit the user's balance, update your ledger, display results, trigger notifications.

{
  "transactionId": "string",
  "sourceProgramId": "string",
  "destinationProgramId": "string",
  "value": number,
  "referenceNumber": "string",
  "destinationAccount": {
    "destinationUserEmail": "user@example.com",
    "destinationUserId": "123456"
  },
  "timestamp": number,
  "type": "string"
}

Program connection webhook

Sent when a user links, edits, or removes program connections — update your internal preference model accordingly. type is LINKED | DELINKED | UPDATED.

Verifying signatures

Read the headers, take the raw JSON body exactly as sent, build ${timestamp}:${rawBody}, compute HMAC-SHA-256 with your secret, and compare with the signature — only process on match.

// verify-signature.js
const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(`${timestamp}:${rawBody}`)
  .digest('hex');

const valid = crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(expected)
);