Introduction

Payumoney Payment Gateway API Documentation

Authorization

In order to call our payment gateway API's, you need to pass authentication in the form of merchant key and/or authorization header provided to you (depending on the API both can be used). To pass the header you need to add HTTP header with name as 'Authorization' and value as the value provided to you. Every merchant has a unique authorization and will be used to authenticate our API, hence should not be shared with anyone. Unique key and authorization header for a merchant can be found on the dashboard under Manage Account---->My Account---->Merchant Key Salt

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

To post successfully on the production server, your merchant application should be approved and you should have the merchant key provided by PayUmoney.


 

HTTP Response Code

We use conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing etc.), and codes in the 5xx range indicate an error with PayUmoney's servers.

HTTP Status Error message Description
200 OK Everything worked as expected
400 Bad Request Often missing a required parameter
401 Unauthorized No valid API key provided
403 Forbidden The current API does not have access
to this method
402 Request Failed Parameters were valid but request failed
404 Not Found
The requested item doesn't exist
5XX Server errors Something went wrong on PayUmoney's end

API Reference

1.) Payment API: This API is used to post a payment request on PayUmoney's server.

  Production Server Test Server
API URL https://secure.payu.in/_payment https://test.payu.in/_payment

Type: POST
Authorization Header: REQUIRED

Parameter Required Description/Value
key Mandatory Unique merchant key provided by PayUmoney
txnid Mandatory Transaction id from merchant's end
amount Mandatory Payment amount
productinfo Mandatory Product Description
firstname Mandatory (only alphabets a-z are allowed)
lastname
Optional (only alphabets a-z are allowed)
address1 Optional Length of address1 and address2 must not be more than 100 characters each and the allowed characters are only, A TO Z, a to z, 0 to 9, @, - (Minus), _ (Underscore), / (Backslash), (Space), (Dot)
address2 Optional (allowed characters are same as for address1)
city Optional (allowed characters are same as for address1)
state Optional (allowed characters are same as for address1)
country Optional (allowed characters are same as for address1)
zipcode Optional Numeric value only
email Mandatory Customer's email Id
phone Mandatory mobile number or landline number
(numeric value only)
udf1 Optional user defined field 1
udf2 Optional user defined field 2
udf3 Optional user defined field 3
udf4 Optional user defined field 4
udf5 Optional user defined field 5
surl Mandatory Success URL where PayUmoney will redirect the customer after successful payment
furl Mandatory Failure URL where PayUmoney will redirect the customer after failed payment
hash(Checksum) Mandatory Hash or Checksum
=sha512(key|txnid|amount|
productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||salt)
(SALT will be provided by PayUmoney)
service_provider Mandatory payu_paisa
Note:
  1. Please refer integration document for hash (checksum) calculation and detailed errors.

2.) Get Payment Response API: This API can be used by the merchant to get the payment details of transaction(s) with PayUmoney.

  Production Server Test Server
API URL https://www.payumoney.com/payment/op/getPaymentResponse? https://test.payumoney.com/payment/op/getPaymentResponse?

Type: POST
Authorization Header: REQUIRED

Parameter Required Description/Value
merchantKey Mandatory Merchant key provided by PayUmoney
merchantTransactionIds Optional Transaction Id of the transaction, provided by the merchant
(One merchant transaction Id Or Pipe separated merchantTransactionIds)
from Optional Date (dd-mm-yyyy)
to Optional Date (dd-mm-yyyy)
count Optional Number of payments to fetch
Note:
  1. You can send one or multiple merchantTransactionIds in one API call.
  2. From and to both should be posted, if date parameter is used.
  3. Any one of the three (merchantTransId, Date, Count) optional parameters is mandatory.
Code Example:
<?php 
$url = 'https://www.payumoney.com/payment/op/getPaymentResponse?merchantKey= eM8ZaP&merchantTransactionIds=563445'; 
$data =array('merchantKey'=>'eM8ZaP', 'merchantTransactionIds '=>'563445'); 
$options = array( 
  'http' => array( 
    'header' => "Authorization: 0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=", 
    'method' => 'POST', 
    'Authorization'=> '0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=', 
    'content' => http_build_query($data) 
    ), 
  ); 
