Express Merchant Payment REST API
Custom Features(on-demand only)
base_url: https://paymoney.techvill.org/modern/
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.
Login Via API
URL: https://{base_url}/api/login
Method Type: POST
Sample Request
Body Parameter (form-data)
{"email":"irish@gmail.com","password":"123456"}
| Parameter | Description | Status | Type | Sample |
|---|---|---|---|---|
| Must be email | Required | String | irish@gmail.com | |
| password | User Password | Required | String | 123456 |
Sample Response
Login Successful
{"RESPONSE": {"USER_ID":4,"FIRST_NAME":"Irish","LAST_NAME":"Watson","EMAIL":"irish@gmail.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 all other steps as Authorization-token in the header section.
Possible reasons for failure:
Credentials do not match, user suspended.
EndPoint Name: Merchant Verify
URL: https://{base_url}/merchant/verify
Method: POST
Description: Go to merchant account, https://{base_url}/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.
N.B: If the merchant is approved by the admin, only then the gear icon will be available for that merchant. Authorization-token must be sent as header.
Sample Request
Body Parameter (form-data)
{" client_id":" yMKqAvC2dILUyhwdIbryh4rsl784kF"," client_secret":" ZubitDCg2QyxuoSu0l6pJkNB5lOrcl1Ivy0qZlhlu8QhWHDYOelkVSNC8B0ybunOb3i832W3FC2SUuXw04Rj8kRHduMx7pdD4a48"}
Header Parameter
{“ Authorization-token”:” eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIzIiwianRpIjoiNTFiMTU5N2EyYjI4NDMxMzFiZWM0MTdlZGI4NmExOTcyNGZhYWVlZWMzZGNjMjNkMzRlOTE2YjVkYzJlM2M0NjEwODJkOGNlNTdlZGNkNmYiLCJpYXQiOjE2MzYxNzk5MjgsIm5iZiI6MTYzNjE3OTkyOCwiZXhwIjoxNjY3NzE1OTI4LCJzdWIiOiI0Iiwic2NvcGVzIjpbXX0...”}
| Parameter | Description | Status | Type | Sample |
|---|---|---|---|---|
| client_id | Merchnat Client ID | Required | String | yMKqAvC2dILUyhwdIbryh4rsl784kF |
| client_secret | Merchant Secret | Required | String | ZubitDCg2QyxuoSu0l6pJkNB5lOrcl1Ivy0qZlhlu8QhWHDYOelkVSNC8B0ybunOb.. |
| Authorization -token | Must be given in header, token that is generate after login response for user. | Required | String | eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIzIiwianRpIjoiNTFiMTU5N2EyY.. |
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.
EndPoint Name: Transaction Info
URL: https://{base_url}/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. Use “Authorization-token” and “Authorization” as headers. “Authorization-token” is generated from https://{base_url}/api/login
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://{base_url}/dashboard","cancelUrl":"https://{base_url}/" }
Header Parameter:
{" Authorization-token ":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0OGU2NjhhZDdjMWRmYzhjODA1NGE0NjY5ZTM0OGYyND..."," Authorization ":"Bearer 5UTduND48M4qrbSJ9i3CVuQ2cE "}
| Parameter | Description | Status | Type | Sample |
|---|---|---|---|---|
| payer | Who will receive the payment | Required | String | Irish Watson |
| amount | The amount User have to pay | Required | String | 10 |
| currency | The payment occur on which currency, it should be ISO code. | Required | String | USD |
| successUrl | Application dashboard url | Required | String | https://{base_url}/dashboard |
| cancelUrl | Application root url | Required | String | https://{base_url} |
| Authorization-token | Must be given in header, token that is generate after login response for user | Required | String | eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIzIiwianRp... |
| 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://{base_url}/merchant/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 next step.
EndPoint Name: PAYMENT
URL: https://{base_url}/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 Response
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://{base_url}}?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!"}}
EndPoint Name: PAYMENT CANCEL
URL: https://{base_url}/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://{base_url}/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 | eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0OGU2NjhhZD |
Sample Response
Payment Success:
{ "success": { "status": 200, "message": "Payment cancelled successfully", "cancelUrl": "https://{base_url}/dashboard" } }