Reports API documentation v1.0
Introduction:
This protocol allows merchants to extract the following types of reports:
Protocol description
The reports API provides methods for accessing merchant reports such as order reports, products reports or operator reports.
All API requests are made using the HTTPs GET protocol.
All API responses are in JSON format, except the operator report download method that returns the specified operator report in PDF format.
Resources:
Orders report Description: returns the orders report for a specified time period. The maximum time period is one calendar month.API endpoint: https://secure.payu.ro/reports/orders
| Required request fields | Description |
| merchant | Internal merchant code (string) or internal merchant id (integer) |
| startDate | Orders created date filters (YYYY-mm-dd). Either startDate and endDate, or startCompleteDate and endCompleteDate should be sent. |
| endDate | |
| startCompleteDate | Orders complete date filters (YYYY-mm-dd). Either startDate and endDate, or startCompleteDate and endCompleteDate should be sent. |
| endCompleteDate | |
| timeStamp | Current Unix time (Unix time) |
| signature | Request's unique signature, see the signature for more details |
| Optional request fields | Description |
| externalRefNo | Merchant referance number send in authorization request. Should be send to signature too. |
| orderStatus[] | Orders status filter. Array of order statuses. Available values: 'COMPLETE', 'CANCELED', 'AUTHRECEIVED', 'REFUND', 'PENDING', 'REVERSED' |
Note: If you're using externalRefNo optional parameter, startDate and endDate or startCompleteDate and endCompleteDate parameters will become optional and will not be required anymore.
| Response fields | Description |
| statusCode | See available status codes for more details |
| statusDescription | Text description for statusCode |
| data | Report data on success, false / NULL on error |
https://secure.payu.ro/reports/orders?merchant=TestMerchantCode&startDate=2012-12-01&endDate=2012-12-31&orderStatus[]=COMPLETE&orderStatus[]=AUTHRECEIVED&timeStamp=1360588205&signature=4ecee87cef96688beba343794fe1e9bcResponse example:
{
"statusCode":"0",
"statusDescription":"Success",
"data":[
{
"Order No":"13650",
"Order status":"AUTHRECEIVED",
"Reference No":"11691083",
"External Reference No":"9",
"Pay Method":"Star BT",
"Order Date":"2012-12-03 09:52:43",
"Order Finish Date":"2012-12-03 09:52:47",
"Currency":"RON",
"Quantity":"1",
"Unit price (without VAT)":"10",
"Total Price":"10.00",
"Total VAT":"0.00",
"Unit Discount":"0.00",
"Promotion":"",
"Promotion Coupon Code":"",
"General Discount":"0",
"PAYU Discount":"0",
"Shipping":"0",
"General Total":"10",
"Processing fee":"0",
"Company":"Company3",
"Client":"first name10 last name1",
"Address":"address9 address6",
"Phone":"0749100713",
"Email":"email2@email.com",
"City":"city5",
"Zip Code":"3",
"Country":"Romania",
"State":"",
"CNP":"",
"Fiscal Code":"136810",
"Registration Number":"136810",
"Bank":"Bank2",
"Bank Account":"136810",
"Delivery Client":"first name10 last name1",
"Delivery Address":"address9 address6",
"Delivery Phone":"0749100713",
"Delivery Email":"email2@email.com",
"Delivery City":"city5",
"Delivery Zip Code":"3",
"Delivery Country":"Romania",
"Delivery state":"",
"Authorization":"An error occurred during processing. Please retry the operation",
"Approval status":"In progress",
"Net Profit":"10",
"Delivered codes":"",
"Installments":"3",
"Token":"PAY_BY_CLICK",
"RRN":"548463672275",
"Order Confirmation Date":"2012-12-03 09:52:47",
"Merchant Code":"TestMerchantCode",
"Issuer Bank Country":"Romania",
"Issuer Bank":"Bank Name",
"Customer IP":"91.220.167.201",
"Credit Card Masked Number":"411111-xxxxxx-1111",
"Interchange Fee":"2.09",
"Authorization Code":"579951",
"Response Code":"00",
"Card Payment Type" : "DEBIT"
}
]
}
Products report
Description: Returns the products report for a specified time period. The maximum time period is one calendar month.API endpoint: https://secure.payu.ro/reports/products
| Required fields | Description |
| merchant | Internal merchant code (string) or internal merchant id (integer) |
| startDate | Report's start date (YYYY-mm-dd) |
| endDate | Report's end date (YYYY-mm-dd) |
| timeStamp | Current Unix time (Unix time) |
| signature | Request's unique signature, see the signature for more details |
| Response fields | Description |
| statusCode | See available status codes for more details |
| statusDescription | Text description for statusCode |
| data | Report data on success, false / NULL on error |
https://secure.payu.ro/reports/products?merchant=TestMerchantCode&startDate=2012-12-01&endDate=2012-12-31&timeStamp=1360588205&signature=0b141e59e099ea0ee080fb4a63a5a698Response example:
{
"statusCode":"0",
"statusDescription":"Success",
"data":[
{
"Product ID":"8004001",
"Product Code":"4",
"Product":"prod2",
"Extra info":"2",
"Order No":"13650",
"Order status":"AUTHRECEIVED",
"Reference No":"11691083",
"External Reference No":"9",
"Pay Method":"Star BT",
"Order Date":"2012-12-03 09:52:43",
"Order Finish Date":"2012-12-03 09:52:47",
"Currency":"RON",
"Quantity":"1",
"Unit price (without VAT)":"10",
"Total Price":"10.00",
"Total VAT":"0.00",
"Unit Discount":"0.00",
"Promotion":"",
"Promotion Coupon Code":"",
"General Discount":"0",
"PAYU Discount":"0",
"Shipping":"0",
"General Total":"10",
"Processing fee":"0",
"Company":"Company3",
"Client":"first name10 last name1",
"Address":"address9 address6",
"Phone":"0749100713",
"Email":"email2@email.com",
"City":"city5",
"Zip Code":"3",
"Country":"Romania",
"State":"",
"CNP":"",
"Fiscal Code":"136810",
"Registration Number":"136810",
"Bank":"Bank2",
"Bank Account":"136810",
"Delivery Client":"first name10 last name1",
"Delivery Address":"address9 address6",
"Delivery Phone":"0749100713",
"Delivery Email":"email2@email.com",
"Delivery City":"city5",
"Delivery Zip Code":"3",
"Delivery Country":"Romania",
"Delivery state":"",
"Authorization":"An error occurred during processing. Please retry the operation",
"Approval status":"In progress",
"Net Profit":"10",
"Delivered codes":"",
"Installments":"3",
"Token": "",
"RRN": "",
"Order Confirmation Date": "2012-12-03 09:52:47",
"Merchant Code":"TestMerchantCode",
"Issuer Bank Country": "Romania",
"Issuer Bank": "Bank Name",
"Customer IP": "91.220.167.201",
"Credit Card Masked Number": ""
}
]
}
Operator report
Description: Returns the operator report for a specified time period.
Note: foreach of the returned reports, the operator report download method should be called in order to obtain each report in PDF format.
API endpoint: https://secure.payu.ro/reports/operator
| Required fields | Description |
| merchant | Internal merchant code (string) or internal merchant id (integer) |
| startDate | Report's start date (YYYY-mm-dd) |
| endDate | Report's end date (YYYY-mm-dd) |
| timeStamp | Current Unix time (Unix time) |
| signature | Request's unique signature, see the signature for more details |
| Response fields | Description |
| statusCode | See available status codes for more details |
| statusDescription | Text description for statusCode |
| data | Report data on success, false / NULL on error |
https://secure.payu.ro/reports/operator?merchant=TestMerchantCode&startDate=2012-12-01&endDate=2012-12-31&timeStamp=1360590579&signature=93082a090599d9264e4da426e9688138Response example:
{
"statusCode":"0",
"statusDescription":"Success",
"data":[
{
"IdOperatorReports":"316",
"DateFrom":"2012-11-01",
"DateTo":"2012-11-31",
"Autostamp":"0000-00-00 00:00:00",
"IdAccount":"10612",
"CompanyName":"Test Merchant SRL"
},
{
"IdOperatorReports":"317",
"DateFrom":"2012-12-01",
"DateTo":"2012-12-31",
"Autostamp":"0000-00-00 00:00:00",
"IdAccount":"10612",
"CompanyName":"Test Merchant SRL"
}
]
}
Operator report download
Description: returns the specified operator report in PDF format.API endpoint: https://secure.payu.ro/reports/operator/<IdOperatorReports>
| Required fields | Description |
| merchant | Internal merchant code (string) or internal merchant id (integer) |
| timeStamp | Current Unix time (Unix time) |
| signature | Request's unique signature, see the signature for more details |
https://secure.payu.ro/reports/operator/316?merchant=TestMerchantCode&timeStamp=1360596963&signature=88f0bd36ba4f3f7033d559f5484498aeResponse:
Case 1: Success
The response will be the actual PDF report file
Case 2: Error
In case of an error, an error message type will be returned in JSON format with the following structure:| Response fields | Description |
| statusCode | See available status codes for more details |
| statusDescription | Text description for statusCode |
| data | False / NULL on error |
Note: the Content-Type HTTP header of the response can be used to check the type of the response:
- "application/json" will indicate a response containing an error message in JSON format.
- "application/pdf" will indicate a response containing a downloadable PDF report file.
Available status codes
| statusCode | statusDescription |
| 0 | Success |
| 1 | Invalid report type |
| 2 | Invalid merchant |
| 3 | Invalid start date |
| 4 | Invalid end date |
| 5 | Invalid time period |
| 6 | Invalid timestamp |
| 7 | Invalid signature |
| 8 | Expired request, check timestamp |
| 9 | Invalid report ID |
| 10 | Internal error |
| 11 | Invalid date parameters |
| 12 | Invalid start complete date |
| 13 | Invalid end complete date |
| 14 | Invalid orderStatus |
Signature
For security reason, each HTTP request must carry a unique signature. Signature is performed using the HMAC MD5 algorithm and merchant's secret key.
Step 1: compose the source string by adding the length of each field value at the beginning of field value
Considering the following orders report request:
https://secure.payu.ro/reports/orders?merchant=TestMerchantCode&startDate=2012-12-01&endDate=2012-12-31&timeStamp=1360679091
The source string will be:
16TestMerchantCode102012-12-01102012-12-31101360679091
Note: when composing the source string, the fields order is important and should not be changed
Step 2: calculate the hash using the source string (as message) and merchant's secret key (as key)
Considering that merchant's secret key in this example is "SECRET_KEY", the hash value will be:
831e95506286b2bdf5990dce5d1cebe8
Step 3: add the hash value to the HTTP request as signature
https://secure.payu.ro/reports/orders?merchant=TestMerchantCode&startDate=2012-12-01&endDate=2012-12-31&timeStamp=1360679091&signature=831e95506286b2bdf5990dce5d1cebe8
Note: the timeStamp parameter is used to limit the valability of the request to 15 minutes.