$context = stream_context_create($options); 
$result = file_get_contents($url, false, $context); 
if ($result === FALSE) { /* Handle error */ } 
var_dump($result); 
?>
Sample Response:

                { 
  "status":0, 
  "message":"All txnIds are valid", 
  "result":[ 
  { 
    "merchantTransactionId":"563445", 
    "postBackParam":{ 
      "postBackParamId":211715, 
      "mihpayid":"403993715512972380", 
      "paymentId":1110275478, 
      "mode":"CC", 
      "status":"success", 
      "unmappedstatus":"captured", 
      "key":"eM8ZaP", 
      "txnid":"203061309", 
      "amount":"1345.0", 
      "additionalCharges":"", 
      "addedon":"2015-08-11 12:48:09", 
      "createdOn":1439277517000, 
      "productinfo":"", 
      "firstname":"test mayank", 
      "lastname":"", 
      "address1":"", 
      "address2":"", 
      "city":"", 
      "state":"", 
      "country":"", 
      "zipcode":"", 
      "email":"testmerchant420@gmail.com", 
      "phone":"1234567890", 
      "udf1":"", 
      "udf2":"", 
      "udf3":"", 
      "udf4":"", 
      "udf5":"", 
      "udf6":"", 
      "udf7":"", 
      "udf8":"", 
      "udf9":"", 
      "udf10":"", 
      "hash":"c6c69e67a3e3d64fcaa682662f8bc1f3ba865c14011da20d6b8699085872e7325d8fba6bf1a31ebfdeef4fd0acb47d9d6e82ea78b026f1d25c74453f5c7b47c8", 
      "field1":"522379003051", 
      "field2":"999999", 
      "field3":"7722572481252231", 
      "field4":"-1", 
      "field5":"", 
      "field6":"", 
      "field7":"", 
      "field8":"", 
      "field9":"SUCCESS", 
      "bank_ref_num":"7722572481252231", 
      "bankcode":"CC", 
      "error":"E000", 
      "error_Message":"No Error", 
      "cardToken":"", 
      "offer_key":"", 
      "offer_type":"", 
      "offer_availed":"", 
      "pg_ref_no":"", 
      "offer_failure_reason":"", 
      "name_on_card":"payu", 
      "cardnum":"512345XXXXXX2346", 
      "cardhash":"This field is no longer supported in postback params.", 
      "card_type":"", 
      "card_merchant_param":null, 
      "version":"", 
      "postUrl":"https://www.payumoney.com/customer/dashboard/#/payment/notification/success/1110275478", 
      "calledStatus":false, 
      "additional_param":"", 
      "amount_split":"{\"PAYU\":\"1345.0\"}", 
      "discount":"0.00", 
      "net_amount_debit":"1345", 
      "fetchAPI":null, 
      "paisa_mecode":"", 
      "meCode":"{\"tranportalid\":\"90000970\",\"pg_alias\":\"90000970\",\"pg_name\":\"hdfctraveltesting\",\"tranportalpwd\":\"password\"}", 
      "payuMoneyId":"1110275478", 
      "encryptedPaymentId":null, 
      "pg_TYPE":"HDFCPG" 
    }
  } 
  ], 
  "errorCode":null, 
  "responseCode":null 
}

3.) Check Transaction Status API: This API can be used by the merchant to reconcile/get update status of transaction(s) with PayUmoney.

  Production Server Test Server
API URL https://www.payumoney.com/payment/payment/chkMerchantTxnStatus? https://test.payumoney.com/payment/payment/chkMerchantTxnStatus?

Type: POST
Authorization Header: REQUIRED

