Saman Micro Payment

Technical Specification

Last update at:22 August, 2006 –22 Mordad ,1385

Saman MP Specification
# ' ( ) & &% " & # $ ! "
* % . + ,& - & * &) %

!"#
& 1 /0
# ' ( 1 0
% 2 1 /0

'( ) * ' $% $%&

% ' '
% '

$ * , - # & # ") +
5'3 4 "
5'3 4 67
6 %2 6

0 # 0 % / . $( .
Web service # $

%2 1
48 4
67 8 4
9 :

'( ) (5 - # * $ * , - # 4 % '.0 5 % 6 3
# ' ( %( & &
# ' ( % & &

Saman MP Specification
 !"#
? ( . 64 < /0 <= > 4 3 # $ % ;!

7
*& 3 A @ >4 3 % 0 ? 7
*& D 4 ' #C (& B :8 9

$ * ,
* % & & & & & 3 A 3% 0 ? $ * ,
# ' ( D 4 3 Acceptor ID Terminal ID E 3 4 ?(Merchant ID) $ * , 9
* % FG

'( ) (5
* % IJ G & 3 <% , B)H ?(Transaction) ;$9
& I / & ,& 3 , GM6 & I& 3 % KBL % ?'( ) (5 - #
/ I >( ,& - & )% 4 &# ' (# O NB2 = > )% &
%6 M 'H 4 % & 3 8 & P* & -=> I % " & <= >
U (7 Q & # R S T
% 2 3 3& 3 ! B!B ?(Reference Number) '. < 0 #
* % V& & # ' ( 5'3 4 " A & 'H
7% Q & & 5'3 4 # ' ( 3 3 ?(Reservation Number) * &
# ' ( ) & 5'3 4 GM6 8 & P * '3 C & < 3 I D 4 4% &
U*

+ Saman MP Specification
 '( ) * ' $% $%&
* % USSL certificateP % ' ' 7 S L4 W X Y ' Z@ .2
% % YB ( , H\] % )4 & \ I UEncryptionP & R7 3 [ & Z % ' ' 7
= > ' & ' _9 4 & /7 3 Z * % = & &3 ^ 3
Q & ^ - C' ^ & # 3 [&Z & * % #
`& I = a & ] * % # $ http 0 ^ 'L USecure httpP https . 4
`& I 3 % X & % = & % )L # 3 b ,& - , H\] http://www.sb24.com
3R * % = & &3 ^ # 3 ,& - , H\] https://www.sb24.com
' 7 & - /3 & % ' ' 7 3 ' % & & B % Y ^ 3
* ' # 3 EG ^ & # 3 Y4

' $% $%&
2L % ' ' 7 & U acquirer.sb24.com www.sb24.com P Y
& / # ' ( 7* " SSL ! & 4% # ' (, & 1 24& ' %
' * ,& - SSL ! & / # ' ( & 1 24& < 2L ' 7
* C' Y B < ! & 20 < 2L ' 7 & # ' (
<,& 3 , GM6 ' P & % , H\] 3c # ' ( 3 !' C % ' '
% , H\] Z c & # ' ( ] ) * 6 8B9 U **** 0 / <,& 3 / & )B3
* % & & & D 4 , H\] % )4 '3 %) ( & %
5'3 4 4 & 3 ' & " 7 ' ( D>( 3 C % ' '
# &I 7 B0 = ( & * ''3 & - & 5'3 4 & 67 &
& - I % # 0 4< # # ' ( IP `& I # K>d UAcquirerP
*
# # ' ( / & )B3 < ' & 67 & C' & # ' ( ' )]
# UPayment gatewayP # 7& 5'3 4 67 C' & 3 %
U % # # ' ( e] = & # ' ( # & C' & / & )B3 P *

