Library Usage — Account

Account APIs retrieve subscriber information and validate account status. They are shared across all product types (Collection, Disbursements, Remittance) — pass the appropriate productType and productSubscriptionKey for the product you are using.

Environment and cross-cutting headers are automatic. You set the target environment once during SDK setup — ApiConfig.environment, which is sourced from MOMO_ENVIRONMENT in local.properties. On every request the SDK's EnvironmentInterceptor adds the required X-Target-Environment header, so environment is never a per-call parameter. Authentication headers (Authorization) are attached the same way by the SDK's interceptors.

---

Get Account Balance

Returns the current balance of the product wallet.

defaultRepository.getAccountBalance(
    productType = ProductTypes.COLLECTION.productType,
    apiVersion = "v1_0",
    currency = null,           // null returns balance in the account's default currency
    productSubscriptionKey = collectionPrimaryKey
).collect { result ->
    when (result) {
        is NetworkResult.Success -> {
            val balance = result.response
            // balance.availableBalance, balance.currency
        }
        is NetworkResult.Error   -> { /* failed */ }
        is NetworkResult.Loading -> { /* in progress */ }
    }
}

Pass a specific ISO-4217 currency code to currency to retrieve the balance in that currency:

defaultRepository.getAccountBalance(
    productType = ProductTypes.REMITTANCE.productType,
    apiVersion = "v1_0",
    currency = "EUR",
    productSubscriptionKey = remittancePrimaryKey
).collect { result -> /* ... */ }

Parameter	Type	Description
productType	String	Product type string
apiVersion	String	API version, e.g. "v1_0"
currency	String?	ISO-4217 currency code, or null for the default currency
productSubscriptionKey	String	Primary subscription key for the product

---

Get Basic User Info

Retrieves the name and other non-sensitive profile fields for a given account holder without requiring the subscriber's consent.

defaultRepository.getBasicUserInfo(
    productType = ProductTypes.COLLECTION.productType,
    apiVersion = "v1_0",
    accountHolder = "256770000000",   // MSISDN
    productSubscriptionKey = collectionPrimaryKey
).collect { result ->
    when (result) {
        is NetworkResult.Success -> {
            val info = result.response
            // info.name, info.givenName, info.familyName, etc.
        }
        is NetworkResult.Error   -> { /* failed */ }
        is NetworkResult.Loading -> { /* in progress */ }
    }
}

Parameter	Type	Description
productType	String	Product type string
apiVersion	String	API version
accountHolder	String	MSISDN of the account holder
productSubscriptionKey	String	Primary subscription key

This endpoint is available for every product. For Remittance it resolves to /remittance/{apiVersion}/accountholder/msisdn/{accountHolder}/basicuserinfo — call it with productType = ProductTypes.REMITTANCE.productType and the account holder MSISDN.

BasicUserInfo response fields

BasicUserInfo is a superset covering both response shapes: the OIDC-style payload returned by Collection/Disbursements (includes sub, name, gender, updatedAt) and the Remittance KYC payload (givenName, familyName, birthDate, locale, status), which omits sub/name. Every server-supplied field is therefore nullable, so a payload that omits any of them deserializes without failure.

Field	Type	Description
sub	String?	Subject identifier for the user. Absent in the Remittance KYC response
name	String?	Full name. Absent in the Remittance KYC response
givenName	String?	Given name(s) / first name(s) (given_name)
familyName	String?	Surname(s) / last name(s) (family_name)
birthDate	String?	Account holder birth date (birthdate)
locale	String?	BCP47 [RFC5646] language tag, e.g. en-US or en_US
gender	String?	Gender
status	String?	Account holder status (returned by the Remittance KYC response)
updatedAt	Int?	Last-updated timestamp as a Unix epoch integer in seconds (updated_at)
displayUpdatedAt	String	Human-readable form of updatedAt; computed locally (@Transient) — never part of the payload

---

Get User Info With Consent

Retrieves full profile information for the authenticated subscriber. This is an OAuth2 consent resource endpoint (/{productType}/oauth2/{apiVersion}/userinfo): it requires a valid OAuth2 consent token (the subscriber must have approved via the CIBA flow). The SDK attaches that consent token automatically — see Authentication for how the consent token is provisioned.

defaultRepository.getUserInfoWithConsent(
    productType = ProductTypes.REMITTANCE.productType,
    apiVersion = "v1_0",
    productSubscriptionKey = remittancePrimaryKey
).collect { result ->
    when (result) {
        is NetworkResult.Success -> {
            val info = result.response
            // info.name, info.email, info.phonenumber, info.address?.country, info.creditScore, ...
        }
        is NetworkResult.Error   -> { /* failed */ }
        is NetworkResult.Loading -> { /* in progress */ }
    }
}

Parameter	Type	Description
productType	String	Product type string. Use the product whose subscription key you have provisioned (e.g. ProductTypes.REMITTANCE.productType)
apiVersion	String	API version
productSubscriptionKey	String	Primary subscription key

UserInfoWithConsent response fields

Only sub and name are always present; every other field is optional (nullable) and is simply omitted when the API does not return it.

Field	Type	Description
sub	String	Subject identifier for the user
name	String	Full name
givenName / familyName / middleName	String?	Name parts
birthDate	String?	Date of birth
gender	String?	Gender
locale	String?	Locale, e.g. sv_SE
email	String?	Email address
emailVerified	Boolean?	Whether the email is verified
phonenumber	String?	Phone number (phone_number)
phoneNumberVerified	Boolean?	Whether the phone number is verified
address	Address?	Nested address object (formatted, streetAddress, postalCode, locality, region, country)
creditScore	Int?	Credit score
active	Boolean?	Whether the account is active
countryOfBirth / regionOfBirth / cityOfBirth	String?	Birthplace
occupation / employerName	String?	Employment details
identificationType / identificationValue	String?	Identification document type and number

---

Validate Account Holder Status

Checks whether a given account holder is registered and active on the MTN MoMo platform.

defaultRepository.validateAccountHolderStatus(
    productType = ProductTypes.COLLECTION.productType,
    apiVersion = "v1_0",
    party = Party(partyIdType = PartyTypes.MSISDN, partyId = "256770000000"),
    productSubscriptionKey = collectionPrimaryKey
).collect { result ->
    when (result) {
        is NetworkResult.Success -> { /* account is active */ }
        is NetworkResult.Error   -> { /* account not found or inactive */ }
        is NetworkResult.Loading -> { /* in progress */ }
    }
}

Parameter	Type	Description
productType	String	Product type string
apiVersion	String	API version
party	Party	Account identifier; partyIdType is a PartyTypes enum (e.g. MSISDN)
productSubscriptionKey	String	Primary subscription key