Read Chargeback API

The Read Chargeback API responds with the all the chargebacks corresponding to the merchant. The chargebacks are filtered out on the basis of dispute received date and pagination.

Request parameters

Without date

This must contain the header with token you get using the Get Token API in the following format:

\--header 'X-Optimus-API-Key: <Bearer token>'

Query parameters

Parameter

Description

Example

merchant_Id mandatory

This parameter must contain the PayU ID provided by PayU.

143419

With date

This must contain the header with token you get using the Get Token API in the following format:

\--header 'X-Optimus-API-Key: <Bearer token>'

Query parameters

Parameter

Description

Example

merchant_Id mandatory

This parameter must contain the PayU ID provided by PayU.

143419

from_date optional

This parameter must contain the from date from when the charge back is required.

20-02-2023

to_date optional

This parameter must contain the to date of charge back.

21-02-2023

Sample request

Without date range

curl --location 'https://bankportal.payu.in/api/v1/chargebacks/16652223102' \
--header 'X-Optimus-API-Key: MerchantToken' \
--header 'Cookie: PHPSESSID=uq1sm7npk9dmid33bbe9dvdtcn'

With date range

curl --location 'https://bankportal.payu.in/api/v1/chargebacks?from_date=20-02-2023&to_date=21-02-2023&merchant_id=143419' \
--header 'X-Optimus-API-Key: MerchantToken' \
--header 'Cookie: PHPSESSID=uq1sm7npk9dmid33bbe9dvdtcn'

Response parameters

ParameterDescription
dataThis parameter contains the chargeback details as a JSON array. For more information, refer to data JSON field descriptions.
metaThis parameter contains the pagination details as a JSON object. For more information, refer to meta JSON field descriptions

data JSON field descriptions

FeildDescription
idThis parameter contains the chargeback ID.
typeThe parameter contains the chargebacks as type.
attributesThis parameter contains the chargeback details in a JSON format. For more information, refer to attributes JSON field descriptions.

attributes JSON field descriptions

FieldDescription
idThe field contains the chargeback ID.1295751
chargeback-amountThe field contains the chargeback amount.1.0
chargeback-typeThe field contains the chargeback type.CB
statusThe field contains the chargeback status.Closed Customer Favour
reply-beforeThe field contains the date before which the merchant must reply.24-Feb-2023
chargeback-reasonThe field contains the chargeback reason.Non Receipt of Goods or Services
bank-case-noThe field contains the bank case number for the chargeback.30008130343023154997151
debit-dateThe field contains the chargeback debit date.24-Jul-2023
debit-statusThe field contains the chargeback debit status.Chargeback Debited
credit-dateThe field contains the chargeback credit date.
customer-dispute-docsThe field contains the location of the docs or additional information provided to bank support about the disputed transaction.
transaction-detailsThis field contains the transaction details in a JSON format. For sample and description, refer to transaction-details JSON

transaction-details JSON

Sample JSON

\{  
"payu-id": "16652223102",
"transaction-id": "c0bb0c2107f53e791cb4",
"transaction-date": "23-Jan-2023",
"transaction-amount": "1.0",
"pg-name": "HPYIndusInd",
"card-number": "XXXXXXXXXXXX7559",
"refunded": false,
"refund-amount": null,
"bank-reference-number": "302315499715",
"settlement-date": "NA",
"merchant-utr": null,
"product-info": "Product Info",
"additional-charges": "0.0",
"transaction-fee": "1.0",
"udf-1": "",
"udf-5": null,
"card-scheme": null
}

JSON field descriptions

