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://payplantation.com/gateway/api/merchant/verify
Method: POST
Description: Go to merchant account, https://payplantation.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://payplantation.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://payplantation.com/gateway/dashboard","cancelUrl":"https://payplantation.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://payplantation.com/gateway/dashboard |
| cancelUrl | Application root url | Required | String | https://payplantation.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://payplantation.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://payplantation.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://payplantation.com/gateway/api/login
Method Type: POST
SAMPLE REQUEST
BODY PARAMETER (form-data)
{"email":"test@payplantation.com","password":"123456"}
| Parameter | Description | Status | Type | Sample |
|---|---|---|---|---|
| Must be email | Required | String | test@payplantation.com | |
| password | User Password | Required | String | 123456 |
SAMPLE RESPONSE
Login Successful
{"RESPONSE":{"USER_ID":4,"FIRST_NAME":"David","LAST_NAME":"Luca","EMAIL":"test@payplantation.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://payplantation.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://payplantation.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://payplantation.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://payplantation.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://payplantation.com/gateway/dashboard"
}
}
2. Hosted page
From step 2, get the approvedUrl & redirect user to the url
URL: https://payplantation.com/gateway/merchant/initiate-payment?grant_id=78509912&token=VPJSyzRvTgzWGll3xjTI
Payment page
User can select PayPlantation wallet or PayPlantation gateway from
Payment via wallet
If user select PayPlantation wallet, user have to login to the application
After login if user press confirm button, payment will complete & user will redirect success page.
Payment via PayPlantation gateway
If user select PayPlantation gateway, user will redirect to gateway page.
User do have to login to pay via PayPlantation gateway.
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.
