Portal API Reference

Role: Return the public zone name/label for portal branding.

Access: Public

Operator use case: On portal load, display the exact zone name automatically (e.g. ED Center).

Parameters:

• companyRef (path, required)

Response body (sample):

{
  "name": "ReadyZone Center",
  "label": "ReadyZone Center",
  "reference": "ed-center-68819"
}

Status codes:

• 200 OK
• 400 Bad Request (company not found)

Role: List active plans for the zone.

Access: Public

Operator use case: When users open the “Buy a plan” tab, load only active plans for the selected zone.

Parameters:

• companyRef (query, required)

Response body (sample):

[
  {
    "id": "plan_uuid",
    "name": "2H Plan",
    "price": 500,
    "currency": "XAF",
    "type": "time-based",
    "durationHours": 2,
    "isGuestPurchaseEnabled": true,
    "isActive": true
  }
]

Status codes:

• 200 OK
• 400 Bad Request (missing/invalid companyRef)

Role: Open ReadyZone checkout page for standard OM/MoMo payment.

Access: Public (ReadyZone web page)

Operator use case: “Pay via OM/Momo” button: redirect user to ReadyZone checkout to complete payment.

Parameters:

• planId (path, required)
• companyRef (query, recommended)

Response body (sample):

ReadyZone checkout page displayed with selected plan and full payment flow.

Status codes:

• 200 OK
• 400 Bad Request
• 404 Not Found

Role: Start guest checkout (without account) and create payment transaction.

Access: Public (API anti-abuse checks apply)

Operator use case: “Instant Payment” button: walk-in customer pays quickly without account creation.

Parameters:

• key (query, optional depending on configuration)

Request body:

{
  "planId": "plan_uuid",
  "paymentPhone": "+237690201423",
  "notificationContact": "client@example.com",
  "username": "AA:BB:CC:DD:EE:FF",
  "password": "DOES_NOT_WORKING"
}

Response body (sample):

{
  "message": "Achat invité initié avec succès",
  "purchaseId": "purchase_uuid",
  "merchandTransactionId": "GR-TX-XXXXXXXXXX",
  "notchTransactionId": "np_xxxxx",
  "paymentUrl": "https://...",
  "isGuestPurchase": true
}

Status codes:

• 201 Created
• 400
• 404
• 422
• 429

Role: Check transaction status and sync local state.

Access: Public

Operator use case: After payment start, poll every 5 seconds until final status.

Parameters:

• transactionReference (path, required)

Response body (sample):

{
  "message": "Payment status successfully verified",
  "status": "complete",
  "transactionId": "GR-TX-XXXXXXXXXX",
  "targetType": "payment"
}

Status codes:

• 200 OK
• 404 Not Found

Role: Check ReadyZone username availability before purchase.

Access: Public

Operator use case: Before checkout confirmation, avoid late failures by checking if username already exists.

Parameters:

• username (path, required)

Response body (sample):

{
  "available": true
}

Status codes:

• 200 OK
• 400 Bad Request

Role: Recover guest credentials from notification contact or payment phone.

Access: Public (rate-limited)

Operator use case: User paid but lost credentials: retrieve access without opening support ticket.

Parameters:

• notificationContact (query, optional)
• paymentPhone (query, optional)

Response body (sample):

{
  "items": [
    {
      "username": "AA:BB:CC:DD:EE:FF",
      "password": "********",
      "status": "complete",
      "purchaseDate": "2026-03-12T08:20:00.000Z"
    }
  ]
}

Status codes:

• 200 OK
• 400 Bad Request
• 429 Too Many Requests