Header Parameters

Name	Type	Description	Mandatory (M) , Optional (O)	Provided by INSTANTPAY (Y/N)
X-Ipay-Auth-Code	String	Auth Code - 1 (Fixed)	M	Y
X-Ipay-Client-Id	String	Unique Client ID	M	Y
X-Ipay-Client-Secret	String	Unique secret key	M	Y
X-Ipay-Outlet-Id	String	Merchant unique ID	M	Y
X-Ipay-Endpoint-Ip	String	End Customer IP Address	M	N

Request Parameters

Name	Type	Mandatory (M) , Optional (O)	Description
billerId	String	M	BillerId of the Biller

Sample Request

curl --location --request POST 'https://api.instantpay.in/marketplace/utilityPayments/billerDetails' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Ipay-Auth-Code: {{authCode}}' \
--header 'X-Ipay-Client-Id: {{clientId}}' \
--header 'X-Ipay-Client-Secret: {{clientSecret}}' \
--header 'X-Ipay-Endpoint-Ip: {{endPointIP}}' \
--header 'X-Ipay-Outlet-Id: {{outletID}}' \
--data-raw '{
		"billerId" : "ATP"
}'

POST /marketplace/utilityPayments/billerDetails HTTP/1.1
Host: api.instantpay.in
Accept: application/json
Content-Type: application/json
X-Ipay-Auth-Code: 1
X-Ipay-Client-Id: YWY3OTAzYzNlM2ExZTJlOfh549Gzt+5IEcETrD5Yx+Q=
X-Ipay-Client-Secret: 679db35f926b8d0240a8c0d28729528ee8e6d5effa5fa0b20c04454004d2d825
X-Ipay-Endpoint-Ip: 45.115.105.205
X-Ipay-Outlet-Id: 72762
{
    "billerId" : "ATP"
}

Response Parameters

Name	Type	Description
statuscode	String	InstantPay Status Code
actcode	String	Action Code
status	String	Status Message
data	Array	Response Data (If Present)
timestamp	String	Current time (YYYY-MM-DD HH:II:SS)
ipay_uuid	String	Request reference number
orderid	String	Transaction Id ( If transaction otherwise it is null )
environment	String	Live

Sample Response

