APIs Spec

API Specification document

Reference: API system Version: V1.1

Client: Standard
Date: June 16,
2022
 1
API Spec/VA june 16, 2023
 MXMobile APIs Spec

Version Date Summary of Auteur

Modifications
Initial 16/06/2022 Initial KARIM Echaima

Approbation
Project Manager Project Director Project Manager
Name KARIM Echaima ATIFI Kamal Eddine

FONCTION Project Manager Project Director

DATE

VISA

2
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

COPYRIGHT
This document is the property of M2M Group S.A. and may not be copied, reproduced or
transmitted to a third party without the prior written consent of M2M Group S.A.

Copyright by M2M Group S.A, 2012

All rights reserved worldwide.

- M2M Group is the sole owner of MX Payment ™ technology -

3
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

Summary
1. Introduction ........................................................................................................................................................ 5
2. List of functions ................................................................................................................................................. 5
2.1. Get List of Beneficiaries ................................................................................................................................ 6
2.2. List of beneficiaries and amount ................................................................................................................... 9
2.3. Profile management .................................................................................................................................... 10
2.4. Add beneficiary ........................................................................................................................................... 10
2.5. Update beneficiary ...................................................................................................................................... 11
2.6. Delete beneficiary ....................................................................................................................................... 11
2.7. Make transfer .............................................................................................................................................. 12
2.8. Generate statement by month or year ........................................................................................................ 12
2.9. Review transaction details .......................................................................................................................... 12
2.10. Client information ........................................................................................................................................ 13
2.11. Transaction history ...................................................................................................................................... 14
2.12. Clients balance............................................................................................................................................ 14
2.13. Mobile Transfer ........................................................................................................................................... 15
2.14. Add a blacklisted card ................................................................................................................................. 15
2.15. Remove a blacklisted card .......................................................................................................................... 16
2.16. Top up ......................................................................................................................................................... 16
2.17. Holder Information ...................................................................................................................................... 17
2.18. Historical bank transfer ............................................................................................................................... 18
2.19. E-Recharge by card .................................................................................................................................... 18

4
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

1. Introduction

The purpose of this document is to detail the different functions and flows exchanged in API solution.

2. List of functions

The table below describes the list of API functions and the associated management rules.

Functionalities Functions Description

Authentication /XA02V3 To access the application, user
must enter his phone number
and password
Unit card creation /CreateUnitCard For debit and prepaid card
creation
Get List of Beneficiaries /XX07 This function returns the list of
beneficiaries added
List of beneficiaries and amount /XXBVL This function returns the list of
beneficiaries and the Min and
MAX Rechargeable Amounts
Profile management /XC11 Allow the update of profile
information (phone number,
email, profile picture….)
Add beneficiary /XX02 This function allows you to add
beneficiaries
Update beneficiary /XX04 Allow the update of
beneficiaries information.
Phone num and client ID cannot
be updated.
Delete beneficiary /XX03 Allows you to delete a
beneficiary
Make a transfer /XTV01 Allows you to make a transfer

Generate statement by month /XC033 Allows you to generate

or year statements by month or year.
Review transaction details /XTH01V2 Allows reviewing transaction
details
Client information /XTH03V3 Allows reviewing of clients
information (balance,
transaction history, number of
notifications …)
Transaction history /XTH00 Allows reviewing the history of
transactions carried out by the
client during the last 30 days
and the detail of each
transaction.
Clients balance /XC10 Retrieve clients balance

Mobile Transfer /transfertMobile Allow the mobile transfer

Add a blacklisted card /XC00V2 This feature allows you to add a

card to the blacklist.
Remove a blacklisted card /XC13V2 This feature allows you to
unlock a card

5
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

Top up /XTG07 This feature allows the

customer to top up their own
card using another bank card.
Holder Information /XC12 Allows the review of holders
information
(Name,address,phone number
…)
Historical bank transfer /XTHV Consult the history of his
transfers.

E-Recharge by card /XTGCOF10

2.1. Authentication

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XA02V3

Request
Param. Value Size Mandatory/Optional Comment
login String Mondatory
password String Mondatory
deviceType String Mondatory
deviceVersion String Mondatory
deviceId String Mondatory
deviceName String Mondatory
appliVersion String Mondatory
save String Mondatory
playerId String Optional

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionnalData String Returned
codeError String Returned
photo String Returned
nom String Returned
prenom String Returned
lastconnection String Returned
idPorteur String Returned
tel String Returned
mail String Returned
id String Returned
etatCarte String Returned
rib String Returned
numCarte String Returned
Niveau String Returned
dateExpiration String Returned
CodeAgence String Returned
dateDebut String Returned
isPack String Returned

