m-pesa c2b developers guide

8/18/2019 M-PESA C2B Developers Guide

1/22

PROJECT N AME: M-PESA G2

DOCUMENT N AME: DEVELOPERS GUIDE- P AYBILL

V ALIDATION AND CONFIRMATION

VERSION: 0.3

COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT D ATE: 3RD AUGUST 2015

Developers Guide

PayBill Validation and ConfirmationVersion 0.3

1


2/22




VERSION: 0.3


1 Document Control

1.1 Document History

VERSIO S!"!#S D"!E C$"GE S#%%"R& O'ER ("#!$OR

0.1 Draft 2014-10-07 First Draft Wambugu Clement

0.2 Draft 2015-02-28 Added Buygds definitin and

Br!er a""unt details

#net$ %ubai

0.& Draft 2015-08-0& Added t$e res'nse "des fr(alidatin res'nse

#net$ %ubai

2


3/22




VERSION: 0.3


1.2 Stakeholder & Review Panel

"%E R O)E

)ar! )um *FC BA

#net$ %ubai *FC BA

Wambugu Clement *FC BA

&


4/22




VERSION: 0.3


2 Contents

Table o Contents

1 Document Control........................................................................21.1 Document History................................................................................................... 21.2 Stakeholder & Review Panel....................................................................................3

2 Contents.....................................................................................!

" #verview.....................................................................................$3.1.1 Background....................................................................................................... 5

3.1.2 Service Flow......................................................................................................5

! %nterace Seci'cation.................................................................(4.1 PayBill ransaction !alidation and "on#rmation.....................................................$

4.1.1 PayBill Transaction Validation Reuest !ro" #$Pesa to Broker..........................%4.1.2 PayBill Transaction Validation Result !ro" Broker to #$Pesa.............................&4.1.3 PayBill Transaction 'on(r"ation Reuest !ro" #$Pesa to Broker...................1)4.1.4 PayBill Transaction 'on(r"ation Result !ro" Broker to #$Pesa......................12

4.2 Re%isterR'.......................................................................................................... 134.2.1 Register*R+ inter!ace s,eci(cation.................................................................13

$ )nne*.......................................................................................1+

4


5/22




VERSION: 0.3


" #verview

&.1.1 Ba*+,round

W$en a "ustmer initiates a +ay Bill ser,i"e t$e system ill firstly aut$ri/e t$e transa"tin reser,e funds and

t$en sends a ,alidatin message t t$e bill issuer r mer"$ant riginatin ,ia A+. 3$e transa"tin ill nly besu""essful $en t$e t$ird 'arty ,alidatin is 'assed t$erise it ill be "an"elled r be !e't in Aut$ri/ed

status.

W$en t$e transa"tin is su""essfully "m'leted in t$e )bile )ney system ant$er "nfirmatin message illals be sent t t$e t$ird 'arties fr real-time re"n"iliatin. 3$e "nfirmatin re6uest ill be sent fr bt$ Buy

gds and +aybill transa"tins.

&.1.2 Servi*e -lo

3$e ser,i"e fl fr t$is interfa"e s$all be as flls

5


6/22




VERSION: 0.3


&.1.2.1 PayBill !ransa*tion Validation and Confirmation

A "ustmer +ayBill transa"tin "an be initiated ,ia *3% r A+ "$annel. 3$e transa"tin re6uest ill be sent t$e

)-+esa system fr 'r"essing.

After t$e )-+esa system aut$ri/es t$e transa"tin an eternal transa"tin ,alidatin re6uest ill be sent t &rd

+arty system ,ia Br!er. 3$e eternal transa"tin ,alidatin is 'tinal.

f t$e "rre"t res'nse t$e esult Cde 'arameter frm t$e t$ird 'arty ,alue is 0 is re"ei,ed frm t$e Br!er t$e)bile )ney system ill "m'lete t$e "rres'nding 'ayment transa"tin. 3$e transa"tin status ill be

"$anged t 9Cm'leted:.

