Developer

PAYREMITS 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.

LOGIN VIA API

URL: https://app.payremits.com/api/login
Method Type: POST
Sample Request: BODY PARAMETER (form-data)

                        
                            {"email":"david.luca@gmail.com","password":"123456"}

Parameter	Description	Status	Type	Sample
email	Must be email	Required	String	david.luca@gmail.com
password	User Password	Required	String	123456

SAMPLE RESPONSE

Login Successful

                        
                            {"response":{"user_id":4,"first_name":"David","last_name":"Luca","email":"david.luca@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 generated TOKEN on all other steps as Authorization-token in the header section.

End Point 1: Merchant Verify

URL: https://app.payremits.com/api/merchant/verify
Method: POST
Description: Go to merchant account, https://app.payremits.com/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	Merchant Client ID	Required	String	yMKqAvC2dILUyhwdIbryh4rsl784kF
client_secret	Merchant Secret	Required	String	ZubitDCg2QyxuoSu0l6pJkNB5lOrcl1Ivy0qZlhlu8QhWHDYOe...
Authorization-token	Must be given in header, token that is generated after login response for user.	Required	String	eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIzIiw...

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 generated access_token on next step as AUTHORIZATION

End Point - 2. Transaction Info

URL: https://app.payremits.com/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://app.payremits.com/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":"Wallet","amount":"10","currency":"USD","email":"david.luca@gmail.com","successUrl":"https://app.payremits.com/dashboard","cancelUrl":"https://app.payremits.com"}

HEADER PARAMETER

                        
                            {" Authorization-token ":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0OGU2NjhhZDdjMWRmYzhjODA1NGE0NjY5ZTM0OGYyND..."," Authorization ":"Bearer 5UTduND48M4qrbSJ9i3CVuQ2cE "}

Parameter	Description	Status	Type	Sample
payer	Payment method	Required	String	Wallet/Mtn
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
email	Email of the user who is making the payment	Optional	Email	david.luca@gmail.com
successUrl	Application dashboard url	Required	String	https://app.payremits.com/dashboard
cancelUrl	Application root url	Required	String	https://app.payremits.com
Authorization-token	Must be given in header, token that is generated after login response for user.	Required	String	eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQi...
Authorization	Must be given in header, collect it from merchant verify	Required	String	Bearer PIdb49a6imxSecjkr2tn21YSPn

SAMPLE RESPONSE

Success

                        
                            {"success":{"status":"success","grandId":78509912,"token":"VPJSyzRvTgzWGll3xjTI","message":"","data":{"approvedUrl":"https://app.payremits.com/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":[]}}

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

End Point - 3. PAYMENT

URL: https://app.payremits.com/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 For Wallet Payment

BODY PARAMETER (form-data)

                        
                            {"grant_id":"55890128","token":"OfCErZrxuiDqxTjscQon"}

SAMPLE REQUEST For Mtn Payment

BODY PARAMETER (form-data)

                        
                            {"grant_id":"55890128","token":"OfCErZrxuiDqxTjscQon","carrierCode":"244","phone":"123456","message":"hello","note":"note"}

HEADER PARAMETER

                        
                            {“ Authorization-token”:” eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijg0OGU2NjhhZDdjMWRmYzhjODA1NGE0NjY5ZTM0OGYyND...”}

Parameter	Description	Status	Type	Sample
grant_id	Get from endpoint-2	Required	Double	78509912
token	Get from endpoint-2	Required	String	VPJSyzRvTgzWGll3xjTI
carrierCode	Mtn mobile number carrier code	Required	String	244
phone	Mtn mobile number without carrier code	Required	String	123456
message	Message for the MTN user	Required	String	123456
note	Note for the transaction	Required	String	note
Authorization-token	Must be given in header, token that is generate after login response for user.	Required	String	eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aS...

N.B: carrierCode, phone, message, note are required only for the MTN payment.

SAMPLE RESPONSE

Payment Success

                        
                            {"success": {"status": 200,"message": "Success","successUrl": "https://app.payremits.com?eyJzdGF0dXMiOjIwMCwidHJhbnNhY3Rpb25faWQiOiJFQjlCRUM0MUYyMDRCIiwibWVyY2hhbnQiOiJBc2hyYWZ1bCBSYXNlbCIsImN1cnJlbmN5IjoiVVNEIiwiZmVlIjowLjE0OTk5OTk5OTk5OTk5OTk5NDQ0ODg4NDg3Njg3NDIxNzI5Nzg4MTg0MTY1OTU0NTg5ODQzNzUsImFtb3VudCI6OS44NDk5OTk5OTk5OTk5OTk2NDQ3Mjg2MzIxMTk5NDk5MDcwNjQ0Mzc4NjYyMTA5Mzc1LCJ0b3RhbCI6IjEwLjAwMDAwMDAwIn0="}}

SAMPLE RESPONSE

MTN Payment

                        
                            {"success": {"status": 200,"message": "Success","successUrl": "payremits.com?eyJzdGF0dXMiOjIwMCwidHJhbnNhY3Rpb25faWQiOiI5RkRFMkZGMTJDN0FEIiwibWVyY2hhbnQiOiJGb2lzYWwgQWhtZWQiLCJjdXJyZW5jeSI6IlhBRiIsImZlZSI6MS41LCJhbW91bnQiOjk4LjUsInRvdGFsIjoxMDB9","mtnResponse": {"primary_key": "95fc9962968840ceb8c001755a8e11db","uuid": "d9f8d42b-66f0-4c4c-9d66-267db3b7cfb6","env": "mtncameroon","access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0.eyJjbGllbnRJZCI6ImJkZmVjMjcyLTk3ODgtNGU2OS1iZWI1LTJkZTYxMWJjN2IyYyIsImV4cGlyZXMiOiIyMDI1LTA4LTE1VDA5OjM3OjU2LjIzNCIsInNlc3Npb25JZCI6IjYyYWE3OTc3LTI3MGMtNDZjNC1hZjRjLTkzZDc5YjFkYmNlOCJ9.M0L5IoX3AWEdLICJmxfW9Olq81Z6rlKjVwO6CDHlPe4f2qsRddNrN88v3a2Ntf6soRgPiZTyxWvuCVHc75hMK3jipEgKWjD2M9jEMntAIFDbMrCuIpDVyr2Z-WC_RO-T0wzOweVOQSaym05goIWnY8GY96zf6w55JG6MSKem0FGPB9N13WIgQ9eCocdVwqcGaBdaY4IH7oHL5R6sHev2ECb9metu58bkcb0v1-CWzAsjCH_lkXDFwFSUPvyF9mzg9xyJFzRw3Rp_z94mQ04_VNT4AX2TZUjm-jEepTvo_ju2Y7kQwa8zOVfIp9sElPJY--2e4YyMED9ZxxISqZgkKQ"}}}

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://app.payremits.com/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://app.payremits.com/api/login and token from endpoint #2.

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	Double	78509912
token	Get from endpoint-2	Required	String	VPJSyzRvTgzWGll3xjTI
Authorization-token	Must be given in header, token that is generated after login response for user.	Required	String	eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiO...

SAMPLE RESPONSE

Payment Cancelled

                        
                            {"success": {"status": 200, "message": "Payment cancelled successfully", "cancelUrl": "https://app.payremits.com/dashboard"}}

End Point 5: MTN Payment Status Check

URL: https://app.payremits.com/api/mtn-payment-status
Method: POST
Description: To check the payment status this url is used. To check the payment status, after endpoint #3 make a request to endpoint #5.

SAMPLE REQUEST

BODY PARAMETER (form-data)

                        
                            {"primary_key":"OfCErZrxuiDqxTjscQon","env":"mtncameroon","access_token":"OfCErZrxuiDqxTjscQondkhfgkdhkh","uuid":"55890128"}

HEADER PARAMETER

                        
                            {“Accept”:”application/json”,“Content-Type”:”application/json”}

Parameter	Description	Status	Type	Sample
primary_key	MTN Primary Key	Required	String	OfCErZrxuiDqxTjscQon
env	MTN API Environment	Required	String	mtncameroon
access_token	MTN Access Token	Required	String	OfCErZrxuiDqxTjscQondkhfgkdhkh
uuid	MTN Transaction ID	Required	String	55890128

SAMPLE RESPONSE

MTN Payment Status Check

                        
                            {"externalId": "16306036-4b04-4106-8c9d-aecbeb3e5c70","amount": "98.5","currency": "XAF","payer": {"partyIdType": "MSISDN","partyId": "237677265707"},"payerMessage": "note","payeeNote": "note","status": "FAILED","reason": "VALIDATION_ERROR"}