Get Started With Cosmo

This guide walks you through how to integrate your application with the Cosmo API. It’s designed for developers who want a clear, straightforward understanding of how to authenticate, work with partner programs, and issue points using Cosmo’s 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.

By following the steps in this guide, you’ll learn how to:

• Set up your organization and obtain API credentials
• Authenticate and make authorized requests
• Load the programs available to your business
• Validate destination users
• Preview and issue point transactions
• Retrieve transactions and handle errors correctly

Account Setup

Cosmo supports two onboarding paths depending on your organization’s needs and operational workflow.

Managed Setup

For enterprises that require guided onboarding, Cosmo can manage the account creation and configuration process on your behalf. This includes:

• Provisioning your organization in Cosmo
• Assigning API credentials
• Enabling program partnerships
• Completing KYB and compliance checks

Self-Service Setup

If you prefer to set up your account directly, follow the onboarding flow in the Cosmo Portal. Steps:

• Sign up using your business email.
• Enter your organization’s legal name.
• Complete the automated KYB process.
• Once approved, your organization and API credentials are created automatically.

Sign Up

To begin using Cosmo, your team must create an organization and complete identity verification.

Sign Up Flow

• Provide your organization’s legal details
• Verify your email
• Log into the Cosmo Portal
• Submit your KYB information
• Await automated approval (typically minutes)

Your API credentials (client_id and client_secret) will be visible once your KYB has been approved.

Sandbox Integration

Sandbox mode allows you to build and test your integration without affecting live partner programs. All transactions created in Sandbox are isolated and do not interact with production systems.

User Flow

This section describes the complete flow your system will follow to issue points through Cosmo. Each step maps directly to a specific API endpoint, with links to the exact documentation for reference.

Endpoint:

GET /transactions/<transactionId>

See full documentation for this endpoint here:

When to use:

• To confirm the final status of a transaction (especially after asynchronous flows)
• To reconcile your internal ledger with Cosmo’s ledger
• To display transaction details in your dashboard or to the end-user
• For troubleshooting failed or partial transactions
• When handling webhook retries or verifying you haven’t double-processed a transaction

Request:

transactionId (path parameter)

Production Integration

Once your integration works as expected in Sandbox, you can move to Production. The production environment uses the same API structure and endpoints, so no code changes are required — only updated credentials and real program configurations.

Production Credentials

Your production client_id and client_secret will be issued after:

• Your KYB is approved
• At least one partner program is enabled for your organization

These credentials must be stored securely and should never be exposed in client-side code.

Environment Changes

Production differs from Sandbox in the following ways:

• Transactions interact with live partner systems
• User validation checks real member accounts
• All issued points are financially binding
• Error simulation is not available

Recommended Steps Before Going Live

• Confirm your organization has active partnerships
• Validate the required destination fields for each program
• Ensure all error cases are handled gracefully
• Verify your reconciliation logic
• Test your webhook handling (if used)

Once you replace your Sandbox token flow with Production credentials, your integration is considered live.

Going Live

Going Live means your system will start issuing real points to real user accounts. To ensure a smooth launch, your backend should follow a few final checks and operational best practices.

Final Pre-Launch Checks

• Confirm your Production authentication flow is functioning
• Validate at least one real user account using the Validate Member endpoint
• Issue a small live transaction for internal testing
• Confirm that you can retrieve the transaction via GET /transactions/<transactionId>
• Verify all transaction details are stored in your internal system

Monitoring

Operational Notes

• All Production transactions are permanent and billable
• You should alert your team on any error spikes or partner program failures
• Keep logs for validation, preview, and issue calls to support downstream audits

Once these items are confirmed, your integration is fully operational and ready to handle real users at scale.

Purchase Widget Integration

The Purchase widget lets you offer point purchases or exchanges without building your own frontend. You embed the widget in your web or mobile app; your backend handles authentication and post-transaction logic.

Use this if you:

• Want a ready-made UX for buying/exchanging points
• Prefer to keep all sensitive logic (auth, debits, reconciliation) on your backend

This token:

• Is valid for 10 minutes
• Is passed as a query parameter to the widget URL
• Must be obtained server-side only
• Must never expose clientId or clientSecret in the frontend

1 

1 

1 

Users can:

• Select and edit their preferred loyalty programs
• Decide how rewards are allocated across multiple programs
• Update preferences over time, with changes pushed back to your system via webhooks

Key points:

• Token lifetime: 10 minutes
• Obtained via backend-to-backend call
• Passed in the widget URL as a token query parameter
• Never expose clientId or clientSecret to the frontend

1 

1 

Your backend should associate the user and card metadata with this token so you can later reconcile changes coming from webhooks.

1 

Once launched, the widget:

• Displays the list of available programs for that card
• Allows users to add, remove, or edit reward preferences
• Sends any changes back to your backend via webhooks

Your backend should:

• Verify the webhook signature (see Section 10 – Webhooks)
• Update the user’s reward configuration in your system based on:
  • destinationProgramId
  • destinationAccount fields (e.g., destinationUserId, destinationUserEmail)
  • sourceUserId
  • type (e.g., "LINKED", "DELINKED")

For the exact payload and signature verification example, refer to the Program Connection Webhook description in Section 10.

Webhooks

Cosmo uses webhooks to notify your backend of important events, such as completed point transactions or updates to a user’s Multibrand program preferences.

All webhook deliveries support multiple authentication mechanisms and include a signed payload for verification.

You can configure your webhook endpoints in the Cosmo Portal → Developers → Webhooks.

1 

1 

1 

Best Practices

• Always verify webhook signatures before processing any event.
• Use timingSafeEqual to prevent timing attacks.
• Log invalid signatures for security monitoring.
• Store multiple versions of secrets if you rotate keys.
• Do not parse or trust the webhook body until after signature validation.
• Ensure your webhook endpoint is publicly reachable and uses HTTPS.