Parameter Required Description/Value
merchantKey Mandatory Merchant key provided by PayUmoney
merchantTransactionIds Mandatory Transaction Id of the transaction, provided by the merchant (One merchant transaction Id Or Pipe separated merchantTransactionIds)
Note:
  1. You can send a maximum of 50 merchantTransactionIds in one API call.
Code Example:
<?php 
$url = 'https://www.payumoney.com/payment/payment/chkMerchantTxnStatus?'; 
$data =array('merchantKey'=>'eM8ZaP','merchantTransactionIds'=>'563445'); 
$options = array( 
  'http' => array( 
    'header' => "Authorization: 0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=", 
    'method' => 'POST', 
    'Authorization'=> '0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=', 
    'content' => http_build_query($data) 
    ), 
  ); 
$context = stream_context_create($options); 
$result = file_get_contents($url, false, $context); 
if ($result === FALSE) { /* Handle error */ } 
  var_dump($result); 
?>
Sample Response:
{ 
  "status":0, 
  "message":"All txnIds are valid", 
  "result":[ 
  { 
    "merchantTransactionId":"563445", 
    "paymentId":1110275478, 
    "status":"Refund in progress", 
    "amount":1345.0 
  } 
  ], 
  "errorCode":null, 
  "responseCode":null 
}

4.) Refund API: This API can be used by the merchant to initiate a partial or full refund for any successful transaction.

  Production Server Test Server
API URL https://www.payumoney.com/payment/merchant/refundPayment? https://test.payumoney.com/payment/merchant/refundPayment?

Type: POST
Authorization Header: REQUIRED

Parameter Required Description/Value
merchantKey Mandatory Merchant key provided by PayUmoney
paymentId Mandatory PayUmoney's paymentId of the transaction
refundAmount Mandatory The amount that is to be refunded to the customer
Code Example:
<?php 
$url = 'https://www.payumoney.com/payment/merchant/refundPayment?merchantKey=eM8ZaP&paymentId=1110275478&refundAmount=10'; 
$data =array('merchantKey'=>'eM8ZaP','paymentId'=>'1110275478','refundAmount'=>'10'); 
$options = array( 
  'http' => array( 
    'header' => "Authorization: 0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=", 
    'method' => 'POST', 
    'Authorization'=> '0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=', 
    'content' => http_build_query($data) 
    ), 
  ); 
$context = stream_context_create($options); 
$result = file_get_contents($url, false, $context); 
if ($result === FALSE) { /* Handle error */ }
  var_dump($result);
?>
Sample Response:
{ 
  "status":0, 
  "rows":0, 
  "message":"Refund Initiated", 
  "result":13918, 
  "guid":null, 
  "sessionId":null, 
  "errorCode":null 
}

5.) Get Refund Details API 1: This API returns details of all refunds for a specific payment.

  Production Server Test Server
API URL https://www.payumoney.com/treasury/ext/merchant/getRefundDetailsByPayment? https://test.payumoney.com/treasury/ext/merchant/getRefundDetailsByPayment?

Type: GET
Authorization Header: REQUIRED

Parameter Required Description/Value
merchantKey Mandatory Merchant key provided by PayUmoney
paymentId Mandatory PayUmoney's paymentId of the transaction
Code Example:
<?php 
$url = 'https://www.payumoney.com/treasury/ext/merchant/getRefundDetailsByPayment?merchantKey=eM8ZaP&paymentId=1110275478'; 
$data =array('merchantKey'=>'eM8ZaP','paymentId'=>'1110275478'); 
$options = array( 
  'http' => array( 
    'header' => "Authorization: 0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=", 
    'method' => 'GET', 
    'Authorization'=> '0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=', 
    'content' => http_build_query($data) 
    ), 
  ); 
$context = stream_context_create($options); 
$result = file_get_contents($url, false, $context); 
if ($result === FALSE) { /* Handle error */ } 
  var_dump($result);  
