Get Started With Cosmo
Integrate Cosmo's loyalty infrastructure to enable seamless point issuance, cross-brand exchanges, and secure authentication. Our APIs and widgets provide the backbone for enterprise-grade partner programs.
Account Setup
Choose the onboarding model that fits your business requirements.
Managed Setup
Enterprise-grade onboarding. Our team handles your configuration, partnership whitelisting, and custom rate limits.
Contact Sales →Self-Service Setup
Instant access via the developer portal. Create your own application, generate keys, and start building in minutes.
Open Portal →Sign Up Flow
- 1
Create Account
Register with your work email at console.cosmo.io.
- 2
Verify Domain
Complete the DKIM/SPF verification to enable automated user notifications.
- 3
Generate API Keys
Navigate to Settings > API Keys to retrieve your Sandbox Client ID and Secret.
Sandbox Integration
Sandbox Authentication
Use your sandbox credentials against the testing environment. Tokens generated here are not valid for production.
--header 'Content-Type: application/json' \
--data-raw { "client_id": "sb_client_123", "client_secret": "sb_secret_xyz", "grant_type": "client_credentials" }
Environment Behavior
- check_circleSimulated Transactions: All point issuances are mocked and do not affect real balances.
- check_circleError Triggers: Pass specific headers (e.g.,
x-mock-error: 402) to test failure states.
User Flow Guide
Authenticate
Initialize your session with the Client Credentials flow to receive an access_token.
Authorization: Bearer {access_token}
Retrieve Partnerships
Fetch the loyalty programs available to your client and the current exchange rates.
{ "data": [ { "id": "prog_789", "name": "Global Miles", "rate": 0.01 } ] }
Issue Points
Process the transaction by sending a request to the points endpoint with the user's target wallet.
Key API Endpoints
Validate User
GETCheck if a user exists and is eligible for a specific loyalty program before starting a flow.
Issue Points Preview
POSTCalculate exact point conversion and fees without committing the transaction.
Issue Points (Fiat/Exact)
POSTIssue points based on a specific fiat amount or an exact point count.
Get Program Fields
GETRetrieve the required identification fields for a specific partner program.
Get Transaction
GETRetrieve the status and details of a specific transaction ID.
Production Integration
verified_userProduction Credentials
Once your sandbox tests pass, request Production Keys via the portal. These require a brief security review and updated REDIRECT_URIs.
- circle Update API Base URL to: api.cosmo.io
- circle Cycle your client secrets every 90 days.
Going Live
Final pre-launch checklist to ensure a smooth transition to production.
Error Handling
Ensure you handle 429 Rate Limit and 402 Insufficient Balance errors with graceful degradation.
Webhooks
Confirm your webhook listener is responding with 200 OK and implementing signature verification.
Monitoring
Set up alerts for transaction failure rates exceeding 5% in 5 minutes via the dashboard.
Point Exchange Widget
The Point Exchange Widget provides a seamless, drop-in UI for users to purchase or exchange loyalty points between participating brands. This embeddable component handles the complex math of point conversions and provider-specific validation steps automatically.
Authentication
To launch the widget, you must first generate a short-lived session token. These tokens are valid for 10 minutes and are specific to a single user session.
{ "user_id": "user_98765",
"program_id": "delta_skymiles",
"experience": "embedded"
} // Response Body
{ "token": "wgt_ex_live_7a21...",
"expires_at": "2023-11-24T15:45:00Z"
}
Launching
The widget can be hosted in any web or mobile application using an iFrame. Ensure you pass the generated token as a URL parameter.
src="https://widgets.cosmo.io/exchange?auth_token=wgt_ex_live_7a21..."
width="100%"
height="700px"
frameborder="0"
allow="payment"
></iframe>
Transaction Completion
Once a user completes a transaction, the widget will emit a browser event. However, for security, you must verify the transaction via our Webhooks. Implement post-completion logic (e.g., updating UI balances) only after receiving the transaction.succeeded event.
Multibrand Widget
The Multibrand Widget allows users to view and manage their loyalty reward preferences across all their connected accounts in one centralized interface. It's ideal for "My Account" or "Profile" sections of your application.
Authentication
Due to the sensitive nature of viewing multiple balances, Multibrand tokens have a strict 1-minute lifetime. This must be a backend-to-backend call triggered just as the user navigates to the rewards page.
{ "user_id": "user_98765",
"allowed_brands": ["*"],
"theme": "light"
} // Response Body
{ "token": "wgt_mb_live_1b88...",
"ttl": 60
}
Launching
Embed the widget using the following iFrame code. The Multibrand Widget automatically adapts its layout to fit the container width, supporting both grid and list views depending on the available space.
src="https://widgets.cosmo.io/multibrand?auth_token=wgt_mb_live_1b88..."
width="100%"
height="500px"
frameborder="0"
></iframe>
Note: The widget supports native-like capabilities including balance refreshing, link/unlink account flows, and transaction history filtering.
Webhooks
Authentication Methods
We support three methods to secure your webhook endpoints:
Basic
Simple username/password headers sent in every request.
OAuth 2.0
Token-based authentication requiring a client secret.
Signature
HMAC verification (Highly Recommended) using a shared secret.
Transaction Webhook Payload
"type": "transaction.succeeded",
"data": { "transaction_id": "tx_5544...",
"user_id": "user_98765",
"amount": 500.00
} }
Verifying Webhook Signatures
Validate the payload using the X-Cosmo-Signature header to ensure the request originated from our servers.
function verifyWebhook(payload, signature, secret) { const hmac = crypto.createHmac('sha256', secret);
const digest = hmac.update(JSON.stringify(payload)).digest('hex');
return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}