Purpose

“PayMate” API allows a business to seamlessly interface with the “PayMate” platform over a RESTful HTTP interface. The purpose of the API is to allow business to initiate make payments, send payment collection requests, approve transactions, track payment status, check account balance and view contacts.

API Protocol

The API accepts data in JSON format over a POST request and sends response in JSON array format. While posting, the JSON data needs to be encrypted with AES 256 bit encryption logic using the key provided by “PayMate” at the time of account signup. The response provided by the API will also be encrypted with AES 256 bit encryption logic with same key. API requests will be authenticated with the help of three separate identification keys provided to the business after account signup.

Requirement

Before any business integrates with the “PayMate” API platform, the business needs to signup on “PayMate” and acquire the authentication keys.
To integrate with “PayMate” API platform, you should
  • Be registered as a business on “PayMate” platform
  • Be a valid and active business.
  • Be on a Premium or an Enterprise subscription plan
Once the above requirements are met user can email for access to authentication keys with registered email address on support@paymate.co.in. Once the details are verified the business will be issued the following authentication keys
  • 32 digit alphanumeric BusinessIdentification ID
  • 32 digit alphanumeric TerminalIdentification ID
  • 10 digit alphanumeric XpressID
  • AES encryption key for encrypting and decrypting JSON data in API requests and response
*Note - The AES encryption key can be changed anytime due to security reasons. Please keep the key handy in such cases.
The business will also have to whitelist the IP address at “PayMate” from where it will be making the API requests.

Authentication

Description: Every API request has to be authenticated by using the keys provided after successful signup. The authentication keys are to be passed in the headers in the key value format for each request.
Note: If you have added multiple users in your PayMate account pass the email address for UserEmail to enable role specific function for that particular user. If the UserEmail is absent the API will assume the Admin user role

Sr.No Parameter Required Data Type Max Length Special Character Description
1 BusinessIdentification Yes Alphanumeric 20 As provided by “PayMate”
2 TerminalIdentification Yes Alphanumeric 20 As provided by “PayMate”
3 XpressID Yes Alphanumeric 20 As provided by “PayMate”
4 UserEmail Optional Alhanumeric 180 Registered user email ID

Add Contact

Method name - AddContact()

Request parameters

Description: Use this method to add your vendors and customers as Contacts on your PayMate account. If adding a vendor, please provide the vendor's account details also. When adding a customer provide an email address for the customer which will be used for communication.

Sr.No Parameter Required Data Type Max Length Special Character Description
1 CompanyName Yes Alphanumeric 60 ,.@!' - Contact's Company Name
2 FirstName Yes Alphabet 30 Contact's first name
3 LastName Yes Alphabet 30 Contact's last name
4 NickName Optional Alphabet 10 Contact's nick Name
5 EmailId Yes Alphanumeric 200 Contact Company's Email address
6 MobileNo Optional Numeric 10 Contact Company's Mobile no.
7 CompanyAddress Optional Alphanumeric 300 Contact Company's Address
8 ReferenceCode Optional Alphanumeric 20 Contact Company's Reference Code
9 AccountNo Optional Alphanumeric 30 Contact Company's Account no
10 IFSCode Optional Alphanumeric 11 Contact Company's Account IFSC Code
11 GSTIN Optional Alphanumeric 15 Contact Company's GSTN

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 Error Description
4 Response Yes Text - Array of response data. In case of any error this parameter will be empty
Add Contact
{  
   "CompanyName":"Nelson Group",
   "FirstName":"Watson",
   "LastName":"Nelson",
   "NickName":"Watson",
   "EmailId":"abc@watson.com",
   "MobileNo":"8811224455",
   "CompanyAddress":"Mumbai",
   "ReferenceCode":"200050",
   "AccountNo":"PAYMY200AM45",
   "IFSCode":"CITI0100000"
   "GSTIN":"27ATYPR6435K1N0"
}
                       
{  
   
   "XpressID":"LEGM000001",
   "ErrorCode":"000",
   "ErrorDescription":"Contact saved successfully.",
   "Response":{  
      "VirtualAccountNo":"PAYMYS123456",
      "VANIFSC":"CITI0100000",
      "ContactXpressID":"TEMH000012"
              }
                                        
  }

Get Contact List

Method name - GetContactList()