{
    "statuscode": "TXN",
    "actcode": null,
    "status": "Biller Details fetched successfully",
    "data": {
        "billerId": "UPPCL0000UTP01",
        "mode": "ONLINE",
        "acceptsAdhoc": "F",
        "paymentAmountExactness": "EXACT",
        "fetchRequirement": "MANDATORY",
        "supportValidation": "NOT_SUPPORTED",
        "billerInfo": {
            "type": "OFFUS",
            "name": "Uttar Pradesh Power Corp Ltd (UPPCL) - URBAN",
            "description": "-",
            "ownership": "Government",
            "effectFrom": 20170929,
            "effectTo": 20251231
        },
        "category": {
            "key": "C04",
            "name": "Electricity"
        },
        "initChannels": [
            {
                "name": "AGT",
                "desc": "Agent",
                "commercialType": "OFFLINE",
                "deviceInfo": [
                    {
                        "name": "terminalId",
                        "desc": "Terminal ID of the device",
                        "minLength": 1,
                        "maxLength": 10,
                        "inputType": "NUMERIC",
                        "regex": "^[0-9]{1,10}$"
                    },
                    {
                        "name": "mobile",
                        "desc": "Mobile number of the agent",
                        "minLength": 10,
                        "maxLength": 10,
                        "inputType": "NUMERIC",
                        "regex": "^[5-9][0-9]{9}$"
                    },
                    {
                        "name": "geoCode",
                        "desc": "Latitude and longitude of the device - Represented in degrees with 4 digits after decimal",
                        "minLength": 13,
                        "maxLength": 15,
                        "inputType": "ALL",
                        "regex": "^[0-9]{1,2}+[.]{1}+[0-9]{4}+[,]{1}+[0-9]{1,2}+[.]{1}+[0-9]{4}$"
                    },
                    {
                        "name": "postalCode",
                        "desc": "Postal code of the agent",
                        "minLength": 6,
                        "maxLength": 6,
                        "inputType": "NUMERIC",
                        "regex": "^[1-9][0-9]{5}$"
                    }
                ]
            },
            
                    {
                        "name": "app",
                        "desc": "Application used in the device",
                        "minLength": 1,
                        "maxLength": 20,
                        "inputType": "ALL",
                        "regex": "^[A-Za-z0-9- .]{1,20}$"
                    }
                ]
            },
            {
                "name": "MOBB",
                "desc": "Mobile Banking (Post-login)",
                "commercialType": "ONLINE",
                
            {
                "name": "BNKBRNCH",
                "desc": "Bank Branch",
                "commercialType": "OFFLINE",
                
            {
                "name": "BSC",
                "desc": "Business Correspondent",
                "commercialType": "OFFLINE",
                "deviceInfo": [
                    {
                        "name": "terminalId",
                        "desc": "Terminal ID of the device",
                        "minLength": 1,
                        "maxLength": 10,
                        "inputType": "NUMERIC",
                        "regex": "^[0-9]{1,10}$"
                    },
                    
                    {
                        "name": "postalCode",
                        "desc": "Postal code of the agent",
                        "minLength": 6,
                        "maxLength": 6,
                        "inputType": "NUMERIC",
                        "regex": "^[1-9][0-9]{5}$"
                    }
                ]
            }
        ],
        "paymentModes": [
            {
                "name": "Cash",
                "desc": "Cash",
                "paymentInfo": [
                    {
                        "name": "Remarks",
                        "desc": "Remarks when the mode of payment is cash",
                        "minLength": 1,
                        "maxLength": 50,
                        "inputType": "ALL",
                        "regex": "^[A-Za-z0-9- .]{1,50}$"
                    }
                ]
            },
            {
                "name": "Wallet",
                "desc": "Wallet",
                "paymentInfo": [
                    {
                        "name": "WalletName",
                        "desc": "Wallet name used for the payment",
                        "minLength": 4,
                        "maxLength": 20,
                        "inputType": "ALL",
                        "regex": "^[A-Za-z0-9 ]{4,20}$"
                    },
                    {
                        "name": "MobileNo",
                        "desc": "Mobile number for the payment",
                        "minLength": 10,
                        "maxLength": 10,
                        "inputType": "NUMERIC",
                        "regex": "^[5-9][0-9]{9}$"
                    }
                ]
            },
            {
                "name": "Internet_Banking",
                "desc": "Internet_Banking",
                "paymentInfo": [
                    {
                        "name": "IFSC",
                        "desc": "IFSC of the branch from which the transaction is initiated",
                        "minLength": 11,
                        "maxLength": 11,
                        "inputType": "ALPHANUMERIC",
                        "regex": "^[A-Z0-9]{11}$"
                    },
                    {
                        "name": "AccountNo",
                        "desc": "Account number used for the payment",
                        "minLength": 2,
                        "maxLength": 30,
                        "inputType": "ALL",
                        "regex": "^[A-Z0-9]{3,30}$"
                    }
                ]
            },
            {
                "name": "Debit_Card",
                "desc": "Debit_Card",
                "paymentInfo": [
                    {
                        "name": "CardNum",
                        "desc": "Card number used for the payment",
                        "minLength": 5,
                        "maxLength": 20,
                        "inputType": "ALL",
                        "regex": "^[0-9]{5,20}$"
                    },
                    {
                        "name": "AuthCode",
                        "desc": "Authorization code used for the payment",
                        "minLength": 3,
                        "maxLength": 10,
                        "inputType": "ALL",
                        "regex": "^[0-9]{3,10}$"
                    }
                ]
            },
            {
                "name": "Credit_Card",
                "desc": "Credit_Card",
                "paymentInfo": [
                    {
                        "name": "CardNum",
                        "desc": "Card number used for the payment",
                        "minLength": 5,
                        "maxLength": 20,
                        "inputType": "ALL",
                        "regex": "^[0-9]{5,20}$"
                    },
                    {
                        "name": "AuthCode",
                        "desc": "Authorization code used for the payment",
                        "minLength": 3,
                        "maxLength": 10,
                        "inputType": "ALL",
                        "regex": "^[0-9]{3,10}$"
                    }
                ]
            },
            {
                "name": "Prepaid_Card",
                "desc": "Prepaid_Card",
                "paymentInfo": [
                    {
                        "name": "CardNum",
                        "desc": "Card number used for the payment",
                        "minLength": 5,
                        "maxLength": 20,
                        "inputType": "ALL",
                        "regex": "^[0-9]{5,20}$"
                    },
                    {
                        "name": "AuthCode",
                        "desc": "Authorization code used for the payment",
                        "minLength": 3,
                        "maxLength": 10,
                        "inputType": "ALL",
                        "regex": "^[0-9]{3,10}$"
                    }
                ]
            },
            {
                "name": "IMPS",
                "desc": "IMPS",
                "paymentInfo": [
                    {
                        "name": "MobileNo",
                        "desc": "Mobile number for the payment",
                        "minLength": 10,
                        "maxLength": 10,
                        "inputType": "NUMERIC",
                        "regex": "^[5-9][0-9]{9}$"
                    }
                ]
            },
            {
                "name": "UPI",
                "desc": "UPI",
                "paymentInfo": [
                    {
                        "name": "VPA",
                        "desc": "Virtual Provider Address used for the payment",
                        "minLength": 3,
                        "maxLength": 50,
                        "inputType": "ALL",
                        "regex": "^[A-Za-z0-9@]{3,50}$"
                    }
                ]
            },
            {
                "name": "NEFT",
                "desc": "NEFT",
                "paymentInfo": [
                    {
                        "name": "IFSC",
                        "desc": "IFSC of the branch from which the transaction is initiated",
                        "minLength": 11,
                        "maxLength": 11,
                        "inputType": "ALPHANUMERIC",
                        "regex": "^[A-Z0-9]{11}$"
                    },
                    {
                        "name": "AccountNo",
                        "desc": "Account number used for the payment",
                        "minLength": 2,
                        "maxLength": 30,
                        "inputType": "ALL",
                        "regex": "^[A-Z0-9]{3,30}$"
                    }
                ]
            },
            {
                "name": "Account_Transfer",
                "desc": "Account_Transfer",
                "paymentInfo": [
                    {
                        "name": "IFSC",
                        "desc": "IFSC of the branch from which the transaction is initiated",
                        "minLength": 11,
                        "maxLength": 11,
                        "inputType": "ALPHANUMERIC",
                        "regex": "^[A-Z0-9]{11}$"
                    },
                    {
                        "name": "AccountNo",
                        "desc": "Account number used for the payment",
                        "minLength": 2,
                        "maxLength": 30,
                        "inputType": "ALL",
                        "regex": "^[A-Z0-9]{3,30}$"
                    }
                ]
            }
        ],
        "parameters": [
            {
                "name": "param1",
                "desc": "Consumer Number",
                "minLength": 10,
                "maxLength": 12,
                "inputType": "NUMERIC",
                "regex": "^([0-9]{10,12})$"
            }
        ],
        "timeout": 130
    },
    "timestamp": "2022-09-14 15:17:58",
    "ipay_uuid": "h005974333cf-**************-b12d-34b5397df325",
    "orderid": null,
    "environment": "LIVE",
    "internalCode": null
}

