API Reference

Check all endpoints available in our Swagger UI:

• Swagger Ecommerce API
• Webhook.

---

OpenAPI Contract

In addition to Swagger UI, we also publish the full OpenAPI contract so you can validate, version, and auto-generate SDKs in your pipelines.

Downloads

• YAML
• JSON

Replace these URLs with the final ones where you decide to host the contract.

Versioning

• We use SemVer: MAJOR.MINOR.PATCH.
• Breaking changes only in MAJOR with prior notice.
• Backward-compatible changes (new optional fields, new endpoints) in MINOR.
• Fixes and examples in PATCH.

---

Response Standard

Success (200/201)

Envelope

{
  "message": "Payment created",
  "timestamp": "2024-04-16T17:44:51Z",
  "data": { /* resource or result */ }
}

Example (create payment)

{
  "message": "OK",
  "timestamp": "2024-04-16T17:44:51Z",
  "data": {
    "id": "263600a1-1514-4e57-a11d-be91e9c8e9d4",
    "merchant_reference": "INV-25-AUG-0001",
    "title": "My new payment",
    "description": "Purchase of food and groceries on March 3, 2025",
    "network": "TRON",
    "currency": "USDT",
    "amount": "1234.56",
    "confirmed_amount": "0",
    "status": "OPEN",
    "valid_until": 1755532150,
    "created_at": "2024-04-16T17:44:51Z",
    "updated_at": "2024-04-16T17:44:51Z"
  }
}

Errors (4xx/5xx)

Envelope

{
  "error": "0004",
  "title": "INVALID_REQUEST",
  "message": "The received request contains invalid data.",
  "timestamp": "2024-04-16T17:44:51Z",
  "details": [
    {
      "field": "network",
      "message": "The received field exceeds the maximum allowed length."
    }
  ]
}

• error: stable numeric identifier so your client logic doesn’t depend on text.
• title: stable text identifier.
• message: human-readable message.
• timestamp: date and time when the response was generated.
• details: optional array with field-level errors or other metadata.

Headers

• For validation errors, we recommend Content-Type: application/json (simple and universal).

---

URL Versioning

SP Cuvex uses URL versioning to ensure compatibility:

• Format: /v{number}/endpoint
• Current version: v1 (only version available so far)
• Example: /v1/payments

---

Caching

Payment/invoice status endpoints are time-sensitive and real-time in nature. We do not recommend caching them client-side.
SP Cuvex may include conservative headers (Cache-Control: no-store) in critical responses. If your platform applies intermediate caches (CDN/proxy), disable them for these routes.

---

Rate Limiting

In the current version we do not apply formal rate limits by API Key.
We reserve the right to enable anti-abuse protections. If we introduce 429 Too Many Requests in the future, we will follow the Retry-After standard and publish the policy (quotas and windows) in this section.

---

Compliance

SP Cuvex is a non-custodial service: we never have control over your wallet funds.
Responsibility for private key custody, wallet operation, and accounting records rests with you as the merchant.

---

Main Endpoints

Sandbox

• Base endpoint:

  https://sp-dev.cuvex.io/ecommerce

Production

• Base endpoint:

  https://sp.cuvex.io/ecommerce

---

Postman Collection

To simplify integration testing, we provide a Postman collection with all endpoints and ready-to-use examples.

Download Collection

📋 Download Postman Collection

Collection Contents

The collection includes the following endpoint groups:

• Status: Service health check
• Networks: Query supported blockchain networks
• Tokens: Query available tokens (stablecoins)
• Payments: Full payment management
  • Create payments with idempotency
  • List payments with pagination and date filters
  • Retrieve details of specific payments

Preconfigured Variables

Variable	Default value	Description
baseUrl	http://localhost:8080/ecommerce	API base URL (update for your environment)
apiKey	your-api-key-here	Your API key
paymentId	39bdc393-dbda-47a6-b812-73c2fc5cbf91	Example ID for payment queries

Recommended Setup

1. Import the collection in Postman.
2. Update environment variables:
   • For sandbox: https://sp-dev.cuvex.io/ecommerce
   • For production: https://sp.cuvex.io/ecommerce
3. Configure your real apiKey.
4. Execute requests in order to get familiar with the flow.

---

Error Codes

See the Error Codes section for the list of error codes handled by the API.