Request parameters

Description: Use this method to get all the contacts added by you in your PayMate account. To get a list of contacts added between a particular date range, provide FromDate & ToDate . To get a details of a single contact provide CompanyName or ReferenceCode.

Sr.No Parameter Required Data Type Max Length Special Character Description
1 FromDate Optional Date 10 / DD/MM/YYYY
2 ToDate Optional Date 10 / DD/MM/YYYY
3 CompanyName Optional AlphaNumeric 30 ,.@!'- Registered Company Name
4 ReferenceCode Optional AlphaNumeric 20 Registered Company's ReferenceCode

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 Error Description
4 Response Yes - Array of response data. In case of any error this parameter will be empty
Get Contact List
{  
   "CompanyName":"",
   "CompanyCode":"200050",
   "FromDate":"",
   "ToDate":""
}
                       
{  
   "XpressID":"LEGM000001",
   "ErrorCode":"000",
   "ErrorDescription":"Success",
   "Response":[  
      {  
         "CompanyName":"Nelson Group",
         "FirstName":"Watson",
         "LastName":"Nelson",
         "NickName":"Watson",
         "EmailId":"abc@watson.com",
         "MobileNo":"8811224455",
         "CompanyAddress":"Mumbai",
         "ReferenceCode":"200050",
         "AccountNo":"PAYMY200AM45",
         "IFSCode":"CITI0100000",
         "VirtualAccountNo":"PAYMYS123456",
	     "VANIFSC":"CITI0100000",
         "ContactXpressID":"TEMH000012"
      }
   ],
   
}

Book Payment

Method name - BookPayment()

Description: Create a make payment request for vendors you have not added on “PayMate” by using this method. The method returns the Transaction Reference Number on successful payment request creation. This method will not add the vendor details passed in the API as contacts on the “PayMate” platform.
Note - This API allows make payment request creation only with Xpress Account as Payment Mode

Request parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 CompanyName Yes Alphabet 60 ,.@!'- Company name of the beneficiary
2 CompanyEmailId No Alphanumeric 200 Email Id of the beneficiary.
3 CompanyMobileNo No Numeric 10 Mobile no of the beneficiary
4 AccountNo Yes Alphanumeric 30 Account no of the beneficiary
5 IFSCode Yes Alphanumeric 11 IFSC Code of the beneficiary account no
6 OrderId Yes Alphanumeric 20 Business generated OrderID
7 Amount Yes Decimal 9,2 Amount to be paid
8 PaymentType Yes Alphanumeric 10 For IMPS transaction provide "Instant", for NEFT/RTGS provide "Normal"
9 PaymentFrom Yes Alphanumeric 20 Payment mode to be used for makeing payments. Options will be XpressAccount, CreditCard, DebitCard or NetBanking
10 Remarks No Alphanumeric 200 Remarks for the transaction
11 ReturnURL No Alphanumeric 200 :,// For payments using Credit Card, Debit Card or Net Banking provide a Return URL to redirect the user after successful transaction

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 if strErrorCode=000 then Success else Specific Error Description
4 Response Yes Text Array of response data. In case of any error this parameter will be empty
Book Payment
{  
   "CompanyName":"Watson Group",
   "ReceiverEmailId":"abc@watson.com",
   "AccountNo":"PAYMY200AM45",
   "IFSCode":"CITI0100000",
   "OrderId":"WAT432562",
   "Amount":"1000000",
   "PaymentType":"Normal",
   "PaymentFrom":"XpressAccount"
   "Remarks":"Payment for the invoice no WAT345678"
}

                       
{  
   "strXpressID":"LEGM000001",
   "ErrorCode":"000",
   "ErrorDescription":"Success",
   "ResponseText":{  
      "TransactionRefNo":"816618019204",
      "OrderID":"WAT432562"
   }

}

Book Payments by XpressID

Method name - BookPaymentsByXpressID()

Description:: This method is used to book make payment request to vendors which you have registered on “PayMate”. The method returns the Transaction Reference Number on successful payment request creation. Note - This API allows make payment request creation only with Xpress Account as Payment Mode

