Sator Tracking ↔ E-Certificate

1. Introduction

Thanks for sharing the API document. The certificate endpoints already cover most of the flow we need. The main point we suggest adjusting is authentication: this integration is server-to-server, so it should not depend on an individual customer's username and password.

POST /tracking/sign could technically work if it uses a dedicated integration account and has a documented token-expiry or refresh process. A service Bearer token is simpler and safer for both systems, so that is the preferred option below.

People continue to sign in to Sator Tracking as they do today. Integration credentials stay on the servers. The dashboard only receives the public IremboPay fields: publicKey and invoiceNumber.

2. Authentication

Our preferred option is a Bearer token issued specifically for the integration. In that setup, these user-account operations are not part of the integration flow:

• POST /tracking/sign
• POST /tracking/signout
• POST /tracking/changepassword
• The accessToken header

Both systems use the standard header:

Authorization: Bearer <partner_token>

Wrong or missing token → 401

{
  "success": false,
  "message": "Unauthorized"
}

3. Who does what

4. Price and period

The e-certificate system should remain the source of truth for pricing. Sator Tracking will not calculate the certificate amount or keep a separate hardcoded rate.

The customer selects one of the period-and-rate options returned by the templates API. Sator Tracking sends the selected period and the selected templateId to POST /certificates. The e-certificate API then returns the final amount and currency. That returned amount is what Sator Tracking displays and what the IremboPay invoice charges.

• The templates API returns each allowed period together with its rate.
• Sator Tracking sends only templateId and the selected period; it does not send a price.
• Sator Tracking displays the returned period rate without calculating it.
• The e-certificate backend validates the selected period and returns the final amount again when creating the invoice.
• The amount returned by POST /certificates is authoritative.

5. Payment flow

From the customer clicking Renew to having a PDF:

6. Sator Tracking vehicle API

The e-certificate backend can use this endpoint to confirm that a vehicle exists in Sator Tracking.

6.1 Get vehicle by key

This can replace the separate /vehicles/plateNumber/{plateNumber} and /vehicles/serialNumber/{serialNumber} calls in the shared document.

{
  "success": true,
  "data": {
    "id": 42,
    "make": "TOYOTA",
    "imei": "352544071445473",
    "plate_number": "RAD 292 T",
    "chassis_number": "YVZE4C4A7WB20794",
    "vehicle_type": "van",
    "status": "online",
    "tenant": {
      "id": "...",
      "name": "Karinda DESIRE",
      "contact_email": "owner@example.com",
      "phone": "078xxxxxxx",
      "address": "Kigali"
    }
  }
}

{ "success": false, "message": "Vehicle not found" }

7. Proposed use of the e-certificate APIs

The existing resource paths can remain as documented. For automated calls, we suggest service authentication as described in section 2. To open checkout in the Sator Tracking dashboard, the response from POST /certificates would also need the public IremboPay fields: IremboPay.initiate({ publicKey, invoiceNumber }).

7.1 Templates and rates by period

Sator Tracking uses this endpoint to load the certificate choices. Each template returns its allowed periods together with the rate for each period, so no price calculation is required in Sator Tracking.

[
  {
    "id": "temp001",
    "name": "GPS tracking certificate",
    "currency": "RWF",
    "periodRates": [
      { "period": 1, "amount": 2000 },
      { "period": 3, "amount": 5500 },
      { "period": 6, "amount": 10000 }
    ]
  }
]

7.2 Certificates for a vehicle

7.3 Start buy / renew

In the proposed flow, this endpoint creates the IremboPay invoice on the e-certificate merchant account. The e-certificate backend determines the final amount using its own pricing rules and returns it to Sator Tracking.

{
  "vehicle": {
    "ownerNames": "Karinda DESIRE",
    "registrationNumber": "RAD 292 T",
    "plateNumber": "RAD 292 T",
    "make": "TOYOTA",
    "chassisNumber": "YVZE4C4A7WB20794",
    "deviceSerialNumber": "352544071445473",
    "imeiNumber": "352544071445473",
    "ownerTelephoneNumber": "078xxxxxxx",
    "ownerEmail": "owner@example.com",
    "type": "van",
    "simNumber": "078xxxxxxx"
  },
  "issuer": 1,
  "paymentMethod": "MOBILE",
  "period": 3,
  "templateId": "temp001",
  "referenceId": "550e8400-e29b-41d4-a716-446655440000",
  "requestId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

{
  "referenceId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 5500,
  "currency": "RWF",
  "period": 3,
  "invoiceNumber": "IPAY-XXXX",
  "publicKey": "<your IremboPay public key>",
  "widgetScriptUrl": "https://dashboard.irembopay.com/assets/payment/inline.js",
  "locale": "EN"
}

IremboPay.initiate({
  publicKey,
  invoiceNumber,
  locale: IremboPay.locale.EN,
  callback: function (err) { /* then poll 7.4 */ }
});

7.4 Payment status

The e-certificate system issues the certificate after receiving payment confirmation from IremboPay. Sator Tracking checks the status through this endpoint instead of checking settlement directly with IremboPay.

{
  "code": 200,
  "description": "Payment done successfully",
  "certificate": {
    "certificateNumber": "CERT-...."
  }
}

7.5 Official certificate PDF

8. Errors

JSON is enough. Please do not send stack traces.

{ "success": false, "message": "Vehicle not found" }

9. Integration details to confirm

1. The full base URL on 165.232.70.85 (HTTPS, port, and any path prefix).
2. Authentication choice: service Bearer token, or dedicated /tracking/sign credentials with token expiry and refresh details.
3. countryId, issuer, and templateId for Rwanda.
4. Which period-rate options apply to each certificate template.
5. Whether POST /certificates can return invoiceNumber, publicKey, widgetScriptUrl, and the final amount.
6. Test credentials and two or three sample plates.
7. Whether a payment-confirmed webhook is available or polling should remain the only confirmation mechanism.

Sator Tracking will share its vehicle-lookup token through a separate secure channel.

10. Testing after integration

Once both sides are connected in the test environment, we can verify the complete flow together using a known Sator Tracking vehicle and an IremboPay sandbox payment.

1. Use a known plate to confirm the vehicle lookup returns 200 and the expected vehicle details.
2. Try an unknown plate and confirm the lookup returns 404.
3. Call an endpoint without the Bearer token and confirm it returns 401.
4. Load the certificate templates and confirm each allowed period and its rate match the e-certificate system.
5. Select a template and period, then confirm Sator Tracking displays the final amount and currency returned by the API without recalculating them.
6. Open the IremboPay widget and complete a sandbox payment.
7. Check the payment reference. It may return 201 while pending, followed by 200 with the certificate number.
8. Download the PDF using the certificate number and verify the vehicle, price, issue date, and expiry date.
9. Repeat the request with the same requestId and confirm that a second certificate is not created.