f errr res'nse is re'lied by t$e Br!er t$e esult Cde 'arameter frm t$e t$ird 'arty ,alue is nt 0 t$e

)bile )ney system ill "an"el t$e "rres'nding 'ayment transa"tin. 3$e transa"tin status ill be "$angedt 9Can"elled:.

3$e t$ird 'arty s$all be registered in t$e br!er and must 'r,ide a "allba"! ;< fr t$e Cnfirmatin and t$e

(alidatin and a default res'nse $en t$ey are unrea"$able fr t$e ,alidatin. 3$is interfa"e is des"ribed in t$eegister;< interfa"e s'e"ifi"atin bel.

After t$e ,alidatin t$e )-+esa system ill "m'lete t$e transa"tin. W$en t$e transa"tin is "m'leted besides*)* ntifi"atins ill be sent t t$e Custmer a transa"tin "nfirmatin message ill als be sent t t$e 3$ird

+arty system ,ia Br!er. 3$e 3$ird 'arty system ill "a'ture t$e transa"tins frm t$e "nfirmatin message.

=


7/22




VERSION: 0.3


3$e "nfirmatin message $as n effe"t in t$e 'r"essing f t$e transa"tin.

7


8/22




VERSION: 0.3


! %nterace Seci'cation

!.1 Pay,ill Transaction -alidation andCon'rmation

4.1.1 PayBill !ransa*tion Validation Re/uest from %Pesa to

Bro+er

3$e detail f C2B+ayment(alidatine6uest message frm )-+esa t Br!er des"ribes as flling>

S /ield ame Tye 0*amle

value#tional

Descrition

1 3rans3y'e *tring +ayBill ?3$e 3ransa"tin 3y'e name f t$eBuy@ds transa"tin.

2 3ransD *tring 12&45=00000070 ? 3$e uni6ue identifier f t$e 'ayment

8


9/22




VERSION: 0.3


&1 transa"tin t$at is generated by )-+esasystem.

& 3rans3ime *tring

))DD$$mmss

20140227082020

?3$e date and time $en "ustmerinitiates a Buy @ds transa"tin.

4 3ransAmunt *tring

12&.00

?

3$e amunt f t$e transa"tin. 3de"imals fied 'int number. Fied

Curren"y 3y'e> %#* e.g. 12&.00 stands

fr> 12&.00 %s$

5 Business*$rtCde *tring12&45

?3$e rgani/atin s$rt "de f t$e)er"$ant in t$e )-+esa system

= Billef?umber *tring

31001

es

3$is field is nt a''li"able fr Buy

@ds transa"tins. t ill alays be

blan!.

7 n,i"e?umber *tring&&4&4&

es

n,i"e ?umber as #ntered by dentity

3$is field is reser,ed. t ill alays be

blan! in "urrent deli,ery.

8 )**D? *tring25472270&=14

?3$e "ustmer:s )**D? $i"$ is it$

"untry "de 'refi.

%Cnf3$e "ustmer:s %C infrmatin maybemulti'le %C inf.

%C?ame *tring+ersnal DetailsE

First ?ameEes

3$is %C indi"ates t$e "ustmer:s first

name

10 %C(alue *tring iyr es 3$e ,alue f %C field

11 %C?ame *tring+ersnal DetailsE

)iddle ?ameEes

3$is %C indi"ates t$e "ustmer:s

middle name

12 %C(alue *tring @ es 3$e ,alue f %C field

1& %C?ame *tring+ersnal DetailsE


10/22




VERSION: 0.3


+lease refer t t$e CB+nterfa"eHC2B+ayment(alidatinAndCnfirmatin.sdl file in se"tin 5 Anne fr

detail.

4.1.2 PayBill !ransa*tion Validation Result from Bro+er to %

Pesa

3$e detail f C2B+ayment(alidatinesult message frm Br!er t )-+esa des"ribes as flling>

S /ield

ameTye 0*amle

-alue#tional

Descrition

1 esultCde string 0 ?3$e result "de f t$e aut$ri/atin. 0 fr su""ess

t$ers are errr "de.

2 esultDes" *tring*er,i"e 'r"essing

su""essful

es #rrr message $en errr ""urs.

10


11/22




VERSION: 0.3


&3$ird+arty3ransD

*tring

12&45=0000088888

es

3$e uni6ue identifier f t$e 'ayment transa"tin t$at

is generated by t$e t$ird 'arty

3$is field is reser,ed. 3$e )-+esa system "an