Request parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 ClientXpressId Yes Alphanumeric 10 Registered Contact’s XpressID. A unique XpressID is generated by PayMate for each and every registered contact.
2 OrderID Yes Alphanumeric 10 Business generated OrderID
3 Amount Yes Decimal 9,2 Amount to be paid
4 Remarks Option Alphanumeric 200 Remarks for the transaction
5 PaymentType Yes Alphanumeric 30 For IMPS transaction provide "Instant", for NEFT/RTGS provide "Normal"
6 PaymentFrom Yes Alphanumeric 30 Payment mode to be used for makeing payments. Options will be XpressAccount, CreditCard, DebitCard or NetBanking
7 ReturnURL Yes Text :,// For payments using Credit Card, Debit Card or Net Banking provide a Return URL to redirect the user after successful transaction

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 if strErrorCode=000 then Success else Specific Error Description
4 Response Yes Text Array of response data. In case of any error this parameter will be empty
Book Payments by XpressID
{  
   "ClientXpressId":"TEMH000012",
   "OrderID":"WAT9856343",
   "Amount":"1000000",
   "PaymentType":"Normal",
   "PaymentFrom":"XpressAccount"
   "Remarks":"Payment against the invoice no WAT3456789"
}
                       
{
  
   "XpressID":"LEGM000001",
   "ErrorCode":"000",
   "ErrorDescription":"Success",
   "ResponseText":{  
      "TransactionRefNo":"816619019205",
      "OrderID":"WAT9856343"
   }
  
}

Approve Payment

Method name - ApprovePayment()

Description:: Use this method when approving or rejecting a pending payment request. Pass the relevant Order ID of the payment request and approval action to process the approval / rejection of the payment request.
Note - This method can only be used for approving/rejecting a single payment request at a time.

Request parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 OrderId Yes Alphanumeric 20 Business OrderID against the booked transaction
2 TransactionRefNo Optional Numeric 12 PayMate Reference no against the booked transaction
3 ApprovalAction Yes Text 30 Approve or Reject
4 Reason Option Alphanumeric 60 You can add reason if you want to reject the transaction.

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 if strErrorCode=000 then Success else Specific Error Description
4 Response Yes Text Array of response data. In case of any error this parameter will be empty
Approve Payment
{  
   "AprovalAction":"Approve",
   "OrderId":"WAT9856343",
   "Reason":"",
   "TransactionRefNo":""
}

                       
{  
   "XpressID":"LEGM000001",
   "ErrorCode":"000",
   "ErrorDescription":"Success",
   "Response":{  
      "TransactionStatus":"202",
      "TransactionMessage":"Sent to bank",
      "strBankRefNo":"N234567895434",
      "IsBankResponse":true,
      "TransactionRefNo":"816618019204",
      "OrderID":"WAT9856343",
      "Amount":"1000000.00",
      "CompanyName":"Watson Group",
      "AccountNo":"PAYMY200AM45"
      "PaymentURL":"https://xyz.com/SenderAuthentication.aspx?abc=BA44590&prakriya=AB567B3F"
   },
   
}

Get Payment Status

Method name - GetPaymentReport()

Description: Get all the pending payment requests which are awaiting approval or awaiting payment. This method can also be used to fetch pending requests within a specific date range or get status of a specific pending request using OrderID.

Request parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 OrderId Yes Alphanumeric 20 Business OrderID against the booked transaction
2 TransactionRefNo Optional Numeric 12 PayMate Reference no against the booked transaction
3 FromDate Optional Date 10 / DD/MM/YYYY
4 ToDate Optional Date 10 / DD/MM/YYYY

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 if strErrorCode=000 then Success else Specific Error Description
4 Response Yes Text Array of response data. In case of any error this parameter will be empty
Get Payment Status
{  
   "OrderId":"WAT9856343",
   "TransactionRefNo":"",
   "FromDate":"",
   "ToDate":""
}


                       
{  
"XpressID":"LEGM000001",
"ErrorCode":"000",
"ErrorDescription":"Success",
"Response":[  
{  
 "OrderId":"WAT9856343",
 "TransactionRefNo":"816618019204",
 "CompanyName":"Nelson Group",
 "AccountNo":"PAYMY200AM45",
 "ReceiverIFSC":"CITI0100000",
 "TransactionType":"Xpress Account",
 "PaidAmount":1000000.00,
 "Commission":10.00,
 "ServiceTax":1.80,
 "NetAmount":1000010.80,
 "transactionDate":"24-04-2018 14:45:21",
 "TransactionStatus":"202",
 "TrasnsactionMessage":"Sent to bank",
 "BankRefNo":"P795109156364004",
 "BankSummary":"SENT_TO_BENEFICIARY"
}
 ],
   
}

