Get Started With Cosmo

Account Setup

Managed Account

Cosmo can assign a dedicated account manager to help you get set up. If you opt in for a managed account setup, you will not need to go through step 2 below. Simply contact us and we'll guide you through.

Cosmo will issue your organization a unique Client ID and a Client Secret per environment. These credentials will allow you to make secure and authenticated API requests.

Self-Service

Cosmo offers a secure self-service portal to set up and manage your own account. We encourage this type of setup as it puts your organization in control.

Sign Up

Create an account using the client portal You will be prompted to verify your email address via OTP.

Enter Business Name

After verifying your email, you will be prompted to enter your business name. Please enter the legal entity name for your business.

Access the Portal

You can now log into the portal and start completing your company profile

Complete Company KYB

Profile Setup

Complete your company profile by filling in program name, company address, industry, and other required information.

Submit for KYB Verification

Submit your company profile for KYB verification. Once submitted, you may not change any information until acceptance or rejection of your business profile. After approval, you will be able to access all features in the portal. This process requires 1-3 business days.

Sandbox Environment

After KYB approval, you will be issued a unique Client ID and Secret to get you started in our Sandbox environment.Visit the API keys page to access your Client ID and environment secrets. For production access, you will need to manually request your keys in the portal (or contact us if you have a managed account). to access your Client ID and environment secrets.

Sandbox Integration

Your Client ID is the same across environments. However, secrets are unique to each environment. Your sandbox secret key is automatically generated for you and accessible in the portal. In sandbox, your base URL is always api.sandbox.cosmopoints.com when making API calls. This will allow you to test your integration in a non-production environment.

For detailed API specifications, endpoints, and request/response formats, please refer to our API Documentation

Production Environment

Ideally after testing your sandbox integration, you proceed to request a production API key in the portal. Our team will review the request and provide the production key if your system is ready to go live.

Now that your account is fully set up, you can test your integration in production. You can do so by using your production secret key and switching your base URL to api.cosmopoints.com. Follow our API documentation for a full list of API functions.

Classic Flow

Authenticate

Start by retrieving an access token used to authenticate you in subsequent API calls. You will need your Client ID and Secret to acquire an access token. Here's the endpoint documentation:

https://api.cosmopoints.com/docs#tag/Authentication

Make sure you prepend your token with Bearer when adding it to the Authorization header in later API calls.

Retrieve partners

Retrieve a list of your organization's active partners. Partnerships are established on demand by contacting the Cosmo team. Here's the endpoint documentation:

https://api.cosmopoints.com/docs#tag/Programs

Issue points

Issue your users points with any active partner. All transactions are stored on a centralized ledger and are included in the monthly settlement process between your organization and Cosmo. Here’s the endpoint documentation:

https://api.cosmopoints.com/docs#tag/
Transactions/paths /~1transactions/post

For a complete and detailed API specification, please refer to our API documentation.

Going Live

Once your integration is thoroughly tested in Sandbox, you are ready to go live and enable point conversions to any of the partners in your Cosmo catalog.

Purchase Widget Integration

The Purchase widget is built to make onboarding to Cosmo’s Simple Point Exchange easier. Choosing a widget-based integration will help you avoid dedicating resources to building your own custom frontend. You may customize your Purchase widget to extend the look and feel of your brand guidelines, and conveniently embed it in your platform (Web & Mobile) where appropriate.

Note: You must have signed up on the Cosmo portal to be able to integrate the widget. If you are using a managed account, simply contact us.

Authentication

Prior to launching the widget, you must establish a secure session by acquiring a secure access token. The obtained token is then passed as a parameter in the widget URL. Cosmo will detect the token and safeguard the session's security.

• Your frontend must request from your backend a secure access token in order to launch the widget.
• Your backend must request the access token from Cosmo, using the endpoint documented below:
  
  Method: POST
  URL: https://api.cosmopoints.com/auth/widget/multibrand
  
  
  Request BodyCopy

  1 
  
  

  
  
  Response BodyCopy

  1 
  
  

Launch Widget

Once your authentication flow is complete, you may now launch the widget with the obtained secure token. The widget is launched ideally within an iFrame as such:

1 

Transaction Webhook

By now, you should have configured your webhook listener in the portal. Upon a transaction completion, your configured webhook will receive a message for transaction confirmation. Your backend should listen for such messages and only then apply post-completion logic (for example: debiting a user's account balance).

1 

Verifying Webhook Signatures

Transaction confirmations are sent to the webhook with a secure signature for you to verify the message's authenticity.

1 

Multibrand Widget

The Multibrand Widget allows users to manage their rewards preferences enabling them to earn rewards with an editable and dynamic list of programs. Users can also earn rewards with multiple programs at once upon spending on a single Multibrand card.

Authentication

Similar to the Purchase widget, the Multibrand widget requires you to establish a secure session by acquiring a secure access token prior to launching the widget in your frontend. The obtained token is then passed as a parameter in the widget URL. Cosmo will detect the token and safeguard the session's security.

• Your frontend must request from your backend a secure access token in order to launch the widget.
• Your backend must request the access token from Cosmo, using the endpoint documented below:
  
  Method: POST
  URL: https://api.cosmopoints.com/auth/widget/point-exchange
  
  
  Request BodyCopy

  1 
  
  

  
  
  Response BodyCopy

  1 
  
  

Launch Widget

Once your authentication flow is complete, you may now launch the widget with the obtained secure token. The widget is launched ideally within an iFrame as such:

1 

Program Connections Webhook

By now, you should have configured your webhook listener in the portal. Upon adding, removing or editing reward preferences, your configured webhook will receive a message to reflect any changes made by the user. Your backend should listen for such messages for post-action logic.

1 

Verifying Webhook Signatures

Program connection confirmations are sent to the webhook with a secure signature for you to verify the message's authenticity.

1