Behpardakht Mellat Co
Behpardakht Payment Gateway
User Guide: How to integrate with Behpardakht
Payment Gateway
Revision: 1.1
Revision: 1.1 Behpardakht Payment Gateway
Date: May 2013 User Guide: How to integrate with Behpardakht Payment Gateway
Index
1. Introduction ......................................... 2
1.1 Scope .......................................... 2
2. Method description in payment flow ......................... 2
2.1 Prerequisites ...................................... 2
2.2 How to use Web Service ............................... 3
2.3 Methods Parameter .................................. 3
2.4 Methods Description ................................. 4
2.4.1 bpPayRequest method ............................... 4
2.4.2 bpVerifyRequest method .............................. 6
2.4.3 bpSettleRequest method .............................. 6
2.4.4 bpInquiryRequest method ............................. 7
2.4.5 bpReversalRequest method ............................ 8
2.5 Return Parameter ................................... 9
2.6 Response code descriptions ............................ 9
Page 1 Behpardakht Mellat Co
Revision: 1.1 Behpardakht Payment Gateway
Date: May 2013 User Guide: How to integrate with Behpardakht Payment Gateway
1. Introduction
Mellat Bank Payment Gateway enables internet merchants to accept online payments
via cards accepted by Shetab network. Mellat Bank Payment Gateway provides secure
and simple means of authorizing Shetab card transactions and takes complete
responsibility for the online transaction, including the collection of card details.
Mellat Bank Payment Gateway uses web service technology over SSL secure link to
expose payment services to merchants. This use the basic web services platform for
transferring data in XML + HTTPS.
The advantage of using Web Services for publishing payment services is that Web
Services are found and used through the web and merchants can use an ecommerce
engine with any programming language to integrate with it. Behpardakht has provided
sample clients for main programming language to make it easy for merchants to have
online payment in their websites.
1.1 Scope
This document explains how your website should communicate Mellat Bank Payment
Gateway, goes on to explain how to integrate with our live environments, and contains
the complete Payment Protocol.
2. Method description in payment flow
2.1 Prerequisites
IP addresses of Merchant host should be officially informed to Mellat Bank to give
privilege to access payment gateway services.
Merchants should make sure to have port 443 and 80 open in their host.
Page 2 Behpardakht Mellat Co
Revision: 1.1 Behpardakht Payment Gateway
Date: May 2013 User Guide: How to integrate with Behpardakht Payment Gateway
2.2 How to use Web Service
WSDL (Web Services Description Language) is an XML-based language for describing
Web services and how to access them. Mellat Bank Payment Gateway WSDL is
accessible with the following links.
Operational Server:
https://bpm.shaparak.ir/pgwchannel/services/pgw?wsdl
2.3 Methods Parameter
Parameters which merchant should pass in calling methods or getting them back in
return are as following:
1. terminalId: Merchant terminal number
2. userName: Merchant terminal username
3. userPassword: Merchant terminal password
4. amount: Transaction amount
5. localDate: Merchant local date
6. localTime: Merchant local time
7. additionalData: Some Additional data to keep for this transaction
8. callBackUrl: Callback URL of merchant which the customer will be redirected
back after payment accomplished.
9. payerId: Merchant Payer ID
10. orderId: Merchant should provide a number for each new payment transaction
too keep track of final payment status. This number must be unique in calling
bpPayRequest and bpRefundRequest.
Page 3 Behpardakht Mellat Co
Revision: 1.1 Behpardakht Payment Gateway
Date: May 2013 User Guide: How to integrate with Behpardakht Payment Gateway
11. saleOrderId: To distinguish between method calls, merchant can send a unique
orderId in consequence method calls after bpPayRequest or bpRefundRequest.
12. saleReferenceId: This is a unique number generated for successful sales by
Mellat Bank Payment Gateway and must be used as main transaction identifier
in consequence method calls.
Note: All parameter names are case-sensitive
2.4 Methods Description
Mellat Bank Payment Gateway publishes 8 methods, which the first 3 ones are building
the core elements of online payment flow and the remained 5 methods will be handy in
special cases.
2.4.1 bpPayRequest method
This method is called by merchant to initial a payment transaction. In this step, terminal
and transaction validity will be controlled and if terminal is authorize by the Mellat Bank
Payment Gateway, a unique encrypted hash reference number will be generated and
sent back in return which Merchant site should use it to redirect customer to Mellat
Bank Payment Gateway site.
This method will return a string as a result which in case of an error, it will include
relevant response code, otherwise it will include a zero as approved response code plus
a second part which will be the encrypted hash reference number.
Example: 0, AF82041a2Bf6989c7fF9
The two values are comma separated.
The first part is the response code (for more information, see table 10)
The second part is an encrypted hash reference number which should be post to
Mellat Bank Payment Gateway when redirecting customer to.
Page 4 Behpardakht Mellat Co
Revision: 1.1 Behpardakht Payment Gateway
Date: May 2013 User Guide: How to integrate with Behpardakht Payment Gateway
The URL which the encrypted hash reference number should be posted to is as
following:
Operational Server:
https://bpm.shaparak.ir/pgwchannel/startpay.mellat
Row Parameter Name Example Description Type
1 terminalId 1234 Merchant Terminal Identifier long
2 Merchant Username string
userName “User”
3 userPassword “******” Merchant Password string
4 orderId 10 Order Identifier long
5 amount 1 Order Amount long
6 localDate “20101008” Merchant Local Date string
7 localTime "102003" Merchant Local Time string
8 “Have 3 items in Any text with 1000 characters
additionalData string
basket” limit
9 “http://www.mysite.com/ The Merchant URL which
callBackUrl myfolder/callbackmellat. customer will be redirected to string
aspx” at the end.
10 payerId 0 Payer Identifier long
Table1: bpPayRequest Input parameters description
Note: Order Id should be unique in each pay request call.
Note: Use your site domain address instead of IP address in callBackUrl.
Note: encrypted hash reference number value is case-sensitive.
Note: Merchants who have payer Id in theirs bank account, can pass the correct
value in pay request call, otherwise, you must pass “0” as default value.
Page 5 Behpardakht Mellat Co
Revision: 1.1 Behpardakht Payment Gateway
Date: May 2013 User Guide: How to integrate with Behpardakht Payment Gateway
2.4.2 bpVerifyRequest method
When card holder made payment transaction in Mellat Bank Payment Gateway site,
some information including ResCode and SaleReferenceId will be posted back to
merchant and then merchant should confirm payment transaction by calling
bpVerifyRequest method and passing the following parameters to:
Row Parameter Name Example Description Type
1 terminalId 1234 Merchant Terminal Identifier long
2 Merchant Username string
userName “User”
3 userPassword “******” Merchant Password string
4 orderId 11 Order Identifier long
5 orderId of pay request
saleOrderId 10 long
(Original Order identifier)
saleReferenceId returned in
6 saleReferenceId 5142510 long
pay request
Table2: bpVerifyRequest Input parameters description
Note: The Return Value of this method call will be a string which shows the verify
request result (See table 10 for the list of response codes).
Note: Merchants should display the right message in their site according to returned
ResCode.
Note: If Merchant doesn’t verify payment transaction after 15 minutes, the payment
transaction will be reversed automatically by Mellat Bank Payment Gateway and the
money will be charged back to card holder.
2.4.3 bpSettleRequest method
Merchant can settle payment transactions which already were verified successfully at
any time by calling bpSettleRequest an passing the following parameters:
Page 6 Behpardakht Mellat Co
Revision: 1.1 Behpardakht Payment Gateway
Date: May 2013 User Guide: How to integrate with Behpardakht Payment Gateway
Row Parameter Name Example Description Type
1 terminalId 1234 Merchant Terminal Identifier long
2 Merchant Username string
userName “User”
3 userPassword “******” Merchant Password string
4 orderId 12 Order Identifier long
5 orderId of pay request
saleOrderId 10 long
(Original Order identifier)
saleReferenceId returned in
6 saleReferenceId 5142510 long
pay request
Table3: bpSettleRequest Input parameters description
Note: The Return Value of this method call will be a string which shows the settle
request result (See table 10 for the list of response codes).
Note: Merchants should call settle request method to release the payment
transaction and transfer payment amount to their bank account.
2.4.4 bpInquiryRequest method
Merchant can get status of verify request (sale and it's verify) at any time by calling
bpInquiryRequest method and passing the following parameters to:
Row Parameter Name Example Description Type
1 terminalId 1234 Merchant Terminal Identifier long
2 Merchant Username string
userName “User”
3 userPassword “******” Merchant Password string
4 orderId 13 Order Identifier long
5 orderId of pay request
saleOrderId 10 long
(Original Order identifier)
Page 7 Behpardakht Mellat Co
Revision: 1.1 Behpardakht Payment Gateway
Date: May 2013 User Guide: How to integrate with Behpardakht Payment Gateway
saleReferenceId returned in
6 saleReferenceId 5142510 long
pay request
Table4: bpInquiryRequest Input parameters description
Note: The Return Value of this method call will be a string which shows the inquiry
request result (See table 10 for the list of response codes).
Note: Merchants should just call this method when it is not aware of verify request for
any reason.
2.4.5 bpReversalRequest method
If Merchants decided to not deliver products or services to card holders till current
working day, they can cancel the payment transaction and charge back the cardholder
with the order amount by calling bpReversalRequest method and passing the following
parameters:
Row Parameter Name Example Description Type
1 terminalId 1234 Merchant Terminal Identifier long
2 Merchant Username string
userName “User”
3 userPassword “******” Merchant Password string
4 orderId 14 Order Identifier long
5 orderId of pay request
saleOrderId 10 long
(Original Order identifier)
saleReferenceId returned in
6 saleReferenceId 5142510 long
pay request
Table5: bpReversalRequest Input parameters description
Note: The Return Value of this method call will be a string which shows the reversal
request result (See table 10 for the list of response codes).
Note: Merchants can just reverse not settled payment transaction till 2 hours after
the pay transaction by calling reversal request method.
Page 8 Behpardakht Mellat Co
Revision: 1.1 Behpardakht Payment Gateway
Date: May 2013 User Guide: How to integrate with Behpardakht Payment Gateway
2.5 Return Parameter
The following parameters posted back to merchant call back URL after payment
transaction by Mellat Bank Payment Gateway:
Row Parameter Name Example Description Type
1 RefId AF82041a2Bf689c7fF9 Merchant Terminal Identifier long
2 Merchant Username string
ResCode 0
3 orderId of pay request
SaleOrderId 10 string
(Original Order identifier)
4 SaleReferenceId 5142510 Sale reference Id long
5 C9086F2AACF739F7D Encrypted information of card
50ACC9FDC60C53E81 holder (One way encrypted
CardHolderInfo string
0FB9135723D256732C PAN)
E4D1E2E409F7
Table9: Return parameters posted to merchant callback URL
2.6 Response code descriptions
Response Code Description
0 Transaction Approved
11 Invalid Card Number
12 No Sufficient Funds
13 Incorrect Pin
14 Allowable Number Of Pin Tries Exceeded
15 Card Not Effective
16 Exceeds Withdrawal Frequency Limit
17 Customer Cancellation
18 Expired Card
19 Exceeds Withdrawal Amount Limit
111 No Such Issuer
112 Card Switch Internal Error
113 Issuer Or Switch Is Inoperative
114 Transaction Not Permitted To Card Holder
21 Invalid Merchant
23 Security Violation
Page 9 Behpardakht Mellat Co
Revision: 1.1 Behpardakht Payment Gateway
Date: May 2013 User Guide: How to integrate with Behpardakht Payment Gateway
24 Invalid User Or Password
25 Invalid Amount
31 Invalid Response
32 Format Error
33 No Investment Account
34 System Internal Error
35 Invalid Business Date
41 Duplicate Order Id
42 Sale Transaction Not Found
43 Duplicate Verify
44 Verify Transaction Not Found
45 Transaction Has Been Settled
46 Transaction Has Not Been Settled
47 Settle Transaction Not Found
48 Transaction Has Been Reversed
49 Refund Transaction Not Found
412 Bill Digit Incorrect
413 Payment Digit Incorrect
414 Bill Organization Not Valid
415 Session Timeout
416 Data Access Exception
417 Payer Id Is Invalid
418 Customer Not Found
419 Try Count Exceeded
421 Invalid IP
51 Duplicate Transmission
54 Original Transaction Not Found
55 Invalid Transaction
61 Error In Settle
Table 10: Response code description
Page 10 Behpardakht Mellat Co
