Library Usage — Collection

Collection APIs let you request payments from customers, check transaction status, send delivery notifications, manage invoices, and handle pre-approvals.

All flows require a valid Bearer access token and OAuth2 token stored in CredentialStorage. The SDK's TokenAuthenticator refreshes expired tokens automatically on 401 responses.

---

Request to Pay

Initiates a debit request against a customer's Mobile Money account.

val transactionUuid = UUID.randomUUID().toString()

val result = defaultRepository.requestToPay(
    accessToken = credentialStorage.getAccessToken(),
    momoTransaction = MomoTransaction(
        amount = "500",
        currency = "EUR",
        externalId = UUID.randomUUID().toString(),
        payer = AccountHolder(partyIdType = "MSISDN", partyId = "256770000000"),
        payerMessage = "Payment for order #42",
        payeeNote = "Order #42"
    ),
    apiVersion = "v1_0",
    productSubscriptionKey = collectionPrimaryKey,
    uuid = transactionUuid
)
// result is a Retrofit Response<Unit>; check result.isSuccessful

Parameter	Type	Description
accessToken	String	Bearer access token from CredentialStorage
momoTransaction	MomoTransaction	Payment details (amount, currency, payer, messages)
apiVersion	String	API version, e.g. "v1_0"
productSubscriptionKey	String	Collection primary subscription key
uuid	String	Unique reference ID — save this to poll for status

---

Request to Pay — Transaction Status

Polls the status of a previously initiated requestToPay call.

val response = defaultRepository.requestToPayTransactionStatus(
    referenceId = transactionUuid,
    apiVersion = "v1_0",
    productSubscriptionKey = collectionPrimaryKey,
    accessToken = credentialStorage.getAccessToken()
)

Parameter	Type	Description
referenceId	String	UUID used when calling requestToPay
apiVersion	String	API version, e.g. "v1_0"
productSubscriptionKey	String	Collection primary subscription key
accessToken	String	Bearer access token

---

Request to Withdraw

Initiates a credit request to a customer's Mobile Money account.

val transactionUuid = UUID.randomUUID().toString()

val result = defaultRepository.requestToWithdraw(
    accessToken = credentialStorage.getAccessToken(),
    momoTransaction = MomoTransaction(
        amount = "200",
        currency = "EUR",
        externalId = UUID.randomUUID().toString(),
        payee = AccountHolder(partyIdType = "MSISDN", partyId = "256770000000"),
        payerMessage = "Withdrawal request",
        payeeNote = "Withdrawal"
    ),
    apiVersion = "v2_0",
    productSubscriptionKey = collectionPrimaryKey,
    uuid = transactionUuid
)

Parameter	Type	Description
accessToken	String	Bearer access token
momoTransaction	MomoTransaction	Transaction details
apiVersion	String	API version, e.g. "v2_0"
productSubscriptionKey	String	Collection primary subscription key
uuid	String	Unique reference ID

---

Request to Withdraw — Transaction Status

val response = defaultRepository.requestToWithdrawTransactionStatus(
    referenceId = transactionUuid,
    apiVersion = "v2_0",
    productSubscriptionKey = collectionPrimaryKey,
    accessToken = credentialStorage.getAccessToken()
)

Parameter	Type	Description
referenceId	String	UUID used when calling requestToWithdraw
apiVersion	String	API version, e.g. "v2_0"
productSubscriptionKey	String	Collection primary subscription key
accessToken	String	Bearer access token

---

Request to Pay Delivery Notification

Sends a delivery notification to the payer after a successful requestToPay.

defaultRepository.requestToPayDeliveryNotification(
    apiVersion = "v1_0",
    referenceId = transactionUuid,
    momoNotification = MomoNotification(notificationMessage = "Your payment was received."),
    productSubscriptionKey = collectionPrimaryKey,
    environment = "sandbox"
).collect { result ->
    when (result) {
        is NetworkResult.Success -> { /* notification sent */ }
        is NetworkResult.Error   -> { /* failed */ }
        is NetworkResult.Loading -> { /* in progress */ }
    }
}

Parameter	Type	Description
apiVersion	String	API version, e.g. "v1_0"
referenceId	String	UUID of the original requestToPay
momoNotification	MomoNotification	Notification message body
productSubscriptionKey	String	Collection primary subscription key
environment	String	"sandbox" or "production"

---

Create Invoice

Creates a payment invoice that a customer can pay via the USSD menu or MoMo app.

