Services, pays et providers

Avant de lancer un paiement, votre backend doit connaitre trois choses:

le pays actif;
le service de paiement a utiliser;
le statut operationnel du provider.

Les pays sont identifies en ISO alpha-3. Utilisez par exemple CMR, pas CM.

Les codes de services utilises dans les payloads de transaction suivent le format provider_country_code, par exemple mtn_cmr ou orange_cmr.

Verifier un numero mobile

Avant d’envoyer un wallet telephone dans une collection ou un disbursement, vous pouvez verifier le numero via la gateway publique:

POST https://api.mysoleas.com/phone-numbers/verify

Cette route utilise votre API key marchand SoleasPay et retourne le pays detecte, le type de numero, l’operateur mobile si disponible et le provider_wallet, c’est-a-dire le numero national sans indicatif international attendu par les providers.

curl -X POST "https://api.mysoleas.com/phone-numbers/verify" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "650020109",
    "country": "CMR"
  }'

{
  "valid": true,
  "country": {
    "alpha2": "CM",
    "alpha3": "CMR",
    "calling_code": "237"
  },
  "number": {
    "e164": "+237650020109",
    "international": "+237 6 50 02 01 09",
    "national": "650020109",
    "provider_wallet": "650020109"
  },
  "type": "MOBILE",
  "operator": "MTN Cameroon",
  "supported_country": true,
  "support_message": null
}

Formats acceptes pour un numero camerounais:

Entree	Pays requis	`provider_wallet`
`+237650020109`	Non	`650020109`
`00237650020109`	Non	`650020109`
`237650020109`	Oui	`650020109`
`650020109`	Oui	`650020109`

Envoyez toujours country pour les numeros sans prefixe international + ou 00. Mysoleas garde les pays en alpha-3 (CMR, CIV, SEN, etc.). L’alpha-2 peut apparaitre dans la reponse pour faciliter l’interoperabilite, mais il ne remplace pas le code alpha-3.

Voir la reference complete: Verifier un numero de telephone.

Lister les pays

curl "https://api.mysoleas.com/country/list?page=1&limit=100" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN"

Un pays utilisable doit avoir active: true.

{
  "id": 1,
  "code": "CMR",
  "name": "Cameroon",
  "active": true
}

Pays d’exercice principal

Le pays d’exercice principal est porte par la relation TenantCountry.isPrimary. Il sert de contexte par defaut pour router les paiements et calculer les frais lorsqu’aucun pays explicite fiable n’est fourni.

curl "https://api.mysoleas.com/country/primary" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN"

Pour le modifier, utilisez l’identifiant de la relation TenantCountry, pas seulement le code pays.

curl -X PATCH "https://api.mysoleas.com/country/tenant-countries/42/primary" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN"

Le changement est applique cote User Service de maniere transactionnelle: l’ancien pays primaire est desactive et le nouveau devient l’unique primaire du tenant. Si aucun pays primaire n’est configure sur un ancien compte, les flux de paiement conservent le fallback historique.

Lister les services

curl "https://api.mysoleas.com/service/list?country=CMR&currency=XAF" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN"

Un service de paiement retourne les capacites dont votre integration a besoin.

Champ	Role
`code`	Valeur a envoyer dans `provider` lors d’une transaction, par exemple `mtn_cmr`
`provider`	Provider technique qui execute l’operation
`country`	Pays du service
`currency`	Devise
`is_active`	Le service est disponible cote Mysoleas
`is_public`	Le service peut etre expose aux marchands
`is_need_otp`	L’execution demande `otp`
`is_can_collect`	Le service accepte les collections
`is_can_disburse`	Le service accepte les disbursements
`confirmation_method`	`MSISDN`, `LINK` ou `QRCODE`
`confirmation_helper`	Instruction affichee au payeur pour finaliser la confirmation, par exemple `Veuillez composer le #150*50# pour finaliser le paiement.`

Lister les frais

curl "https://api.mysoleas.com/pricing-rule/fees?country=CMR&service_code=mtn_cmr" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN"

La gateway retourne les frais du pays demande uniquement si votre token donne acces a ce pays. Sinon, l’API retourne 403 access_denied. Vous pouvez filtrer par service_code, ou separer le sens avec incoming_service_code et outgoing_service_code. Ajoutez operation et user_tier pour obtenir les frais d’un cas precis.

{
  "id": 12,
  "operation": "COLLECTION",
  "user_tier": 1,
  "fee_value": 1.5,
  "fee_type": "PERCENTAGE",
  "incoming_service": {
    "code": "mtn_cmr",
    "country": "CMR",
    "currency": "XAF"
  },
  "outgoing_service": null
}

Obtenir un devis de frais

Avant d’initialiser une transaction, votre backend peut demander le montant des frais calcule cote serveur.

curl -X POST "https://api.mysoleas.com/transactions/fees/quote" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": 1,
    "amount": 10000,
    "currency": "XAF"
  }'

Pour une application API directe, feeBearer vient de la configuration de l’application. Pour un plugin, envoyez feeBearer dans le payload ou la query string; le payload est prioritaire.

{
  "baseAmount": 10000,
  "feeAmount": 350,
  "payableAmount": 10350,
  "currency": "XAF",
  "feeBearer": "CUSTOMER",
  "countryCode": "CMR",
  "userTier": 5,
  "source": "APPLICATION_CONFIGURATION"
}

Les transactions stockent ensuite un snapshot immuable dans metadata.fees avec le montant, la devise, le porteur des frais, la source, le pays, le tier et la version de calcul.

Lister les providers

curl "https://api.mysoleas.com/provider/list?page=1&limit=100" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN"

Le statut d’un provider se lit dans is_active.

{
  "id": 1,
  "code": "mtn_cmr",
  "name": "MTN Cameroon",
  "is_active": true,
  "countries": ["CMR"],
  "updated_at": "2026-07-28 13:20:10"
}

Choisir correctement

Pour une collection:

Verifiez que le pays est actif.
Filtrez les services par country et currency.
Gardez les services avec is_active: true et is_can_collect: true.
Si is_need_otp vaut true, demandez l’OTP au client avant execute.
Envoyez service.code dans le champ provider.

Pour un disbursement:

Verifiez que le pays est actif.
Filtrez les services par country et currency.
Gardez les services avec is_active: true et is_can_disburse: true.
Verifiez votre solde avant de lancer de gros volumes.
Envoyez service.code dans le champ provider.

Provider inactif

Si is_active vaut false, masquez le moyen de paiement dans votre checkout. Si un provider devient indisponible apres la selection du client, affichez un message clair et proposez un autre service actif du meme pays.

Demarrer

Paiements

Catalogue

Services, pays et providers

Verifier un numero mobile

Lister les pays

Pays d’exercice principal

Lister les services

Lister les frais

Obtenir un devis de frais

Lister les providers

Choisir correctement

Provider inactif

​Verifier un numero mobile

​Lister les pays

​Pays d’exercice principal

​Lister les services

​Lister les frais

​Obtenir un devis de frais

​Lister les providers

​Choisir correctement

​Provider inactif

Verifier un numero mobile

Lister les pays

Pays d’exercice principal

Lister les services

Lister les frais

Obtenir un devis de frais

Lister les providers

Choisir correctement

Provider inactif