Introduction
Payumoney payment gateway API documentation
Authorization
In order to call our payment gateway API, 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 |
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:
- 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:
- You can send one or multiple merchantTransactionIds in one API call.
- From and to both should be posted, if date parameter is used.
- 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:
- 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:
- 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.
- 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"
}