> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caibo.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Payment Request

> Retrieve detailed information about a specific payment request using its ID

# Overview

Retrieve comprehensive details about a specific payment request, including its current status, customer information, and transaction data.

## API Endpoint

```
GET /payment-requests/{id}
```

## Authentication

* **HTTP Header**: `X-API-Key` with your API key obtained from the dashboard
* **Content Type**: `application/json`

## Path Parameters

| Parameter | Description                | Type            | Required |
| --------- | -------------------------- | --------------- | -------- |
| `id`      | Payment request identifier | integer (int64) | YES      |

## Response

Returns complete payment request information including:

### Payment Request Details

* **ID**: Unique payment request identifier
* **Status**: Current payment request status
* **Amount**: Transaction amount and currency
* **Reference**: Merchant reference ID
* **Created Date**: When the payment request was created
* **Updated Date**: Last modification timestamp

### Customer Information

* **Customer ID**: Associated customer identifier
* **Name**: Customer full name
* **Email**: Customer email address
* **Phone**: Customer phone number
* **Address**: Billing/shipping address details

### Payment Configuration

* **Payment Methods**: Available payment options
* **Callback URLs**: Success, failure, and notification URLs
* **Expiration**: Payment request expiration time
* **Currency**: Transaction currency code

## Example Request

```bash theme={null}
curl -X GET \
  "https://apay.caibo.digital/payment-requests/12345" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json"
```

## Example Response

```json theme={null}
{
  "id": 12345,
  "status": "pending",
  "amount": 100.50,
  "currency": "USD",
  "referenceId": "ORDER-12345",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2024-01-15T11:30:00Z",
  "customer": {
    "id": 67890,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "paymentMethods": ["credit_card", "apple_pay", "google_pay"],
  "urls": {
    "success": "https://yoursite.com/success",
    "failure": "https://yoursite.com/failure",
    "notify": "https://yoursite.com/webhook"
  },
  "metadata": {
    "orderId": "ORD-12345",
    "productName": "Premium Subscription"
  }
}
```

## Response Status Codes

| Code  | Description                                   |
| ----- | --------------------------------------------- |
| `200` | OK - Payment request found and returned       |
| `400` | Bad Request - Invalid request format          |
| `401` | Unauthorized - Invalid API key                |
| `404` | Not Found - Payment request not found         |
| `500` | Internal Server Error - Server error occurred |

## Error Response Format

```json theme={null}
{
  "error": {
    "code": "PAYMENT_REQUEST_NOT_FOUND",
    "message": "Payment request with ID 12345 not found",
    "details": {
      "requestId": "req_abc123",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  }
}
```

## Use Cases

### Order Management

* **Order Tracking**: Link payment requests to order management systems
* **Status Monitoring**: Track payment progress in real-time
* **Customer Support**: Provide payment details for support inquiries

### Integration Scenarios

* **E-commerce Platforms**: Retrieve payment details for order fulfillment
* **Mobile Apps**: Display payment status to customers
* **Admin Dashboards**: Monitor payment request details
* **Reporting Systems**: Generate payment reports and analytics

## Implementation Example

### JavaScript/Node.js

```javascript theme={null}
async function getPaymentRequest(paymentId, apiKey) {
  try {
    const response = await fetch(
      `https://apay.caibo.digital/payment-requests/${paymentId}`,
      {
        method: 'GET',
        headers: {
          'X-API-Key': apiKey,
          'Content-Type': 'application/json'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const paymentRequest = await response.json();
    return paymentRequest;
    
  } catch (error) {
    console.error('Error fetching payment request:', error);
    throw error;
  }
}

// Usage
const paymentDetails = await getPaymentRequest(12345, 'your-api-key');
console.log('Payment Status:', paymentDetails.status);
console.log('Amount:', paymentDetails.amount, paymentDetails.currency);
```

### PHP

```php theme={null}
<?php
function getPaymentRequest($paymentId, $apiKey) {
    $url = "https://apay.caibo.digital/payment-requests/" . $paymentId;
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json'
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception("Failed to fetch payment request: " . $response);
    }
}

// Usage
try {
    $paymentDetails = getPaymentRequest(12345, 'your-api-key');
    echo "Payment Status: " . $paymentDetails['status'];
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}
?>
```

## Best Practices

### Security

* **API Key Protection**: Keep API keys secure and rotate regularly
* **HTTPS Only**: Always use HTTPS for API communications
* **Rate Limiting**: Implement appropriate rate limiting
* **Input Validation**: Validate payment request IDs before making requests

### Performance

* **Caching**: Cache payment request details when appropriate
* **Error Handling**: Implement robust error handling and retry logic
* **Monitoring**: Monitor API response times and success rates
* **Pagination**: Use pagination for bulk payment request retrieval

### Integration

* **Webhook Integration**: Use webhooks for real-time status updates instead of constant polling
* **Status Mapping**: Map payment request statuses to your system's workflow
* **Logging**: Log all API interactions for debugging and audit purposes
* **Testing**: Test with various payment request states and edge cases

## Related Endpoints

* **[Create Payment Request](/ipg/payment-request)**: Create new payment requests
* **[Payment Status Check](/ipg/payment-status-check)**: Check payment status
* **[Handle Payment Request](/ipg/handle-payment-request)**: Handle payment with specific method
* **[Release Payment Request](/ipg/release-payment-request)**: Release payment request


## OpenAPI

````yaml api GET /payment-requests/{id}
openapi: 3.0.4
info:
  title: FinHub API
  description: >-
    FinHub API provides services for the Caibo platform to support client's
    applications
  version: v1
servers:
  - url: https://apay.caibo.digital
    description: Caibo APay server (Test and Production share base; method IDs differ)
security: []
paths:
  /payment-requests/{id}:
    get:
      tags:
        - PaymentRequests
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}

````