?> 
Sample Response:
{ 
  "status":0, 
  "rows":0, 
  "message":"Refund Details : ", 
  "result":{ 
    "PaymentId":"1110256124", 
    "Total Amount":"1276.0", 
    "Amount Left":"1266.0", 
    "Refund Details Map":"[{RefundId=13920, Refund Amount=10.0, Refund Completed On=null, Refund Status=refundinprogress, Refund Created On=2016-04-21 11:43:58.0}]" 
    }, 
    "guid":null, 
    "sessionId":null, 
    "errorCode":null 
  }

6.) Get Refund Details API 2: This API returns all the refund details of a particular refund.

  Production Server Test Server
API URL https://www.payumoney.com/treasury/ext/merchant/getRefundDetails? https://test.payumoney.com/treasury/ext/merchant/getRefundDetails?

Type: GET
Authorization Header: REQUIRED

Parameter Required Description/Value
merchantKey Mandatory Merchant key provided by PayUmoney
refundId Mandatory PayUmoney's refundId of the refund
Code Example:
<?php 
$url = 'https://www.payumoney.com/treasury/ext/merchant/getRefundDetails?merchantKey=eM8ZaP&refundId=13918'; 
$data =array('merchantKey'=>'eM8ZaP','refundId'=>'13918'); 
$options = array( 
  'http' => array( 
    'header' => "Authorization: 0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=", 
    'method' => 'GET', 
    'Authorization'=> '0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=', 
    'content' => http_build_query($data) 
    ), 
  ); 
$context = stream_context_create($options); 
$result = file_get_contents($url, false, $context); 
if ($result === FALSE) { /* Handle error */ } 
  var_dump($result); 
?> 
Sample Response:
{ 
  "status":0, 
  "rows":0, 
  "message":"Refund Details : ", 
  "result":{ 
    "RefundId":"13918", 
    "Refund Amount":"10.0", 
    "Total Amount":"1345.0", 
    "Refund Completed On":"null", 
    "Refund Status":"refundinprogress", 
    "Refund Created On":"2016-04-20 11:11:44.0", 
    "PaymentId":"1110275478" 
    }, 
    "guid":null, 
    "sessionId":null, 
    "errorCode":null 
  }

7.) Email Invoice API: This API can be used by the merchants to send an email invoice to their customers for collecting payments through PayUmoney.
A merchant can use this to
a) Send an Email Invoice (PayUmoney system generated) to the customer
b) Get a Payment Link in response to the API and send the link to customer by himself/herself

  Production Server Test Server
API URL https://www.payumoney.com/payment/payment/addInvoiceMerchantAPI? https://test.payumoney.com/payment/payment/addInvoiceMerchantAPI?

Type: POST
Authorization Header: REQUIRED

Parameter Required Description/Value
customerEmail Mandatory Customer Email Id
customerPhone Mandatory Mobile number of the customer (just 10 digits of the mobile number)
customerName Mandatory Name of the customer
(numbers, alphabet, space and hyphen are allowed)
amount Mandatory Payment amount
(Positive amount up to 2 decimal places)
paymentDescripton Mandatory A brief description for the customer to identify the payment
(numbers, alphabet, space and hyphen are allowed)
transactionId Mandatory Transaction or order reference Id (numbers, alphabets, space and hyphen are allowed characters)
sendEmail Optional Whether email should be sent by PayUmoney or not
(0 - PayUmoney will not send email to customer
1 - PayUmoney will send the email to customer)
expiryTime Optional Date when the link should be expired
(yyyy-mm-dd format)
Code Example:
<?php 
$url = 'https://www.payumoney.com/payment/payment/addInvoiceMerchantAPI?transactionId=654565&customerEmail=test@gmail.com&customerPhone=7042692055&customerName=Ekansh&amount=10&paymentDescription=soap'; 
$data =array('transactionId'=>'654565'&'customerEmail'=>'test@gmail.com'&customerPhone=7042692055&customerName=Ekansh&amount=10&paymentDescription=soap); 
$options = array( 
  'http' => array( 
    'header' => "Authorization: 0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=", 
    'method' => 'POST', 
    'Authorization'=> '0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=', 
    'content' => http_build_query($data) 
    ), 
  ); 