a""e't t$e ,alidatin result it$ t$is field but t$esystem ill nt 'r"ess t$e field in "urrent deli,ery.

3$e )-+esa system regards t$e esultCde 0 as su""ess. Gt$er result "de areI

ResultCode ResultDes*

C2B00011 n,alid )**D?

C2B00012 n,alid A""unt number

C2B0001& n,alid Amunt

C2B00014 n,alid %C details

C2B00015 n,alid *$rt"de

C2B0001= Gt$er #rrr

*am'le f *GA+ message>

0

4ervice processing successful +2,-00000

+lease refer t t$e CB+nterfa"eHC2B+ayment(alidatinAndCnfirmatin.sdl file in se"tin 7 Anne t seet$e s"$ema definitin.

4.1.& PayBill !ransa*tion Confirmation Re/uest from %Pesa

to Bro+er

3$e detail f C2B+aymenCnfirmatine6uest message frm )-+esa t Br!er des"ribes as flling>

11


12/22




VERSION: 0.3


S /ield ame tye 0*amle

value #tional Descrition

1 3rans3y'e *tring Buy@ds ?3$e 3ransa"tin 3y'e name f t$e +ay

Bill transa"tin.

2 3ransD *tring12&45=00000070&1 ?

3$e uni6ue identifier f t$e 'aymenttransa"tin t$at is generated by )-+esa

system.

& 3rans3ime *tring

))D

D$$mmss

20140227082

020

?3$e date and time $en "ustmerinitiates a Buy @ds transa"tin.

4 3ransAmunt *tring

12&.00

?

3$e amunt f t$e transa"tin. 3

de"imals fied 'int number. Fied

Curren"y 3y'e> %#* e.g. 12&.00 standsfr> 12&.00 %s$

5Business*$rtCd

e*tring

12&45 ?

3$e rgani/atin s$rt "de f t$e

)er"$ant in t$e )-+esa system

= Billef?umber *tring 31001 es 3$is field is nt a''li"able fr Buy

12


13/22




VERSION: 0.3


@ds transa"tins. t ill alays be blan!.

7 n,i"e?umber *tring

&&4&4&

es

n,i"e ?umber as #ntered by dentity

3$is field is reser,ed. t ill alays be

blan! in "urrent deli,ery.

8GrgA""untBalan

"e

*tring

12&45.00

?

3$e A,ailable Balan"e f t$e

rgani/atin:s a""unt fr t$e Buy @dstransa"tin t$e Credit +arty a""unt f

t$e transa"tin.

3 de"imals fied 'int number. FiedCurren"y 3y'e> %#* e.g. 12&45.00

stands fr> 12&45.00 %s$

3$ird+arty3rans

D*tring

12&45=00000

88888

es

3$e uni6ue identifier f t$e 'ayment

transa"tin t$at is generated by t$e t$ird

'arty

3$is 'arameter nly be 'resent $en3$ird+arty3ransD as returned frm t$e

,alidatin res'nse message.

3$is field is reser,ed. t ill alays be blan! in "urrent deli,ery.

10 )**D? *tring25472270&=1

4 ?

3$e "ustmer:s )**D? $i"$ is it$

"untry "de 'refi.

%Cnf3$e "ustmer:s %C infrmatin maybe

multi'le %C inf.

11 %C?ame *tring+ersnalDetailsEFirst

?ameE

es3$is %C indi"ates t$e "ustmer:s first

name

12 %C(alue *tring iyr es 3$e ,alue f %C field

1& %C?ame *tring

+ersnal

DetailsE)iddle

?ameE

es3$is %C indi"ates t$e "ustmer:smiddle name