Get Xpress Account Balance

Method name - GetXpressAccountBalance()

Description: Use this API to get the current balance in your Xpress Account on “PayMate”.

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 if strErrorCode=000 then Success else Specific Error Description
4 Response Yes Text Array of response data. In case of any error this parameter will be empty
Get Xpress Account Balance


                       
{  
   "XpressID":"LEGM000001",
   "ErrorCode":"000",
   "ErrorDescription":"Success",
   "Response":{  
   "XpressBalance":"6000070.20"
              }
}


Vendor Request Payment

Method name - VendorRequestPayment()

Description: This API allows your registered vendors to raise a payment requests to business. The vendor should be registered as a contact on “PayMate” by the business.

Request parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 ClientXpressID Yes Alphanumeric 10 Xpress ID of the registered contact
2 OrderID Yes Alphanumeric 20 Business generated OrderID
3 Amount Yes Decimal 9,2 Amount to be paid
4 Remarks No Alphanumeric 200 Remarks for the transaction

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 if strErrorCode=000 then Success else Specific Error Description
4 Response Yes Text Array of response data. In case of any error this parameter will be empty
Vendor Request Payment
{  
   "ClientXpressId":"JSQA000001",
   "OrderID":"JSQ2456734",
   "Amount":"100000",
   "Remarks":"Please make the payment on time."
}

                       
{  
   "strXpressID":"LEGM000001",
   "strErrorCode":"000",
   "strErrorDescription":"Success",
   "Response":{  
   "TransactionRefNo":"811714017155",
   "OrderID":"JSQ2456734"
                  }
}


Request Payment

Method name - RequestPayment()

Description: Use this method to send payment collection request to a customer who is not registered on “PayMate”. The API returns a Transaction Reference Number on successful request creation.

Request parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 OrderID Yes Alphanumeric 20 Business generated OrderID
2 CompanyName Yes Alphanumeric 60 Vendor Company Name
3 CompanyCode Optional Alphanumeric 10 Code assign to vendor by Business
4 SenderName Yes Alphanumeric 30 Contact Person Name
5 EmailID Yes Alphanumeric 200 Vendor Email address
6 MobileNo Yes Numeric 10 Vendor Mobile Number
7 Amount Yes Decimal 9,2 Transaction Amount
8 Remarks Optional Alphanumeric 200 Remarks for the transaction

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 if strErrorCode=000 then Success else Specific Error Description
4 Response Yes Text Array of response data. In case of any error this parameter will be empty
Request Payment
{  
   "CompanyName":"Nelson Group",
   "EmailID":"account@nelson.co",
   "ContactName":"Watson Nelson",
   "CompanyCode":"NEL123467",
   "OrderId":"NEL3498654",
   "Amount":"100000",
   "MobileNo":"7700112100",
   "Remarks":"Please make the payment against the invoice NEL1245343"
}

                       
{  
   "strXpressID":"LEGM000001",
   "strErrorCode":"000",
   "strErrorDescription":"Success",
   "Response":{  
   "TransactionRefNo":"811617017149",
   "OrderID":"NEL3498654"
              }
}

Request Payment by XpressID

Method name - RequestPaymentByXpressID()

Description: Send payment collection requests to your customers whom you have added on “PayMate” by using this method. The API will return a Transaction Reference Number on successful request creation.

Request parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 ClientXpressId Optional Alphanumeric 10 “PayMate” issued Xpress ID to the Vendor.
2 OrderID Yes Alphanumeric 20 Business generated OrderID
3 Amount Yes Alphanumeric 30 Transaction Amount
4 Remarks Optional Alphanumeric 200 Remarks for the transaction

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 if strErrorCode=000 then Success else Specific Error Description
4 Response Yes Text Array of response data. In case of any error this parameter will be empty
Request Payment by XpressID
{  
   "ClientXpressId":"JSQA000001",
   "OrderID":"NEL4598567",
   "Amount":"1000000",
   "Remarks":"Invoice no 452342342"
}

                       
{  
   "strXpressID":"LEGM000001",
   "strErrorCode":"000",
   "strErrorDescription":"Success",
   "Response":{  
   "TransactionRefNo":"811616017142",
   "OrderID":"NEL4598567"
              }
}