$context = stream_context_create($options); 
$result = file_get_contents($url, false, $context); 
if ($result === FALSE) { /* Handle error */ } 
  var_dump($result); 
?>
Sample Response:
{ 
  "status":0, 
  "message":"Payment Invoice Generated", 
  "result":{ 
    "amount":"10", 
    "customerName":"kartikeya", 
    "transactionId":"45654", 
    "paymentURL":"https://www.payumoney.com/payments/#/user/13F25D4DA937C9A29F7F5FF23310DB7A", 
    "paymentId":"1110599157", 
    "customerEmail":"kartikeya.mishra@payu.in", 
    "emailSent":false 
    }, 
    "errorCode":null, 
    "responseCode":null 
  }

8.) SMS Invoice API: This API can be used by the merchants to send an SMS invoice to their customers for collecting payments through PayUmoney.

  Production Server Test Server
API URL https://www.payumoney.com/payment/payment/smsInvoice? http://test.payumoney.com/payment/payment/smsInvoice?

Type: POST
Authorization Header: REQUIRED

Parameter Required Description/Value
customerName Mandatory Name of the customer (numbers, alphabet, space and hyphen are allowed)
customerMobileNumber Mandatory Mobile number of the customer
(just 10 digits of the mobile number)
amount Mandatory Payment amount
(Positive amount up to 2 decimal places)
description Mandatory A brief description for the customer to identify the payment
(numbers, alphabet, space and hyphen are allowed)
invoiceReferenceId Mandatory Transaction or Order Reference Id (numbers, alphabet, space and hyphen are allowed)
confirmSMSPhone Optional Mobile Number for sending additional Confirmation SMS Notification
(just 10 digits of the mobile number)
Code Example:
<?php 
$url = 'https://www.payumoney.com/payment/payment/smsInvoice?invoiceReferenceId=654565&customerMobileNumber=7042692055&customerName=Ekansh&amount=10&description=soap'; 
$data =array('merchantKey'=>'eM8ZaP','refundId'=>'13918'); 
$options = array( 
  'http' => array( 
    'header' => "Authorization: 0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=", 
    'method' => 'POST', 
    'Authorization'=> '0SC8FamYqWnwFzVgYKmiCfSsT96xerU8E+WBUh/KDXc=', 
    'content' => http_build_query($data) 
    ), 
  ); 
$context = stream_context_create($options); 
$result = file_get_contents($url, false, $context); 
if ($result === FALSE) { /* Handle error */ } 
  var_dump($result); 
?>
Sample Response:
{ 
  "status":0, 
  "message":"SMS Sent", 
  "result":{ 
    "paymentId":1110599220, 
    "merchantTransactionId":"sms-1110599220", 
    "amount":10.0, 
    "customerMobileNumber":"7042692055", 
    "customerName":"kartikeya", 
    "url":" " 
    }, 
    "errorCode":null, 
    "responseCode":null 
  }

Webhooks

A Webhook is an HTTP callback. The call back is done to a url specified while creating a webhook.
The webhook callbacks are event driven i.e. a callback to a webhook will be done whenever the event associated with the webhook occurs.

Eg: Successful Payment Webhook - The event associated with this webhook is Successful Payment. So whenever a successful payment happens, a callback to the webhook url will be done.

Webhook help in automated updation of database rather than doing it manually. You can also use webhook to notify yourself for various events. Currently we are providing 4 types of webhook events-
1.) Successful Payment: Whenever a payment is success for your merchant account, you will receive a callback to your server.
2.) Failed Payment: Whenever a payment is failed for your merchant account, you will receive a callback to your server.
3.) Refunds: Whenever a payment is refunded (refund initiated as well as refund completed), you will receive a callback to your server.
4.) Dispute: Whenever a dispute is raised or resolved, you will receive a callback to your server with details of the dispute.