defaultRepository.createInvoice(
    apiVersion = "v1_0",
    invoice = Invoice(
        externalId = UUID.randomUUID().toString(),
        amount = "1000",
        currency = "EUR",
        validityDuration = "3600",
        intendedPayer = AccountHolder(partyIdType = "MSISDN", partyId = "256770000000"),
        payee = AccountHolder(partyIdType = "MSISDN", partyId = "256770000001"),
        description = "Invoice for service #99"
    ),
    uuid = UUID.randomUUID().toString(),
    productSubscriptionKey = collectionPrimaryKey,
    environment = "sandbox"
).collect { result ->
    when (result) {
        is NetworkResult.Success -> { /* invoice created */ }
        is NetworkResult.Error   -> { /* failed */ }
        is NetworkResult.Loading -> { /* in progress */ }
    }
}

Parameter	Type	Description
apiVersion	String	API version, e.g. "v1_0"
invoice	Invoice	Invoice details including amount, currency, payer, and payee
uuid	String	Unique reference ID for the invoice
productSubscriptionKey	String	Collection primary subscription key
environment	String	"sandbox" or "production"

---

Get Invoice Status

Retrieves the current status of an invoice.

defaultRepository.getInvoiceStatus(
    apiVersion = "v1_0",
    referenceId = invoiceUuid,
    productSubscriptionKey = collectionPrimaryKey,
    environment = "sandbox"
).collect { result ->
    when (result) {
        is NetworkResult.Success -> { /* parse result.response */ }
        is NetworkResult.Error   -> { /* failed */ }
        is NetworkResult.Loading -> { /* in progress */ }
    }
}

Parameter	Type	Description
apiVersion	String	API version
referenceId	String	UUID used when calling createInvoice
productSubscriptionKey	String	Collection primary subscription key
environment	String	"sandbox" or "production"

---

Cancel Invoice

Cancels an active invoice.

defaultRepository.cancelInvoice(
    apiVersion = "v1_0",
    referenceId = invoiceUuid,
    productSubscriptionKey = collectionPrimaryKey,
    environment = "sandbox"
).collect { result ->
    when (result) {
        is NetworkResult.Success -> { /* invoice cancelled */ }
        is NetworkResult.Error   -> { /* failed */ }
        is NetworkResult.Loading -> { /* in progress */ }
    }
}

Parameter	Type	Description
apiVersion	String	API version
referenceId	String	UUID of the invoice to cancel
productSubscriptionKey	String	Collection primary subscription key
environment	String	"sandbox" or "production"

---

Create Pre-Approval

Creates a pre-approval that allows future debits without further subscriber interaction.

defaultRepository.createPreApproval(
    apiVersion = "v1_0",
    preApproval = PreApproval(
        payer = AccountHolder(partyIdType = "MSISDN", partyId = "256770000000"),
        payerCurrency = "EUR",
        payerMessage = "Authorize monthly subscription",
        validityTime = 3600
    ),
    uuid = UUID.randomUUID().toString(),
    productSubscriptionKey = collectionPrimaryKey,
    environment = "sandbox"
).collect { result ->
    when (result) {
        is NetworkResult.Success -> { /* pre-approval created */ }
        is NetworkResult.Error   -> { /* failed */ }
        is NetworkResult.Loading -> { /* in progress */ }
    }
}

Parameter	Type	Description
apiVersion	String	API version
preApproval	PreApproval	Payer details, currency, message, and validity duration in seconds
uuid	String	Unique reference ID
productSubscriptionKey	String	Collection primary subscription key
environment	String	"sandbox" or "production"

---

Get Pre-Approval Status

Checks the status of a pre-approval.

defaultRepository.getPreApprovalStatus(
    apiVersion = "v1_0",
    referenceId = preApprovalUuid,
    productSubscriptionKey = collectionPrimaryKey,
    environment = "sandbox"
).collect { result -> /* ... */ }

Parameter	Type	Description
apiVersion	String	API version
referenceId	String	UUID used when calling createPreApproval
productSubscriptionKey	String	Collection primary subscription key
environment	String	"sandbox" or "production"

---

Cancel Pre-Approval

Cancels an active pre-approval.

defaultRepository.cancelPreApproval(
    apiVersion = "v1_0",
    referenceId = preApprovalUuid,
    productSubscriptionKey = collectionPrimaryKey,
    environment = "sandbox"
).collect { result -> /* ... */ }

Parameter	Type	Description
apiVersion	String	API version
referenceId	String	UUID of the pre-approval to cancel
productSubscriptionKey	String	Collection primary subscription key
environment	String	"sandbox" or "production"