KROOZ PAY Merchant Payment Rest API Documentation

Description

This document is a guide on how to integrate Merchant Payment with Rest API.
The API is a restful web service, which accept form data as input. All methods are implemented as POST.
Before anything to do the user (who is paying to the merchant) must be logged in to get the authorization token.

End Point 1: Merchant Verify

URL: https://kroozpay.com/gateway/api/merchant/verify
Method: POST
Description: Go to merchant account, https://kroozpay.com/gateway/merchants Click gear icon of approved express merchant.
From the modal copy Client id, Client Secret. This method is used to generate an access token.

SAMPLE REQUEST

BODY PARAMETER (form-data)
{" client_id":" yMKqAvC2dILUyhwdIbryh4rsl784kF"," client_secret":" ZubitDCg2QyxuoSu0l6pJkNB5lOrcl1Ivy0qZlhlu8QhWHDYOelkVSNC8B0ybunOb3i832W3FC2SUuXw04Rj8kRHduMx7pdD4a48"}

Parameter Description Status Type Sample
client_id Merchant Client ID Required String yMKqAvC2dILUyhwdIbryh4rsl784kF
client_secret Merchant Secret Required String ZubitDCg2QyxuoSu0l6pJkNB5lOrcl1Ivy0qZlhlu8QhWHDYOelkVSNC8B0ybunOb...

SAMPLE RESPONSE

Merchant exists:
{"success":{"response":{"status":"success","message":"Client Verified","data":{"access_token":"PIdb49a6imxSecjkr2tn21YSPn"}},"status":200}}
Merchant does not exist
{"success":{"status":407,"message":"Can not verify the client. Please check client Id and Client Secret!"}}


N.B: You have to use this genereted access_token on next step as AUTHORIZATION

Possible reason for failure:

The client_id or client_secret is invalid.

End Point - 2. Transaction Info

URL: https://kroozpay.com/gateway/api/merchant/transaction-info
Method: POST
Description: We use this endpoint to store the payment information. Get the access token which is generated by verifying merchant in previous step. .
N.B: You will need to set the Authorization: Bearer followed by the token value. Add successUrl and cancelUrl as you need. For currency code use ISO format.


SAMPLE REQUEST

BODY PARAMETER (form-data):
{"payer":"LuxXchange","amount":"10","currency":"USD","successUrl":"https://kroozpay.com/gateway/dashboard","cancelUrl":"https://kroozpay.com/gateway/" }
HEADER PARAMETER:
{"Authorization":"Bearer 5UTduND48M4qrbSJ9i3CVuQ2cE"}

Parameter Description Status Type Sample
payer Who will receive the payment Required String David Luca
amount The amount User have to pay. Required Double 10
currency The payment occur on which currency, it should be ISO code. Required String USD
successUrl Application dashboard url Required String https://kroozpay.com/gateway/dashboard
cancelUrl Application root url Required String https://kroozpay.com/gateway/
Authorization Must be given on header, collect it from merchant verify Required String Bearer PIdb49a6imxSecjkr2tn21YSPn

SAMPLE RESPONSE

Success
{"success":{"status":"success","grandId":78509912,"token":"VPJSyzRvTgzWGll3xjTI","messag e":"","data":{"approvedUrl":"https://kroozpay.com/gateway/merchant/initiate-payment?grant_id=78509912&token=VPJSyzRvTgzWGll3xjTI"}}}
Invalid Currency
{"success":{"status":"error","message":"Currency GBP is not supported by this merchant!","data":[]}}
Amount Zero
{"success":{"status":"error","message":"Amount cannot be 0 or less than 0.","data":[]}}

Possible reason for failure:

Merchant Currency doesn’t exist, no successUrl & no cancelUrl, amount zero, Authorization token mismatch.


N.B: After performing the above step, you will get grant_id and token. These value will be needed for the Payment step.

Payment Process

User can make payement in two way
1. Rest API: user will payment from merchant site
2. Hosted page: user will redirect to hosted page

1. Rest API

User have to login to https://kroozpay.com/gateway/ via API
If user successfully login to the application, a token will be generete for user. User have to user this token as Authorization token for payment step.

LOGIN VIA API

URL: https://kroozpay.com/gateway/api/login
Method Type: POST

SAMPLE REQUEST

BODY PARAMETER (form-data)
{"email":"test@kroozpay.com","password":"123456"}

Parameter Description Status Type Sample
email Must be email Required String test@kroozpay.com
password User Password Required String 123456

SAMPLE RESPONSE