'( ) $%&
# O g 'H & I ) : ( ^ fH % / & # O # ' (
FG Merchant ID #& ) / * ) %( L g# ' (
* '3% %( L #& ) V& & # ' ( 5'3 4 & 3

Saman MP Specification
 $ * , - # & # ") +
;$9 ><
9> & * % 3% Y = ( & # I 3 &% 9> & & # ' (
? ) = 2 & .X # ' (
2 ^ & : # , '% '( ) (5 - # 1* ) 7, $ * , *h
# POST ,& - 3 & ; * % URedirectP # (%
? '4& 2H %
Total Amount *i

Merchant ID *ii

Reservation Number *iii

Redirect URL *iv

* ) ( & & % # ' ( 3 % NB2 Total Amount

* 5'3 4 & # ' (% ' 3 # ' ( 3 Merchant ID
E >L4 cookie session " Reservation Number Y # ' (
& = & % 2 `& I * '3 # $ ^ & 67 (&
3& 9 ) * % https://acquirer.sb24.com/CardServices/controller
* '3 % # $ % ' ' 7 ^ . 4 ^ % # 6
) )@ & & R7 % & & # ' ( 3 & & 20 & . 3:
* # # & Ii

2 ^ & : $9 '% 0 * ? @A% > , 0 4B % * 8 9 8 @AC% 7 *j

? '3 & & . & ,& 3 , H\] & <%
UPANP ,& 3 #& ) *i
UPINP & 2H )B3 *ii
UExpire DateP ,& 3 f> k & 4 *iii
CVV2 *iv

& & %- & 3 c # ' ( # # % 2 ^ & & ? 04

*&

2 ^ : # , '% $ * , - # 1* ) 7 '( ) (5 - # 1* *l
% RedirectURL `& I # ' ( #& && <5'3 4 )4 A %
&% 2 ^ # ` & # ' ( U '3 % RedirectP (
? '4& 2H % & & * '3% ( & POST
Transaction State *i
Reference Number *ii
Reservation Number *iii

= Saman MP Specification
: * m M64 & 5'3 4 / I >( <5'3 4 L@ ` 4% # ' (
* # # & I i ) )@ & & . 3
B( & : F 'F% GFH F B * 0 '% E AC ;$9 - * $ * , *n
P # / I >( I 3 0 4% # ' ( 5'3 4 L@
7 I *U # # & I i ) )@ & I & 7 ; )G4 # d B( K & >
FM , F) F F) %B 0 * ) J7 -# K % $ * ,0 5 %B - L, %
0 0 * 'N F FH F O) FL N0 * ) * 02 7 ) ;$9 - *
& UReference Number P% " &# ' (< OK 5'3 4 L@ 7 -#
Double Spending 7 B0 & Q' & 3 * '3% " !0 # #C &
% # ' ( # YH \ 3 Bo! * % % " & eG &
% & - e ] UUniqueP ( Gd' ,& - % " &
& * % ) 6 & % B)L A H c % " & eG & &
& & Verify Web Method <# ' ( %4 H\] & I 0 H ,& -
? % -
Reference Number *i
Merchant ID *ii

%67 & > * )' $ 3 5'3 4 % ( & " - & )# ' (

& 5'3 4 ,& - b& UTotal AmountP
.3 & > 84
Xn & & & # ' ( 3 & 3 ( NB2 NB2
! > * % . 6
? I 0 )
* ) & & A 4% # ' (< ' NB2 7 *i
Up BX P
A 4% # ' (< # ' ( & 3 ( NB2 )3 % NB2 7 *ii
* / 67 & ' .3 <& \H
A 4% # ' (< # ' ( / & 3 ( NB2 6 % NB2 7 *iii
* / 67 & ' , $ <& \H
9 : 3 % % 9 & C %$' 7 8 4 %0 *iv
* # # & I ^ ) )@ & /

* # I ^ ) )@ & / 8 4 .3 :

& 3& & & % " &# ' ( <5'3 4 & ,& - & : 7 * P ( *p
& 'H
5'3 4 .2 3P Reservation Number I 1
# # C & U # # ' ( ` ^ 5'3 4 L # # `
4 % # +% " & / % > NB2 2 & ,& - & * '3% # +
X 2 \ )H 'q V & # ' ( & I 67 & &
* I 0

D Saman MP Specification
 :8 (
& C % L4 # ' ( ) & % " & %7 e G 3 % 3 4 #& US
E 44 * % [& /7 & % " & # & M 67 NB2 & 2 H Y'4 * ) &
L@ 3 I [& /7 # ' ( & 'q & % " & , GM6 4%
&% " & # ' ( 7 3 & [& !X * '3 r4 I %7 e G
%B ^ 0 % & = & # ' ( & " / %"' & 2 H
#& 4% # ' ( M & &2 H % " &< # ' (
# 3# + # # C & & I " 2a ,& - & ) %"' & 2 H @ >4
* r4 # e G & 5'3 4 & L@
< TimeoutP # ' ( %B verifyTransaction 8 4 ^ 0 3 %4& - & U^
& 4 * ) %L " %GM6 L4 # ' ( U *** # I5 2 . 6
verifyTransaction " ' < # ' ( ^ 0 3 " %4& - &
^ 0 ' 7 # ' ( E 0 [\4 %GM6 L4 L *U %$' P 9 # ' 6
* / 67 . 3 & ] & 5'3 4 '3 %L # ' (< 6 ( &
j a3 X H h . X @ X = X & P %GM6 , & %B 5'3 4 3 %4& - & U,
* 3 5'3 4 67 < 6 4# ' (E 0 U H
0 < # $ SBM # ' ( & % " & ' < t[ & & Us
. % ( 7 # ' ( # O #& ) IP #& ) 04 & ! B0 3 q < &
# & %$L @ ,& - & # ' ( # YH Double Spending 7 B0 ! UW
* 0 I & @ <# ' (
* # 4 ACL SSL )3 ; ! 5M ' U:
[ ( C & 0 S> # $ 5M !& Uu
# O !& / 4% # O = > S> L4 & * 7% ,& - # ' (
[ ( N 2 a3 X < [ ( C %( L # ' ( 'v) * ) &
* ) % %( L &

;$9 -CI )
8 & ,& - ) * '3 # & r 4% # ' (
?
& A 3 C # ' ( ) =a P & r # ' ( •
*U . d4 && Q
* r . & •

? 67 ,& - & 4% # ' (< X &

& # O #& 6 7 . 3 ,& - ' :(Full Reverse) P% 9 -CI ) *h
# ' (& 3 *& NB2 # ' ( # O % & ! NB2
& Reservation Number 1 % " &< # #C # $
3 o)9 I %7 & 67 L@ 3 q AO ) W M & Q
2 , ] 24& & % 0 ( - q 2P # & M . 3 %V/0 67 \2

Q Saman MP Specification
Reverse Web AO *U 7% ,& - / ) & q 7
? (.+ & & Method

Merchant ID *i
Merchant Password *ii
Reference Number *iii
Reverse Amount = Total Amount of Invoice *iv

AO # ' (* % 6 & 67 " 3 3 % 67 & >

* # # & I ^ ) )@ & %0 : * )% & & # #C

* % 67 & NB2 %6M # ' ( ?(Partial Reverse) EN -CI ) *j

'3% 2 d & % 67 NB2 Business Rule ` # ' (&3
Q & Reservation Number 1 % " &< # #C # $
q &% " & %7 & 67 L@ # ' ( AO * ) % W M &
% V/0 6 7 6 3 ) # $ %V/0 67 & I %4& - & Y'4 '3
' N B2 . 3 6 % V/0 67 N 2 ( @ % 67 NB2 #&M
3 q 2 , ] 24& & % 0 ( - / 3 q 2P 2 6
Reverse ) 4% # ' ( ,& - & *U 7% ,& - / ) & q
? (.+ & & Web Method
Merchant ID *i

Merchant Password *ii

Reference Number *iii

Reverse Amount = Desired Reverse Amount *iv

X & * % 6 & 67 " 3 3 % 67 & >

I 1 % " & L@ ) & & # # C # ' (
& L % V/0 67 4 ) #& 67 & Reservation Number

* )

:8 (
& & - 5 % " & %7 & 67 L@ & % / 3 % 3 4 #& US
&# & M 67 NB2 <# ' ( & 0 .2 3 qw q# ' (D 4< I
* )% 0 & 67 & <NB2 $3 ,& - & '3% 2 d & % "
& 3 7 o)9 3 I & -# ' ( / 67 & U^
7 " & * '3% q & & 2H )B3 # ' ( IP #& ) < # & -# ' (
& 2H )B3 < '3 bI & 67 ' ( 4% & 3 7 # ' (
* ) hard code < # & &
# 4 Merchant IP and Password ACL <SSL )3 ;! 5M ' Ui
*

R Saman MP Specification
%(L # ' (* 7% ,& - # ' ( [ ( C # $ 5M !& U,
& " & * ) % %( L & [ ( N 2 a3 X < [ ( C
* M x E 4 4 < 7% & C W& 3 % 67

:Online Demo
* '3 L0 http://demo.sep.ir `& I < # &' online demo # 6

?Sep IMS
`& I 4% & & ( 7 ,& - Y6 '3 4 ! online # 6
& P* V ) L0 https://acquirer.sb24.com/MerchantService/jsp/loginPage.jsp
U* C ` )4 %'( 5M I ( & Y0 3 & 2H )B3 ;!

4 C% ' 5 C6
3 '3 % ^ " ' < U & 2 P zyjn , V & = X& ) 3 0 I
% 3 ` )4 9> * 7 2L4 ) & / zyjn % / ( ` )4 9> K ] %2 6
* # 5 ) # ' ( ^ & & I _@ ,& G Email $B4 . 4

S Saman MP Specification
 0 # 0 % / . $( : .
9> 9> %] 24& # # $ Web Services { ' 4 ; ! #
& %L 4 E & % & E 0 3% A = & * 7% & # ' (
; >! ,& - & 8 4 4% # ' ( * ) # $ I & 4 7% & # ' ( &
* -
1
' SOAP . 4 * SOAP . 4 K9 4 & , H\] = >
HTTP . 4 # YH # = > / ,& O! 4 & * '3% # $ XML & #
* % HTTPS
# { ' 4 4% # ' ( 3 & Web Services # $ !X
)H web method ( 3 consume # d % = a * ) # $
* 7# Y I 4% # ' ( # Y4 0 { ' 4

: Web Method & 0 #

& PHP Module <PHP { ' 4 d4 Web Method # $
U# # 3 ) K 9P 3& & I ! ) (@ # ' (;! NuSOAP

* ) mM6
& SDK * ) EG # ' (;! & & SOAPSDK ASP { ' 4 d4
) & I # $ [ &* ) ( & http://www.microsoft.com/downloads 4%
* # I 3
# $ Web Method - .NET %2 6 4 % ASP .NET { ' 4 &
* # # &I 3 ) & # $ [ &* 3
M! & 2 P 3# $ %! %2 6 4 % / %$ { ' 4 &
% Bd ,& - & Web Service ) % $ M! 7 *U & 0 %2 6 %$ %-
,& - SOAPSDK * ) # $ SOAPSDK & /( ! 4 % < '3%) % 2 6
%$ 3 ) * 3 # $ I 4 % %! Y a3 & 3 | & ActiveX
* 0 X
^ - 3 ) * % - 4 SOAP-Lite & /( ! # $ Perl { ' 4&
* 0
3 client.jar # " interface & wrapper < 0 { ' 4
* & classpath & UWeb Services # $ D24 jar C # ) P& I

1
Simple Object Access Protocol

T Saman MP Specification
 Web Methods 2 :1

& %0 & & : 3 7% & 7 ' (& & (Web Method) 8 4

& 3 ' % % H <% 67 & > type 3 0 4* # I.+
* # mM6 8 4 I 8 4 % 67 & > 'v) * ' , $4 ) %!

;$9 G V) U
double verifyTransaction (

String RefNum,

String MerchantID,

8 4 & &
8 W % 6
3 * ! D 4 I 4 . 3 % " & #& ) String RefNum

* 3 & 3 j}
&3 ,& - 3 '3% V & & 3 # ' ( *# ' ( 3 String MerchantID

# O #& ) K 94 AO * 7% C # O #& )
& ! <# # t% " & 1 ' & 3 # O #& )
% " & 3 7 o)9 # ' ( 4 7% q < #
* % 1
verifyTransaction & : h~S = 0

< %$' 3 %4& - & % 6 & % > NB2 < 2a 3 %4& - & & > ?8 4 % 67 & >
* # I l~S = 0 & 9 3: * 9 3e L

Saman MP Specification
 ;$9 40& -CI ) V) ~j