6
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

2.2. Unit card creation

Method URL
POST /mxplus/services/applicationMobileServiceV3/
CreateUnitCard

Request
Param. Value Size Mandatory/Optional Comment
Institution ID
institution_id string Mandatory assigned by
MXPAYMENT
Cardholder first
crt_first_name string Mandatory
name
Cardholder last
crt_last_name string Mandatory
name
Name to print on the
crt_emboss_name string Mandatory card
cmpl_npai string Mandatory Country code
enr_mail string Mandatory Cardholder Email
crt_code_post string Mandatory Postal code
Currency code : ISO
cpt_currency string Mandatory
NUM prédéfinie
ttl_adrs1 string Mandatory Cardholder Address
Cardholder Address
ttl_adrs2 string Mandatory
line 2
Cardholder Address
ttl_adrs3 string Optional
line 3
ID/ institution
consumer_id string Mandatory
customer
Cardholder phone
mobile_num string Mandatory
number
crt_code_product string Mandatory Card product code
02 = Courier
delivery_method string Mandatory 03 = SMS
99 = none
City code , if bank
state_cde String Optional
City = Customer City
RIB Client Example
837 780
0000000126543891
34
3 positions : Code
EDP 837
3 positions : City
RIB_CLIENT String Mandatory
code
7 positions :
calculated Algo
9 positions : Contract
number
2 positions : Control
Key
Title_client String Mandatory Mr, Ms, Mrs, Dr, Pr,

7
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

Ste, Et, ...

According to
Code_Agency String Mandatory MXPAYMENT
Parameters
C : CIN
Type_Papier String Mandatory P : Passport
L : Driving license
ID_Papier String Mandatory
mac_value String Optional Checksum value

Response
Param. Value Size Mandatory/Optional Comment
Institution ID
institution id string Returned assigned by
MXPAYMENT
ID/ Client's third
consumer_id string Returned party at the
institution
Card product
crt_code_product string Returned
code
Date_Expiry string Mandatory Expiry date
Customer
RIB_Client string Returned
account number
Card number
CARTE_TRONQUEE string Mandatory
truncated
error_msg String Mandatory Error Message
Error code
error_code String Mandatory according to the
error codes list
Check sum
mac_value string Optional value M2m
confirmation

mac_value parameter, is calculated using the "SHA1" function on all the other parameters in addition
to a key shared between the 2 entities.
Example a request signature: Idrequest + Contract + PWD + TrsType + Canal + amount + key.

2.3. Get List of Beneficiaries

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XX07

Request
Param. Value Size Mandatory/Optional Comment
telClient String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
listeBeneficiaire String Returned
additionnalData String Returned

8
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

2.4. List of beneficiaries and amount

Method URL
POST /mxplus/services/applicationMobileServiceV3
/ XXBVL

Request
Param. Value Size Mandatory/Optional Comment
telClient String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
code String Returned
message String Returned
listeBeneficiaire String Returned
mntMin String
mntMax String Returned

9
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

2.5. Profile management

Method URL
POST /mxplus/services/applicationMobileServiceV3
/ XC11

Request
Param. Value Size Mandatory/Optional Comment
idPorteur String Mandatory
numTel String Optional
mail String Optional
photo String Optional

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionnalData String Returned

2.6. Add beneficiary

Method URL
POST /mxplus/services/applicationMobileServiceV3
/ XX02

Request
Param. Value Size Mandatory/Optional Comment
telBeneficiaire String Mandatory
telClient String Mandatory
nombenif String Mandatory
prenomBenif String Mandatory
idPorteur String Mandatory
typeOperation String Mandatory
Photo String Mandatory
numCarte String Mandatory
Adressemailbenef String Mandatory
idBenif String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionnalData String Returned

10
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

2.7. Update beneficiary

Method URL
POST /mxplus/services/applicationMobileServiceV3
/ XX04

Request
Param. Value Size Mandatory/Optional Comment
telBeneficiaire String Mandatory
telClient String Mandatory
nombenif String Mandatory
prenomBenif String Mandatory
idPorteur String Mandatory
typeOperation String Mandatory
Photo String Mandatory
numCarte String Mandatory
Adressemailbenef String Mandatory
idBenif String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionnalData String Returned

2.8. Delete beneficiary

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XX03

Request
Param. Value Size Mandatory/Optional Comment
idBenefic String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionnalData String Returned

11
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

2.9. Make transfer

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XTV01

Request
Param. Value Size Mandatory/Optional Comment
idClient String Mandatory
montant String Optional
idBenif String Optional
motif String Optional
otp String Optional