14 %C(alue *tring @ es 3$e ,alue f %C field

15 %C?ame *tring

+ersnal

DetailsE


14/22




VERSION: 0.3


*am'le f *GA+ message>


15/22




VERSION: 0.3


!.2 ReisterR3

4.2.1 Re,ister#R) interfa*e spe*ifi*ation

4.2.1.1 Interfa*e Introdu*tion

3$is ser,i"e is fr t$e t$ird 'arty system t register end-'ints n t$e br!er $ere t$e ,alidatin and t$e"nfirmatin messages are sent.

3$e detail f egister;< message frm t$e t$ird 'arty t Br!er des"ribes as flling>

4.2.1.2 Data !ype Definition

!.2.1.2.1 %denti'erTye enumeration


16/22




VERSION: 0.3


!.2.1.2.! ReerenceData structure

Element

name

Element

type

Option

al

Des*ription

eferen"ete

m

+arameter3y

'e1..unbun

dedE

? t is used "arry sme referen"e data t$at )) need nt analy/e but

need t re"rd it int transa"tin lg..

!.2.1.2.$ Transaction structure

Element

name

Element

type

Option

al

Des*ription

CmmandD sd>string ? 3$e uni6ue identifier f transa"tinJbusiness 'eratin. )a lengt$is =4.eg

• egister;<

string es t indi"ates language. t:s reser,ed.

GriginatrC

n,ersatinD

sd>string ? 3$e uni6ue identifier f t$e re6uest message generated by t$ird

'arty. t is used t identify a re6uest beteen t$e t$ird 'arty and)). )a lengt$ is 128.

Field must start it$ t$e Grganisatin s$rt and name f

rganisatin. #g.

2&2&2&H%CBGrgH

must be uni6ue fr e,ery transa"tin.

Cn,ersatin

D

sd>string es 3$e uni6ue identifier generated by )) fr a 're,ius re6uest

message. t is used t su''rt "mmuni"atin multi-times beteen

t$e t$ird 'arty and )) fr ne 'eratinJtransa"tin.

emar! sd>string es 3$e remar! infrmatin abut t$is 'eratin. )a lengt$ is 255

+arameters +arameters es t is used t "arry s'e"ifi" 'arameters fr s'e"ifi" transa"tin r

business 'eratin. 3$is ser,i"e ill $a,e ne 'arameter ty'ees'nse3y'e and t$e ,alue "an eit$er be "m'lete r "an"el.

3$is is t$e a"tin t$at ill be ta!en in-"ase t$e &rd 'arty (alidatin

;< registered are nt rea"$able.

