Skip to main content
GET
/
payment-requests
/
{id}
cURL
curl --request GET \
  --url https://apay.caibo.digital/payment-requests/{id}
{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

​
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

ParameterDescriptionTypeRequired
idPayment request identifierinteger (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

curl -X GET \
  "https://apay.caibo.digital/payment-requests/12345" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json"

​
Example Response

{
  "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": "[email protected]",
    "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

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

​
Error Response Format

{
  "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

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
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

Path Parameters

​
id
integer<int64>
required

Response

OK