Response
Param. Value Size Mandatory/Optional Comment
responseErreur String Mandatory
message String Returned

2.10. Generate statement by month or year

Method URL
POST /mxplus/services/applicationMobileServiceV3/ XC033

Request
Param. Value Size Mandatory/Optional Comment
numCarte String Mandatory
mois String Mandatory
annee String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
responseFlag String Returned
responseMessage String Returned
reportPath String Returned

2.11. Review transaction details

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XTH01V2

12
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

Request
Param. Value Size Mandatory/Optional Comment
date String Mandatory
operation String Mandatory
numAutorisation String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionalData String Returned
idOperation String Returned
nomBenif String Returned
nomEmetteur String Returned
dateOperation String Returned
nomCommercant String Returned
heureOperation String Returned
status String Returned
motif String Returned
nomEmetteurCashTocard String Returned
telEmetteurCashTocard String Returned
dateRetraitMAD String Returned
telBenifMD String Returned

2.12. Client information

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XTH03V3

Request
Param. Value Size Mandatory/Optional Comment
idPorteur String Mandatory
limit String Mandatory
telPorteur String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionnalData String Returned
solde String Returned
listeTransactions String Returned
etatCarte String Returned
nbrNotif String Returned
lastconnection String Returned
idPorteur String Returned
tel String Returned
mail String Returned

13
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

id String Returned
etatCarte String Returned
rib String Returned

2.13. Transaction history

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XTH00

Request
Param. Value Size Mandatory/Optional Comment
numcarte String Optional
limit String Optional
dateDebut String Optional
dateFin String Optional

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionnalData String Returned
listeTransaction String Returned

2.14. Clients balance

Method URL
POST /mxplus/services/applicationMobileServiceV3
/ XC10

Request
Param. Value Size Mandatory/Optional Comment
idClient String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
soldeClient String Returned
additionalData String Returned
codeError String Returned

14
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

2.15. Mobile Transfer

Method URL
POST /mxplus/services/applicationMobileServiceV3
/ transfertMobile

Request
Param. Value Size Mandatory/Optional Comment
montant String Mandatory
idClient String Mandatory
telBene String Mandatory
otp String Mandatory
motif String Optional

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionalData String Returned
idTransaction String Returned
codeResponse String Returned
numAuthRecharge String Returned
numAuthDecharge String Returned
numDemRech String Returned
solde String Returned

2.16. Add a blacklisted card

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XC00V2

Request
Param. Value Size Mandatory/Optional Comment
numCarte String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionalData String Returned

15
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

2.17. Remove a blacklisted card

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XC13V2

Request
Param. Value Size Mandatory/Optional Comment
numCarte String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionalData String Returned

2.18. Top up

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XTG07

Request
Param. Value Size Mandatory/Optional Comment
chaine String Mandatory
idClient String Mandatory
solde String Optional

Response
Param. Value Size Mandatory/Optional Comment
errorCode String Returned
responseCodePaiement String Returned
numAuthPaiement String Returned
solde String Returned
numTransaction String Returned
dateTrs String Returned
frais String Returned
chaineClaire String Returned
additionnalData String Returned
numCarteSource String Returned
idCommande String Returned

16
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

2.19. Holder Information

Method URL
POST /mxplus/services/applicationMobileServiceV3/XC12

Request
Param. Value Size Mandatory/Optional Comment
numCarte String Optional
idClient String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
response String Returned
additionnalData String Returned
nom String Returned
prenom String Returned
pieceIdentite String Returned
passport String Returned
adresse String Returned
tel String Returned
Profession String Returned
numerocompte String Returned
codeclient String Returned
datefin String Returned
solde String Returned
mail String Returned
numCarte String Returned
numSerieCarte String Returned
lastDebit String Returned
lastCredit String Returned
niveau String Returned

17
MXMobile API Spec/VA June 16, 2022
 MXMobile APIs Spec

2.20. Historical bank transfer

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XTHV

Request
Param. Value Size Mandatory/Optional Comment
idClient String Mandatory
dateDebut String Optional
dateFin String Optional
operation String Optional

Response
Param. Value Size Mandatory/Optional Comment
listeVirement String Returned
code String Returned
message String Returned

2.21. E-Recharge by card

Method URL
POST /mxplus/services/applicationMobileServiceV3/
XTGCOF10

Request
Param. Value Size Mandatory/Optional Comment
userId String Mandatory
montant String Mandatory
idClient String Mandatory

Response
Param. Value Size Mandatory/Optional Comment
messageError String Returned
responseCode String Returned
idRecharge String Returned
url String Returned

18
MXMobile API Spec/VA June 16, 2022