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

Please use the production base url for the endpoints in this section.

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
clientId
required
string

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

clientSecret
required
string

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

Responses

Request samples

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

Response samples

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

Business Info

Please use the production base url for the endpoints in this section.

Get Profile

Retrieve information about your business profile with Cosmopoints.

Authorizations:
Bearer

Responses

Response samples

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

Programs

Please make sure to use the appropriate base url (sandbox or production)

Get Programs

Retrieve a list of all your enabled partner programs along with the price per point in USD and in the program currency.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Validate Member

Validate if a user is a valid member of a specific program.

Authorizations:
Bearer
Request Body schema: application/json
destinationUserId
string

This field may be optional or mandatory depending on the partner program. Please use the Get Program Fields endpoint to check if it is required

destinationUserEmail
string

This field may be optional or mandatory depending on the partner program. Please use the Get Program Fields endpoint to check if it is required

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "isValid": true
}

Currencies

Please make sure to use the appropriate base url (sandbox or production)

Get Currencies

Retrieve a list of the available currencies.

Authorizations:
Bearer

Responses

Response samples

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

Transactions

Please make sure to use the appropriate base url (sandbox or production)

Issue Points - Preview

Preview the points with a specific partner. This endpoint will compute the value of points to be created with this partner

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

The program id of the desired partner

value
required
integer

The value denominated in the configured fiat program for your organization

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "totalPoints": 0
}

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
programId
required
string

The program id of the desired partner

value
required
integer

The value denominated in the configured fiat program for your organization

required
object (DestinationAccount)

The destination user object. Mandatory and optional fields may vary per partner program. Please use the Get Program Fields endpoint to get the required fields for the desired partner program.

referenceNumber
required
string

The transaction reference number provided by the calling application

description
string

Short description to attach to the transaction

Responses

Request samples

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

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

page
number

The number of the page to retrieve

pageSize
number

The number of items per page (default 25, max 5000)

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "data": [
    ]
}

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",
  • "destinationUserId": "string",
  • "pointTransactions": [
    ],
  • "partnership": {
    }
}

Program Connections

Please make sure to use the appropriate base url (sandbox or production)

Get Program Fields

Retrieve the fields for a specific program.

Authorizations:
Bearer
path Parameters
programId
required
string

The program id of the desired partner.

Responses

Response samples

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

Get Program Connections

Retrieve program connections for a specific user id.

Authorizations:
Bearer
query Parameters
sourceUserId
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
[
  • {
    }
]

Create or Update Program Connection

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

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

The program id of the desired partner.

required
object (DestinationAccount)

The destination user object. Mandatory and optional fields may vary per partner program. Please use the Get Program Fields endpoint to get the required fields for the desired partner program.

sourceUserId
required
string

The user identifier with your organization.

sourceUserEmail
string

The user email with your organization.

Responses

Request samples

Content type
application/json
{
  • "programId": "string",
  • "destinationAccount": {
    },
  • "sourceUserId": "string",
  • "sourceUserEmail": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceUserId": "string",
  • "sourceUserEmail": "string",
  • "programId": "string",
  • "destinationUserId": "string",
  • "destinationUserEmail": "string",
  • "updatedAt": "string",
  • "createdAt": "string"
}

Get Program Connections History

Retrieve program connections history.

Authorizations:
Bearer
query Parameters
startDate
string

The starting date in epoch (seconds, 10 digits)

endDate
string

The end date in epoch (seconds, 10 digits)

page
number

The number of the page to retrieve

pageSize
number

The number of items per page (default 25, max 5000)

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "data": [
    ]
}

Delete Program Connection

Delete a program connection by id.

Authorizations:
Bearer
path Parameters
programConnectionId
required
string

The unique identifier of the program connection to be deleted.

Responses

Aggregator

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
programId
required
string

The program id of the desired partner

value
required
integer

The value denominated in the configured fiat program for your organization

required
object (DestinationAccount)

The destination user object. Mandatory and optional fields may vary per partner program. Please use the Get Program Fields endpoint to get the required fields for the desired partner program.

referenceNumber
required
string

The transaction reference number provided by the calling application

description
string

Short description to attach to the transaction

originalProgramId
required
string

The original program id

Responses

Request samples

Content type
application/json
{
  • "programId": "string",
  • "value": 0,
  • "destinationAccount": {
    },
  • "referenceNumber": "string",
  • "description": "string",
  • "originalProgramId": "string"
}

Response samples

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

Get Partner Codes

Retrieve a list of the available partner codes.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • "EXAMPLE_PARTNER"
]