Mamsco Enterprise

API

Generate and manage API keys, and browse the available endpoints.

Your API keys

Use a key to call the API on your own behalf — see the Documentation tab for available endpoints.

Loading your API keys…

Environments

Use the sandbox for all testing and development — point at production only when you're ready to send real, billable requests.

SandboxUse for testing: https://sandox.mamscoenterprise.com
Production: https://mamscoenteprise.com

Authentication

Every endpoint below (unless marked Public) authenticates the same way a logged-in session would, just with an API key instead of a browser cookie.

Generate a key from the "Your Keys" tab, then send it as a Bearer token on every request:

Authorization: Bearer sk_...

Example with curl, against the sandbox:

curl -H "Authorization: Bearer sk_..." \
  https://sandox.mamscoenterprise.com/api/orders/me

A key acts with the full permissions of the account that created it — an agent's key can do anything that agent can do in the dashboard, an admin's key anything an admin can. Keys can be given an expiry (or none) when generated, and revoked instantly at any time from the "Your Keys" tab.

Orders

Place and track data bundle orders.

POST/api/ordersYour key

Place one or more orders in a single request. Orders that get blocked or rejected upstream (e.g. an unvalidated MTN number) are listed separately and never billed.

Request Body

{
  "orders": [
    {
      "packageID": "string",
      "bundle": "5",
      "recipient": "0241234567",
      "ref": "string (optional)",
      "callbackUrl": "string (optional)"
    }
  ]
}

Response

{
  "message": "Order(s) created",
  "status": 201,
  "rejectedOrders": [
    { "orderID": "...", "recipient": "...", "bundle": "5", "amount": 21.00, "reason": "..." }
  ]
}

GET/api/orders/meYour key

List your own orders. All query params are optional.

Request Body

?provider=MTN&status=PENDING&search=...&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&page=1&limit=20

Response

{
  "orders": [ { "id": "...", "recipient": "...", "bundle": "5", "amount": 21.00, "status": "SENT", "ref": "...", "orderDate": "..." } ],
  "pagination": { "page": 1, "limit": 20, "totalCount": 42, "totalPages": 3 }
}

GET/api/orders/me/[id]Your key

Get a single order by id — 403 if it doesn't belong to you.

Response

{ "id": "...", "recipient": "...", "bundle": "5", "amount": 21.00, "status": "SENT" }

AFA Orders

AFA (registration) orders — a separate order type from data bundles.

POST/api/orders/afaYour key

Place an AFA registration order.

Request Body

{
  "packageID": "string",
  "order": {
    "name": "string", "phone": "string", "id": "string",
    "dob": "YYYY-MM-DD", "town": "string", "occupation": "string",
    "email": "string (optional)"
  }
}

Response

{ "message": "Order(s) created", "status": 201 }

GET/api/orders/afa/meYour key

List your own AFA orders.

Request Body

?status=PENDING&search=...&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD

Response

[ { "id": "...", "name": "...", "phone": "...", "status": "PENDING" } ]

MTN Precheck

POST/api/orders/mtn/precheckPublic

Check whether MTN numbers are already validated before ordering — a number set aside by this check would otherwise be blocked (and unbilled) if ordered directly. No API key required, but throttled per IP.

Request Body

{ "phoneNumbers": ["0241234567", "0209990000"] }  // up to 500

Response

{
  "enabled": true,
  "results": [
    { "phone": "0241234567", "normalized": "0241234567", "valid": true, "known": true },
    { "phone": "0209990000", "normalized": "0209990000", "valid": true, "known": false }
  ]
}

Cart

Stage orders before checkout — the same cart the dashboard's Cart page uses.

GET/api/cartYour key

List your cart items.

Response

[ { "id": "...", "packageID": "...", "bundle": "5", "recipient": "...", "amount": 21.00 } ]

POST/api/cartYour key

Add one item ({packageID, bundle, amount, recipient}) or several ({items: [...]}).

