INTEGRATION MANUAL & GUIDELINES
Version 4.0
CONTENT
| NO | TITLE |
|---|---|
| 1 | Request For Payment |
| 2 | Sample Method Form 1 |
| 2.1 | Online Form |
| 2.2 | Simple HTML Form Coding |
| 3 | Receive Response Via Redirect URL (Browser) |
| 3.1 | Payment Response Parameters |
| 3.2 | Sample Receive Coding |
| 4 | Receive Response Via Callback |
| 4.1 | Payment Response Parameters |
| 4.2 | Sample Receive Via Callback URL |
| 5 | Web URL API Reference |
| 5.1 | Payment Request Form Submission |
| 5.2 | Query All Transactions Via ZenPay API |
| 5.3 | Query Transaction API Using Payment Reference ID |
| 5.4 | Query All Transaction Payment Status Via Gateway API |
| 5.5 | Settlement Request By Merchant API |
| 5.6 | Malaysia Bank/Finance Swift Code |
Request For Payment
There are two options merchants can integrate with payment page:
a) Merchant directly passes HTTP POST parameters to payment page.
b) Merchant sends parameters via curl to get payment session id. Once get payment session id then submit to payment page.
Using Method 1 (Direct HTTP Post)
Merchant must send the following parameters listed below to integrate with payment page :-
| NO | PARAMETERS & DESCRIPTIONS | STATUS PARAMETER | EXAMPLE |
|---|---|---|---|
| 1 | Billercode is provided by ZenPay after successfully registered. Character Length:10 | Mandatory | 200020021 |
| 2 | Hashkey is provided by ZenPay after successfully registered. This parameter will be validated at payment page interface. Character Length:32 | Mandatory | 9517fe9ea58068d1a239318713382ff1 |
| 3 | Amount in Ringgit Malaysia (RM) with 2 decimal places. Maximum Amount RM30000 per transaction and minimum value RM2 for Retail/Individual Account and Maximum Value RM1Million for Corporate Account(B2B) | Mandatory | 10.00 (for ten ringgit) |
| 4 | Order Reference is an Alphanumeric merchant order number reference ID Character Length:20 | Mandatory | 12345 |
| 5 | Return URL – browser to browser communication that allow ZenPay to redirect page to merchant web interactively. Web URL either http or https. All Response parameters can be referred Section 3.0 | Optional | http://marchant.com/rsp/webpayment.php (if returnURL is blank, ZenPay will remain at the Standard Receipt Page without any further redirection) |
| 6 | Callback URL Server to Server communication that allows ZenPay payment gateway to post payment status parameters using background mode. Response parameters can be referred Section 4.0 | Mandatory | https://marchant.com/rsp/bgpayment.php |
Using Method 2 (cURL Request)
STEP 1: Merchant must send the following parameters listed below via CURL –
| NO | PARAMETERS & DESCRIPTIONS | STATUS PARAMETER | EXAMPLE |
|---|---|---|---|
| 1 | Billercode is provided by ZenPay after successfully egistered. Character Length:10 | Mandatory | 200020021 |
| 2 | Hashkey is provided by ZenPay after successfully registered. This parameter will be validated at payment page interface. Character Length:32 | Mandatory | 9517fe9ea58068d1a239318713382ff1 |
| 3 | Amount in Ringgit Malaysia (RM) with 2 decimal places. Maximum Amount RM30000 per transaction and minimum value RM2 for Retail/Individual Account and Maximum Value RM1Million for Corporate Account(B2B) | Mandatory | 10.00 (for ten ringgit) |
| 4 | Order Reference is an Alphanumeric merchant order number reference ID. Character Length:20 | Mandatory | 12345 |
| 5 | Return URL – browser to browser communication that allow ZenPay to redirect page to merchant web interactively. Web URL either http or https. All Response parameters can be referred Section 3.0 | Optional | http://marchant.com/rsp/webpayment.php (if returnURL is blank, ZenPay will remain at the Standard Receipt Page without any further redirection) |
| 6 | Callback URL Server to Server communication that allows ZenPay payment gateway to post payment status parameters using background mode. Response parameters can be referred Section 4.0 | Mandatory | https://marchant.com/rsp/bgpayment.php |
CURL REQUEST is submitted to URL:
https://app.thezenpay.com/ebiz/ezp/get3Dpaysession.php
STEP 2: Merchant will receive CURL RESPONSE in JSON Format
| NO | PARAMETER | DESCRIPTION |
|---|---|---|
| 1 | PaymentSessionID (String Length:64) | If valid biller code and hashkey, payment server will respond immediately payment session id to be used by merchant for the next submission. This payment ref session id will expire after 5 minutes. If invalid biller code and hash key, payment will return blank |
| 2 | status (Character Length 2) | 0 : for approve & valid session request -1 : for unauthorised and Invalid Biller Code and Hashkey |
Sample Successful Response:
{“PaymentSessionID”:”344272c8c59c2b1c1cef7a158e46dbb5d22a6fcdccf7c95688
8d931139ab9c37″,”status”:”0″}
STEP 3: MAKING PAYMENT
In order to proceed to make payment, merchant need to submit form to url:
https://app.thezenpay.com/ebiz/ezp/zenpay3Dnow.php
by posting parameters below :-
| NO | PARAMETER | STATUS | DESCRIPTION |
|---|---|---|---|
| 1 | PaymentSessionID (string 64) | Mandatory | Valid PaymentSessionID provided in step 2. |