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.

License Key Lifecycle & States

When a customer purchases software, you can generate a secure license key. License keys track usage and device limits, and can hold one of these statuses:

ACTIVE: The license is in good standing and can record activations.
SUSPENDED: The license has been temporarily suspended by the merchant.
EXPIRED: The license has passed its expiry date.
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.

POST /v1/licenses

Request Scopes

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 number of 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.

Example Request

curl https://api.xtopay.co/v1/licenses \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_cl8z2l...",
    "productId": "prod_cl8z2j...",
    "maxActivations": 3,
    "expiresAt": "2027-06-05T12:00:00Z"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "lic_cl8z2m...",
    "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_cl8z2l...",
      "name": "Yaw Mensah",
      "email": "yaw@example.com"
    },
    "product": {
      "id": "prod_cl8z2j...",
      "name": "Cloud Hosting Standard"
    }
  }
}

Validate a License Key

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

GET /v1/licenses/:key

Request Scopes

licenses:read

Example Request

curl https://api.xtopay.co/v1/licenses/A9E3-8F2D-C1B0-77E5 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "lic_cl8z2m...",
    "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.

POST /v1/licenses/:key/activate

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

Request Scopes

licenses:write

Example Request

curl -X POST https://api.xtopay.co/v1/licenses/A9E3-8F2D-C1B0-77E5/activate \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Example Response

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

Modify a License

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

PATCH /v1/licenses/:key

Request Parameters

Parameter	Type	Required	Description
`status`	`string`	No	Update 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.

Example Request

curl -X PATCH https://api.xtopay.co/v1/licenses/A9E3-8F2D-C1B0-77E5 \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -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 updated.

DELETE /v1/licenses/:key

Request Scopes

licenses:write

Example Request

curl -X DELETE https://api.xtopay.co/v1/licenses/A9E3-8F2D-C1B0-77E5 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Example Response

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

Digital Commerce & Licenses

On this page