Note:
  1. Your webhook should acknowledge that it received data with 200 OK response. Any response outside of the 200 range will be treated as failure to receive data.
  2. A webhook will be disabled (i.e. will not POST data on URL) if there are 20 consecutive failures in sending POST requests to the specified URL.
1.) Successful Payment
{ 
  "split_info":"59017743", 
  "customerName":"Test user", 
  "additionalCharges":"", 
  "paymentMode":"DC", 
  "hash":"64700c3a13f37c1271df8c0ebe67c4aad2d29a2086e80aaa3d16580bbe38f9ffd0c3996eab241aa730a4efe512c6c15730ca66020064d71d85dcb68631119f29", 
  "status":"Success", 
  "error_Message":"No Error", 
  "paymentId":"59017743", 
  "productInfo":"Description1", 
  "customerEmail":"storedcard8@yopmail.com", 
  "customerPhone":"6709133497", 
  "merchantTransactionId":"4826753-59017743", 
  "amount":"100.0", 
  "udf2":"", 
  "notificationId":"37208", 
  "udf1":"", 
  "udf5":"", 
  "udf4":"", 
  "udf3":"" 
}
2.) Failure Payment
{ 
  "split_info":"59017411", 
  "customerName":"First Name", 
  "additionalCharges":"3.56", 
  "paymentMode":"CC", 
  "hash":"3d4ef7d8136e7ca969c4b6a08f6b01eb765bf7a545d50365b86c181f76ae4678294752e0bcf74d0c30d3c36571dc795ebb9194dea4445b7e89a388bf799a67df", 
  "status":"failed", 
  "error_Message":"Card authentication failed at the bank due to invalid CVV (or CVC or Card Security Code)", 
  "paymentId":"59017411", 
  "productInfo":"shopping", 
  "customerEmail":"storedcard1@yopmail.com", 
  "customerPhone":"6508591183", 
  "merchantTransactionId":"50c85e12568bf852f6a6", 
  "amount":"100.0", 
  "udf2":"", 
  "notificationId":"37174", 
  "udf1":"", 
  "udf5":"", 
  "udf4":"", 
  "udf3":"" 
}
3.) REFUNDS
   A) Refund initiated
{ 
  "notificationId":"25", 
  "completedOn":"null", 
  "refundAmount":"20.0", 
  "refundStatus":"Refund Initiated", 
  "refundId":"187680", 
  "paymentId":"58748975", 
  "merchantTxnId":"4826176-58748975", 
  "addedOn":"2016-03-08 19:14:44.0" 
}
   B) Refund Completed
{ 
  "notificationId":"24", 
  "completedOn":"2016-03-08 19:12:37.0", 
  "refundAmount":"124.0", 
  "refundStatus":"Refund Completed", 
  "refundId":"187679", 
  "paymentId":"58748973", 
  "merchantTxnId":"4826176-58748973", 
  "addedOn":"2016-03-08 19:10:37.0" 
}
4.) disputes
   A) dispute initiated
{ 
  "paymentId":"58749104", 
  "adminComment":"", 
  "issueType":"Goods/service not received", 
  "initiatorType":"customer", 
  "merchantTransactionId":"4826176-58749104", 
  "initiatedOn":"2016-03-09 16:39:20", 
  "notificationId":"74", 
  "disputeId":"389056", 
  "title":"Gd", 
  "totalAmount":"20.0", 
  "comment":"te", 
  "disputeStatus":"initiated", 
  "updatedOn":"2016-03-09 16:39:20" 
}
   B) dispute resolved
{ 
  "paymentId":"58749104", 
  "adminComment":"", 
  "issueType":"Goods/service not received", 
  "initiatorType":"customer", 
  "merchantTransactionId":"4826176-58749104", 
  "initiatedOn":"2016-03-09 16:39:20", 
  "notificationId":"77", 
  "disputeId":"389056", 
  "title":"Gd", 
  "totalAmount":"20.0", 
  "comment":"te", 
  "disputeStatus":"resolved", 
  "updatedOn":"2016-03-09 16:44:16" 
}