Request Body

{ "packageID": "string", "bundle": "5", "amount": 21.00, "recipient": "0241234567" }

Response

{ "message": "Item added to cart" }

DELETE/api/cartYour key

Clear your entire cart.

Response

{ "message": "Items removed from cart" }

DELETE/api/cart/[itemID]Your key

Remove a single cart item.

Response

{ "message": "Item removed from cart" }

Deposits

Wallet top-ups.

POST/api/deposit/meYour key

Record a deposit against your own wallet, keyed by a unique transactionID (safe to retry).

Request Body

{ "transactionID": "string", "amount": 50.00 }

Response

{ "message": "Deposit recorded" }

GET/api/deposit/meYour key

List your own deposits.

Request Body

?status=CONFIRMED&search=...&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD

Response

[ { "id": "...", "transactionID": "...", "amount": 50.00, "status": "CONFIRMED", "paidAt": "..." } ]

Transactions

Your wallet ledger.

GET/api/transactions/meYour key

List your own transactions.

Request Body

?status=...&type=DEBIT&search=...&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD

Response

[ { "id": "...", "type": "DEBIT", "channel": "data-order", "amount": 21.00, "balance": 79.00, "paidAt": "..." } ]

Storefront

Manage your own reseller storefront. Creating one requires an agent-tier role (Agent, Super Agent, Dealer, or Super Dealer).

GET/api/storefrontYour key

Get your own storefront settings.

Response

{ "tag": "my-store", "pricingType": "PERCENTAGE", "markup": 10, "active": true, "customPrices": {} }

POST/api/storefrontYour key

Create your storefront (one per account).

Request Body

{ "tag": "my-store", "pricingType": "PERCENTAGE", "markup": 10, "active": true, "customPrices": {} }

Response

{ "message": "Storefront created!", "status": 201 }

PUT/api/storefrontYour key

Update your storefront settings.

Request Body

{ "tag": "my-store", "pricingType": "FIXED", "markup": 2, "active": true, "customPrices": {} }

Response

{ "message": "Storefront updated!" }

GET/api/storefront/[tag]Public

Public storefront catalog by tag — what a customer sees at /store/[tag].

Response

{ "agentName": "...", "agentContact": "...", "packages": [ ... ] }

GET/api/storefront/check-tag?tag=...Public

Check whether a storefront tag is available.

Response

{ "available": true }

Notifications

GET/api/notificationsYour key

List your notifications.

Response

[ { "id": "...", "message": "...", "read": false } ]

PUT/api/notifications?id=...Your key

Mark a notification as read.

Response

{ "message": "Notification updated" }

Profile

GET/api/auth/users/meYour key

Get your own profile.

Response

{ "id": "...", "name": "...", "email": "...", "phone": "...", "role": "AGENT", "balance": 79.00 }

PUT/api/auth/users/meYour key

Update your own name, email, phone, or password (password change requires oldPassword).

Request Body

{ "name": "string", "email": "string", "phone": "string", "password": "string (optional)", "oldPassword": "string (required if changing password)" }

Response

{ "message": "Profile updated" }

API Keys

Manage your own keys programmatically — the same operations as the “Your Keys” tab.

GET/api/keys/meYour key

List your own API keys. Never returns the key value itself, only its prefix.

Response

[ { "id": "...", "name": "...", "keyPrefix": "sk_a1b2c3", "expiresAt": "...", "createdAt": "..." } ]

POST/api/keys/meYour key

Generate a new key. The raw key is returned only in this response — copy it immediately, it can't be retrieved again.

Request Body

{ "name": "string", "duration": 30 }  // duration in days, omit for no expiry

Response

{ "key": "sk_...", "name": "string", "expiresAt": "...", "message": "API key generated successfully" }

DELETE/api/keys/me/[id]Your key

Revoke one of your own keys immediately.

Response

{ "message": "Key revoked successfully" }