FieldDescription
payu-idUnique identifier assigned by PayU for the transaction (also known as mihpayid). This serves as the primary reference for all future actions on this transaction.
transaction-idMerchant's transaction identifier that was used when initiating the payment. This is the unique reference provided by the merchant system.
transaction-dateThe date when the transaction was processed, typically in the format DD-MMM-YYYY (e.g., "23-Jan-2023").
transaction-amountThe monetary value of the transaction. This is the original amount that was charged to the customer.
pg-namePayment Gateway name used for processing the transaction (e.g., "HPYIndusInd" indicates HDFC Bank Payment Gateway).
card-numberMasked card number used for the transaction, with most digits replaced by X for security (e.g., "XXXXXXXXXXXX7559").
refundedBoolean flag indicating whether the transaction has been refunded (true/false).
refund-amountThe amount that has been refunded from the transaction, if applicable. Shows null if no refund has been processed.
bank-reference-numberReference number provided by the bank for the transaction. This is used for reconciliation and serves as proof of transaction at the bank's end.
settlement-dateThe date when the transaction amount was settled to the merchant's account. Shows "NA" if settlement is pending.
merchant-utrUnique Transaction Reference number for merchant settlement. Used to track the settlement transaction in the merchant's bank account.
product-infoInformation about the product or service purchased in the transaction, as provided during payment initiation.
additional-chargesAny additional charges applied to the transaction beyond the base transaction amount.
transaction-feeThe fee charged by PayU for processing the transaction. This is typically a percentage of the transaction amount plus any fixed fees.
udf-1User-defined field 1 that can be used by merchants for storing custom data related to the transaction.
udf-5User-defined field 5 that can be used by merchants for storing custom data related to the transaction.
card-schemeThe card network or scheme associated with the payment card (e.g., Visa, Mastercard, RuPay, etc.).

meta JSON field descriptions

FieldDescription
paginationContains pagination information for the response. This object provides details about how the results are paginated and the total count of chargebacks. For more information, refer to pagination JSON field descriptions

pagination JSON field descriptions

FieldDescription
paginationContains pagination information for the response. This object provides details about how the results are paginated and the total count of chargebacks.
per-pageThe number of chargeback records displayed per page in the response. In the example, this is set to 500, meaning up to 500 chargeback records can be displayed on a single page.
total-chargebacksThe total number of chargeback records that match the query criteria. This indicates how many chargebacks exist in total, regardless of pagination. In the example, there are 3 total chargebacks.
total-pagesThe total number of pages available based on the per-page setting and the total number of chargebacks. In the example, there is 1 page since the total chargebacks (3) is less than the per-page limit (500).

Sample response

Without date range

{
    "data": {
        "id": "1295751",
        "type": "chargebacks",
        "attributes": {
            "id": 1295751,
            "chargeback-amount": "1.0",
            "chargeback-type": "CB",
            "chargeback-date": "20-Feb-2023",
            "status": "Closed Customer Favour",
            "reply-before": "24-Feb-2023",
            "chargeback-reason": "Non Receipt of Goods or Services",
            "bank-case-no": "30008130343023154997151",
            "debit-date": "24-Jul-2023",
            "comments": null,
            "debit-status": "Chargeback Debited",
            "credit-date": "NA",
            "customer-dispute-docs": [],
            "transaction-details": {
                "payu-id": "16652223102",
                "transaction-id": "c0bb0c2107f53e791cb4",
                "transaction-date": "23-Jan-2023",
                "transaction-amount": "1.0",
                "pg-name": "HPYIndusInd",
                "card-number": "XXXXXXXXXXXX7559",
                "refunded": false,
                "refund-amount": null,
                "bank-reference-number": "302315499715",
                "settlement-date": "NA",
                "merchant-utr": null,
                "product-info": "Product Info",
                "additional-charges": "0.0",
                "transaction-fee": "1.0",
                "udf-1": "",
                "udf-5": null,
                "card-scheme": null
            },
            "customer-details": {
                "first-name": "Payu-Admin",
                "last-name": "",
                "email": "[email protected]",
                "phone-number": "1234567890"
            }
        }
    }
}

With date range

