Purpose of this page. This is the partner API reference an integrator must read, test, and map when building the Renew NovaSat TV Subscription service on IremboHub. It describes every endpoint, its request/response payloads, the field-level contract, and the full error catalogue. There is no live NovaSat host for this certification — you build a mock of this API yourself (see §1.3) and test every endpoint against your mock before you begin mapping.
NovaSat TV is a decoder/smartcard pay-TV operator. Subscriptions are monthly and post-paid, so a subscriber renews every month — either with the same offer or by switching to a different offer (formula × options × duration). All amounts are settled through the partner (IremboHub) and reconciled by NovaSat via a daily settlement report.
The mobile-payment API lets a partner (here, IremboHub / IREMBO) renew a NovaSat subscriber's TV subscription on their behalf. There are three actions:
| Action | typeOperation |
Notes |
|---|---|---|
| Re-subscription with the same offer | 1 |
Most common. Subscriber pays the same formula for the coming month(s). |
| Regularization | 2 |
Rare / optional. Only on markets with debit subscribers. |
| Re-subscription with a different offer | 3 |
Subscriber switches formula / options / duration. |
A subscriber is identified by a single number:
| Name | Format | Comment |
|---|---|---|
| Decoder / card number | Exactly 14 digits | One card number maps to one subscription. Printed on the decoder's smartcard. |
application/json{{MpaymentRestUrl}} — a mock you build. There is no live NovaSat host. Stand up a mock of this API (a Postman mock server, or any mock/stub service) that returns the payloads documented on this page, then set {{MpaymentRestUrl}} to your mock's base URL. Every path below is relative to that placeholder — never hard-code a host.RWF).146).tokenId is an identifier generated by NovaSat in the CheckAccount response. It is mandatory on every follow-up call (getRenewalOffers, verifyRenewalOffers, registerStandardRenewal, registerAutomaticRenewal) and is what NovaSat uses to correlate the whole renewal flow. Always carry the exact tokenId returned by CheckAccount through the rest of the flow.
A. Same offer (typeOperation = 1)
CheckAccount → (show amount, subscriber confirms) → registerAutomaticRenewal
B. Different offer (typeOperation = 3)
CheckAccount → getRenewalOffers → verifyRenewalOffers → registerStandardRenewal
CheckAccount validates the card and returns identity + token (+ the current offer for flow A, or the offers catalogue for flow B).getRenewalOffers returns the full priced catalogue (formulas, durations, options).verifyRenewalOffers validates the chosen formula/options/duration triplet and returns the amount to pay.registerStandardRenewal / registerAutomaticRenewal commit the payment and activate the renewal.There is no live NovaSat endpoint. Part of this certification is standing up your own mock of this API:
returnCode = "0") and at least one error case (returnCode = "1", e.g. 0013 unknown smartcard or 0141 transaction already done).{{MpaymentRestUrl}} (in Postman and in your IremboHub endpoint config) to your mock's base URL.Your mock is what your IremboHub fetch/push endpoints call. A faithful mock is graded (see the SRD rubric).
All endpoints are POST with a JSON body, except healthCheck (GET). Path = {{MpaymentRestUrl}}/<method>.
| # | Method | Path | Used in |
|---|---|---|---|
| 2.1 | checkAccount |
POST {{MpaymentRestUrl}}/checkAccount |
Both flows |
| 2.2 | getRenewalOffers |
POST {{MpaymentRestUrl}}/getRenewalOffers |
Different-offer flow |
| 2.3 | verifyRenewalOffers |
POST {{MpaymentRestUrl}}/verifyRenewalOffers |
Different-offer flow |
| 2.4 | registerStandardRenewal |
POST {{MpaymentRestUrl}}/registerStandardRenewal |
Different-offer flow |
| 2.5 | registerAutomaticRenewal |
POST {{MpaymentRestUrl}}/registerAutomaticRenewal |
Same-offer flow |
| 2.6 | healthCheck |
GET {{MpaymentRestUrl}}/healthCheck |
Availability probe |
Description. Checks whether the decoder/card number exists. If it does, returns the subscriber's identity, the tokenId, and (depending on typeOperation) either the current offer + amount (same-offer flow) or the catalogue of offers available for renewal (different-offer flow).
Input
| Field | Type | Required | Comment |
|---|---|---|---|
numCard |
String | Yes | Decoder/card number — exactly 14 digits. |
accountRef |
String | No | Transaction ID on the partner platform. |
currency |
String | Yes | ISO 4217 currency code. |
operatorName |
String | Yes | Partner name — fixed value provided by NovaSat (IREMBO). |
country |
String | Yes | NovaSat country code of the subscriber. |
typeOperation |
String | Yes | 1 = renew same offer · 2 = regularization · 3 = renew new offer. |
Output
| Field | Description |
|---|---|
returnCode |
0 = no error, 1 = error. |
errorCode |
Error code when returnCode = 1. |
errorLabel |
Error description when returnCode = 1. |
subscriberFound |
1 if the card exists. |
idBase |
Database ID (carry to later calls). |
numSubscriber |
Subscriber number. |
numContract |
Contract number. |
accountRef |
Echo of the partner reference. |
mainOffer |
Current main offer object {code,label,amount,currency} (same-offer flow). |
duration |
Duration object {code,label}. |
optionsList |
List of active options. |
amount |
Amount of the current subscription. |
currency |
ISO 4217 currency code. |
endDate |
End date of the current subscription. |
offersList |
Catalogue of offers available for renewal (different-offer flow). |
tokenId |
Unique token — carry to every follow-up call. |
Request example (typeOperation = 1)
{
"numCard": "40071500912345",
"accountRef": null,
"currency": "RWF",
"operatorName": "IREMBO",
"country": "146",
"typeOperation": 1,
"productId": null,
"etopupDistributorId": null
}
Response example (same-offer flow — subscriber found)
{
"returnCode": "0",
"errorCode": "",
"errorLabel": "",
"wsCallId": null,
"subscriberFound": "1",
"idBase": "NovaSatDB",
"numSubscriber": "13115795",
"numContract": "1",
"accountRef": null,
"mainOffer": {
"code": "STDD",
"label": "STARTER",
"amount": "",
"currency": ""
},
"duration": {
"code": "1",
"label": "1 month"
},
"optionsList": [],
"amount": "5000.0",
"currency": "RWF",
"endDate": "06/05/2026",
"offersList": [],
"tokenId": "a7c1f0e9b4d2478e9f3c5a1b8e2d6f04c9a71b35"
}
Response example (different-offer flow — offersList populated). See the offersList shape in getRenewalOffers: in the CheckAccount response for typeOperation = 3 the same list is returned but with empty amount/currency (prices arrive from getRenewalOffers).
The same-offer flow uses
checkAccount→registerAutomaticRenewal. The different-offer flow usescheckAccount→getRenewalOffers→verifyRenewalOffers→registerStandardRenewal. See §1.5.
Method: getRenewalOffers · Description. Returns the full catalogue of offers available for renewal, with durations and options and their prices.
Rules: validate type/length of all input; verify token status.
Input
| Field | Type | Required | Comment |
|---|---|---|---|
idBase |
String | Yes | Database ID (from CheckAccount). |
numSubscriber |
String | Yes | |
numContract |
String | Yes | |
accountRef |
String | Yes | Transaction ID on the partner platform. |
operatorName |
String | Yes | Fixed value provided by NovaSat (IREMBO). |
country |
String | Yes | Country code (ISO 3166 numeric). |
tokenId |
String | Yes | Token from CheckAccount. |
Output
| Field | Description |
|---|---|
returnCode / errorCode / errorLabel |
Standard return triple. |
idBase, numSubscriber, numContract, accountRef |
Echoed identity. |
offersList |
Commercial offers. Each element: code, label, amount, currency, a durationsList (each {code,label}), and an optionsList (each {code,label,amount,currency}). |
tokenId |
Same token echoed back. |
Request example
{
"idBase": "NovaSatDB",
"numSubscriber": "8949890",
"numContract": "1",
"accountRef": null,
"operatorName": "IREMBO",
"country": "146",
"tokenId": "a7c1f0e9b4d2478e9f3c5a1b8e2d6f04c9a71b35"
}
Response example (priced catalogue)
{
"returnCode": "0",
"errorCode": "",
"errorLabel": "",
"wsCallId": null,
"idBase": "NovaSatDB",
"numSubscriber": "8949890",
"numContract": "1",
"accountRef": null,
"offersList": [
{
"code": "NS1ST|STDD",
"label": "STARTER",
"amount": "5000.0",
"currency": "RWF",
"durationsList": [
{ "code": "1", "label": "1 month" },
{ "code": "3", "label": "3 months" }
],
"optionsList": [
{ "code": "KIDS", "label": "KIDS PACK", "amount": "3000.0", "currency": "RWF" }
]
},
{
"code": "NS2FM|FMDD",
"label": "FAMILY",
"amount": "10000.0",
"currency": "RWF",
"durationsList": [
{ "code": "1", "label": "1 month" },
{ "code": "3", "label": "3 months" }
],
"optionsList": [
{ "code": "KIDS", "label": "KIDS PACK", "amount": "3000.0", "currency": "RWF" },
{ "code": "SPRT", "label": "SPORTS EXTRA", "amount": "7000.0", "currency": "RWF" }
]
},
{
"code": "NS3PR|PRDD",
"label": "PREMIUM",
"amount": "16000.0",
"currency": "RWF",
"durationsList": [
{ "code": "1", "label": "1 month" },
{ "code": "3", "label": "3 months" },
{ "code": "6", "label": "6 months" }
],
"optionsList": [
{ "code": "SPRT", "label": "SPORTS EXTRA", "amount": "7000.0", "currency": "RWF" },
{ "code": "PVR", "label": "PVR", "amount": "2000.0", "currency": "RWF" }
]
},
{
"code": "NS4CP|CPDD",
"label": "COMPLETE",
"amount": "25000.0",
"currency": "RWF",
"durationsList": [
{ "code": "1", "label": "1 month" },
{ "code": "3", "label": "3 months" },
{ "code": "6", "label": "6 months" },
{ "code": "12", "label": "12 months" }
],
"optionsList": [
{ "code": "SPRT", "label": "SPORTS EXTRA", "amount": "7000.0", "currency": "RWF" },
{ "code": "KIDS", "label": "KIDS PACK", "amount": "3000.0", "currency": "RWF" },
{ "code": "PVR", "label": "PVR", "amount": "2000.0", "currency": "RWF" }
]
}
],
"tokenId": "a7c1f0e9b4d2478e9f3c5a1b8e2d6f04c9a71b35"
}
Method: verifyRenewalOffers · Description. Verifies that the selected options are consistent with the chosen main offer and returns the amount to be paid (promotions applied).
Rules: validate type/length of all input; verify token status; validate the selected offers.
Input
| Field | Type | Required | Comment |
|---|---|---|---|
idBase |
String | Yes | |
numSubscriber |
String | Yes | |
numContract |
String | Yes | |
accountRef |
String | Yes | Transaction ID on the partner platform. |
operatorName |
String | Yes | IREMBO. |
country |
String | Yes | |
currency |
String | Yes | ISO 4217. |
mainOffer |
String | Yes | Chosen formula offer code (e.g. NS2FM|FMDD). |
duration |
String | Yes | Chosen duration code. |
optionsList |
List | Optional | List of chosen option codes. |
tokenId |
String | Yes | Token from CheckAccount. |
Output. Standard return triple, echoed identity, mainOffer object, duration object, optionsList, amount (to be paid), currency, endDate, tokenId.
Request example (with options)
{
"idBase": "NovaSatDB",
"numSubscriber": "13115795",
"numContract": "1",
"accountRef": null,
"operatorName": "IREMBO",
"country": "146",
"currency": "RWF",
"mainOffer": "NS2FM|FMDD",
"duration": "1",
"optionsList": ["SPRT", "KIDS"],
"tokenId": "a7c1f0e9b4d2478e9f3c5a1b8e2d6f04c9a71b35"
}
Response example (with options)
{
"returnCode": "0",
"errorCode": "",
"errorLabel": "",
"wsCallId": null,
"idBase": "NovaSatDB",
"numSubscriber": "13115795",
"numContract": "1",
"accountRef": null,
"mainOffer": { "code": "FMDD", "label": "FAMILY", "amount": null, "currency": null },
"duration": { "code": "1", "label": "1 month" },
"optionsList": [
{ "code": "SPRT", "label": "SPORTS EXTRA", "amount": null, "currency": null },
{ "code": "KIDS", "label": "KIDS PACK", "amount": null, "currency": null }
],
"amount": "20000.0",
"currency": "RWF",
"endDate": "06/06/2026",
"tokenId": "a7c1f0e9b4d2478e9f3c5a1b8e2d6f04c9a71b35"
}
Request/response example (without options): send "optionsList": []; response amount reflects the base formula only (e.g. "10000.0" for FAMILY, 1 month).
Method: registerStandardRenewal · Description. Registers a standard (different-offer) renewal and the payment.
Rules: validate type/length of all input; the amount paid must be strictly positive; token mandatory.
Input
| Field | Type | Required | Comment |
|---|---|---|---|
idBase |
String | Yes | |
numSubscriber |
String | Yes | |
numContract |
String | Yes | |
accountRef |
String | Yes | Transaction ID on the partner platform. |
amount |
String | Yes | Amount paid (must equal the verifyRenewalOffers amount). |
currency |
String | Yes | ISO 4217. |
operatorName |
String | Yes | IREMBO. |
country |
String | Yes | |
mainOffer |
String | Yes | Formula code for the renewal. |
duration |
String | Yes | Duration code. |
optionsList |
List | Optional | Option codes. |
tokenId |
String | Yes | Token from CheckAccount. |
etopupTransactionId |
String | No | Unique transaction ID from the partner platform. |
etopupDistributorId |
String | No | Point-of-sale ID (used by BI). |
Output. Standard return triple, echoed identity, amount, currency, transactionId (generated by NovaSat), mainOffer object, duration object, optionsList, endDate, etopupTransactionId.
Request example (with options)
{
"idBase": "NovaSatDB",
"numSubscriber": "13115795",
"numContract": "1",
"accountRef": null,
"amount": "20000.0",
"currency": "RWF",
"operatorName": "IREMBO",
"country": "146",
"mainOffer": "NS2FM|FMDD",
"duration": "1",
"optionsList": ["SPRT", "KIDS"],
"tokenId": "a7c1f0e9b4d2478e9f3c5a1b8e2d6f04c9a71b35",
"productId": null,
"etopupTransactionId": null,
"etopupDistributorId": null
}
Response example (success)
{
"returnCode": "0",
"errorCode": "",
"errorLabel": "",
"wsCallId": null,
"idBase": "NovaSatDB",
"numSubscriber": "13115795",
"numContract": "1",
"accountRef": null,
"amount": "20000.0",
"currency": "RWF",
"transactionId": "1699936228",
"mainOffer": { "code": "FMDD", "label": "FAMILY", "amount": null, "currency": null },
"duration": { "code": "1", "label": "1 month" },
"optionsList": [
{ "code": "SPRT", "label": "SPORTS EXTRA", "amount": null, "currency": null },
{ "code": "KIDS", "label": "KIDS PACK", "amount": null, "currency": null }
],
"endDate": "06/06/2026",
"etopupTransactionId": null
}
Response example (transaction already done)
{
"returnCode": "1",
"errorCode": "0141",
"errorLabel": "Transaction already done",
"wsCallId": null,
"idBase": "",
"numSubscriber": "",
"numContract": "",
"accountRef": "",
"amount": "",
"currency": "",
"transactionId": "",
"mainOffer": { "code": "", "label": "", "amount": "", "currency": "" },
"duration": { "code": "", "label": "" },
"optionsList": [],
"endDate": "",
"etopupTransactionId": ""
}
Method: registerAutomaticRenewal · Description. Registers a same-offer renewal and the payment. Used in the same-offer flow (§1.5-A).
Rules: validate type/length of all input; amount strictly positive; token mandatory.
Input
| Field | Type | Required | Comment |
|---|---|---|---|
idBase |
String | Yes | |
numSubscriber |
String | Yes | |
numContract |
String | Yes | |
accountRef |
String | Yes | Transaction ID on the partner platform. |
amount |
String | Yes | Amount paid by the subscriber. |
currency |
String | Yes | ISO 4217. |
operatorName |
String | Yes | IREMBO. |
country |
String | Yes | |
tokenId |
String | Yes | Token from CheckAccount. |
etopupTransactionId |
String | No | Unique transaction ID from the partner platform. |
etopupDistributorId |
String | No | Distributor ID (used by BI). |
Output. Standard return triple, echoed identity, amount, currency, transactionId, mainOffer object, duration object, optionsList, endDate, etopupTransactionId.
Request example
{
"idBase": "NovaSatDB",
"numSubscriber": "13115795",
"numContract": "1",
"accountRef": null,
"amount": "5000",
"currency": "RWF",
"operatorName": "IREMBO",
"country": "146",
"tokenId": "a7c1f0e9b4d2478e9f3c5a1b8e2d6f04c9a71b35",
"etopupTransactionId": null,
"etopupDistributorId": null
}
Response example (success)
{
"returnCode": "0",
"errorCode": "",
"errorLabel": "",
"wsCallId": null,
"idBase": "NovaSatDB",
"numSubscriber": "13115795",
"numContract": "1",
"accountRef": null,
"amount": "5000",
"currency": "RWF",
"transactionId": "1699936189",
"mainOffer": { "code": "STDD", "label": "STARTER", "amount": "", "currency": "" },
"duration": { "code": "1", "label": "1 month" },
"optionsList": [],
"endDate": "06/05/2026",
"etopupTransactionId": null
}
Method: healthCheck (GET) · Description. Probes availability of the NovaSat application.
GET {{MpaymentRestUrl}}/healthCheckOKKOEvery method returns returnCode (0/1), plus errorCode and errorLabel when returnCode = 1.
| Code | Description |
|---|---|
0001 |
The field {0} is required |
0002 |
Numeric value expected for the field |
0003 |
Invalid email |
0004 |
Format DD/MM/YYYY expected for the field |
0005 |
Format MM/YYYY expected for the field |
0006 |
Incorrect value for the field |
0007 |
Incorrect length for the field {0} ({1} characters min) |
0008 |
Incorrect length for the field {0} ({1} characters max) |
0009 |
Unknown database |
0108 |
Token id is mandatory for this web service |
0110 |
Unknown computation mode |
0111 |
Error in data computation |
| Code | Field | Description |
|---|---|---|
0013 |
numCard | Unknown smartcard |
0100 |
numSubscriber | Unknown subscriber |
0101 |
numContract | Unknown contract |
0102 |
— | Operation not allowed for this subscriber |
0103 |
— | Nothing to pay |
0104 |
currency | Unknown currency |
0106 |
— | Amount incorrect for this operation |
0130 |
— | Renewal not allowed: |
0133 |
— | This operator is not allowed to work in this country |
0135 |
operatorName | Unknown operator |
0136 |
country | Unknown country code |
0140 |
— | Transaction in progress |
0141 |
— | Transaction already done |
0142 |
— | Transaction cancelled |
0143 |
— | Transaction not allowed |
0150 |
— | This distributor is not allowed to work with this currency |
0151 |
— | Exchange rate is missing |
| Code | Description |
|---|---|
9997 |
Technical problem |
9998 |
SQL error |
9999 |
Unexpected error |
Each day the partner deposits a CSV of the previous day's successful transactions to a NovaSat SFTP endpoint, for reconciliation.
SETTLE_<OPERATOR>_<COUNTRY>_YYYYMMDD.csv;| # | Field | Description | Format |
|---|---|---|---|
| 1 | TRANSACTION_OPERATEUR |
Operator transaction ID | VARCHAR(30) |
| 2 | TRANSACTION_NOVASAT |
NovaSat transaction ID | NUMBER(10) |
| 3 | NO_TELEPHONE |
Phone number (with country code) | NUMBER |
| 4 | IDBASE |
Fixed value NovaSatDB |
VARCHAR(10) |
| 5 | NO_ABONNE |
Subscriber number | NUMBER(8) |
| 6 | CONTRAT |
Contract number | NUMBER(2) |
| 7 | NO_CARTE |
Card number | NUMBER(14) |
| 8 | DATE_TRANSACTION |
Date/time of the transaction | dd/mm/yyyy hh:mm:ss |
| 9 | MONTANT |
Amount | NUMBER(6,2) |
| 10 | DEVISE |
Currency | VARCHAR(10) |
| 11 | OPERATION |
1 = same offer · 2 = regularization · 3 = change offer | NUMBER(1) |
| 12 | PAYS |
Country code | NUMBER(3) |
| 13 | OPERATEUR |
Operator name | VARCHAR(30) |
Only one currency is accepted per country.
| Country | Currency (ISO 4217) | ISO 3166 | NovaSat country code | Amount format |
|---|---|---|---|---|
| Rwanda | RWF | RW | 146 | 0.0 |
| Burundi | BIF | BI | 108 | 0.0 |
| DR Congo | CDF / USD | CD | 161 | 0.0 / 0.00 |
| Kenya | KES | KE | — | 0.00 |
| Tanzania | TZS | TZ | — | 0.00 |
| Uganda | UGX | UG | — | 0.0 |
For the certification build you will use Rwanda (
146,RWF).
| Formula code | Label | Base price / month (RWF) | Durations | Options |
|---|---|---|---|---|
NS1ST\|STDD |
STARTER | 5,000 | 1, 3 | KIDS PACK |
NS2FM\|FMDD |
FAMILY | 10,000 | 1, 3 | KIDS PACK, SPORTS EXTRA |
NS3PR\|PRDD |
PREMIUM | 16,000 | 1, 3, 6 | SPORTS EXTRA, PVR |
NS4CP\|CPDD |
COMPLETE | 25,000 | 1, 3, 6, 12 | SPORTS EXTRA, KIDS PACK, PVR |
Option codes: SPRT = SPORTS EXTRA (7,000) · KIDS = KIDS PACK (3,000) · PVR = PVR (2,000). Prices are indicative sandbox values; always take the authoritative price from getRenewalOffers / verifyRenewalOffers.
This is sandbox documentation for the IremboHub Service-Manager certification. All decoder numbers, tokens, subscriber IDs and transaction IDs are fictitious. Never submit real credentials or personal data when testing.