Get Request Payment Status

Method name - GetRequestPaymentReport()

Description:Get all the pending request payments which are still awaiting payment by the customer. This method can also be used to fetch pending requests within a specific date range or get status of a specific pending request.

Request parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 TransactionRefNo Optional Numeric 12 “PayMate” Reference No against the requested transaction
2 OrderID Optional Alphanumeric 20 Business OrderID against the requested transaction
3 FromDate Optional Date 10 / DD/MM/YYYY
4 ToDate Optional Date 10 / DD/MM/YYYY
*Note: Either TransactionRefNo or OrderID need to be present when making this API request

Response parameters

Sr.No Parameter Required Data Type Max Length Special Character Description
1 XpressID Yes Alphanumeric 20 Sent during Request
2 ErrorCode Yes Numeric 3 if strStatus=Success then 000 else specific error code will be provided
3 ErrorDescription Yes Text 100 if strErrorCode=000 then Success else Specific Error Description
4 Response Yes Text Array of response data. In case of any error this parameter will be empty
Get Request Payment Status
{  
   "OrderId":"rest0",
   "TransactionRefNo":"",
   "FromDate":"",
   "ToDate":""
}

                             
{  
  "XpressID":"LEGM000001",
  "ErrorCode":"000",
  "ErrorDescription":"Success",
  "Response":[  
  {  
    "TransactionRefNo":"811618017151",
    "CompanyName":"test",
    "CompanyCode":"rsma",
    "Amount":10.00,
    "TrasnsactioStatus":"250",
    "TrasnsactionMessage":"Pending",
    "BankRefNo":null,
    "RequestDate":"26/04/2018 18:27:55",
    "PaymentDate":null,
    "OrderId":"rest0"
   }
 ],

}


Error Codes & Description

Kindly refer the following table for Error Description

Sr.No Error Code Description
1 000 Success
2 101 UnAuthorised User Access Denied
3 102 Request Data Decryption Failed
4 103 Invalid Header XpressID
5 104 UnAuthorised Access of Request Type / Sub Type
6 105 Request Data has been Tampered
7 106 Request Data Validation Fail - Company Name
8 107 Request Data Validation Fail - Contact Person
9 108 Request Data Validation Fail - Mobile Number
10 109 Request Data Validation Fail - Email Address
11 120 SOAP Credential is Empty
12 122 Request Data Validation Fail - Company Code
13 123 Invalid Company Code
14 124 Empty / Invalid Company Name
15 125 Empty / Invalid Contact Person
16 126 Empty / Invalid Mobile Number
17 127 Empty / Invalid Email Address
18 128 Empty / Invalid Company Address
19 129 Request from invalid Source
20 159 Transaction Amount is Blank or Invalid Amount
21 162 Remitter Bank Account No is Blank
22 163 Invalid Remitter Account No
23 166 Remitter Bank IFSC is Blank
24 167 Invalid Remitter Bank IFSC
25 176 Invalid OrderId
26 177 Invalid PMX TransactionID
27 178 Invalid Input Parameter(s)
28 179 Cannot Abort Transaction
29 180 Amount limit exceeded
30 181 Remarks length exceeded
31 192 No Method Access for ip
32 198 Awaiting to check
33 199 Awaiting to approve
34 200 Awaiting to pay
35 201 Awaiting payment
36 202 Sent to bank
37 203 Aborted
38 204 Failed
39 205 Expired
40 207 Pending
41 211 Processing
42 212 Rejected
43 214 Returned from beneficiary
44 215 Scheduled for next working day
45 216 Sent to Beneficiary
46 224 Transaction already processed
47 225 No Record(s) found
48 226 Invalid Vendor's XpressId
49 227 OrderID Already Exsits.
50 228 Empty / Invalid Sender Code.
51 229 Sender Name is Empty.
52 230 Payment request has been initiated successfully
53 231 Paid
54 232 Empty / Invalid Company Name.
55 233 Empty / Invalid Account No.
56 234 Empty / Invalid Date.
57 235 Invalid Date Range
58 999 Technical error
Error Codes & Description