Integration API Reference

Cloudike PAYG integration documentation provides a comprehensive guide for customers to connect their systems with Cloudike's platform, enabling seamless authentication, subscription management, and SMS notifications.

Definitions

The main subjects involved in the cross-integrations are described below:

Term	Description
Cloudike PAYG (or Cloudike)	Cloudike PAYG (Pay-As-You-Go) is a universal software platform owned by Cloudike Inc. and hosted on its Amazon AWS account. The platform is designed to launch various projects for different Customers, enabling them to provide cloud services to their end users.
Customer	A company that has contracted with Cloudike Inc. and uses Cloudike PAYG resources to provision its users.
Customer Core System	The Customer Core System (hereafter referred to as Customer's System) is an infrastructure of the specific Customer that is located on the Customer's hardware resources (i.e., outside of Cloudike PAYG). It can be integrated with Cloudike PAYG's infrastructure via the Internet.
User	An end user of Cloudike PAYG who belongs to a specific Customer (and hence to a specific Tenant).
Tenant	A tenant is an isolated entity in the Cloudike PAYG platform created for a specific Customer. The concept of a tenant includes: - Private tenant settings (e.g., name, description, logo, project domain, various Customer's System endpoints, etc.) - Customer's Users - A set of Packages
Package	A product that includes Cloudike's cloud disk quota and can be purchased by Users.
Subscription	A Package that has been activated for a specific User.

User Authentication Procedure

All Cloudike PAYG apps (web, Android and iOS) and all tenants use the same authentication method.

The first API method is used by clients when the user first launches the client. This API method provides a list of all tenants available to end users on the Platform.

During the first launch, the user must select a Tenant (i.e., project) they wish to register or log into.

The API method accepts the user's phone number (optional parameter) as input.
As output, the server returns a list of tenants recommended for this phone number.
Recommendation logic can be implemented by analyzing:
- The phone number's country prefix
- The source IP address of the requesting client
- The domain entered by the user in the browser (for web clients)

If no phone number is provided, the method will return an array with all tenants available on the Platform.

The second API method is used to retrieve the public Privacy Policy content of the selected Tenant. The third API method signs the user up or in.

Get list of "recommended" Tenants by phone number

GET https://payg.cloudike.com/api/3/tenants/

Request Parameters

Parameter	Type	Required	Description
`phone`	`string`	Optional	If provided, the system will return a sublist of a few recommended tenants.

Output

Returns an array of tenants with the following fields:

Field	Type	Description
`tenant_name`	`string`	The name of the tenant (i.e., internal ID).
`frontend_url`	`string`	A web link to the public frontend.
`title`	`string`	A human-readable name of the tenant.
`description`	`string`	A brief summary of the project.
`logo_url`	`string`	A URL to the tenant's logo.
`available_langs`	`string`	A list of languages available for the tenant.

Response Codes

Code	Description
200 OK	The request was successful.

Example Response (JSON)

{
  "_embedded": {
    "tenants": [
      {
        "tenant_name": "star",
        "title": "StarCloud",
        "frontend_url": "https://starcloud.example.com/",
        "description": "The solution for backing up your best moments",
        "logo_url": "https://starcloud.example.com/assets/logo.svg",
        "available_langs": "en, kk",
        "_links": {
          "self": {
            "href": "https://payg.cloudike.com/api/3/tenants/101/"
          }
        }
      },
      {
        "tenant_name": "ice",
        "title": "IceCloud",
        "frontend_url": "https://icecloud.example.com/",
        "description": "Secure storage for your files and documents",
        "logo_url": "https://domain.ice/ice-logo.svg",
        "available_langs": "en, id",
        "_links": {
          "self": {
            "href": "https://payg.cloudike.com/api/3/tenants/167/"
          }
        }
      }
    ]
  }
}

Get the "Privacy Policy" Document of the Tenant

GET https://payg.cloudike.com/api/3/offers/

Request Parameters

Parameter	Type	Required	Description
`offset`	`number`	No	The starting position of the returned list.
`limit`	`number`	No	The number of results to return.
`tenant_name`	`string`	Yes	The Tenant's name.
`type`	`string`	Yes	The required offer's code. Use `"privacy_policy"`.
`lang`	`string`	Yes	The language code of the offer (e.g., `"en"`).

API documentation of the method: https://be-saas.cloudike.com/backend_docs/rest/api/3/core_pkg/offers_app/Offers/index.html

Example Request

GET https://payg.cloudike.com/api/3/offers/?offset=0&limit=2&tenant_name=star_cloud&type=privacy_policy&lang=en

Response Codes

Code	Description
200 OK	The request was successful.

Example Response (JSON)

{
  "_links": {
    "self": {
      "href": "https://payg.cloudike.com/api/3/offers/"
    },
    "next": {
      "href": "https://payg.cloudike.com/api/3/offers/?limit=2&offset=2"
    }
  },
  "_embedded": {
    "offers": [
      {
        "created": "2025-02-14T13:01:57.117000+00:00",
        "updated": "2025-02-14T13:01:57.117000+00:00",
        "id": "67af3ec589695ea21a9ef830",
        "tenant_name": "star_cloud",
        "type": "privacy_policy",
        "lang": "en",
        "url": "",
        "_links": {
          "self": {
            "href": "https://payg.cloudike.com/api/3/offers/67af3ec589695ea21a9ef830/"
          },
          "content": {
            "href": "https://payg.cloudike.com/api/3/offers/67af3ec589695ea21a9ef830/content/"
          },
          "offer_view": {
            "href": "https://payg.cloudike.com/offers/67af3ec589695ea21a9ef830"
          }
        }
      }
    ]
  }
}

Notes

The _embedded → offers field contains the array of offers. Each offer contains two useful fields:

_links → content contains a link to download the offer content, which is formatted with HTML markup.
- The URL could be used to insert the content into an HTML page.
_links → offer_view contains a link to the web frontend's view page, which would display the offer as a separate HTML page.

Method of User Authentication (Sign-up/Sign-in)

POST https://payg.cloudike.com/api/3/tenants/<tenant_name>/payg/phone_otp_auth_tokens/

Request Parameters

Parameter	Type	Required	Description
`long_lived`	boolean	No	By default `False`. Set to `True` to create long-lived tokens for mobile apps.
`device_description`	string	No (if `long_lived=True`)	Description of the device.
`phone`	string	Yes	The user's phone number.
`action`	string	Yes	One of `"login"` or `"reg"`.
`sms_otp`	string	Yes	One-time password (OTP) sent via SMS (e.g., `"12345"`).

Output Parameters

Parameter	Type	Description
`id`	string	ID of the created authentication token.
`client_type`	string	Type of client.
`device_description`	string	Taken from the input parameter.
`created`	string	Timestamp of token creation (ISO 8601 format).
`expires`	string	Expiration time of the token (ISO 8601 format).
`last_activity`	string	Time of last account activity (ISO 8601 format).
`user_id`	number	Cloudike user account unique ID.
`tenant_name`	string	Tenant where the user's account belongs.
`token`	string	Session token (secret).
`user_created`	boolean	`True` if a new user account was created during authentication.

Response Codes

201 Created – Token successfully created.

{
  "id": "Z6Mk8BqiYtZ6Ffpd",
  "client_type": "android-client",
  "client_version": "1.2.0",
  "device_description": "Android 10",
  "created": "2025-02-05T08:44:32.229000+00:00",
  "expires": "2025-03-08T08:44:32.229000+00:00",
  "last_activity": null,
  "user_id": 55651,
  "tenant_name": "project_123",
  "secret": "Zt0q3CAcQg6OKMZwcGbtAQ",
  "token": "Z6Lk8BqiYtZ6Ffpd:Zt0q3CAcQb6OKMZwcGbtAQ",
  "user_created": false,
  "_links": {
    "self": { "href": "https://payg.cloudike.com/api/3/users/55651/tokens/Z6Mk8BqiYtZ6Ffpd/" },
    "user": { "href": "https://payg.cloudike.com/api/3/users/55651/" },
    "credential": { "href": "https://payg.cloudike.com/api/3/users/55651/credentials/67a324ef1aa262d67a15fa4b/" },
  }
}

422 ValidationError – Incorrect or missing input parameters. Usually requires additional parameters; check the body for specific required fields:
- input OTP required
- incorrect OTP was inputted

{
  "code": "ValidationError",
  "description": "The request has wrong parameters.",
  "detail": {
    "sms_otp": "Required",
    "password": "Required"
  }
}

429 TooManyIncorrectAttempts – Too many incorrect attempts; temporary block applied. The response contains the number of seconds until the block ends.

HTTP Headers

Retry-After: 59

Response Body

{
  "code": "TooManyIncorrectAttempts",
  "description": "The action could not be performed because there were too many incorrect attempts by the client. Try again after a while.",
  "detail": {
    "retry_after": 59
  }
}

SMS Notifications Sent to the User

We have two options for sending SMS notifications:

Customer provides Cloudike PAYG with an endpoint to the standard SMPP protocol interface.
Customer implements the REST API as described below.

REST API for Sending SMS

POST https://smsgate.customer.com/send-sms

HTTP Headers

Authorization: Bearer JWT
Content-type: application/json

Request Parameters

Parameter	Type	Required	Description
`msisdn`	number	Yes	Recipient's phone number.
`message`	string	Yes	Message text.

Response Codes

HTTP Code	Description
200 OK	Message was successfully sent.
400 Bad Request	Incorrect request format. The platform will not retry the message.
422 Unprocessable Entity	Invalid phone number or message text (too long/invalid). The platform will not retry the message.
429 Too Many Requests	Too many requests were sent. The platform will retry the message later.
5xx Server Errors	SMSGate is temporarily down. The platform will retry the message.

Example Request

POST https://smsgate.customer.com/send-sms

HTTP Headers

Authorization: Bearer JWT
Content-type: application/json

Request Body

{
  "msisdn": 123456789012,
  "message": "12345 is your sign-in code for StarCloud"
}

User Subscriptions Management

Subscription Model and Concepts

Cloudike PAYG platform provides a specific set of packages tailored to each Customer. The tenant's packages are available for subscription by tenant's users.

Cloudike's package model has the following fields:

Field Name	Type	Description
`id`	string	Unique ID of the package.
`customer_product_id`	string	Unique ID of package from Customer's side.
`name`	string	Human-readable name of the package.
`cost`	number	The package's cost for one period, in the natural number of minor currency units (i.e. “cents”). Can be `0`, in this case the subscription is free for user. Cloudike still requests purchase approval from Customer's side by calling `/purchase_package_approve`.
`cost_scale`	number	By default, it is 100. This represents the number of minor currency units (“cents”) in one major currency unit (“dollar”).
`currency`	string	The currency's code, from ISO 4217.
`size`	number	The amount of storage provided by subscription to the user's quota (in bytes).
`duration`	number	The number of `period_type` time periods included in the pre-paid period. Can be `0`, that means the end-less pre-paid period (one-time purchase, not a subscription), Cloudike will never do auto-renewal tries for such package.
`period_type`	string	There are four variants: `hour`, `day`, `month`, `year`.
`is_default`	boolean	Whether it is the default package or not. The default package can only exist once. If it exists, it is automatically purchased by the system for the user when they get a 0 quota.
`is_enabled`	boolean	Whether the package is enabled or disabled. The system does not allow users to subscribe to a disabled package.
`is_visible`	boolean	Whether the package is displayed in Cloudike's applications and allowed for user's self-purchasing. The packages with `is_visible=false` parameters will not be displayed and allowed to purchase in the apps. Such packages could be subscribed only by MO request from Customer's side.
`tenant_name`	string	Assigning the package to a specific Customer based on their tenant name.
`description`	string	An internal brief summary (not visible to end users).
`discount.is_enabled`	boolean	Whether the package's discount is enabled or disabled.
`discount.cost`	number	The package's cost for one period during the discount period.
`discount.period_type`	string	Discount's period type (`hour`, `day`, `month` or `year`).
`discount.duration`	number	Duration of discount periods.

Subscription Rules

Cloudike's end users initially have a 0 GB disk quota. Users cannot use Cloudike cloud functions with a 0 GB quota. To upload any data to the cloud, a positive disk quota (>0 GB) is required.

Subscription Mechanism

Packages are required for incremental increases in the user's disk quota.
Packages can be purchased by users either in Cloudike apps or via MO requests from the Customer's System.
A successful package purchase results in an active subscription.
A user can have either no active subscription or only one active subscription at a time.
- Users cannot have two or more active subscriptions simultaneously.

Upgrade & Downgrade Subscription Rules

If a user has an active subscription and orders another subscription:

If the new subscription has a larger size, Cloudike will activate it, canceling the old subscription immediately.
If the new subscription has a smaller or equal size, the system will block the change.

Subscription Cancellation

A User or Customer's System can initiate the cancellation of an active subscription.

Cancellation means:
- Auto-prolongation stops.
- The subscription remains active until the end of the current pre-paid period.
- Once the pre-paid period expires, the subscription is automatically closed.

Default Package

A default package is optional. Cloudike sets one up if the Customer asks for it.
A tenant can have only one default package.
Default package behavior:
- Cloudike tries to purchase it automatically for every new user account.
- Cloudike tries to purchase it again when a user loses their active subscription and their quota drops to 0 GB.
- It can be free (cost = 0) or paid, depending on the Customer's preference.
If the tenant has no default package, or its purchase is not approved, the user's quota stays at 0 GB.

Subscription Approval

Subscription to any package requires approval from the Customer's System.
Unsubscribing does not require approval, but Cloudike notifies the Customer's system about any such event.

Subscription Renewal

For each package, Cloudike and the Customer agree before the package is created who renews it: Cloudike or the Customer's billing.
Packages renewed by the Customer's billing: the Customer's System doesn't send renewal requests, and there is no grace period. The subscription stays active until the Customer's System unsubscribes the user.
Packages renewed by Cloudike:
- When the paid period ends, Cloudike asks the Customer's System to approve the renewal by calling /purchase_package_approve with "action": "renew".
- If the renewal is not approved, the subscription enters a renewal grace period. The subscription stays active during the renewal grace period.
- The renewal grace period has two parts, both set in days for each package:
  - Paid grace period. Comes first and is paid for by the Customer. It is optional: 0 days means there is no paid grace period.
  - Free grace period. Comes next and is provided by Cloudike. It is 2 days by default and can be changed by agreement, down to 0 days.
- During the whole renewal grace period, Cloudike retries the renewal about every 8 hours (3 times a day).
- If the renewal is still not approved when both grace periods end, the subscription is canceled.
- Cloudike doesn't notify the Customer's System when the renewal grace period starts. The subscription_renewed event is sent only after a successful renewal.

Account Deletion at 0 GB Quota

This is separate from the renewal grace period.

If a user's quota drops to 0 GB, for example because the subscription was canceled and the default package was not purchased, a 7-day deletion period begins.
During these 7 days, Cloudike sends daily SMS notifications about the upcoming removal of the account and its data.
If the user still has no package after 7 days, Cloudike deletes the user account and all associated data.

Customer's System API

User's Subscription Approval

Cloudike will call the Customer API to approve actions related to user subscriptions, such as:

Creation of a new subscription
Renewal (prolongation) of an already active subscription, for packages renewed by Cloudike

POST https://customer.com/purchase_package_approve

HTTP Headers

Authorization: Bearer JWT
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`msisdn`	number	no¹	User's phone number (MSISDN).
`email`	string	no¹	User's email.
`package_id`	string	no²	Unique package ID in Cloudike system.
`customer_product_id`	string	no²	Unique package ID on Customer's side.
`action`	string	yes	"create" (new subscription) or "renew" (subscription prolongation).
`cost`	number	yes	Subscription cost in minor currency units (e.g., cents).
`cost_scale`	number	yes	Scale factor (default: `100`, e.g., cents per dollar).
`currency`	string	yes	Currency code (ISO 4217 format).
`trx_id`	string	yes	Unique transaction ID (max length: 100 bytes, UUID v4 recommended).

Response Codes

HTTP Code	Description
200 OK	Customer's billing processed the request in real time (the charge was approved or declined). Return the result in the JSON body:

{
  "action": "approved"
}

{
  "action": "declined"
}

HTTP Code	Description
202 Accepted	Request was successfully accepted by Customer's billing, queued, and will be processed asynchronously. Once billing processes the request (i.e., charges the user), it must send a callback to Cloudike's backend with the result by calling the corresponding method. Optionally, the Customer's billing can return a web page URL to redirect the user to, for example to choose a payment method or enter card details. In the JSON body:

HTTP Code

Description

202 Accepted

Request was successfully accepted by Customer's billing, queued, and will be processed asynchronously. Once billing processes the request (i.e., charges the user), it must send a callback to Cloudike's backend with the result by calling the corresponding method.

Optionally, the Customer's billing can return a web page URL to redirect the user to, for example to choose a payment method or enter card details.

In the JSON body:

{
  "approval_page": "https://domain.com/page/to/be/displayed/for/user"
}

HTTP Code	Description
400 Bad Request	Incorrect format of request. No retries required.
422 Unprocessable Entity	Invalid `msisdn`, `package_id`, or other parameters. No retries required.
429 Too Many Requests	Too many requests sent. The sender can retry later.
5xx Server Errors	Web service is temporarily broken. The sender can retry later.

Cloudike's Side API

Create or Delete a User Subscription

This is a low-level method for managing any user's subscriptions. This request is sent from the Customer's side to the Cloudike system.

The request is executed immediately and synchronously: it creates a new subscription or deletes an existing one for the user with the specified msisdn.

Creating a subscription:

The user is assumed to have already paid for the subscription; Cloudike does not send a charge request.
If no user with this MSISDN exists in Cloudike, a new user account is created when the request succeeds.
If the user already has this subscription, no duplicate is created.
If the user has another active subscription (with a different package_id), Cloudike cancels it first and then creates the new one: a user can have only one active subscription at a time.

Deleting a subscription:

The subscription is deleted immediately, even if its prepaid period has not ended.
If the user has no active subscription with this package_id, the request still succeeds (200 OK).

The idempotency_key parameter must be unique for each Customer's transaction; send the same value only when retrying the same request. It should be HEX of a randomly generated UUID version 7 value - 32 chars without hyphens in lower-case, for example e50e8400e29b41d4a7164266a544b301. Any other random 32-character string can also be used.

POST https://payg-provisioner.cloudike.com/provisioning-api/1/tenants/<tenant_name>/payg/subscription_changes/

HTTP Headers

Authorization: Bearer JWT
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`msisdn`	number	no¹	User's phone number (MSISDN).
`email`	string	no¹	User's email.
`package_id`	string	no²	Unique package ID in Cloudike system.
`customer_product_id`	string	no ²	Customer's side package ID
`action`	string	yes	`"create"` (to create new subscription of any package) or `"delete"` (to unsubscribe).
`reason`	string	no	Empty by default. Any human readable text (for logging of operation), max 250 chars.
`idempotency_key`	string	yes	Unique transaction ID. It should be HEX of randomly generated UUID version 7 value - 32 chars without hyphens in lower-case. Example: `'e50e8400e29b41d4a7164266a544b301'`. Any other random 32-character string can also be used.

Response Codes

HTTP Code	Description
200 OK	Request was successfully processed.
201 Created	Request was successfully processed.
400 Bad Request	Incorrect format of request. No retries required.
401 Unauthorized	Invalid secret was sent. No retries required.
422 Unprocessable Entity	Invalid `msisdn`, `package_id`, `action` or other mandatory parameters. No retries required.
429 Too Many Requests	Too many requests sent. The sender can retry later.
5xx Server Errors	Web service is temporarily broken. The sender can retry later.

MO Request to Purchase a Package for the User

This is an MO (Mobile Originated) message with a user's request sent from the Customer's side to the Cloudike system (as the content provider). The request invokes Cloudike to approve package purchase (by calling the /purchase_package_approve API from the previous section) and then (after callback receiving) to create a new subscription for the user.

Cloudike always calls the /purchase_package_approve method on Customer's side, even if the package cost is zero: the Customer must approve providing the package to the user.

This method can also be used to create a new user. If no user with such an MSISDN exists in Cloudike, the user will be created upon successful approval of the request.

To subscribe the user, set command to "subscribe". To stop a subscription, send "unsubscribe": auto-renewal stops, and the subscription ends when the current prepaid period expires. A subscription with a zero-length period ends immediately.

idempotency_key parameter should be unique for each call. It should be HEX of a randomly generated UUID version 7 value - 32 chars without hyphens in lower-case, for example e50e8400e29b41d4a7164266a544b301. Any other random 32-character string can also be used.

POST https://payg-provisioner.cloudike.com/provisioning-api/1/tenants/<tenant_name>/payg/subscription_change_requests/

HTTP Headers

Authorization: Bearer JWT
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`msisdn`	number	no¹	User's phone number (MSISDN).
`email`	string	no¹	User's email.
`package_id`	string	no²	Unique package ID in Cloudike system.
`customer_product_id`	string	no²	Customer's side package ID
`command`	string	yes	`"subscribe"` (subscribe to package) or `"unsubscribe"` (unsubscribe from package).
`promo_code`	string	no	A promo code the user entered when subscribing. Cloudike passes it to the Customer's billing, for example to apply a discount.
`idempotency_key`	string	yes	Unique transaction ID. It should be HEX of randomly generated UUID version 7 value - 32 chars without hyphens in lower-case. Example: `'e50e8400e29b41d4a7164266a544b301'`. Any other random 32-character string can also be used.

Response Codes

HTTP Code	Description
200 OK	Request was successfully accepted and will be processed.
201 Created	Request was successfully accepted and will be processed.
400 Bad Request	Incorrect format of request. No retries required.
401 Unauthorized	Invalid secret was sent. No retries required.
422 Unprocessable Entity	Invalid `msisdn`, `package_id`, or other parameters. No retries required.
429 Too Many Requests	Too many requests sent. The sender can retry later.
5xx Server Errors	Web service is temporarily broken. The sender can retry later.

Customer's billing should notify Cloudike of the result of a delayed purchasing process (previously initiated by the https://customer.com/purchase_package_approve method). The trx_id parameter must be exactly the same as in the initial /purchase_package_approve request.

In case of sending action='approved' parameter, Cloudike will

create subscription of the required package;
create new user account, if required;
send an SMS or email notification about the new subscription (depending on whether msisdn or email was used in the initial request).

In case of sending action='declined' parameter, Cloudike will do nothing.

POST https://payg-provisioner.cloudike.com/provisioning-api/1/tenants/<tenant_name>/payg/purchase_package_callbacks

HTTP Headers

Authorization: Bearer JWT
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`msisdn`	number	no¹	User's phone number (MSISDN).
`email`	string	no¹	User's email.
`package_id`	string	yes	Unique package ID in Cloudike system.
`customer_product_id`	string	no	Unique package ID on Customer's side.
`action`	string	yes	One of: `"approved"` or `"declined"`
`trx_id`	string	yes	Unique transaction ID (must match the one used in the original request)

Response Codes

HTTP Code	Description
200 OK	Request was successfully accepted.
401 Unauthorized	Invalid secret was sent. No retries required.
403 Forbidden	The request was sent with an authentication token of another tenant.
422 Unprocessable Entity	Invalid `msisdn`, `package_id`, or other mandatory parameters. No retries required.

If the callback is sent again with the same trx_id and the same parameters, Cloudike returns the same response as for the first request (200 OK).

Port-out Notification for the User

The Customer's System should inform Cloudike immediately if the user has performed a port-out action or contract cancellation.

POST https://payg-provisioner.cloudike.com/provisioning-api/1/tenants/<tenant_name>/payg/port_out_requests

HTTP Headers

Authorization: Bearer JWT
Content-Type: application/json

Request Parameters

Parameter	Type	Description
`msisdn`	number	User's phone number (MSISDN).
`idempotency_key`	string	Unique transaction ID. It should be HEX of randomly generated UUID version 7 value - 32 chars without hyphens in lower-case. Example: `'e50e8400e29b41d4a7164266a544b301'`. Any other random 32-character string can also be used.

Response Codes

HTTP Code	Description
200 OK	Request was successfully accepted and will be processed.
201 Created	Request was successfully accepted and will be processed.
400 Bad Request	Incorrect format of request. No retries required.
401 Unauthorized	Invalid `tenant_name` / `secret` pair sent. No retries required.
422 Unprocessable Entity	Invalid `msisdn` or other parameters. No retries required.
429 Too Many Requests	Too many requests sent. The sender can retry later.
5xx Server Errors	Web service is temporarily broken. The sender can retry later.

MSISDN Change Notification

The Customer's System should inform Cloudike immediately when a user changes their MSISDN. The user's active subscription will be automatically transferred to the new MSISDN without requiring re-creation or additional actions.

POST https://payg.cloudike.com/api/3/tenants/<tenant_name>/payg/msisdn_change_requests

HTTP Headers

Authorization: Bearer JWT
Content-Type: application/json

Request Parameters

Parameter	Type	Description
`msisdn`	number	New MSISDN value.
`old_msisdn`	number	Previous (old) MSISDN value.
`idempotency_key`	string	Unique transaction ID. It should be HEX of randomly generated UUID version 7 value - 32 chars without hyphens in lower-case. Example: `'e50e8400e29b41d4a7164266a544b301'`. Any other random 32-character string can also be used.

Response Codes

HTTP Code	Description
200 OK	Request was successfully accepted and will be processed.
201 Created	Request was successfully accepted and will be processed.
400 Bad Request	Incorrect format of request. No retries required.
401 Unauthorized	Invalid `tenant_name` / `secret` pair sent. No retries required.
422 Unprocessable Entity	Invalid `msisdn`/ `old_msisdn` or other parameters. No retries required.
429 Too Many Requests	Too many requests sent. The sender can retry later.
5xx Server Errors	Web service is temporarily broken. The sender can retry later.

Get JWT Token to Access a Private API

The Customer's System should use a JWT token for authentication when making API requests to Cloudike services. A JWT token is generated using the following API request:

POST https://payg.cloudike.com/api/3/applications/<app_id>/tokens/

HTTP Headers

Content-Type: application/json

Request Parameters

Parameter	Type	Description
`access_key`	string	Application's access key.
`scope_name`	string	Name of the scope (a list of functions the customer is allowed to call).

Response Body

Field	Type	Description
`token`	string	The generated JWT token.
`expires`	string	Date-time of token expiration.

Response Codes

HTTP Code	Description
201 Created	Request was successfully accepted, JWT token generated.
400 Bad Request	Incorrect format of request. No retries required.
422 Unprocessable Entity	Invalid `access_key` or `scope_name`. No retries required.

User's Actions Notifications Sent to Customer's System

Cloudike will notify the Customer's System of various events occurring with the users. Only one callback will be used for this notification.

POST https://customer.com/user_event_notify

HTTP Headers

Authorization: Bearer JWT
Content-Type: application/json

Request Parameters

Parameter	Type	Description
`created`	string	The date and time of the event in ISO-8601 format (e.g., "2025-02-25T08:37:20+00:00").
`event`	string	The name of the occurred event (see table below).
`msisdn`	number	The user's MSISDN (mobile number). Omitted if the user account has no MSISDN.
`email`	string	The user's email. Omitted if the user account has no email.
`user_id`	number	Cloudike's user ID.
`parameters`	structure	The JSON structure with variable additional parameters depending on the event.

Events

Event	Additional Parameters (JSON)	Description
`user_created`	`{}`	The user account was created.
`user_removed`	`{}`	The user account with all its data was removed.
`subscription_created`	`{ "package_id": "9999", "customer_product_id": "CLOUD123" }`	The user was subscribed to a new subscription.
`subscription_renewed`	`{ "package_id": "9999", "customer_product_id": "CLOUD123" }`	The user's active subscription was successfully prolonged.
`subscription_canceled`	`{ "package_id": "9999", "customer_product_id": "CLOUD123" }`	The user's active subscription was canceled.
`user_quota_exceed_80`	`{}`	The user's used storage has reached 80% of their available disk quota.
`user_quota_exceed_90`	`{}`	The user's used storage has reached 90% of their available disk quota.
`user_quota_exceed_95`	`{}`	The user's used storage has reached 95% of their available disk quota.
`user_quota_exceed_100`	`{}`	The user's used storage has reached 100% of their available disk quota.
`user_quota_zero`	`{}`	The user's disk quota has reached zero, meaning their account is planned to be removed after 7 days.

Response Codes

HTTP Code	Description
200 OK	Event was accepted by the Customer's System.
400 Bad Request	Incorrect format of request. The platform will not retry the message.
401 Unauthorized	Invalid secret sent. Request was not accepted, no retries required.
422 Unprocessable Entity	Invalid `msisdn` number or other parameters. The platform will not retry the message.
429 Too Many Requests	Too many requests sent. The platform will retry the message.
5xx Server Errors	Web service is temporarily broken. The platform will retry the message.

The response body can be empty: Cloudike ignores it.

Appendix: Sequence Diagrams

User Orders a New Subscription in the App

msisdn and email parameters - one of them is required. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸
package_id and customer_product_id parameters - one of them is required. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

Definitions​

User Authentication Procedure​

Get list of "recommended" Tenants by phone number​

Request Parameters​

Output​

Response Codes​

Example Response (JSON)​

Get the "Privacy Policy" Document of the Tenant​

Request Parameters​

Example Request​

Response Codes​

Example Response (JSON)​

Notes​

Method of User Authentication (Sign-up/Sign-in)​

Request Parameters​

Output Parameters​

Response Codes​

HTTP Headers​

Response Body​

SMS Notifications Sent to the User​

REST API for Sending SMS​

HTTP Headers​

Request Parameters​

Response Codes​

Example Request​

HTTP Headers​

Request Body​

User Subscriptions Management​

Subscription Model and Concepts​

Subscription Rules​

Subscription Mechanism​

Upgrade & Downgrade Subscription Rules​

Subscription Cancellation​

Default Package​

Subscription Approval​

Subscription Renewal​

Account Deletion at 0 GB Quota​

Customer's System API​

User's Subscription Approval​

HTTP Headers​

Request Parameters​

Response Codes​

Cloudike's Side API​

Create or Delete a User Subscription​

HTTP Headers​

Request Parameters​

Response Codes​

MO Request to Purchase a Package for the User​

HTTP Headers​

Request Parameters​

Response Codes​

Confirm Delayed Request of Initial Subscribe or Renew​

HTTP Headers​

Request Parameters​

Response Codes​

Port-out Notification for the User​

HTTP Headers​

Request Parameters​

Response Codes​

MSISDN Change Notification​

HTTP Headers​

Request Parameters​

Response Codes​

Get JWT Token to Access a Private API​

HTTP Headers​

Request Parameters​

Response Body​

Response Codes​

User's Actions Notifications Sent to Customer's System​

HTTP Headers​

Request Parameters​

Events​

Response Codes​

Appendix: Sequence Diagrams​

User Orders a New Subscription in the App​

MO Request to Subscribe a User to a Package​

Footnotes​

Definitions

User Authentication Procedure

Get list of "recommended" Tenants by phone number

Request Parameters

Output

Response Codes

Example Response (JSON)

Get the "Privacy Policy" Document of the Tenant

Request Parameters

Example Request

Response Codes

Example Response (JSON)

Notes

Method of User Authentication (Sign-up/Sign-in)

Request Parameters

Output Parameters

Response Codes

HTTP Headers

Response Body

SMS Notifications Sent to the User

REST API for Sending SMS

HTTP Headers

Request Parameters

Response Codes

Example Request

HTTP Headers

Request Body

User Subscriptions Management

Subscription Model and Concepts

Subscription Rules

Subscription Mechanism

Upgrade & Downgrade Subscription Rules

Subscription Cancellation

Default Package

Subscription Approval

Subscription Renewal

Account Deletion at 0 GB Quota

Customer's System API

User's Subscription Approval

HTTP Headers

Request Parameters

Response Codes

Cloudike's Side API

Create or Delete a User Subscription

HTTP Headers

Request Parameters

Response Codes

MO Request to Purchase a Package for the User

HTTP Headers

Request Parameters

Response Codes

Confirm Delayed Request of Initial Subscribe or Renew

HTTP Headers

Request Parameters

Response Codes

Port-out Notification for the User

HTTP Headers

Request Parameters

Response Codes

MSISDN Change Notification

HTTP Headers

Request Parameters

Response Codes

Get JWT Token to Access a Private API

HTTP Headers

Request Parameters

Response Body

Response Codes

User's Actions Notifications Sent to Customer's System

HTTP Headers

Request Parameters

Events

Response Codes

Appendix: Sequence Diagrams

User Orders a New Subscription in the App

MO Request to Subscribe a User to a Package

Footnotes