> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Payment Request Details API
> Retrieve a single payment request (vendor advance) by its identifier
## Authentication
All requests require an API key in the request headers.
**Headers:**
```
Authorization: Api-Key YOUR_API_KEY
```
The permission required on your API key is **Payment Request** with the **Read** action enabled.
In addition to the API key permission, the user the API key belongs to must have an **admin** or **bookkeeper** role in the organization. Any other role gets a `403 ACCESS_DENIED` — see [Error Responses](#error-responses).
## Request
### Path Parameters
| Parameter | Type | Required | Description |
| ------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentRequestId` | string | Yes | Identifier of the payment request to retrieve (1–100 characters). This is the `paymentRequestId` returned by the [Vendor Advance Creation](/apis/vendor-advance-creation) API, or the `id` of any row returned by the [Payment Request List](/apis/payment-request-list) API |
Only payment requests of type `VENDOR_ADVANCE` are supported today. Requesting any other payment request type returns a `400 VALIDATION_ERROR` — see [Error Responses](#error-responses).
## Code Examples
```bash cURL theme={null}
curl -X GET https://api.pazy.io/v1.0/payment/request/payment_request_identifier \
-H "Authorization: Api-Key YOUR_API_KEY"
```
```javascript JavaScript (Fetch API) theme={null}
const response = await fetch(
'https://api.pazy.io/v1.0/payment/request/payment_request_identifier',
{
method: 'GET',
headers: {
Authorization: 'Api-Key YOUR_API_KEY'
}
}
);
const result = await response.json();
```
```python Python (requests) theme={null}
import requests
url = "https://api.pazy.io/v1.0/payment/request/payment_request_identifier"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
result = response.json()
```
## Success Response
**HTTP Status:** `200 OK`
**Response Fields:**
| Field | Type | Description |
| ------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `ok` | boolean | Indicates whether the request was successful |
| `data.paymentRequest.id` | string | Identifier of the payment request — the same value you passed as `paymentRequestId` |
| `data.paymentRequest.sequenceNo` | string | Human-readable running number assigned to the request within the organization |
| `data.paymentRequest.type` | string | Always `VENDOR_ADVANCE` |
| `data.paymentRequest.amount` | number | Net payable amount of the request (after GST, TDS and round-off) |
| `data.paymentRequest.tax` | object | Amount breakdown. `null` when no tax data is stamped on the advance |
| `data.paymentRequest.tax.subTotal` | number | Original (pre-tax) amount the advance was raised for |
| `data.paymentRequest.tax.gst` | number | GST amount added. `0` when GST was not applicable |
| `data.paymentRequest.tax.tds` | number | TDS amount deducted. `0` when TDS was not applicable |
| `data.paymentRequest.tax.roundOff` | number | Round-off adjustment applied to reach the net payable. Absent when no round-off was applied |
| `data.paymentRequest.currency` | string | ISO currency code of the request e.g. `INR` |
| `data.paymentRequest.state` | string | Approval lifecycle state of the request e.g. `PENDING`, `APPROVED`, `REJECTED` |
| `data.paymentRequest.paymentState` | string | Payment lifecycle state e.g. `AWAITING`, `PAID` |
| `data.paymentRequest.approvalState` | string | Payer's approval state e.g. `PENDING`, `APPROVED` |
| `data.paymentRequest.requestDate` | string | ISO 8601 timestamp of when the request was created |
| `data.paymentRequest.narration` | string | Free-text description stored against the advance. Empty string when none was given |
| `data.paymentRequest.tags` | object | Tags and custom fields on the advance, keyed by tag slug. See [Tags Object](#tags-object) |
| `data.paymentRequest.createdBy` | object | User who created the request. `null` if the user could not be resolved |
| `data.paymentRequest.createdBy.id` | string | Identifier of the creating user |
| `data.paymentRequest.createdBy.name` | string | Name of the creating user |
| `data.paymentRequest.payer` | object | User assigned as payer. `null` when no payer is assigned |
| `data.paymentRequest.payer.id` | string | Identifier of the payer |
| `data.paymentRequest.payer.name` | string | Name of the payer |
| `data.paymentRequest.vendor` | object | Vendor the advance was raised for |
| `data.paymentRequest.vendor.id` | string | Vendor identifier — usable with the [Vendor Details](/apis/vendor-details) API |
| `data.paymentRequest.vendor.name` | string | Vendor display name |
| `data.paymentRequest.vendor.GSTIN` | string | Vendor GSTIN. `null` when the vendor has none on record |
| `data.paymentRequest.vendor.PAN` | string | Vendor PAN. Derived from the GSTIN when not stored separately; empty string when neither is available |
| `data.paymentRequest.purchaseOrderLink` | object | Linked purchase order. `null` when the advance is not linked to a PO |
| `data.paymentRequest.purchaseOrderLink.id` | string | Purchase order identifier — usable with the [PO Details](/apis/po-details) API |
| `data.paymentRequest.purchaseOrderLink.poNumber` | string | Human-readable purchase order number |
### Tags Object
`tags` is keyed by tag/field slug. Predefined organization tags (cost centre, department, location, expense head) carry the selected value's `id` alongside its `value`; custom fields carry only a `value`.
```json theme={null}
"tags": {
"cost-centre": { "id": 812, "value": "Operations" },
"department": { "id": 47, "value": "Procurement" },
"project-code": { "value": "PRJ-1" }
}
```
### Response Example
```json theme={null}
{
"ok": true,
"data": {
"paymentRequest": {
"id": "",
"sequenceNo": "615",
"type": "VENDOR_ADVANCE",
"amount": 106200,
"tax": {
"subTotal": 100000,
"gst": 18000,
"tds": 1000,
"roundOff": -0.2
},
"currency": "INR",
"state": "PENDING",
"paymentState": "AWAITING",
"approvalState": "PENDING",
"requestDate": "2026-06-19T13:17:51.749Z",
"narration": "Advance for Q3 packaging order",
"tags": {
"cost-centre": { "id": 812, "value": "Operations" },
"project-code": { "value": "PRJ-1" }
},
"createdBy": {
"id": "",
"name": "John Doe"
},
"payer": {
"id": "",
"name": "Jane Smith"
},
"vendor": {
"id": "",
"name": "MDP Coffee House",
"GSTIN": "29AAJCM3528P1ZR",
"PAN": "AAJCM3528P"
},
"purchaseOrderLink": {
"id": "",
"poNumber": "PO-2026-0042"
}
}
}
}
```
## Error Responses
### Validation Errors
**HTTP Status:** `400 Bad Request`
Returned when `paymentRequestId` fails schema validation (empty, or longer than 100 characters).
```json theme={null}
{
"ok": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed: /paymentRequestId: must NOT have more than 100 characters"
}
}
```
### Unsupported Payment Request Type
**HTTP Status:** `400 Bad Request`
The identifier resolves to a payment request that isn't a vendor advance (e.g. a direct payment, reimbursement group, or bulk payout).
```json theme={null}
{
"ok": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Payment request API does not support DIRECT yet."
}
}
```
### Payment Request Not Found
**HTTP Status:** `404 Not Found`
```json theme={null}
{
"ok": false,
"error": {
"code": "PAYMENT_REQUEST_NOT_FOUND",
"message": "Payment request not found"
}
}
```
### Access Denied
**HTTP Status:** `403 Forbidden`
The API key's user is not an admin or bookkeeper:
```json theme={null}
{
"ok": false,
"error": {
"code": "ACCESS_DENIED",
"message": "Access denied: only admins and bookkeepers can view payment request"
}
}
```
The request exists but has not been submitted yet, so it isn't readable over the API:
```json theme={null}
{
"ok": false,
"error": {
"code": "ACCESS_DENIED",
"message": "Payment request is not yet submitted"
}
}
```
The request is a bulk payout and bulk payout isn't enabled for the organization:
```json theme={null}
{
"ok": false,
"error": {
"code": "ACCESS_DENIED",
"message": "Bulk payout is not enabled for this organization"
}
}
```
### Authentication Errors
**HTTP Status:** `401 Unauthorized`
```json theme={null}
{
"ok": false,
"error": {
"code": "MISSING_CREDENTIALS",
"message": "Missing Credentials"
}
}
```
```json theme={null}
{
"ok": false,
"error": {
"code": "INVALID_API_KEY",
"message": "Invalid API Key"
}
}
```
### Permission Errors
**HTTP Status:** `403 Forbidden`
```json theme={null}
{
"ok": false,
"error": {
"code": "INSUFFICIENT_PERMISSIONS",
"message": "Permission check failed - PERMISSION_CHECK_FAILED"
}
}
```
## Best Practices
* Use `tax.subTotal` (not `amount`) when you need the pre-tax value the advance was raised for — `amount` is the net payable after GST, TDS and round-off
* Treat `purchaseOrderLink` and `payer` as optional; both are `null` for advances raised without a PO link or before a payer is resolved
* Poll `state`, `approvalState` and `paymentState` together to track a request end-to-end: `state` covers approval, `paymentState` covers settlement
* Store the `paymentRequestId` returned by [Vendor Advance Creation](/apis/vendor-advance-creation) at create time rather than looking the request up by sequence number later