📘
The terms EXACT, EXACT_UP, and EXACT_DOWN refer to the modes of amount validation for bill payments. These modes are used by billers to specify how they want the payment amount to be handled.
EXACT:
This means that the amount entered by the customer must match the exact amount of the bill provided by the biller. No deviation is allowed. For example, if a bill is ₹500, the customer must pay exactly ₹500.
EXACT_UP:
This allows the customer to pay an amount that is either equal to or higher than the bill amount. The minimum payment should be the bill amount, but customers can choose to pay more if they want to round up or pay extra. For example, if the bill is ₹500, the customer can pay ₹500 or more (e.g., ₹510, ₹520).
EXACT_DOWN:
This allows the customer to pay an amount that is either equal to or less than the bill amount. The customer must pay at least some part of the bill, but they are not required to pay the full amount. For example, if the bill is ₹500, the customer can pay ₹500 or less (e.g., ₹490, ₹480), subject to the biller's minimum payment rules.

📘
The terms fetchRequirement and supportValidation are related to the handling of customer details and validation mechanisms during the bill payment process. Here's what they mean:
fetchRequirement:
This field indicates whether the bill fetch is mandatory before making the payment. In some cases, before a customer can make a payment, the system needs to retrieve the bill details from the biller using the customer identifier (e.g., account number, customer ID).
If fetchRequirement is true, it means the customer must first fetch the bill details from the biller before proceeding with the payment. The customer cannot directly input the amount or pay without fetching.
If fetchRequirement is false, the system allows the customer to directly make the payment without fetching the bill details. In such cases, the customer may manually enter the payment amount.
supportValidation:
This field specifies whether the biller supports validation of customer details before fetching the bill or making a payment.
If supportValidation is true, it means the biller’s API will validate customer details (like account number, phone number, etc.) during the process. This ensures that the details entered by the customer are correct before proceeding to fetch or pay.
If supportValidation is false, it means the system does not perform customer detail validation before fetching the bill or processing the payment. This could be useful in cases where validation is not necessary or when the biller does not support such checks.