Get started with Cosmo

• ✓Set up your organization and get credentials
• ✓Authenticate and make authorized requests
• ✓Load the programs available to your business
• ✓Validate destination users
• ✓Issue point transactions and apply campaign bonuses
• ✓Retrieve transactions and handle errors correctly

• ✓Simulated transactions — no real balances are affected.
• ✓Error triggers — error responses can be triggered deterministically with specific destinationUserId values.
• ✓Mirrors production — program configurations match production structure.
• ✓No real points — no partner systems are contacted.

Every endpoint path in this guide is appended to the base URL of the environment you're targeting.

Your backend sends grant_type: client_credentials together with your client_id and client_secret; Cosmo returns a short-lived JWT. Include Authorization: Bearer <token> in all requests. If the token expires, re-authenticate and retry.

Always authenticate against production — api.cosmopoints.com — even when you are working in sandbox. There is no separate sandbox auth endpoint, and the client_id is the same in both environments. The client_secret you send is what decides which environment the token is valid for: send your sandbox secret and this same endpoint returns a token for api.sandbox.cosmopoints.com; send your production secret and it returns a production token.

Fetch the partner programs available to your organization — for populating your UI, obtaining the programId needed for issuing, and reading each program's required fields. Cache the list, refresh periodically.

1. Generate a referenceNumber, unique within your organization, and store it with the order before you call.
2. Call POST /transactions. Keep the call open — Cosmo answers within 30 seconds.
3. 201 — or 200 on a resend: the points were issued. Store the transaction id, totalPoints and referenceNumber for reconciliation. Done.
4. Any 4xx, or any 5xx other than 504: the transfer failed and no points were issued. Release the customer's debit. A failed transaction is not retried: to issue again, go back to step 1 with a new referenceNumber. The old one is consumed — resending it answers 409 with errorCode: TRANSACTION_FAILED.
5. 504, timeout, or no response: the outcome is unknown. Do not reverse anything. Wait briefly, then resend the exact same request — same referenceNumber, same details — and go back to step 3. A resend never issues points twice; repeat until you get a definitive answer.

If your issue call times out, the connection drops, or you receive a 504, the outcome is unknown: the points may already have been issued to the customer's partner account. Reversing the debit on your side at that moment could leave the customer with both.

1. Do not treat it as a failure and do not reverse anything. Keep the customer's debit on hold.
2. Once the original call has ended, resend the exact same request: the same referenceNumber and the same transfer details. A resend never issues points twice — if the original went through, you get it back with a 200.
3. If the resend times out again, the transaction is still unresolved. Wait a short while and resend again. Repeat until you receive a definitive answer.
4. Act on the definitive answer only: a 200 or 201 means the transfer succeeded and nothing should be reversed; a definitive error means no points were issued and the debit can be released.

• Expired or invalid token
• Missing required fields
• Missing reference number
• Reference number already used for a different transaction
• Exceeding allowed transaction value limit
• Exceeding allowed transaction points limit
• Invalid program ID
• No partnership with the specified program
• Destination user rejected by the partner program

When the partner itself refuses the credit — an unknown, blocked or closed membership, for example — POST /transactions answers 400 with errorCode: BAD_REQUEST. message is the reason as classified by Cosmo, and data.partnerError is the partner's own error text, verbatim. It is present only when the partner supplied one and is worded differently per program, so display or log it rather than matching on it. The transaction is recorded as failed and no points are issued. The reference number stays used: send the corrected request under a new reference number, and expect 409 with errorCode TRANSACTION_FAILED if the failed one is resent. Sandbox error simulation returns the same shape.

{
  "statusCode": 400,
  "errorCode": "BAD_REQUEST",
  "message": "Invalid destination user",
  "data": {
    "isValid": false,
    "error": "Invalid destination user",
    "partnerError": "Blocked User"
  }
}

• ✓Production authentication flow is functioning
• ✓At least one real user validated via Validate Member
• ✓A small live transaction issued for internal testing
• ✓Reference numbers generated uniquely and stored before each call, with retries reusing the same value
• ✓Transaction retrievable via GET /transactions/{transactionId}
• ✓All transaction details stored in your internal system

{
  "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>

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

// 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)
);

• ✓Always verify signatures before processing any event
• ✓Use timingSafeEqual to prevent timing attacks
• ✓Log invalid signatures for security monitoring
• ✓Store multiple secret versions if you rotate keys
• ✓Don't parse or trust the body until after validation
• ✓Keep your endpoint publicly reachable over HTTPS