eferen"eData eferen"eData ? t is used "arry sme referen"e data t$at )) need nt analy/e butneed t re"rd it int transa"tin lg.1. (alidatin;< is t$e %ey and t$e (alue is t$e (alidatin

*er,i"e ;< n t$e &rd 'arties end.

2. Cnfirmatin;< is t$e %ey and t$e (alue is t$e

Cnfirmatin *er,i"e ;< n t$e &rd 'arties end.

3imestam' sd>string ? 3$e timestam' generated by t$e t$ird 'arty.

!.2.1.2.4 Caller structure

Element

name

Element

type

Option

al

Des*ription

Caller3y'e sd>integer es ndi"ates t$e ty'e f t$e "aller>

2-A+Caller

1=


17/22




VERSION: 0.3


&-Gt$ereser,ed. Fr t$is ser,i"e use 2.

3$ird+artyD sd>string es 3$e uni6ue identifier f a t$ird 'arty system defined in )). tindi"ates t$e t$ird 'arty $i"$ initiates t$e re6uest. )a lengt$ is

20 3$is 'arameter is nt used in t$is ser,i"e. string es 3$is se"urity "redential f t$e 3$ird+artyD defined in )). f t$e 'assrd feature fr t$ird 'arty is used in )) t$en t$is 'arameter

must be 'resented in t$e re6uest message. 3$is 'arameter is nt

used in t$is ser,i"e.


18/22




VERSION: 0.3


Caller Caller es t indi"ates t$e t$ird 'arty $i"$ initiates t$e re6uest

nitiatr nitiatr es t indi"ates t$e identity $ ma!es t$e re6uest. An initiatrmust be ne f t$e flling identity ty'es> *+ 'eratr Grgani/atin 'eratr11

?G3#3$e ,alue 11Or,ani1ation Operator ill be used fr all

t$e ser,i"es in t$is d"ument.

+rimary+arty +rimary+arty ? f business 'eratinJa"tin t$is element is nt 'resentI if

transa"tin t$is "an be eit$er t$e debit 'arty r t$e "redit 'arty

a""rding t t$e transa"tin ty'e. 3$e ,alue 1 Custmer

!.2.1.2.16 Re7uest structure

Element

name

Element

type

Option

al

Des*ription

3ransa"tin 3ransa"tin ? t indi"ates a transa"tin.

dentity dentity ? 3$is se"tin is used t s'e"ify all identities in,l,ed in t$e re6uest

%eyGner sd>integer ? t indi"ates $i"$ %ey is used t en"ry't t$e elementsnitatr.*e"urityCredential and t$e #n"ry'ted+arameters.

ts ,alue are enumerated as flls>

1>t$e A+ CallerKs %ey

2>t$e nitiatrKs %eyFr t$is ser,i"e use 1.

2..4..44 8essae Header9 Re7uestS#)PHeader

Element name Element type Optional Description

*'d sd> string ? *+ D.

3$is is t$e *er,i"e +r,ider dentifier t$at is all"ated by t$e

Br!er t t$e &rd 'arty.

#am'leE 000201

18


19/22




VERSION: 0.3


Element name Element type Optional Description

*'+assrd sd> string es 3$is is an en"ry'ted frm f t$e *+ 'assrd issued t an *+ $en

an a""unt is "reated n t$e Br!er.

3$e en"ry'ted 'assrd is a Base=4 en"ded string f t$e *A-25= $as$ f t$e "n"atenatin f t$e s'd 'assrd and t$e

time*tam' as illustrated bel>

@i,en t$e flling 'arameters

s'd> =01&

'assrd> s'+assrd

timestam'> 201&0702212854

s'+assrd L BA*#=4*A-25=s'd M +assrd M time*tam'

e.g.

s'+assrd L BA*#=4*A-

25==01&s'+assrd201&0702212854

#am'leE

e=4&4ef24df55"7a21a0b45758a&bb

*er,i"ed sd> string es *er,i"e D.

3$is is t$e *er,i"e dentifier t$at is all"ated by t$e Br!er fre,ery ser,i"e "reated.

#am'leE

&500001000012

3imestam' sd> string es 3ime stam' ;3C time.

3$e ,alue is re6uired during *A-25= en"ry'tin fr s'+assrd.

?G3#

f t$e s'+assrd 'arameter must be set t$is 'arameter ismandatry.

FrmatE

yyyy))ddmmss

#am'leE

201007&10=4245

!.2.1.2.12 Resonse structure

Element

name

Element

type

Option

al

Des*ription

es'nseCd

e

sd>string ? t indi"ates $et$er )) a""e'ts t$e re6uest r nt.

es'nseDes"

sd>string es ts ,alue is a des"ri'tin fr t$e 'arameter esultCde.

Cn,ersatin

D

sd>string es 3$e uni6ue identifier generated by )-+esa fr t$e re6uest message.

1


20/22




VERSION: 0.3


GriginatrC

n,ersatinD

sd>string es 3$e uni6ue identifier generated by t$e t$ird 'arty fr t$e re6uest

message.

*er,i"e*tatus sd> integer es t indi"ates t$e )) ser,i"e status.

4.2.1.& Instan*e

Re/uest messages


21/22




VERSION: 0.3


+

+

HH-2

+


22/22




VERSION: 0.3


$ )nne*

Th !""!#h$ %& "h 'SDL (%) !$*+"$ (*, B G**$& ",!) !)%$!"%* #*(%,!"%*.

"BP(nter)ace*"2BPayment!alidation+nd"on#rmation.wsdl

22

m-pesa c2b developers guide

Documents