int reverseTransaction (

String RefNum,

String MerchantID,

String Password,

Double RevAmount

8 4 & &
8 W % 6
3 * ! D 4 I 4 . 3% " & #& ) String RefNum

* 3 & 3 j}
#& ) &3 ,& - 4 '3% V & & 3 # ' ( *# ' ( 3 String MerchantID

# O #& ) & # O #& ) K 94 * 7 C # O

q< # & ! <# # t% " & 1 ' & 3
* 7%
# ' ( / & )B3 String Password

* 67 % " & 1 ' . # ' ( 3 %rB2 Double RevAmount

NB2 NB2 3 '3% q 67 & 0 5

* )3 6 %V/0 67 N 2 Z )" x => '
reverseTransaction & : j~S = 0

>( e L h % 67 & > * % ' ( 67 , B)H L@ e L & > ?8 4 % 67 & >

. # I l~S = 0 & 9 3: * ' % 9 3 % $' > 67 &

Saman MP Specification
 J7 92

8 * 9
*% 2 %B 9 -1

U I %) 0 D @X=X& P* ' ! # O -2

* ' % " b 3& 3 X & -3

U #2 # ' ( 3 & 2H )B3 P Merchant Authentication Failed -4

Database Exception -5

* ( . 3 67 \2 ' -6

* %Y4 % " & -7

* " X 6 & =] -8

*% 67 NB2 & " b 3& 3 0 -9

*U " b 3& 3 XP ! Base64 ,& - % " & -10

* " X )3 & =] -11

* %$' % 67 NB2 -12

* % " & #&M 67 NB2 5 %V/0 67 % 67 NB2 -13

* # 6 S L4 %6'3 4 'q -14

* # # & 6H ,& - % 67 NB2 -15

;! %B 9 -16

* ( R " b% ,& 3 3 %6'3 4 % /0 67 -17

* 2L # ' ( IP Address -18

9 3: l~S = 0

* ' % %$' %C) 3 > *

+ Saman MP Specification
 '( ) (5 - # * $ * , - # 4 % '.0 5 % 6 :3

, H\] 1 24& & '3% V & POST ,& - % 2 # ' ( 3% &

? ' % 5'3 4

8 % 6
= & NB2 Amount

Reservation Number ResNum

# ' ( 3 MID

5'3 4 " (7& # ' ( & 3 URL `& I RedirectURL

* % = & POST ,& - d$-

2 d$ - T 4 '3% V & POST ,& - % 2 # ' ( 3% &

? 7 K 9 &%

8 % 6
= 0 •& TableBorderColor

/3 = 0 ' A • & TableBGColor

%B- d$- ' A •& PageBGColor

%B- d$- •& PageBorderColor

d$- %B- 'H ( TitleFont

d$- %B- 'H • & TitleColor

d$- %B- 'H (# TitleSize

* ' % 6 & & > ,d @ 4 3% ( TextFont

* ' % 6 & & > ,d @ 4 3% •& TextColor

* ' % 6 & & > ,d @ 4 3% (# TextSize

* ' % 6 & Ug# ' ( g ' P & 'H 3 % ( TypeTextColor

* ' % 6 & Ug# ' ( g ' P & 'H 3 % •& TypeTextColor

6 & Ug# ' ( g ' P & 'H 3 % (# TypeTextSize

* ' %
# ' ( 7 . (% ' `& I LogoURI

Saman MP Specification
 ? 7% POST ,& - # ' ( % 2 3% &

8 % 6
Reservation Number ResNum

% " & RefNum

5'3 4 L@ State

:8 (
5'3 4 & %B 6 3 'L < 7 # ' (
%Y4 RefNum 3 %4& - & ?h
* # I 0 & D 4
,& - b& * OK State < # " >( 5'3 4 3 %4& - & ?j
& 5'3 4 K( . 4% B( )3 ) * % # 7 # I 0 9 :
* 6 &
" Cookie Based # ` & Session Management # ' ( 7 % X ?l
= )L X 5 & & 7 3 q ` & ResNum < #
* # 7 Expire 67 & # ' ( Session < &RC
& 3 %2 4 4 ) & r R ` !X q 3 €&/ e X 2! ; ! ?n
* & = & # 3+ # /0

04 &# I 0 9 Z ST # ' (< # #&I = 0& k & State B( >

? '3 mM6 & = 0

> X% L%
* # .!'3 & D 4 5'3 4 Canceled By User

6 %B- 5'3 4 NB2 <% 67 ' NB2 Invalid Amount

*
& < # & 5'3 4 67 & Invalid Transaction

* %) %B- 5'3 4 3 % X
* #2 ,& 3 #& ) Invalid Card Number

*& 0 %4& 3 # ''3 & - 'q No Such Issuer

C ,& 3 R7 ,& 3 f> k & 4 Expired Card Pick Up

* ! 2L
# & #2 24 l UPINP ,& 3 / & Allowable PIN Tries Exceeded Pick Up

* = L( b ,& 3 " &

# 3 & #2 & UPINP ,& 3 / & & Incorrect PIN

= Saman MP Specification
 * % S> 5 NB2 Exceeds Withdrawal Amount Limit

PIN#& ) P # Authorize 5'3 4 Transaction Cannot Be Completed

& ' % U '! & PAN

*& 0
#& Timeout % 2 & 5'3 4 Response Received Too Late

*
& ExpDate B ( CVV
2 B( & Suspected Fraud Pick Up

U # & \- P * # #2
*& 0 ^ !X & %( 3 0 No Sufficient Funds

L @ & # ''3 & - ,& 3 ; ! Issuer Down Slm

* ! %4 B)H
'q " •H % C 9 B3 TME Error

* 7% % 9

(
3 C UPINP ,& 3 / & ‚ & % *; & / & #& ) j ' & ,& 3 # $ 8 &
& ' POS ATM # $ ;H Y6'3 4 % )4 & ,& 3 PIN * % UCVV2 P " /&
! / & CVV2 7 % ,& 3 = L( b •H 6 & l # 2 & ,& - & % # $
# $ Y0 D >( % ,& 3 #& ) hƒ 4 hz & ; & l & # i q ,& 3 6 & 3
3+ . * 7 %) ,& 3 = L( b •H ;! I#2 & % '
,& 3 # ''3& - 2L CVV 2 „ L4 L0 ] ATM ,& 3 PIN „ L4
* L0

'. < 0 # * * ;$9 >< ) G ) - # Y 0B

? 7% ,& - . + `& I K ] % 2 , H\] = &
https://acquirer.sb24.com/CardServices/controller

Web Service Provider Y 0B

3 ) < 6 , V/0 * '3 # $ .+ `& I % Web Method (
? '3 Z 0& # $ & { ' 4 1
https://acquirer.sb24.com/ref-payment/ws/ReferencePayment?WSDL

https://acquirer.sb24.com/ref-payment/ws/ReferencePayment

G )- # * ) >< ;$9 C%
?# " 5'3 4 # 6 `& I
https://acquirer.sb24.com/MerchantService/jsp/loginPage.jsp

* ( V& & & 2H )B3 # ' ( 3 )! %

D Saman MP Specification
 $ * , 9
% 2 6 5M I ( & * % 002XXX-XXXX ,& G ) UMerchant P# ' ( 3
ID

* C ` )4

Q Saman MP Specification