Login Successful
{"RESPONSE":{"USER_ID":4,"FIRST_NAME":"David","LAST_NAME":"Luca","EMAIL":"test@kroozpay.com","FORMATTEDPHONE":NULL,"PICTURE":"","DEFAULTCOUNTRY":"US","TOKEN":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0OGU2NjhhZDdjMWRmYzhjODA1NGE0NjY5ZTM0OGYyND","STATUS":200,"USER-STATUS":"ACTIVE"}}
Login Error
{"response":{"status":401,"message":"Invalid email & credentials"}}


N.B: You have to use this genereted TOKEN on next steps as Authorization-token in the header section.

Possible reasons for failure:

Credentials do not match, user suspended.

End Point - 3. PAYMENT

URL: https://kroozpay.com/gateway/api/merchant/payment/
Method: POST
Description: In this endpoint payment will success, Checks all kinds of input validation and redirected to payment page (if user not logged in then user have to login) if all validation passed. User have to decide to cancel or accept the payment. User grant_id & token as body parameter which is generated in previous step.

SAMPLE REQUEST

BODY PARAMETER (form-data)
{"grant_id":"55890128","token":" OfCErZrxuiDqxTjscQon "}
HEADER PARAMETER
{“ Authorization-token”:” eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0OGU2NjhhZDdjMWRmYzhjODA1NGE0NjY5ZTM0OGYyND...”}

Parameter Description Status Type Sample
grant_id Get from endpoint-2 Required String 78509912
token Get from endpoint-2 Required String VPJSyzRvTgzWGll3xjTI
Authorization-token Must be given in header, token that is generate after login response for user. Required String eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0OGU2NjhhZD...

SAMPLE RESPONSE

Payment Success:
{ "success": { "status": 200, "message": "Success", "successUrl": "https://kroozpay.com/gateway?eyJzdGF0dXMiOjIwMCwidHJhbnNhY3Rpb25faWQiOiJFQjlCRUM0MUYyMDRCIiwibWVyY2hhbnQiOiJBc2hyYWZ1bCBSYXNlbCIsImN1cnJlbmN5IjoiVVNEIiwiZmVlIjowLjE0OTk5OTk5OTk5OTk5OTk5NDQ0ODg4NDg3Njg3NDIxNzI5Nzg4MTg0MTY1OTU0NTg5ODQzNzUsImFtb3VudCI6OS44NDk5OTk5OTk5OTk5OTk2NDQ3Mjg2MzIxMTk5NDk5MDcwNjQ0Mzc4NjYyMTA5Mzc1LCJ0b3RhbCI6IjEwLjAwMDAwMDAwIn0=" } }
Merchant & User same:
{"success":{"status":801,"message":"Merchant cannot make payment to himself!"}}
Grant Id or Token Mismatch :
{"success":{"status":401,"message":"Grant Id or Token does not Match!"}}
Insufficient Balance :
{"success":{"status":401,"message":"User doesn't have sufficient balance!"}}

End Point 4: PAYMENT CANCEL

URL: https://kroozpay.com/gateway/api/merchant/payment/cancel
Method: POST
Description: To cancel the payment this url is used. To cancel a payment, after endpoint #2 make a request to endpoint #4. Provide “Authorization-token” from https://kroozpay.com/gateway/api/login and token from endpoint #2.

SAMPLE REQUEST

BODY PARAMETER (form-data)
{"grant_id":"78509912","token":" VPJSyzRvTgzWGll3xjTI "}
HEADER PARAMETER
{“ Authorization-token”:” eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIzIiwianRpIjoiNTFiMTU5N2EyYjI4NDMxMzFiZWM0MTd...”}

Parameter Description Status Type Sample
grant_id Get from endpoint-2 Required String 78509912
token Get from endpoint-2 Required String VPJSyzRvTgzWGll3xjTI
Authorization-token Must be given in header, token that is generate after login response for user. Required String eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIzIiwianRpIjoiNTFiMTU5N2Ey...

SAMPLE RESPONSE

Payment Success:
{ "success": { "status": 200, "message": "Payment cancelled successfully", "cancelUrl": "https://kroozpay.com/gateway/dashboard" } }



2. Hosted page

From step 2, get the approvedUrl & redirect user to the url
URL: https://kroozpay.com/gateway/merchant/initiate-payment?grant_id=78509912&token=VPJSyzRvTgzWGll3xjTI

Payment page

User can select Kroozpay wallet or Kroozpay gateway from

KROOZ Pay

Payment via wallet


If user select kroozpay wallet, user have to login to the application
After login if user press confirm button, payment will complete & user will redirect success page.

KROOZ Pay

Payment via Kroozpay gateway

If user select kroozpay gateway, user will redirect to gatway page.
User don't have to login to pay via kroozpay gateway.

KROOZ Pay

Redirect after payment

If payment complete user will redirect success url, which you use on step 2.
If you press cancel button, transaction will cancell. User will redirect to cancel url which you provided on step 2.