Behpardakht Mellat Payment Gateway PGW User Manual English Ver 1.1

User Manual:

Open the PDF directly: View PDF .
Page Count: 11

Behpardakht Mellat Co

Behpardakht Payment Gateway

User Guide: How to integrate with Behpardakht

Payment Gateway

Revision: 1.1

Behpardakht Payment Gateway

Revision: 1.1

User Guide: How to integrate with Behpardakht Payment Gateway

Date: May 2013

 Behpardakht Mellat Co

Page 1

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

Behpardakht Payment Gateway

Revision: 1.1

User Guide: How to integrate with Behpardakht Payment Gateway

Date: May 2013

 Behpardakht Mellat Co

Page 2

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.

Behpardakht Payment Gateway

Revision: 1.1

User Guide: How to integrate with Behpardakht Payment Gateway

Date: May 2013

 Behpardakht Mellat Co

Page 3

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.

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.

Operational Server:

https://bpm.shaparak.ir/pgwchannel/services/pgw?wsdl

Behpardakht Payment Gateway

Revision: 1.1

User Guide: How to integrate with Behpardakht Payment Gateway

Date: May 2013

 Behpardakht Mellat Co

Page 4

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.

Behpardakht Payment Gateway

Revision: 1.1

User Guide: How to integrate with Behpardakht Payment Gateway

Date: May 2013

 Behpardakht Mellat Co

Page 5

The URL which the encrypted hash reference number should be posted to is as

following:

Row

Parameter Name

Example

Description

Type

1

terminalId

1234

Merchant Terminal Identifier

long

2

userName

“User”

Merchant Username

string

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

additionalData

“Have 3 items in

basket”

Any text with 1000 characters

limit

string

9

callBackUrl

“http://www.mysite.com/

myfolder/callbackmellat.

aspx”

The Merchant URL which

customer will be redirected to

at the end.

string

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.

Operational Server:

https://bpm.shaparak.ir/pgwchannel/startpay.mellat

Behpardakht Payment Gateway

Revision: 1.1

User Guide: How to integrate with Behpardakht Payment Gateway

Date: May 2013

 Behpardakht Mellat Co

Page 6

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

userName

“User”

Merchant Username

string

3

userPassword

“******”

Merchant Password

string

4

orderId

11

Order Identifier

long

5

saleOrderId

10

orderId of pay request

(Original Order identifier)

long

6

saleReferenceId

5142510

saleReferenceId returned in

pay request

long

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:

Behpardakht Payment Gateway

Revision: 1.1

User Guide: How to integrate with Behpardakht Payment Gateway

Date: May 2013

 Behpardakht Mellat Co

Page 7

Row

Parameter Name

Example

Description

Type

1

terminalId

1234

Merchant Terminal Identifier

long

2

userName

“User”

Merchant Username

string

3

userPassword

“******”

Merchant Password

string

4

orderId

12

Order Identifier

long

5

saleOrderId

10

orderId of pay request

(Original Order identifier)

long

6

saleReferenceId

5142510

saleReferenceId returned in

pay request

long

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

userName

“User”

Merchant Username

string

3

userPassword

“******”

Merchant Password

string

4

orderId

13

Order Identifier

long

5

saleOrderId

10

orderId of pay request

(Original Order identifier)

long

Behpardakht Payment Gateway

Revision: 1.1

User Guide: How to integrate with Behpardakht Payment Gateway

Date: May 2013

 Behpardakht Mellat Co

Page 8

6

saleReferenceId

5142510

saleReferenceId returned in

pay request

long

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

userName

“User”

Merchant Username

string

3

userPassword

“******”

Merchant Password

string

4

orderId

14

Order Identifier

long

5

saleOrderId

10

orderId of pay request

(Original Order identifier)

long

6

saleReferenceId

5142510

saleReferenceId returned in

pay request

long

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.

Behpardakht Payment Gateway

Revision: 1.1

User Guide: How to integrate with Behpardakht Payment Gateway

Date: May 2013

 Behpardakht Mellat Co

Page 9

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

ResCode

0

Merchant Username

string

3

SaleOrderId

10

orderId of pay request

(Original Order identifier)

string

4

SaleReferenceId

5142510

Sale reference Id

long

5

CardHolderInfo

C9086F2AACF739F7D

50ACC9FDC60C53E81

0FB9135723D256732C

E4D1E2E409F7

Encrypted information of card

holder (One way encrypted

PAN)

string

Table9: Return parameters posted to merchant callback URL

2.6 Response code descriptions

Description

Response Code

Transaction Approved

0

Invalid Card Number

11

No Sufficient Funds

12

Incorrect Pin

13

Allowable Number Of Pin Tries Exceeded

14

Card Not Effective

15

Exceeds Withdrawal Frequency Limit

16

Customer Cancellation

17

Expired Card

18

Exceeds Withdrawal Amount Limit

19

No Such Issuer

111

Card Switch Internal Error

112

Issuer Or Switch Is Inoperative

113

Transaction Not Permitted To Card Holder

114

Invalid Merchant

21

Security Violation

23

Behpardakht Payment Gateway

Revision: 1.1

User Guide: How to integrate with Behpardakht Payment Gateway

Date: May 2013

 Behpardakht Mellat Co

Page 10

Invalid User Or Password

24

Invalid Amount

25

Invalid Response

31

Format Error

32

No Investment Account

33

System Internal Error

34

Invalid Business Date

35

Duplicate Order Id

41

Sale Transaction Not Found

42

Duplicate Verify

43

Verify Transaction Not Found

44

Transaction Has Been Settled

45

Transaction Has Not Been Settled

46

Settle Transaction Not Found

47

Transaction Has Been Reversed

48

Refund Transaction Not Found

49

Bill Digit Incorrect

412

Payment Digit Incorrect

413

Bill Organization Not Valid

414

Session Timeout

415

Data Access Exception

416

Payer Id Is Invalid

417

Customer Not Found

418

Try Count Exceeded

419

Invalid IP

421

Duplicate Transmission

51

Original Transaction Not Found

54

Invalid Transaction

55

Error In Settle

61

Table 10: Response code description