API docs by Redocly

Cosmopoints (v1)

Download OpenAPI specification:Download

Welcome to the Cosmopoints API documentation. The service simplifies transactions with loyalty programs by aggregating different APIs into a single, consistent interface.

Authentication

Authenticate

Before starting to use the Cosmopoints APIs, you must authenticate yourself using the supplied Client ID and Client Secret.

  • This API uses Bearer token for authentication.
  • Every token is valid for 10 minutes.
  • That token must be provided in Authorization header. Please prepend your token with 'Bearer '.
Request Body schema: application/json
required
clientId
required
string

Unique ID for your app
You can find it in the keys section of the portal

clientSecret
required
string

Secret key for your app
You can find it in the keys section of the portal

Responses

Request samples

Content type
application/json
{
  • "clientId": "string",
  • "clientSecret": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string"
}

Business Info

Get Profile

Retrieve information about your business profile with Cosmopoints.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "programId": "string"
}

Programs

Get Programs

Retrieve a list of all your enabled partner programs.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Currencies

Get Currencies

Retrieve a list of the available currencies.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • "USD",
  • "AED",
  • "SAR"
]

Transactions

Issue Points

Issue points with a specific partner. This endpoint will create a new transaction record in the database.

Authorizations:
Bearer
Request Body schema: application/json
required
programId
required
string

The program id of the desired partner

value
required
integer

The value denominated in the configured fiat program for your organization

userId
required
string

The destination user id with the partner where points are created

referenceNumber
required
string

The transaction reference number provided by the calling application

description
string

Short description to attach to the transaction

bonus
boolean

Specifies whether the points were issued as bonus points for the user or not

Responses

Request samples

Content type
application/json
{
  • "programId": "string",
  • "value": 0,
  • "userId": "string",
  • "referenceNumber": "string",
  • "description": "string",
  • "bonus": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "totalPoints": 0,
  • "referenceNumber": "string",
  • "date": "string"
}

Get All Transactions

Retrieve all transactions in a specific interval.

Authorizations:
Bearer
query Parameters
startDate
required
string

The starting date in epoch (seconds, 10 digits)

endDate
required
string

The end date in epoch (seconds, 10 digits)

programId
string

The program id of the desired partner

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Transaction

Get a single transaction record by Transaction ID or Reference Number.

Authorizations:
Bearer
path Parameters
transactionId
required
string

Either the transaction identifier issued by Cosmopoints, or the transaction reference number provided by the calling application

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "referenceNumber": "string",
  • "sourceValue": 0,
  • "description": "string",
  • "createdAt": "string",
  • "userId": "string",
  • "pointTransactions": [
    ],
  • "partnership": {
    }
}

Program Connections

Create or Update Program Connection

Create or update a program connection for a specific user id.

Authorizations:
Bearer
Request Body schema: application/json
required
programId
required
string

The program id of the desired partner

endUserId
required
string

The user identifier with your organization - Identifier might be opaque

destinationUserId
required
string

The destination user id with the partner where points are created

Responses

Request samples

Content type
application/json
{
  • "programId": "string",
  • "endUserId": "string",
  • "destinationUserId": "string"
}

Response samples

Content type
application/json
{
  • "endUserId": "string",
  • "programId": "string",
  • "destinationUserId": "string",
  • "createdAt": "string"
}

Get Program Connections

Retrieve program connections for a specific user id.

Authorizations:
Bearer
query Parameters
endUserId
required
string

The user identifier with your organization - Identifier might be opaque

programId
string

The program id of the desired partner

Responses

Response samples

Content type
application/json
[
  • {
    }
]