Get Started With Cosmo
This guide will help you integrate your platform with Cosmo, allowing your users to access any partner in our catalogue of loyalty partners.
Please follow the steps below, and if you get stuck or need assistance during this process, please do not hesitate to contact us.
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.
Note: Cosmo will deliver your credentials using a secure mechanism. Please store your credentials in a secure environment and limit access to authorized personnel.
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.
Submit KYB
You can now log into the portal and start filling out your company's KYB submission (~2-3 min)
KYB Approval
Cosmopoints partners with companies that operate legally and adhere to our ethical guidelines.
Our team will review your KYB submission and provide approval within 1–3 business days.
Sandbox Integration
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 must request your keys in the portal (or contact us if you are on a managed account setup).
Sandbox Authentication
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 requests, with a single exception that is Authentication. Our authentication service is shared between both environments and is hosted at api.cosmopoints.com/idm/auth. See screenshot below:
After authenticating, you should switch your Base URL to api.sandbox.cosmopoints.com to make API requests to Sandbox.
This will allow you to authenticate and test your integration in a non-production environment. Check out the Issuing Points section below for a basic example on how to authenticate and start issuing points with Partners in the Cosmo catalogue.
For detailed API specifications, endpoints, and request/response structure, please refer to our complete API Documentation
Issuing Points
Below are three simple steps to issue points with a Partner program via the Cosmo platform. For a complete and detailed API specification, please refer to our API Documentation, and remember to use the correct Base URL
1. Authenticate
Start by retrieving an access token used to authenticate you. As mentioned, authentication is always done in Production. You will need your Client ID and Secret to acquire an access token valid for 10 min. If you provide the Sandbox secret, you will receive a token valid in Sandbox, and likewise for Production. See the full endpoint documentation here.
Make sure you prepend your token with Bearer when adding it to the Authorization header in later API requests.
1
2. Retrieve Partnerships
Retrieve a list of your organization's active partnerships. Partnerships are established on demand by contacting the Cosmo team. In future versions of the platform, Partners and Clients alike shall be able to initiate partnership requests from within the Portal. See the full endpoint documentation here.
1
3. 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. See the full endpoint documentation here.
1
Production Integration
Ideally after testing your Sandbox integration, you can proceed to request a Production Client Secret in the Portal. Our team will review the request and provide the production secret if your system is ready to go live and your organization meets legal requirements.
Now that your account is fully set up, you can test your integration in Production. You can do so by using your Production client secret and switching your Base URL to api.cosmopoints.com. Follow our API documentation for the full Cosmo API functionality.
Going Live
Once your integration is thoroughly tested in Sandbox, you are ready to go live and enable point conversions or transfers to any of the enabled 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 valid for 1 hour. 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-exchangeRequest BodyCopy1Response BodyCopy1
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 valid for 1 hour. 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/multibrandRequest BodyCopy1Response BodyCopy1
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