m-pesa b2c development guide
Post on 06-Jul-2018
228 Views
Preview:
TRANSCRIPT
-
8/18/2019 M-PESA B2C Development Guide
1/52
PROJECT N AME: M-PESA
DOCUMENT N AME: B2C API SPECIFICATION VERSION: 1.5
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT D ATE: 7TH OCTOBER 2014
B2C API
Specification
1
-
8/18/2019 M-PESA B2C Development Guide
2/52
PROJECT N AME: M-PESA
DOCUMENT N AME: B2C API SPECIFICATION VERSION: 1.5
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT D ATE: 7TH OCTOBER 2014
Approvals
T!" #$%&'()* )((#" +(,$ $," $ !',('()**!$).
Author(s) Name Signature Date
S(!%( D((,$'()* E)3!)(( E)(* &+!
Reviewers Name Signature Date
S()!$ M)3( S(!%( D((,$'()* R(3!),# T$,(
Revision Log
RevisionNumber
RevisionDate
Revision Revision madeby
1.0 1* J&)(6201
I)!*!, D* E)(* &+!
1.1 8* J&,96 201 A##(# "(%*!$) ..1:P""$# E)%9*!$)
E!% M$9
1.2 28* J&,9 201 A##(# R("&,* %$#(" E)(* &+!
1. 1* J) 2014 A##(# R("&,* %$#((;,)*!$)"
E)(* &+!
1.4 7* S(* 2014 A##(# %)3(P""$#!)*(%(6 (#!*(#
-
8/18/2019 M-PESA B2C Development Guide
3/52
PROJECT N AME: M-PESA
DOCUMENT N AME: B2C API SPECIFICATION VERSION: 1.5
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT D ATE: 7TH OCTOBER 2014
# !(,# ("*!%*!$)".R('$(# ()%9*(#
'(*( *3. E#!*(#
*( 3()(!%API (
-
8/18/2019 M-PESA B2C Development Guide
4/52
PROJECT N AME: M-PESA
DOCUMENT N AME: B2C API SPECIFICATION VERSION: 1.5
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT D ATE: 7TH OCTOBER 2014
Abbreviations
Term Definition
API Application Po$a%%in$ Inteface
B2C Business to Custo%e
Bo&e Se'ice Access "ate(a)
SP Se'ice Po'ide
*
-
8/18/2019 M-PESA B2C Development Guide
5/52
PROJECT N AME: M-PESA
DOCUMENT N AME: B2C API SPECIFICATION VERSION: 1.5
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT D ATE: 7TH OCTOBER 2014
Table of Contents
Approvals........................................................................................ii
Revision Log.................................................................................... ii
Abbreviations.................................................................................iv
1 Introduction.................................................................................7
1.1 Scope.................................................................................................................................+
2 Message Flow escription...........................................................!
" ata T#pe e$nition...................................................................%
#.1 Identit),)pe enu%eation..................................................................................................-
#.2 Identifie,)pe enu%eation...............................................................................................-
#.# Paa%ete,)pe stuctue....................................................................................................-
#.* Paa%etes stuctue..........................................................................................................-
#. Refeence/ata stuctue....................................................................................................-
#. ,ansaction stuctue.......................................................................................................10
#.+ Calle stuctue................................................................................................................10
#. Initiato stuctue.............................................................................................................11
#..1 Pass(od Enc)ption.......................................................................................................11
#.- Pi%a)Pat) stuctue.....................................................................................................12
#.10 Recei'ePat) stuctue...................................................................................................12
#.11 Access/e'ice stuctue...................................................................................................12
#.12 Identit) stuctue..............................................................................................................12
#.1# Reuest stuctue.............................................................................................................12
#.1* Response stuctue...........................................................................................................1#
#.1 ResultPaa%etes stuctue..............................................................................................1##.1 Result stuctue................................................................................................................1#
#.1+ Result code......................................................................................................................1*
& 'eb (ervice Interface e$nition................................................2)
*.1 Inteface3 Reuest4$Pot,)pe......................................................................................20
*.1.1 5peation3 "eneicAPIReuest.......................................................................................20
*.2 Inteface3 Result4$Pot,)pe.........................................................................................22
*.2.1 5peation3 "eneicAPIResult..........................................................................................22
*.# Inteface3 6ueue,i%eout7otificationPot.......................................................................2
*.#.1 5peation3 notif)6ueue,i%eout......................................................................................2
-
8/18/2019 M-PESA B2C Development Guide
6/52
PROJECT N AME: M-PESA
DOCUMENT N AME: B2C API SPECIFICATION VERSION: 1.5
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT D ATE: 7TH OCTOBER 2014
*.* Inteface3 6ue),ansactionPot.....................................................................................2+
*.*.1 5peation3 ue),ansaction...........................................................................................2+
*. Inteface3 4ana$e%ent....................................................................................................................................2-
*..1 5peation3 chan$ePass(od...................................................................................................................2-
* +,a-ple...................................................................................""
.1 "eneicAPIReuest.........................................................................................................##
.1.1 ,he #d pat) send B2C euest to the Bo&e................................................................##
.1.2 ,he Bo&e etun esponse to the #d pat)....................................................................#
.2 "eneicAPIResult............................................................................................................*0
.2.1 ,he Bo&e send notification to the #d pat).................................................................*0
.2.2 ,he #d pat) etun esponse to the Bo&e....................................................................*#
.# notif)6ueue,i%eout........................................................................................................*#
.#.1 ,he Bo&e send notification to the #d pat).................................................................*#
.#.2 ,he #d pat) etun esponse to the Bo&e....................................................................*
.* ue),ansaction.............................................................................................................*
.*.1 ,he #d pat) sends ue) euest to the Bo&e.............................................................*
.*.2 ,he Bo&e etun esponse to the #d pat)....................................................................*+
. chan$ePass(od..............................................................................................................0
..1 Reuest e8a%ple3.............................................................................................................0
..2 Response e8a%ple3..........................................................................................................1
-
8/18/2019 M-PESA B2C Development Guide
7/52
1 Introduction1.1 (cope
,he pesent docu%ent specifies the eal ti%e B2C 9eb Se'ice aspects of the inteface. All aspects of B2C9eb Se'ice ae defined hee: these bein$3
4essa$e ;lo( /esciption
/ata ,)pe /efinition
9eb Se'ice Inteface /efinition
9S/! fo this specification
E8a%ple
-
8/18/2019 M-PESA B2C Development Guide
8/52
2 Message Flow escription
-
8/18/2019 M-PESA B2C Development Guide
9/52
" ata T#pe e$nition
".1 Identit#T#pe enu-eration
!ist of Identit),)pe 'alues.
Enumeration Description
1000 C&"*$'(
2000 SPO(*$
000 O3)!>*!$)O(*$
5000 O3)!>*!$)
?000 T!,,
000 SP
".2 Identi$erT#pe enu-eration
!ist of Identit),)pe 'alues.
Enumeration Description
1 MSISDN
2 T!,,N&'+(
SPS$*C$#(
4 O3)!>*!$)S$*C$#(
5 I#()*!*9ID
? O2CL!)
8 SPO(*$C$#(
10 POSN&'+(
11 O3)!>*!$)O(*$U"(N'(
12 O3)!>*!$)O(*$C$#(
1 V$&%(C$#(
"." ara-eterT#pe structure
Elementname
Element type Optional
Description
(9 ;"#:"*!)3 N$ I* !)#!%*(" '(*( )'(.
V,&( ;"#:"*!)3 N$ I* !)#!%*(" '(*( ,&(.
".& ara-eters structure
Elementname
Element type Optional Description
P'(*( P'(*(T9
(@1..&)+$&)#(#
N$ I* !" &"(# *$ %9 "(%!!% '(*(" $ "(%!!% *)"%*!$) $
+&"!)("" $(*!$).
".* Referenceata structure
Elementname
Element type Optional
Description
R((()%(I*(' P'(*(T9(@1..&)+$&)#(#
N$ I* !" &"(# %9 "$'( ((()%( #* ** MM )((# )$* ),9>( +&*)((# *$ (%$# !* !)*$ *)"%*!$) ,$3..
-
8/18/2019 M-PESA B2C Development Guide
10/52
"./ Transaction structure
Elementname
Element type Optional
Description
C$'')#ID ;"#:"*!)3 N$ T( &)!
-
8/18/2019 M-PESA B2C Development Guide
11/52
".! Initiator structure
Elementname
Element type Optional
Description
I#()*!!(T9( I#()*!!(T9( N$ I* !)#!%*(" *( !#()*!!( *9( $ *( !)!*!*$. T( ,&( $ *!" '(*( '&"* +( ,!# !#()*!!( *9( "&$*(# +9 MM.
I#()*!!( ;"#:"*!)3 N$ I* !)#!%*(" *( !#()*!!( $ *( !)!*!*$. I*" ,&( '&"* '*% *(!)&**(# ,&( $ *( '(*( I#()*!!(T9(.
S(%&!*9C(#()*!,
;"#:"*!)3 N$ I* !)#!%*(" *( "(%&!*9 %(#()*!, $ *( !)!*!*$. I*" ,&( '&"* '*%*( !)&**(# ,&( $ *( '(*( I#()*!!(T9(.
S$*C$#( ;"#:"*!)3 N$ G() *( !)!*!*$ !" ) $3)!>*!$) $(*$6 *!" '(*( '&"* +(("()* !) *( (
-
8/18/2019 M-PESA B2C Development Guide
12/52
".1)Receiverart# structure
Elementname
Element type Optional
Description
I#()*!!(T9( I#()*!!(T9( N$ I* !)#!%*(" *( !#()*!!( *9( $ *( (%!!()* *9. T( ,&( $ *!"
'(*( '&"* +( ,!# !#()*!!( *9( "&$*(# +9 MM.I#()*!!( ;"#:"*!)3 N$ I* !)#!%*(" *( !#()*!!( $ *( (%!!()* *9. I*" ,&( '&"* '*% *(
!)&**(# ,&( $ *( '(*( I#()*!!(T9(.
S$*C$#( ;"#:"*!)3 Y(" G() *( (%(!( *9 !" ) $3)!>*!$) $(*$ $ T!,,6 *!"'(*( '&"* +( ("()* !) *( (
-
8/18/2019 M-PESA B2C Development Guide
13/52
".1&Response structure
Elementname
Element type Optional
Description
R("$)"(C$#
(
;"#:"*!)3 N$ I* !)#!%*(" (*( MM %%(*" *( (
-
8/18/2019 M-PESA B2C Development Guide
14/52
".17 Resultcode
E$ %$#(
E$ D("%!*!$)
0 S&%%("" A!R("&,*
1 I)"&!%!()* F&)#" A!R("&,*
2 L("" T) M!)!'&' T)"%*!$) V,&( A!R("&,*
M$( T) M;!'&' T)"%*!$) V,&( A!R("&,*
4 G$&,# E;%((# D!,9 T)"( L!'!* A!R("&,*
5 G$&,# E;%((# M!)!'&' B,)%( A!R("&,*
? U)("$,(# P!'9 P*9 A!R("&,*
7 U)("$,(# R(%(!( P*9 A!R("&,*
G$&,# E;%((# M;!&'&' B,)%( A!R("&,*
11 D(+!* A%%$&)* I),!# A!R("&,*
12 C(#!* A%%$&)* I),! A!R("&,*
1 U)("$,(# D(+!* A%%$&)* A!R("&,*
14 U)("$,(# C(#!* A%%$&)* A!R("&,*
15 D&,!%*( D(*(%*(# A!R("&,*
17 I)*(), F!,&( A!R("&,*
1 I)!*!*$ C(#()*!, C(% F!,&( A!R("&,*
18 M(""3( S(
-
8/18/2019 M-PESA B2C Development Guide
15/52
,he follo(in$ table lists esult codes and esult desciptions (hich ae po'ided to the calle.
,hese %a) be co%%incated eithe in the s)nchonous ApiResponse %essa$e: o in theas)nchonous ApiResult %essa$e.
1 Success
,his is indicated fo both ApiResponse and ApiResult %essa$es. An ApiResponse 'alue of 0 indicatesthat the euest has passed basic 'alidation tests and been passed on to the coe s)ste% fo futhe
pocessin$. An ApiResult 'alue of 0 %eans that the euested financial tansaction has been co%pleted
successfull). In case of %ulti sta$ed tansaction the esponse code (ill be *# fo initiation sta$e and *fo confi%ation.
2 InsufficientFunds
,)picall) indicates that the pi%a) pat) does not ha'e enou$h %one) to co%plete the euested
financial tansaction. In the case of the B2C API: this %eans that the business o$anisation does not ha'e
enou$h %one) in its utilit) account.
,his is etuned b) the ApiResult and epesented intenall) as a tansaction eason.
3 LessThanMinimumTransactionValue
4 MoreThanMaximumTransactionValue
-
8/18/2019 M-PESA B2C Development Guide
16/52
Each of these potential failues dei'e fo% the ules (hich $o'en 4Pesa financial tansactions. In the
case of the B2C API: these ae ta&en fo% DefaultBusinessUtilityAount ules: (hich specif) a lo(e
bound of 10 KE shillin$s and an uppe bound of +0000. ;o po%otion pa)%ents and sala) pa)%ents toune$isteed uses: the uppe li%it is lo(e3 #000. !i&e(ise: the lo(e bound fo these 2 tansactions is
also diffeent3 101 athe than 10.
,hese ae both etuned b) the ApiResult and epesented intenall) as a tansaction eason.
5 ould!xceedDail"TransferLimit
,his is a li%it on dail) acti'it). ;o the business o$anisation: this is 'e) hi$h3 100000000 KE shillin$s.
It is %uch %oe li&el) that this ule (ill appl) to the custo%e: (hee the li%it is 1*0000 KE shillin$s.
,his is etuned b) the ApiResult and epesented intenall) as a tansaction eason.
# ould!xceedMinimum$alance
,his ule is athe confusin$l) na%ed it actuall) %eans that a tansaction (ould bin$ the businesso$anisations utilit) account bello( the euied %ini%u% (hich is cuentl) 0.
,his is etuned b) the ApiResult and epesented intenall) as a tansaction eason. It is co%puted duin$
e8ecution of the financial tansaction.
% &nresol'ed(rimar"(art"
) &nresol'ed*ecei'er(art"
,he pi%a) pat) o ecei'e pat) cannot be associated (ith an 4Pesa identit). ;o tansactions
-
8/18/2019 M-PESA B2C Development Guide
17/52
14 &nresol'edDe-itAccount
15 &nresol'ed.reditAccount
,hese ae all e8istin$ failue tansaction easons fo B2C financial tansactions the) (ould be issued to
the calle in the ApiResult %essa$e. ,he latte 2 in paticula ae unli&el) to occu: as the euest (ould be eected b) Coe API specific chec&s befoe the euest eached the accountin$ en$ine.
1# Du/licateDetected
Cuentl): an) euests (hich pesents an oi$inato con'esation id (hich has been seen befoe (ill beeected. ,his ule (ill need to be econsideed in conte8ts (hich euie %ultista$e con'esations o
%ultiple Calles. ,his chec&
-
8/18/2019 M-PESA B2C Development Guide
18/52
25 Missin*euest(arameters
Reuied input paa%etes ae defined fo each t)pe of API opeation. If these ae %issin$: then this is
issued in the ApiResult %essa$e. ,he na%es of the %issin$ paa%etes ae included in the esult paa%etes field.
2# In'alid*euest(arameters
If all euied paa%etes ae pesented: then 'alidation chec&s ae pefo%ed. Specificall): the paa%ete
is chec&ed to see if it can be con'eted to the intended t)pe: and then chec&ed a$ainst 4! sche%a 'alidation: the API atte%pts to con'et the >4! euest into an intenal ApiRe#uest
obect an) failues esult in this ApiResponse %essa$e. ,he details of the e8ception ae included.
31 InitiatorNotS/ecified
,he initiato usena%e is not specified: o not specified in a (a) that can be pased.
32 !rrorSerialiin*euest
,he pesented identifie fo the initiato is not a usena%e.
33 (rimar"(art"NotS/ecified
34 (rimar"(art"IdentifierIn'alid
35 *ecei'er(art"NotS/ecified
3# *ecei'er(art"IdentifierIn'alid
In all these case: one of the API paties is eithe %issin$ fo% the euest: o has been pesented (ith the
(on$ identifie t)pe.: ,his &ind of failue is indicated in the ApiResult %essa$e.:
3% MissinA/i.ommand
-
8/18/2019 M-PESA B2C Development Guide
19/52
7o co%%and is included in the euest in $eneal this poble% should be captued b) the >4! sche%a'alidation: but if it is not this ApiResult %essa$e is issued.
3) In'alid.on'ersationId
3+ &n0non.on'ersationId
7ot cuentl) chec&ed fo this (ill ta&e place fo %ultista$e con'esations.
4, In'alid(arameterDefinition
7ot been used.
41 Du/licate.on'ersationDetected
If the oi$inatocon'esationid is be eused a$ain: the euest (ill end up (ith duplicate eo code. ,heeuest should ha'e a uniue oi$inatocon'esationid fo e'e) ne( apieuest.
42 Du/licateStaeMessaeDetected
If the sta$e na%e is euested t(ice it (ill end up (ith duplicate sta$e. ,hou$h the occuance of this
(ould be 'e) ae.
43 Aaitin.onfirmation
It is applicable fo %ulti sta$e tansaction. 5nce the fist sta$e of the tansaction is set to authoised (ith
(ill set the esult code as A(aitin$Confi%ation to con'e) the initiato to initiate the confi%ation sta$e.
44 InitiatorTo*ecei'er(art"(ermissionFailure
,he initiato pesented does not ha'e the i$ht to issue euests fo the specified ecei'e pat)
-
8/18/2019 M-PESA B2C Development Guide
20/52
,he esult code is etuned if the o$anisation status is closed.
51 De-it.hareAccountIn'alid
If the Aiti%e puchase account is set to inacti'e state the coespondin$ tansaction (ill etun an in'alid
debit cha$e account failue.
52 ould!xceedMaximumSinleAirtime(urchase
If tansaction a%ount e8ceeds the %a8i%u% a%ount confi$ued fo sin$le euest it (ill fail the
tansaction fo ule failue.
-
8/18/2019 M-PESA B2C Development Guide
21/52
& 'eb (ervice Interface e$nition
&.1 Interface Re0uestMgrortT#pe
%!#!# Operation: &enericA$'Reuest
,he #d pat) in'o&es this opeation to send a B2C euest
4.1.1.1 M(""3( H(#(: R(
-
8/18/2019 M-PESA B2C Development Guide
22/52
Elementname
Element type Optional Description
T!'("*' ;"#: "*!)3 Y(" T!'( "*' UTC *!'(.
T( ,&( !" (
-
8/18/2019 M-PESA B2C Development Guide
23/52
&.2 Interface ResultMgrortT#pe
%!*!# Operation: &enericA$'Result
,his opeation %ust be i%ple%ented b) a 9eb Se'ice at the #d pat) side if it euies notification of thefinal esult fo B2C euest. It (ill be in'o&ed b) Bo&e to notif) the # d pat) once Bo&e ecei'ed the
notification fo% CoeAPI.
4.2.1.1 I)&* M(""3(: R("&,*M"3
Element name Element type Optional Description
Result4s$ 8sd3 stin$ 7o Reuest 4essa$e fo% Bo&e. Its 'alue should be a instance
of Result ,)pe and a C/A,A.
4.2.1.2 O&*&* M(""3(: R("$)"(M"3
Element name Element type Optional Description
Response4s$ 8sd3 stin$ 7o Response etun to Bo&e. Its 'alue should be a instance of
Response ,)pe and a C/A,A.
4.2.1. R("$)"( C$#("
Response+ode ResponseDesc
000000000 Success
200000001 ,he s)ste% is o'eload
200000002 ,hottlin$ eo
20000000# Intenal Se'e Eo
,he paa%etes in the *esult:*esult(arameters ele%ent ae listed belo(3
,he *esult(arameters (ill chan$e to this on Apil 201.
-
8/18/2019 M-PESA B2C Development Guide
24/52
ara-eter ataT#pe
Mandator# orptional
escription +,a-ple
,ansactionReceipt8s3stin$ 4andato)
?niue tansaction I/ fo the pa)%ent tansaction.
1
2#
*
0
0
00
0
0
+
0#
1
,ansactionA%ount 8s3stin$ 4andato) 2 fi8ed point deci%al a%ountof the tansaction
10
0
.2
2
,ansactionCo%plet
ed/ate,i%e
8s3stin$ 4andato) ,he ti%e (hen the financial
tansaction (as co%pleted:as ecoded in the 4Pesa
s)ste%.
;o%at3
dd.%%.)))) DD3443SS
2
2.
0#
.
20
1
2
1
2
32
0
3
20
-
8/18/2019 M-PESA B2C Development Guide
25/52
ara-eter ataT#pe
Mandator# orptional
escription +,a-ple
Recei'ePat)Public7a%e
8s3stin$ 4andato)Public na%e of the custo%e(ho has been issued the
%one).
;o%at3 &'S!SD()*&First
(ame) &+ast (ame)
;o une$iste custo%e: the
&First (ame) &+ast (ame)
(ill be blan&.
2
*
++
#
K
i p
K e
i
n
o
B2C9o&in$AccountA'ailable;unds
8s3stin$ 4andato) 2 fi8ed point deci%al a%ountof the A'ailable Balance of
the o$aniationFs 9o&in$
Account.
7ote3 the e8act Account ,)pe
(ill depend on the
confi$uation.
--
-
-.
B2C?tilit)Account
A'ailable;unds
8s3stin$ 4andato) 2 fi8ed point deci%al a%ount
of the A'ailable Balance ofthe o$aniationFs ?tilit)
Account: (hich is the debit
account of the pincipletansaction.
7ote3 the e8act Account ,)pe(ill depend on the
confi$uation.
-
--
-
.
-
8/18/2019 M-PESA B2C Development Guide
26/52
ara-eter ataT#pe
Mandator# orptional
escription +,a-ple
B2CCha$esPaidAccountA'ailable;und
s
8s3stin$ 4andato)2 fi8ed point deci%al a%ountof the A'ailable Balance of
the o$aniationFs Cha$e
Paid Account: (hich is debitaccount of the cha$e.
7ote3 the e8act Account ,)pe(ill depend on the
confi$uation.
----.
B2CRecipientIsRe$
isteedCusto%e
8s3stin$ 4andato) Indicate if the ecipient is an
e8istin$ 4obile 4one)custo%e: o an une$isteed
custo%e.
;o%at3 G o 7
7ote3 ,his field is not filled
b) the "1 platfo%: but it(ill be filled b) the "2
platfo%.
G
-
8/18/2019 M-PESA B2C Development Guide
27/52
&." Interface 3ueueTi-eout4oti$cationort
%!!# Operation: noti,y-ueueimeout
,his opeation %ust be i%ple%ented b) a 9eb Se'ice at the #d pat) side if it euies notification ofcached B2C euests ae e8pied. It (ill be in'o&ed b) Bo&e to notif) the #d pat) once cached B2C
euests ae e8pied.
4..1.1 I)&* M(""3(: )$*!9&(&(T!'($&*
Elementname
Element type Optional
Description
oi$inatoCon
'esationI/
8sd3stin$ oi$inatoCon'esationI/ fo% the euest sent b) the #d pat)
oi$inReuest 8sd3stin$ 7o 5i$inal euest (ithout S5AP Deade sent b) #d pat). Its 'alue is
encoded (ith base*: (hen the #d pat) ecei'e the euest: itshould decode it.
e8tensionInfo Paa%etes Ges E8tended paa%etes.
4..1.2 O&*&* M(""3(: )$*!9&(&(T!'($&*R("$)"(
Elementname
Element type Optional
Description
esult Result 7o
e8tensionInfo
Paa%etes Ges E8tended paa%etes.
4..1. R("$)"( C$#(
Response+ode ResponseDesc
000000000 Success
000000001 ;ailed
-
8/18/2019 M-PESA B2C Development Guide
28/52
&.& Interface 3uer#Transactionort
%!%!# Operation: ueryransaction
,he #d pat) in'o&es this opeation to ue) tansaction info%ation..
4..1.1 M(""3( H(#(: R(
-
8/18/2019 M-PESA B2C Development Guide
29/52
4..1.2 I)&* M(""3(:
-
8/18/2019 M-PESA B2C Development Guide
30/52
4..1.4 R("$)"( C$#("
Response+ode ResponseDesc
000000000 Success
100000001 ,he s)ste% is o'eload
100000002 ,hottlin$ eo
10000000# E8ceed the li%itation of the !ICE7SE
10000000* Intenal Se'e Eo
10000000 In'alid input 'alue3M1
M1 indicates the paa%eteFs na%e.
10000000 SPFs status is abno%al
10000000+ Authentication failed
10000000 Se'iceFs status is abno%al
100000010 Insufficient pe%issions
10000001* 4issin$ %andato) paa%ete3M1
M1 indicates the paa%eteFs na%e.
&.* Interface Manage-ent
%!.!# Operation: change$assword
,he #d pat) in'o&es this opeation to chan$e his pass(od.
Input Message c5angeassword
+le-entna-e
+le-entt#pe
ptional
escription
spId 8sd3 stin$ 7o SP I/.
ItFs allocated b) the SA" to the #d pat).
HE8a%ple
000201
-
8/18/2019 M-PESA B2C Development Guide
31/52
+le-entna-e
+le-entt#pe
ptional
escription
spPass(od 8sd3 stin$ Ges Enc)pted authentication pass(od fo patnes to access the SA".
,he 'alue is a chaacte stin$ enc)pted
fo% s/Id (assord timeStam/ b)
SDA2. ,he enc)ption fo%ula is asfollo(s3 spPass(od BASE*
-
8/18/2019 M-PESA B2C Development Guide
32/52
+le-entna-e
+le-entt#pe
ptional
escription
ne(Pass(od 8sd3stin$ 7o 7e( authentication pass(od fo #d paties to access the SA". It should be
enc)pted b) AES2 and encoded (ith
base*. Shaed &e) and (ill be allocated b) the SA".
;o e8a%ple3
7e( pass(od is N6AO2(s8:
Secuit) &e) is AAAabcdef$hi&l%:
Vecto is abcdef$hi&l%nop
BASE*
-
8/18/2019 M-PESA B2C Development Guide
33/52
ResponseCode Responseesc
10000001* 4issin$ %andato) paa%ete3M1
M1 indicates the paa%eteFs na%e.
-
8/18/2019 M-PESA B2C Development Guide
34/52
* +,a-ple
*.1 6enericAIRe0uest
.!#!# he rd party send /*+ reuest to the /ro0er
E8a%ple13 Reuest (ith Result?R! and 6ueue,i%eout?R!
"$():E)(,$( ;',)":"$()Q**://"%('".;',"$.$3/"$/()(,$(/Q ;',)":(
-
8/18/2019 M-PESA B2C Development Guide
35/52
/P'(*("
R((()%(D*
R((()%(I*('
(9&(&(T!'($&*URL/(9
V,&(**://10.??.48.78:7/)(/V,&(
/R((()%(I*('
R((()%(I*('
(9O%%"!$)/(9
V,&(J'&&!/V,&(
/R((()%(I*('
/R((()%(D*
T!'("*'201-07-28T1:50:41.2108?75/T!'("*'
/T)"%*!$)
I#()*!*9
C,,(
C,,(T9(2/C,,(T9(
T!#P*9ID /T!#P*9ID
P""$#P""$#0/P""$#
C(%S&'C(%S&'0/C(%S&'
R("&,*URLR("&,*URL0/R("&,*URL
/C,,(
I)!*!*$
I#()*!!(T9(11/I#()*!!(T9(
I#()*!!(&"()'(/I#()*!!(
S(%&!*9C(#()*!,S(%&!*9C(#()*!,0/S(%&!*9C(#()*!,
S$*C$#(58??/S$*C$#(
/I)!*!*$
P!'9P*9
I#()*!!(T9(4/I#()*!!(T9(
I#()*!!(58??/I#()*!!(
S$*C$#(58??/S$*C$#(
/P!'9P*9
R(%(!(P*9
-
8/18/2019 M-PESA B2C Development Guide
36/52
I#()*!!(T9(1/I#()*!!(T9(
I#()*!!(2*+20*+--/I#()*!!(
S$*C$#(S$*C$#(1/S$*C$#(
/R(%(!(P*9
A%%(""D(!%(
I#()*!!(T9(1/I#()*!!(T9(
I#()*!!(I#()*!!(/I#()*!!(
/A%%(""D(!%(
/I#()*!*9
(9O)(1/(9O)(
/(
-
8/18/2019 M-PESA B2C Development Guide
37/52
R('R('0/R('
E)%9*(#P'(*("E)%9*(#P'(*("0/E)%9*(#P'(*("
P'(*("
P'(*(
(9(90/(9
V,&(V,&(0/V,&(
/P'(*(
P'(*(
(9(91/(9
V,&(V,&(1/V,&(
/P'(*(
/P'(*("
R((()%(D*
R((()%(I*('
(9(92/(9
V,&(V,&(2/V,&(
/R((()%(I*('
/R((()%(D*
T!'("*'
/T!'("*'
/T)"%*!$)
I#()*!*9
C,,(
C,,(T9(0/C,,(T9(
T!#P*9IDT!#P*9ID0/T!#P*9ID
P""$#P""$#0/P""$#
C(%S&'C(%S&'0/C(%S&'
/C,,(
I)!*!*$
I#()*!!(T9(1/I#()*!!(T9(
I#()*!!(I#()*!!(0/I#()*!!(
S(%&!*9C(#()*!,S(%&!*9C(#()*!,0/S(%&!*9C(#()*!,
S$*C$#(
-
8/18/2019 M-PESA B2C Development Guide
38/52
/S$*C$#(
/I)!*!*$
P!'*9P*9
I#()*!!(T9(1/I#()*!!(T9(
I#()*!!(I#()*!!(1/I#()*!!(
S$*C$#(S$*C$#(0/S$*C$#(
/P!'*9P*9
R(%(!(P*9
I#()*!!(T9(1/I#()*!!(T9(
I#()*!!(I#()*!!(2/I#()*!!(
S$*C$#(S$*C$#(1/S$*C$#(
/R(%(!(P*9
A%%(""D(!%(
I#()*!!(T9(1/I#()*!!(T9(
I#()*!!(I#()*!!(/I#()*!!(
/A%%(""D(!%(
/I#()*!*9
(9O)(0/(9O)(
/(
-
8/18/2019 M-PESA B2C Development Guide
39/52
O!3!)*$C$)("*!$)ID
/O!3!)*$C$)("*!$)ID
S(!%(S**&"0/S(!%(S**&"
/("$)"(/(
-
8/18/2019 M-PESA B2C Development Guide
40/52
("$)"( ;',)"Q**://!-1.3().''.$#$)(.%$'/''!)*(%(/("$)"(Q
R("$)"(C$#(100000000/R("$)"(C$#(
R("$)"(D("%R(
-
8/18/2019 M-PESA B2C Development Guide
41/52
*.2 6enericAIResult
.!*!# he /ro0er send noti,ication to the rd party
s3En'elope 8%lns3sQhttp3sche%as.8%lsoap.o$soapen'elopeQ
s3Bod) 8%lns38siQhttp3(((.(#.o$2001>4!Sche%ainstanceQ 8%lns38sdQhttp3(((.(#.o$2001>4!Sche%aQ
Result4s$ 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceesultQ
NHC/A,AHResult 8%lns3iQhttp3(((.(#.o$2001>4!Sche%ainstanceQ 8%lnsQhttp3api
'1.$en.%%.'odafone.co%%%intefaceesultQ
Result,)peCo%pletedResult,)pe
ResultCode0ResultCode
Result/escSuccessResult/esc
5i$inatoCon'esationI/R-2ea+cb2++5i$inatoCon'esationI/
Con'esationI/1da*0ad+e-*-#c*1ea++0-1fecCon'esationI/
,ansactionI/>I521#,ansactionI/ResultPaa%etes
Paa%ete
Ke) 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQA%ountKe)
Value 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQKsh200.00Value
Paa%etePaa%eteKe) 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQ,ansaction /ateti%eKe)
Value 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQ2210201* 20332*Value
Paa%etePaa%ete
Ke) 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQ9o&in$ Account A'ailable ;undsKe)
Value 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQ2##002.100Value
Paa%etePaa%ete
Ke) 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQCha$es Paid Account A'ailable ;undsKe)
Value 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQ0.0000Value
Paa%etePaa%ete
Ke) 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQ?tilit) Account A'ailable ;undsKe)
Value 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQ*1-.0000Value
Paa%eteResultPaa%etes
Refeence/ataRefeenceIte%Ke) 8%lnsQhttp3api'1.$en.%%.'odafone.co%%%intefaceeuestQ6ueue,i%eout?R!Ke)Value
8%lnsQhttp3api
'1.$en.%%.'odafone.co%%%intefaceeuestQhttp310..*-.20130-+ValueRefeenceIte%Refeence/ataResultResult4s$
s3Bod)
s3En'elope
-
8/18/2019 M-PESA B2C Development Guide
42/52
5
soapen'3En'elope 8%lns3soapen'Qhttp3sche%as.8%lsoap.o$soapen'elopeQ
soapen'3Deade
soapen'3Bod)
e3Result4s$ 8%lns3eQhttp3cps.hua(ei.co%cpsintefaceesultQNHC/A,AHT8%l 'esionQ1.0Q encodin$Q?,;QT
Result
Result,)pe0Result,)pe
ResultCode0ResultCode
Result/esc,he se'ice euest is pocessed successfull).Result/esc
5i$inatoCon'esationI//+00CE+C*B-BE-+/-;BACC-0*15i$inatoCon'esationI/
Con'esationIdB+2AC01E**++AB*B0-ECAEA2;ECon'esationId
,ansactionId2+2+2-+2,ansactionId
ResultPaa%etes
ResultPaa%ete
Ke),ansactionReceiptKe)
Value2+2+2-+2Value
ResultPaa%ete
ResultPaa%ete
Ke),ansactionA%ountKe)
Value100.00Value
ResultPaa%ete
ResultPaa%ete
Ke),ansactionCo%pleted/ate,i%eKe)
Value22.0#.2012 12320320Value
ResultPaa%ete
ResultPaa%ete
Ke)Recei'ePat)Public7a%eKe)
Value2*++#Kip KeinoValue
ResultPaa%ete
ResultPaa%ete
Ke)B2C9o&in$AccountA'ailable;undsKe)
Value10000.00Value
ResultPaa%ete
-
8/18/2019 M-PESA B2C Development Guide
43/52
ResultPaa%ete
Ke)B2C?tilit)AccountA'ailable;undsKe)
Value100000.00Value
ResultPaa%ete
ResultPaa%ete
Ke)B2CCha$esPaidAccountA'ailable;undsKe)
Value1000.00Value
ResultPaa%ete
ResultPaa%ete
Ke)B2CRecipientIsRe$isteedCusto%eKe)
ValueGValue
ResultPaa%ete
ResultPaa%ete
Ke)B2C9ithda(alCha$eA%ountKe)
Value12.00Value
ResultPaa%ete
ResultPaa%etes
Refeence/ata
RefeenceIte%
Ke)5ccasionKe)
ValueChist%asValue
RefeenceIte%
Refeence/ata
Resulte3Result4s$
soapen'3Bod)
soapen'3En'elope
.!*!* he rd party return response to the /ro0er
E8a%ple13 Success esponse
"$():E)(,$( ;',)":"$()Q**://"%('".;',"$.$3/"$/()(,$(/Q ;',)":(
-
8/18/2019 M-PESA B2C Development Guide
44/52
("$)"( ;',)"Q**://!-1.3().''.$#$)(.%$'/''!)*(%(/("$)"(Q
R("$)"(C$#(00000000/R("$)"(C$#(
R("$)"(D("%"&%%(""/R("$)"(D("%
/("$)"(/(O)J,%T0!HR0%D$L2FS12MS5)G4&+G0'8YG
+'U&Y28*L21*G50J'YGN,LJ,%V,%!P3$3ICA%28%=VC+2R5P3$3ICA3ICA%'V;
O,J,%V,%RN%2%PCF+0RBVEF+PD84+G3#'V9%2,+0!MS4I!B,+'N=,&>0!VVR=LT3!
P>4PHJ,%V,%3(=1"+)M8I'0#HA?L98%=*#E&2V&L'1*L)=F'+25,L'N+S8*+G,&
#=V9'FS89F1N0I4ICA3ID;U%'F&%2F#=,+4ICA3ICA3ICA28*+GF&E,EPN
+G1+'RJRDAL0N+G1+'RJRD4ICA3ICA3ICAT=F&V2VD+2R,P;+'#1YG#,28TA
-
8/18/2019 M-PESA B2C Development Guide
45/52
L0;+'#1YG#,28T4ICA3ICA3ICATJ2,&YR%N+),%)N#=,+,EP89G#+'F0
+JD+252J>YR+25JRDAL089G#+'F0+JD+252J>YR+25JRD4ICA3ICA3ICA28&
#'V9%2F0G8&SU28'V9%2F0G8&SUPC8D+252J>YR+25JRD4ICA3ICA3ICAU'V*
YJP,J,+GF9>AL1J,+GF9>4ICA3ICA3ICARG5%),#=VU=F9YG1,#=V9%>5F+'N9(B0
GRYJ+GV0J>MDRG5%),#=VU=F9YG1,#=V9%>4ICA3ICA3ICAU=F9YG1,#=V9%>4
ICA3ICA3ICA3ICA3PFB%'F*R,%4ICA3ICA3ICA3ICA3ICA3ID;LS2V5MDS2V5P3$3
ICA3ICA3ICA3ICA3ICA3PF+HV,P,+HV,MDV'F"#GUC!A3ICA3ICA3ICA3IDU=F9YG1,
#=V9P3$3ICA3ICA3ICA3ICAU=F9YG1,#=V9P3$3ICA3ICA3ICA3ICA3ICA3PE*,(T5L;PC8L
C!A3ICA3ICA3ICA3ICA3ICAV'F"#GUV'F"#GU;PC8GYG;1T4ICA3ICA3ICA3ICA3PC8
YJ+GV0IC!A3ICA3ICA3PC8YJ+GV0J>P3$3ICA3ICA3ID;SG,%'V&Y2VEYRP3$3
ICA3ICA3ICA3ICAU'V'J,+'N,SR,+T4ICA3ICA3ICA3ICA3ICA3ID;LUV,#GVUG1,
+V0VVJMPC8LC!A3ICA3ICA3ICA3ICA3ICAV'F"#GUV'F"#GU9PC8GYG;1T4ICA3ICA3
ICA3ICA3PC8SG,%'V&Y2VJ#=V*P3$3ICA3ICA3ICA3ICAU'V'J,+'N,SR,+T4ICA3ICA3
ICA3ICA3ICA3ID;LS2V5M>S2V5P3$3ICA3ICA3ICA3ICA3ICA3PF+HV,P,+HV,M>
V'F"#GUC!A3ICA3ICA3ICA3IDU'V'J,+'N,SR,+T4ICA3ICA3ICAL1J,'V9G5UR
#=EC!A3ICA3ICA3PFR+GV>#=F*%D4ICA3ICA3ICAL1R+GV>#=F*%D4ICA3IDVHJ+)N
YR+24C!A3ICASGR,+)R#HC!A3ICA3ICA3PEN+=;,%4ICA3ICA3ICA3ICA3PEN+=;,
%,R5%=UMD2F"+=V9VH,T4ICA3ICA3ICA3ICA3PFR$JU=F9#H,JRD5U=,9FB%)R5
SUPC8U=,9FB%)R5SUC!A3ICA3ICA3ICA3ID;YN>#289D5YN>#289DAL1B%N
+JP3$3ICA3ICA3ICA3ICA2,Y2*T#G02,Y2*T#G0PC8D=V1N1+T4ICA3ICA3ICA3
ICA3PFJ,%V"#FVSTD5SN1+HRVUPC8SN1+HRVUC!A3ICA3ICA3PC8DYG;"IC!A3
ICA3ICA3PE,&RYR%4ICA3ICA3ICA3ICA3PE,G50GJU(B,PEL0,G50G
JU(B,P3$3ICA3ICA3ICA3ICASGR,+)R',,%5J=V=,'GV9MDSGR,+)R',,%4
ICA3ICA3ICA3ICA3PFN,YV9R5J,=V=,+D5TGN1%',0(UN9GR,+)RYGPC8TGN1
%',0(UN9GR,+)RYGC!A3ICA3ICA3ICA3ID;T=89#EN=UC!A3ICA3ICA3ICA3IDU2
%)RD+2R,P3$3ICA3ICA3IDSG5#=,#=89P3$3ICA3ICA3ID;%',*YJ0(VB%)R5P3$3ICA3
ICA3ICA3ICASGR,+)R',,%,R5%=UMTSGR,+)R',,%,R5%=UC!A3ICA3ICA3ICA3ID;J
=V=,'GV9P,G50GI;PC8J=V=,'GV9P3$3ICA3ICA3ICA3ICAU2%)RD+2R,
P,N$+J028TAL1N$+J028T4ICA3ICA3ICAL1B9G1%)R5U=F9#HC!A3ICA3ICA3
PFJ,Y2V#'V9U=F9#HC!A3ICA3ICA3ICA3ID;J=V=,'GV9VH,T4;PC8J=V=,'GV9
VH,T4ICA3ICA3ICA3ICA3PE,G50GISGR,+)R',,%IL0,G50GIC!A3
ICA3ICA3ICA3ID;T=89#EN=UU2%)RD+2R,MTU2%)RD+2R,P3$3ICA3ICA3IDU'V
G,2JYJ0(T4ICA3ICA3ICAGNN>R=V2GN,P3$3ICA3ICA3ICA3ICASGR,+)R',,
-
8/18/2019 M-PESA B2C Development Guide
46/52
%,R5%=UMTSGR,+)R',,%,R5%=UC!A3ICA3ICA3ICA3ID;J=V=,'GV9P,G50G
I>PC8J=V=,'GV9P3$3ICA3ICA3IDGNN>R=V2GN,P3$3ICA3PC8J=V=,0(T4
ICA3ID;L,P#25,%4PC8L,P#25,%4PC89F1N0P,1#P%'V;O,J,%V,%RN%2%
C!A3ID%28%=VC+2R5P3$LNYB,+)Y?RG52G;%=UC3/,$%:$!3!)R(
-
8/18/2019 M-PESA B2C Development Guide
47/52
/"$():B$#9
/"$():E)(,$(
*.& 0uer#Transaction
.!%!# he rd party sends uery reuest to the /ro0er
"$():E)(,$( ;',)":"$()Q**://"%('".;',"$.$3/"$/()(,$(/Q
;',)":2Q**://.&(!.%$'.%)/"%('/%$''$)/21Q ;',)":,$%Q**://.%"!.$3/"%('/*)"%*!$)/#*/10/,$%,Q
;',)":("Q**://!-1.3().''.$#$)(.%$'/''!)*(%(/("&,*Q
"$():H(#(
2:R(E5ME1OE9MJDM>1RUFCN>3M2ODE4R1OTE2MEF=NDU1RCMD9M3/2:"P""$#
2:"(!%(I#151515000/2:"(!%(I#
2:*!'(S*'201407008?20/2:*!'(S*'
/2:R(
-
8/18/2019 M-PESA B2C Development Guide
48/52
)"1:("&,*
)"2:R("$)"(C$#( ;',)":)"2Q**://!-1.3().''.$#$)(.%$'/''!)*(%(/("$)"(Q00000000/)"2:R("$)"(C$#(
)":R("$)"(D("% ;',)":)"Q**://!-1.3().''.$#$)(.%$'/''!)*(%(/("$)"(QS&%%(""/)":R("$)"(D("%
/)"1:("&,*
)"1:"&+'!*A!R(>+2FG52PSJ$#HRO!%2N$G1%954+G;>+2FL'8998>+2FL2V'V"+B,L9I
3(=1"+)M?%'V;PSJ$#HRO!YBLY;L'#,+!5*+S52+2R'8&S5+20+G1+)R,%'Y2U%'V;#GV>#CIC!A3ID;>+2FG5
2O,YGR,%4ICA3ICA3PHR&%>SF1N0U08BUE,YGR,%!B4+G;&%>0+)M8I'0#HA?L98#%&HV#2VL'N+S8>Y2,+GE
+N)L2N+G1+!82M,;I4ICA3ICA3ICA3PHR&%>>%E,PE1MTU;NT#=5>O)NSGC!A3ICA3ICA3ID;0+)M?%BYN>#289
D5PREV4TVS01E+ENO,EU'*(FFVRNO(U1TG*FMU8FU,NETMVJVRNO('#TGM8ERTRS'";T1RFM1FR#
ORFU;UG*S01E,N>08PC80+)M?%BYN>#289D4ICA3ICA3ICA3PHR&%>0G1,UR+AMA;NDAM>AOTM2MALR
&%>0G1,UR+AC!A3ICA3ICA3ID;0+)M?%2V9#',U,PE1MTU;NTAMD#=5>O)N,%)Y2VJD4ICA3ICA3PC80+)M?U'V
;#GV>#FNPVBIGFIC!A3ID%28%=VIGFIC!A3ID;>+2FG52OJHC!A3ICA3ID;9E?U'V;#GV>#E1>>4
IV*DREFUV"P*+CB2J>G8&PS%)MS4J9%3G5+2R+'%8J9#VVEY*OC%)P>4%'V;#GV>#CB4+G;&%>0)J20#HA?L98%=
*#E&2V&L'1*L)=F'+25,L'N+S8*+G,=V9'FS89F1N0J9%C;U%'F&%2F#=,+4CT;D+21*YG5SUU2F"YJ5
U=F5+GVD28*+GF&E,EP3$JPE;+'#1YG#,28T4PC8MYG5)#GF)UN=UC3TJ2,&YR%N+),%)N#=,+
,EP,I5STE*MDAMC00MI1LG%2NDE1M>TJ2,&YR%N+),%)N#=,+,EP3$JPEN+),%)N#=,+,EP28'V9%2F0
G8&SUC3U'V*YJPAL1J,+GF9>4CT;F+'N9(B0GRYJ+GV0J>PV&YJ5%HR,FB%'F*R,%)MPC8F+'N9(
B0GRYJ+GV0J>P3$U=F9YG1,#=V9%>4U=F9YG1,#=V9P3$JPE*,(T5B+G81+)L0*,(T4CT;GYG;1T4MC4MD
V'F"#GUCU=F9YG1,#=V9P3$ICA3ICA3ICA3ICA3C3$L1B%'F*R,%)MC;SG,%'V&Y2VEYRP3$JPFJ,'V9G5U,
0G0C3JPE*,(T5R#GV1VR+GV#RVUL0*,(T4CV'F"#GUHR0%D$L>ELY2L5LIMT$4OT35L>V'F"#GU
C3L1J,'V9G5U,0G0PC8SG,%'V&Y2VEYRP3$JPFR+GV>#=F*%D49MDE0LTA5LTIVDE9OU>OE5LAMDA1MFPC
8UG1,%R+ACVHJ+)NYR+24C;J=V=,0(T4CT;DYG;"IC3JPEN+=;,%,R5%=UM2F"+=V9VH,T4C
V=%'RYJ0(U,EP35OD0MTV=%'RYJ0(U,EP3$JCT;YN>#289D5YN>#289DAL1B%N+JP3$JCT;D=V1N1+T5D=V1N1+TAL0N$GNUV*P3$JCT;SN1+HRVUHR0%D$L>ELY2L5LIMT$4MDL>U'V>#G;0VVJ
MP3$JPC8DYG;"IC3SG5#=,#=89P3$JCT;J=V=,'GV9VH,T4;MTSGR,+)R',,%,R5%=UC3JPE,G50G
IYJM'IL0,G50GIC3JPFN,YV9R5J,=V=,+D5!S!0E0UVV>#V,59">=N0,FJR,U9+2TVV,%$1
GVVCVV%DY2RD,V=,*R=VT%FJ&RVF!%>IOH#H%'$MNBV)VM!8(UR;RT4'U2M0*#F00F;#GF0V
GFC;!N,N045G#VG*&N=>GF#25$,U)N*E1L(TRJUJV=,U0JS0V028=VC1MG5)#
=3?IDI;NDYNC30PHNYB,+)Y?RG52G;%=U3(=1"+)M?%28%=V0!HR0%D$LN=V*YM&(=1"%28%C5%'%%28%C8,+
),+=8S!IH*+=5>O)J,%T0!HR0%D$L2FS12MS5)G4&+G0'8YG+'U&Y28*L21*G50J'YGN,LJ,%V,%!P3$3IC
AICA3PHNYB,+)Y?'8(T4ICA3ICA3PHJ,%TSF1N0TN)PG0NEVRBG>/(=1"IH,%)N+248J9%;LA)J9B,+'N=
,&>0)J1VUR!04J9%/P;9F1N0IH*+=5>PS%)HR0%D$L2FS12MS5)G4&+G0'8YG+'U&Y28*L21*G50J'YGN,L
J,%V,%)J>4PFR9YG5>YGN0G8&P3$JPEN+G1+'RJRD5TYG;%),Y,*G50PC8D+21*YG5SUC3T=F&V2VD+2
R,PAL0;+'#1YG#,28T4CT;P%',)G5#=8928'V9%2F0G8&SUU,JMS0MDALT9MU*>Y0MTU>PC8P%',)G5
#=8928'V9%2F0G8&SUC328'V9%2F0G8&SUPC8D+252J>YR+25JRD4CT;SG1%'"MDU'V*YJP
-
8/18/2019 M-PESA B2C Development Guide
49/52
3$JPEV&YJ5%HR,FB%'F*R,%)MRG5%),#=VU=F9YG1,#=V9%>AL0V&YJ5%HR,FB%'F*R,%)MC;YJ+GV0J>P
;YJ+GV0IC3S2V5PF*+VDS2V5P3$JPF+HV,P%LAPC8GYG;1T4PC8YJ+GV0IC3$3ICA3ICA3ICA3I
CACU=F9YG1,#=V9%>4PFJ,'V9G5UR#=EC3U'V'J,+'N,SR,+T4CS2V5P,F1V,V=,*G81#FVSTDS2V
5P3$JCT;GYG;1T5$#HRO!MTA&NY&ND&MA;O35ODPC8GYG;1T4CTU'V'J,+'N,SR,+T4L1J,'V9G5UR
#=EC3V=,*N0YG1PIMT*MD*M#UMTI?NTM?MT&MDAMDU9MV$L1R+GV>#=F*%D4PC8U%'F&%2F#=,+4PE,
G50R5P3$JPEN+=;,%4C2F"+=V9VH,T49PC8DYG;"JU(B,P3$JCT;U=,9FB%)R5SUOD4OT;PC8U=,9F
B%)R5SUC3JPFB%N+JP,B%N+JMDU=F>%#%'C3JPEN$GNUV*PN$GNUV*MD2,Y2*T#G0C3J
PFJ,%V"#FVSTD5$#HR%>$L>E5N!49MDE&ME0LE>N$;ODM9M98*+G,=V9'FS89N1+HL1J,%V"#FVSTD4CT2F"
+=V9P3$JPE,&RYR%4CSGR,+)R',,%,R5%=UMTEL0,G50GJU(B,P3$JCT;J=V=,'GV9P'I9Y>J!PC8J
=V=,'GV9P3$JCT;TGN1%',0(UN9GR,+)RYGYYNBNFFUL1%%FUOG%M2R#=RSUVM'8Y9(DB+VRLVVIMN9%1NCYU*F',U=NR)J'GFRF0RP
T0L1N,YV9R5J,=V=,+D4CU2%)RD+2R,P35OD0N>U2%)RD+2R,P3$JPC8J+',0GF0+IC3JPFB9G1%)
,YJ0(T4CJPE,G50GJU(B,PL0,G50GJU(B,P3$JCSGR,+)R',,%44OT35NDYL0,G50G
IC3JCT;T=89#EN=UPC8T=89#EN=UC3JPC8%',*YJ5U=F9#HC3U'VG,2JYJ0(T4CSGR,+)R'
,,%,R5%=UMTSGR,+)R',,%,R5%=UC3JPE,G50GIMU0N>AMTY>NA1PC8J=V=,'GV9P3$JCT;T=89#EN=UPC8T=89#EN=UC3L1J,Y2V#'V9U=F9#HC3GNN>R=V2GN,P3$JCT;J=V=,'GV9VH,T4;PC8J=V
=,'GV9VH,T4CSGR,+)R',,%5J=V=,'GV9M>SGR,+)R',,%4CL0FY2V>%0R,#',T4L0,G50R5P3$
JCT;L,P#25,%4;PC8L,P#25,%4CT%'V;#GV>#D5#T4LJ,%TSF1N0TN)P3$3ICALNYB,+)Y?'8(T4PC8>+
2FG52OV'V"+B,P3/)"1:"&+'!*A!R(A3U2VIDIMT3MTI
?NTE?M>U3R01UDD+25&GN0G8&O!B+=8>028=VC1MG5)#=3?IDY>N0D$%>F+),+=8SB4+G;&%>>PS
J$#HRO!%2N$G1%954+G;>+2FL'8998>+2FL2V'V"+B,L9IPHM?'8(SB4+G;&%>4%28I'0#HA?L98#%>M&+
J)L>IMDEGE1MU2N$G1LG,&%R+'N,I!B4+G;&%>4%28I'0#HA?L98#%>M&+J)L>IMDEGE1MU2N$G1I4U'V>%
=8&%2VN%2%3(=1"+)M8I'0#HA?L98%=*#E&2V&L'1*L)=F'+25,L'N+S8*+G,=V9'FS89F1N0I4IV*DREFUV"
U'V>%=8&%2U3(=1"+)M?T0!HR0%D$L##95M95%'%MAMS8YTU;TY2,+GE*G5>#=F&Y2U!IH*+=5>PSJ$#HRO!Y
BLY;L'#,+!5*+S52+2R'8&S5+20+G1+)R,%'Y2U%'V>%=8&%2U!P;SN+25>UN=UMDU'V>%=8&%2VD+2R,P
;D+252J>YR+25JRD5,M=U5N'NS04Y2VLT>MTM*YGF!0N>,NGNND#MDEL0N+),%)N#=,+,EP;P%',)G5#=
8928'V9%2F0G8&SUU,JMS0MDALT9MU*>Y0MTU>PC8P%',)G5#=8928'V9%2F0G8&SUPFN,%)Y2VT#=
F0#MMDU2V9#',VN0YR1%>4L1J,%B+)N,P,1#PU'V>%=8&%2VN%2%PC8>OJHPC8>OV'V"+B,P3/)"1:"&
+'!*A!R("$)"(
)"1:"&+'!*A!R("$)"(SFRUUC;LE3MAIE8LDD+250G50LVR5%=U?IHR,(H(=1"DD+25&GN0G8&O!B+=
8>028=VC1MG5)#=3?IDY>N0D$%>F+),+=8SB4+G;&%>>PSJ$#HRO!%2N$G1%954+G;>+2FL'8998
>+2FL2V'V"+B,L9IPHM?'8(SB4+G;&%>4%28I'0#HA?L98#%>M&+J)L>IMDEGE1MU2N$G1LG,&%R+'N,I!B
4+G;&%>4%28I'0#HA?L98#%>M&+J)L>IMDEGE1MU2N$G1I4U'V>%=8&%2VN%2%3(=1"+)M8I'0#HA?L98%=*#E&2V&L'1*L)=F'+25,L'N+S8*+G,=V9'FS89F1N0I4IV*DREFUV"U'V>%=8&%2U3(=1"+)M?T0!HR0%D$L#
#95M95%'%MAMS8YTU;TY2,+GE*G5>#=F&Y2U!IH*+=5>PSJ$#HRO!YBLY;L'#,+!5*+S52+2R'8&S5+20+G1+
)R,%'Y2U%'V>%=8&%2U!P;SN+25>UN=UMDU'V>%=8&%2VD+2R,P;D+252J>YR+25JRD5,M=U5N'NS04Y2V
LT>MTM*YGF!0N>,NGNND#MDEL0N+),%)N#=,+,EP;P%',)G5#=8928'V9%2F0G8&SUU,JMS0MDALT
9MU*>Y0MTU>PC8P%',)G5#=8928'V9%2F0G8&SUPFN,%)Y2VT#=F0#MMDU2V9#',VN0YR1%>4L1J,%B
+)N,P,1#PU'V>%=8&%2VN%2%PC8>OJHPC8>OV'V"+B,P3/)"1:"&+'!*A!R("$)"(
/)"1:"&+'!*A!R("$)"(L!"*
)"1:"&+'!*A!R("&,*L!"*
)"1:"&+'!*A!R("&,*UE8TVCAIEUVFAMS4;DD+250G50LVR5%=U?IHR,(H(=1"DI+N0O!A;MC42N!40OS49
MDE?ODA5N028&+'V#=,+$3Y2;%2UNCN+)R,+)*T=V&R$O!A;MT%5D$NC;>OV'V"+B,IH*+=5>O)M8I'0#HA?
L98>Y2,+GF>L)*+HNYA&+J)LNYAG52G;%=UI4%>C+2R5IH*+=5>O)>T0!HR0%D$L##95M95%'%MAMS
-
8/18/2019 M-PESA B2C Development Guide
50/52
8YTU;TY2,+GE*G5>#=F&Y2U!IH*+=5>O)>D0!HR0%D$L##95M95%'%MAMS8YTU;TY2,+GE!P;SN1+HRN%2%3(=
1"+)M8I'0#HA?L98%=*#E&2V&L'1*L)=F'+25,L'N+S8*+G,=V9'FS89N1+H!PG0NEVRBG>;SN1+H3(
=1"+)M?T0!HR0%D$L##95M95%'%MAMS8YTU;TY2,+GE*G5>#=F&Y2U!IH*+=5>PSJ$#HRO!YBLY;L'#,+!5*+S
52+2R'8&S5+20+G1+)R,%'Y2U%'V>#G;0I4U'V>#G;0VH,T5D+21+=V0GL1J,%V"#FR5%=UPFJ,%V"#EN
=UMTL1J,%V"#EN=UPFJ,%V"#ER,%2MBU'V;#GV>#E1,%N2VF(HB%),=YG,"#J,PC8SN1+HRENP;P%',)
G5#=8928'V9%2F0G8&SUU,JMS0MDALT9MU*>Y0MTU>PC8P%',)G5#=8928'V9%2F0G8&SUPEN+),%
)N#=,+,EP'UT2O=Y1LTGE*NDM;M91YGN'LTAOGM1Y2E0N2MT28'V9%2F0G8&SUPFJ,%V"#FB%'F*
R,%)MPFB%'F*R,%4S2V5IH*+=5>PSJ$#HRO!YBLY;L'#,+!5*+S52+2R'8&S5+20+G1+)R,%'Y2U%'V;#G
V>#CIVHJ+)NYR+243R=F0VR+GUL0*,(T4V'F"#GU3(=1"+)M8I'0#HA?L98%=*#E&2V&L'1*L)=F'+25,L'N+
S8*+G,=V9'FS89F1N0I4>MC4OS49MDE0IDE9OU9OM;PC8GYG;1T4L1B%'F*R,%4L1J,%V"#FB%'F*R,%)
MPFJ,'V9G5UR#=EPFJ,'V9G5U,0G0PE*,(SB4+G;&%>0!HR0%D$L2FS12MS5)G4&+G0'8YG+'U&Y28
*L21*G50J'YGN,LJ,%V,%!P,F1V,V=,*G81#FVSTDS2V5P;GYG;1SB4+G;&%>0!HR0%D$L2FS12MS5)G4&+G0
'8YG+'U&Y28*L21*G50J'YGN,LJ,%V,%!P'0#HA?L9;MC42N!40OS49MDE?OD4OSL1+HV,PU'V'J,+
'N,SR,+T4L1J,'V9G5UR#=EPC8SN1+HV0PC8SN1+HRN%2%PC8>OJHPC8>OV'V"+B,P3/)"1:"
&+'!*A!R("&,*
/)"1:"&+'!*A!R("&,*L!"*
)"1:
-
8/18/2019 M-PESA B2C Development Guide
51/52
"$():B$#9
,$%:%)3(P""$#
,$%:"I#500001/,$%:"I#
,$%:"P""$#%521?(518071#?01+(##150%#02?/,$%:"P""$#
,$%:*!'(S*'20120101010101/,$%:*!'(S*'
,$%:)(P""$#!27BAH0P#2LR#'%3C8/,$%:)(P""$#
/,$%:%)3(P""$#
/"$():B$#9
/"$():E)(,$(
.!.!* Response e1ample:
E8a%ple13 Success esponse
"$():E)(,$( ;',)":"$()Q**://"%('".;',"$.$3/"$/()(,$(/Q
;',)":,$%Q**://.%"!.$3/"%('/*)"%*!$)/#*/10/,$%,Q ;',)":("Q**://!-
1.3().''.$#$)(.%$'/''!)*(%(/("$)"(Q ;',)":("1Q**://!-1.3().''.$#$)(.%$'/''!)*(%(/("&,*Q
"$():H(#(/
"$():B$#9
,$%:%)3(P""$# R("$)"(
,$%:("&,*
(":R("$)"(C$#(00000000/(":R("$)"(C$#(
(":R("$)"(D("%S&%%(""/(":R("$)"(D("%
/,$%:("&,*
,$%:%)3(P""$#R("$)"(
/"$():B$#9
/"$():E)(,$(
E8a%ple23 Eo esponse caused b) authentication failed.
"$():E)(,$( ;',)":"$()Q**://"%('".;',"$.$3/"$/()(,$(/Q ;',)":(
-
8/18/2019 M-PESA B2C Development Guide
52/52
/"$():B$#9
/"$():E)(,$(
top related