ody class="body-bg">

Virtual Account APIs

Virtual Account API v1.0 Reference

Virtual Account Solution

Introduction

Paysharp API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request and returns response, and uses standard HTTP response codes, authentication, and verbs.

You can use our API in the sandbox(testing) and production(live) environments. We provide two different API urls and tokens for sandbox and production.

Pass API token and content-type for all the requests in header, API token can be generated from merchant dashboard.

  • content-type: application/json
  • authorization: Bearer <Token>

Create Virtual Account API

Create a customer and assign an unique virtual bank account number for the customer. For non required fields you have to pass empty values.

  • URL: /customers
  • Method: POST

Request

Parameters Range Datatype Required Description
externalCustomerId Max 36 string Y Unique identifier to identify customer
name Max 100 string N Customer name
mobileNo 10 Chars string Y Customer Mobile No.
email Max 100 string N Customer email address
whitelistedRemitters Max 5 array N Whitelist remitter bank account details

Response

Parameters Datatype Description
externalCustomerId string Returns the request value
name string Returns the request value
mobileNo string Returns the request value
email string Returns the request value
virtualAccountNo string Virtual account number for the externalCustomerId
ifscCode string IFSC code for the virtual account number
beneficiaryName string Beneficiary name represents the client’s company or brand name
bankName string Name of the bank which provides the virtual account
whitelistedRemitters array Returns the request value

Example

Request

{

   "externalCustomerId" :   "C_111457",

   "name" :   "ABC Corp",

   "mobileNo" :   "9111100000",

   "email" :   "",

   "whitelistedRemitters" : [  

    {

      "accountName" :   "ABC Solutions",

      "accountNo" :   "11020001772",

      "ifscCode" :   "HDFC0000001"

    },

    {

      "accountName" :   "ABC Solutions",

      "accountNo" :   "33225527837",

      "ifscCode" :   "ICIC0000002"

    }

   ]

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"externalCustomerId" :   "C_111457",

"name" :   "ABC Corp",

"mobileNo" :   "9111100000",

"email" :   "",

"virtualAccountNo" :   "799799700105",

"ifscCode" :   "YESB0CMSNOC",

"beneficiaryName" :   "abc corp",

"bankName" :   "Yes Bank",

 "whitelistedRemitters" : [  

     {

        "accountName" :   "ABC Solutions",

        "accountNo" :   "11020001772",

        "ifscCode" :   "HDFC0000001"

    },

     {

        "accountName" :   "ABC Solutions",

        "accountNo" :   "33225527837",

        "ifscCode" :   "ICIC0000002"

    }

    ]

   }

}

Update Virtual Account API

Update the customer information by customer Id. Only able to update name, mobileNo and email.

  • URL: /customers/{externalCustomerId}
  • Method: PUT

Request

Parameters Range Datatype Required Description
name Max 100 string N Customer name
mobileNo 10 Chars string Y Customer Mobile No.
email Max 100 string N Customer email address
whitelistedRemitters Max 5 array N Whitelist remitter bank account details

Response

Parameters Datatype Description
externalCustomerId string Returns the request value
name string Returns the request value
mobileNo string Returns the request value
email string Returns the request value
virtualAccountNo string Virtual account number for the externalCustomerId
ifscCode string IFSC code for the virtual account number
beneficiaryName string Beneficiary name represents the client’s company or brand name
bankName string Name of the bank which provides the virtual account
whitelistedRemitters array Returns the request value

Example 1

Request

{

   "name" :   "ABC Corp",

   "mobileNo" :   "9111100000",

   "email" :   "abcemail@abc.com"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"externalCustomerId" :   "C_111457",

"name" :   "ABC Corp",

"mobileNo" :   "9111100000",

"email" :   "abcemail@abc.com",

"virtualAccountNo" :   "799799700105",

"ifscCode" :   "YESB0CMSNOC",

"beneficiaryName" :   "abc corp",

"bankName" :   "Yes Bank"

}

}

