Issue license keys, validate user activations, track activations counts, and modify licenses.

Digital Commerce & Licenses

Xtopay supports digital commerce workflows. You can sell software packages, ebooks, subscriptions, or membership access. For software and SaaS products, Xtopay provides a built-in License Key Management API to issue, validate, and track software activations across devices.

License Key Lifecycle & States

When a customer purchases software, you can generate a secure license key. License keys track device installations and activation counts, and progress through these states:

Status	Description
`ACTIVE`	The license is active and can record activations.
`SUSPENDED`	The license is temporarily suspended and cannot validate or record activations.
`EXPIRED`	The license has passed its expiry date and is inactive.
`REVOKED`	The license is permanently deactivated and can never be re-used.

Issue a License Key

Generate a new unique software license key for a customer.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/licenses`
Request Type	`POST`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`licenses:write`

Request Parameters

Parameter	Type	Required	Description
`customerId`	`String`	Yes	The ID of the customer receiving this license.
`productId`	`String`	No	Optional ID of the product to bind this license to.
`maxActivations`	`Integer`	No	Maximum allowed device installations. Defaults to `1`.
`expiresAt`	`String`	No	ISO 8601 date string representing the key's expiration.
`metadata`	`Object`	No	Flat key-value object containing license metadata.

Code Examples

curl https://api.xtopay.co/v1/licenses \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_cl8z2l8820000a",
    "productId": "prod_cl8z2j8820000b",
    "maxActivations": 3,
    "expiresAt": "2027-06-05T12:00:00Z"
  }'

Sample Response

201 Created

{
  "success": true,
  "data": {
    "id": "lic_cl8z2m8820000c",
    "key": "A9E3-8F2D-C1B0-77E5",
    "status": "ACTIVE",
    "environment": "TEST",
    "activations": 0,
    "maxActivations": 3,
    "expiresAt": "2027-06-05T12:00:00Z",
    "revokedAt": null,
    "metadata": null,
    "createdAt": "2026-06-05T12:00:00Z",
    "customer": {
      "id": "cust_cl8z2l8820000a",
      "name": "Yaw Mensah",
      "email": "yaw@example.com"
    },
    "product": {
      "id": "prod_cl8z2j8820000b",
      "name": "Cloud Hosting Standard"
    }
  }
}

Validate a License Key

Check if a license key is valid, active, and has device activations remaining. Run this check during app boot or authorization loops.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/licenses/:key`
Request Type	`GET`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`licenses:read`

Path Parameters

Parameter	Type	Required	Description
`:key`	`String`	Yes	The license key token (e.g. `A9E3-8F2D-C1B0-77E5`).

Code Examples

curl https://api.xtopay.co/v1/licenses/A9E3-8F2D-C1B0-77E5 \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "id": "lic_cl8z2m8820000c",
    "key": "A9E3-8F2D-C1B0-77E5",
    "status": "ACTIVE",
    "activations": 1,
    "maxActivations": 3,
    "expiresAt": "2027-06-05T12:00:00Z"
  }
}

Record an Activation

Increment the activation counter when the software is installed on a new device or server.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/licenses/:key/activate`
Request Type	`POST`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`licenses:write`

[!IMPORTANT] The activation request will fail with a 400 Bad Request validation error if the license key status is not ACTIVE, if the key is expired, or if the activations count has already reached maxActivations.

Path Parameters

Parameter	Type	Required	Description
`:key`	`String`	Yes	The license key token to activate.

Code Examples

curl -X POST https://api.xtopay.co/v1/licenses/A9E3-8F2D-C1B0-77E5/activate \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "id": "lic_cl8z2m8820000c",
    "key": "A9E3-8F2D-C1B0-77E5",
    "status": "ACTIVE",
    "activations": 2,
    "maxActivations": 3
  }
}

Modify a License

Extend expiration dates, suspend keys, or change device limits.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/licenses/:key`
Request Type	`PATCH`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`licenses:write`

Path Parameters

Parameter	Type	Required	Description
`:key`	`String`	Yes	The license key token to modify.

Request Parameters

Parameter	Type	Required	Description
`status`	`String`	No	Set key status: `ACTIVE`, `SUSPENDED`.
`maxActivations`	`Integer`	No	Update maximum device activation limit.
`expiresAt`	`String`	No	Update expiration ISO date string (pass `null` to remove expiry).
`metadata`	`Object`	No	Replace the key metadata payload.

Code Examples

curl -X PATCH https://api.xtopay.co/v1/licenses/A9E3-8F2D-C1B0-77E5 \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "SUSPENDED"
  }'

Revoke a License

Permanently revoke a license key. Once revoked, a license cannot be re-activated or modified.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/licenses/:key`
Request Type	`DELETE`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`licenses:write`

Path Parameters

Parameter	Type	Required	Description
`:key`	`String`	Yes	The license key token to revoke.

Code Examples

curl -X DELETE https://api.xtopay.co/v1/licenses/A9E3-8F2D-C1B0-77E5 \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "key": "A9E3-8F2D-C1B0-77E5",
    "status": "REVOKED",
    "revokedAt": "2026-06-05T12:50:00Z"
  }
}

Digital Commerce & Licenses

On this page