{
    "data": [
        {
            "id": "1295751",
            "type": "chargebacks",
            "attributes": {
                "id": 1295751,
                "chargeback-amount": "1.0",
                "chargeback-type": "CB",
                "chargeback-date": "20-Feb-2023",
                "status": "Closed Customer Favour",
                "reply-before": "24-Feb-2023",
                "chargeback-reason": "Non Receipt of Goods or Services",
                "bank-case-no": "30008130343023154997151",
                "debit-date": "24-Jul-2023",
                "comments": null,
                "debit-status": "Chargeback Debited",
                "credit-date": "NA",
                "customer-dispute-docs": [],
                "transaction-details": {
                    "payu-id": "16652223102",
                    "transaction-id": "c0bb0c2107f53e791cb4",
                    "transaction-date": "23-Jan-2023",
                    "transaction-amount": "1.0",
                    "pg-name": "HPYIndusInd",
                    "card-number": "XXXXXXXXXXXX7559",
                    "refunded": false,
                    "refund-amount": null,
                    "bank-reference-number": "302315499715",
                    "settlement-date": "NA",
                    "merchant-utr": null,
                    "product-info": "Product Info",
                    "additional-charges": "0.0",
                    "transaction-fee": "1.0",
                    "udf-1": "",
                    "udf-5": null,
                    "card-scheme": null
                },
                "customer-details": {
                    "first-name": "Payu-Admin",
                    "last-name": "",
                    "email": "[email protected]",
                    "phone-number": "1234567890"
                }
            }
        },
        {
            "id": "1295752",
            "type": "chargebacks",
            "attributes": {
                "id": 1295752,
                "chargeback-amount": "1.0",
                "chargeback-type": "CB",
                "chargeback-date": "20-Feb-2023",
                "status": "Closed Customer Favour",
                "reply-before": "24-Feb-2023",
                "chargeback-reason": "Non Receipt of Goods or Services",
                "bank-case-no": "30008130343023159959693",
                "debit-date": "24-Jul-2023",
                "comments": null,
                "debit-status": "Chargeback Debited",
                "credit-date": "NA",
                "customer-dispute-docs": [],
                "transaction-details": {
                    "payu-id": "16652143419",
                    "transaction-id": "0d344315b040a777f30a",
                    "transaction-date": "23-Jan-2023",
                    "transaction-amount": "1.0",
                    "pg-name": "HPYIndusInd",
                    "card-number": "XXXXXXXXXXXX7559",
                    "refunded": false,
                    "refund-amount": null,
                    "bank-reference-number": "302315995969",
                    "settlement-date": "NA",
                    "merchant-utr": null,
                    "product-info": "Product Info",
                    "additional-charges": "0.0",
                    "transaction-fee": "1.0",
                    "udf-1": "",
                    "udf-5": null,
                    "card-scheme": null
                },
                "customer-details": {
                    "first-name": "Payu-Admin",
                    "last-name": "",
                    "email": "[email protected]",
                    "phone-number": "1234567890"
                }
            }
        },
        {
            "id": "1295753",
            "type": "chargebacks",
            "attributes": {
                "id": 1295753,
                "chargeback-amount": "1.0",
                "chargeback-type": "CB",
                "chargeback-date": "20-Feb-2023",
                "status": "Closed Customer Favour",
                "reply-before": "24-Feb-2023",
                "chargeback-reason": "Non Receipt of Goods or Services",
                "bank-case-no": "30008130343019172078172",
                "debit-date": "24-Jul-2023",
                "comments": null,
                "debit-status": "Chargeback Debited",
                "credit-date": "NA",
                "customer-dispute-docs": [],
                "transaction-details": {
                    "payu-id": "16626771711",
                    "transaction-id": "f73f8ee2567488b03269",
                    "transaction-date": "19-Jan-2023",
                    "transaction-amount": "1.0",
                    "pg-name": "HPYIndusInd",
                    "card-number": "XXXXXXXXXXXX7559",
                    "refunded": false,
                    "refund-amount": null,
                    "bank-reference-number": "301917207817",
                    "settlement-date": "NA",
                    "merchant-utr": null,
                    "product-info": "Product Info",
                    "additional-charges": "0.0",
                    "transaction-fee": "1.0",
                    "udf-1": "",
                    "udf-5": null,
                    "card-scheme": null
                },
                "customer-details": {
                    "first-name": "Payu-Admin",
                    "last-name": "",
                    "email": "[email protected]",
                    "phone-number": "1234567890"
                }
            }
        }
    ],
    "meta": {
        "pagination": {
            "per-page": 500,
            "total-chargebacks": 3,
            "total-pages": 1
        }
    }
}