Example 2

Request

{

   "name" :   "ABC Corp",

   "mobileNo" :   "9111100000",

   "email" :   "abcemail@abc.com",

   "whitelistedRemitters" : [  

     {

      "accountName" :   "ABC Solutions",

      "accountNo" :   "11020001772",

      "ifscCode" :   "HDFC0000001"

    },

     {

      "accountName" :   "ABC Solutions",

      "accountNo" :   "33225527837",

      "ifscCode" :   "ICIC0000002"

    }

   ]

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"externalCustomerId" :   "C_111457",

"name" :   "ABC Corp",

"mobileNo" :   "9111100000",

"email" :   "abcemail@abc.com",

"virtualAccountNo" :   "799799700105",

"ifscCode" :   "YESB0CMSNOC",

"beneficiaryName" :   "abc corp",

"bankName" :   "Yes Bank",

      "whitelistedRemitters" : [  

     {

      "accountName" :   "ABC Solutions",

      "accountNo" :   "11020001772",

      "ifscCode" :   "HDFC0000001"

    },

     {

      "accountName" :   "ABC Solutions",

      "accountNo" :   "33225527837",

      "ifscCode" :   "ICIC0000002"

    }

   ]

   }

}

Get Virtual Account API

Get the customer information by customer Id.

  • URL: /customers/{externalCustomerId}
  • Method: GET

Request

N/A

Response

Parameters Datatype Description
externalCustomerId string Returns the request value
name string Returns the request value
mobileNo string Returns the request value
email string Returns the request value
virtualAccountNo string Virtual account number for the externalCustomerId
ifscCode string IFSC code for the virtual account number
beneficiaryName string Beneficiary name represents the client’s company or brand name
bankName string Name of the bank which provides the virtual account

Example

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

   "externalCustomerId" :   "C_111457",

   "name" :   "ABC Corp",

   "mobileNo" :   "9111100000",

   "email" :   "abcemail@abc.com",

   "virtualAccountNo" :   "799799700105",

   "ifscCode" :   "YESB0CMSNOC",

   "beneficiaryName" :   "abc corp",

   "bankName" :   "YESBANK"

}

}

Deactivate Virtual Account API

Deactivate a customer by customer Id, the virtual account associated with the customer also will be deleted and any future payments to the virtual account will be rejected.

  • URL: /customers/{externalCustomerId}
  • Method: DELETE

Request

N/A

Response

Parameters Datatype Description
externalCustomerId string Returns the request value
name string Returns the request value
mobileNo string Returns the request value
email string Returns the request value
virtualAccountNo string Virtual account number for the externalCustomerId
ifscCode string IFSC code for the virtual account number
beneficiaryName string Beneficiary name represents the client’s company or brand name
bankName string Name of the bank which provides the virtual account

Example

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

   "externalCustomerId" :   "C_111457",

   "name" :   "ABC Corp",

   "mobileNo" :   "9111100000",

   "email" :   "abcemail@abc.com",

   "virtualAccountNo" :   "799799700105",

   "ifscCode" :   "YESB0CMSNOC",

   "beneficiaryName" :   "abc corp",

   "bankName" :   "YESBANK"

   }

}

Reactivate Virtual Account API

Reactivate the deleted customer, so the virtual account again start accepts deposits

  • URL: /customers/reactivate
  • Method: POST

Request

Parameters Range Datatype Required Description
externalCustomerId Max 36 string Y Unique identifier to identify customer

Response

Parameters Datatype Description
externalCustomerId string Returns true if VPA is valid or not
name string Returns the request value
mobileNo string Returns the request value
email string Returns the request value
virtualAccountNo string Virtual account number for the externalCustomerId
ifscCode string IFSC code for the virtual account number
beneficiaryName string Beneficiary name represents the client’s company or brand name
bankName string Name of the bank which provides the virtual account

Example

Request

{

   "externalCustomerId" :   "C_111457"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"externalCustomerId" :   "C_111457",

"name" :   "ABC Corp",

"mobileNo" :   "9111100000",

"email" :   "abcemail@abc.com",

"virtualAccountNo" :   "799799700105",

"ifscCode" :   "YESB0CMSNOC",

"beneficiaryName" :   "abc corp",

"bankName" :   "Yes Bank"

}

}

Virtual Account Webhook

Our system will call your webhook url and post the payment status when payment is received. In case your webhook does not respond, our system will call your url for maximum four times in a 15 minutes interval if all four attempts failed, you will receive email notification about the issue

Parameters Datatype Description
externalCustomerId string Returns the customer Id for the order
amount number Amount for the order
fee number Fee for the transaction
tax number Tax for the transaction fee
totalFee number Sum of fee and tax
netAmount number Actual amount after deducting fee and tax.
paysharpReferenceNo string Payment reference number for the payment
utrNumber string Unique transaction reference number returned by bank for the fund transfer
transactionDate datetime Transaction date
name string Customer name
mobileNo string Customer Mobile No.
email string Customer email address
virtualAccountNo string Virtual account number for the externalCustomerId
ifscCode string IFSC code for the virtual account number
beneficiaryName string Beneficiary name represents the client’s company or brand name
bankName string Name of the bank which provides the virtual account
remitterAccountNo string Remitter account number (The field only applicable for remitters whitelisted transaction)
remitterName string Remitter name provided by bank who done the transaction (The field only applicable for remitters whitelisted transaction)
remitterIfscCode string Remitter account IFSC Code (The field only applicable for remitters whitelisted transaction)
attemptCount number Number of times the webhook invoked

Example 1

Request

    {  

"externalCustomerId" :   "C_111457",

"amount" :   150000.00,

"fee" :   10.00,

"tax" :   1.80,

"totalFee" :   11.80,

"netAmount" :   149988.20,

"paysharpReferenceNo" :   "PS20200105167004",

"utrNumber" :   "N2020015167004",

"transactionDate" :   "2020-04-27T22:23:20Z",

"name" :   "ABC Corp",

"mobileNo" :   "9111100000",

"email" :   "abcemail@abc.com",

"virtualAccountNo" :   "799799700105",

"ifscCode" :   "YESB0CMSNOC",

"beneficiaryName" :   "abc corp",

"bankName" :   "YESBANK",

"attemptCount" :   1

   }

Response

    {  

"code" :   200,

"message" :   "success"

   }

Example 2 (For remitter whitelisted account)

Request

    {  

"externalCustomerId" :   "C_111457",

"amount" :   150000.00,

"fee" :   10.00,

"tax" :   1.80,

"totalFee" :   11.80,

"netAmount" :   149988.20,

"paysharpReferenceNo" :   "PS20200105167004",

"utrNumber" :   "N2020015167004",

"transactionDate" :   "2020-04-27T22:23:20Z",

"name" :   "ABC Corp",

"mobileNo" :   "9111100000",

"email" :   "abcemail@abc.com",

"virtualAccountNo" :   "799799700105",

"ifscCode" :   "YESB0CMSNOC",

"beneficiaryName" :   "abc corp",

"bankName" :   "YESBANK",

"remitterName" :   "ABC Solutions",

"remitterAccountNo" :   "3322457837",

"remitterIfscCode" :   "ICIC0000002",

"attemptCount" :   1

   }

Response

    {  

"code" :   200,

"message" :   "success"

   }

API Success and Error Messages

Http Status Code: 200 - Success

400 - Error

Sample Error Response

     {

      "code" :   400,

      "errorCode" :   2002,

      "message" :   "externalCustomerId already exists"

    }

Possible Errors

Error Codes Error Messages
2001 Customer not found
2002 externalCustomerId already exists
2003 Virtual account No. already exists

Postman Collection

Login to your Sandbox / Production environment and Virtual Account API Postman Collection download from the dashboard.