Add example scripts for Paystack PHP client library usage

Author: frknasir

examples/README.md

@@ -0,0 +1,44 @@
+# Paystack PHP Examples
+
+This directory contains example scripts demonstrating how to use the Paystack PHP client library.
+
+## Prerequisites
+
+Before running these examples, make sure you have:
+
+1. Installed this package via Composer (`composer require starfolksoftware/paystack-php`)
+2. A valid Paystack secret key (test or live)
+
+## Available Examples
+
+### Payment Request Examples
+
+- `simple_payment_request.php`: Basic example showing how to create and list payment requests
+- `payment_request_demo.php`: Comprehensive example demonstrating all payment request API methods
+- `invoice_workflow.php`: Demonstrates a complete invoice workflow using payment requests
+- `recurring_billing.php`: Advanced example showing how to implement recurring billing using payment requests
+
+## How to Run
+
+1. Update the `$secretKey` variable in the example files with your Paystack secret key.
+2. Execute the script using PHP:
+
+```bash
+php examples/simple_payment_request.php
+```
+
+## Notes
+
+- These examples use the test mode by default. To use them in production, replace the test key with your live key.
+- The payment request API allows you to create, manage, and track payment requests and invoices for your customers.
+- Some examples create draft payment requests that don't send notifications automatically, giving you control over when to finalize and notify customers.
+
+## Error Handling
+
+The examples include basic error handling. In a production environment, you should implement more comprehensive error handling strategies based on your application's requirements.
+
+## Documentation
+
+For more information on the available methods and parameters, refer to:
+- The official Paystack API documentation: https://paystack.com/docs/api/payment-request/
+- The library's main README file

examples/invoice_workflow.php

@@ -0,0 +1,105 @@
+<?php
+
+// Include Composer autoloader
+require_once __DIR__ . '/../vendor/autoload.php';
+
+// Import the Paystack Client
+use StarfolkSoftware\Paystack\Client as PaystackClient;
+
+// Replace with your actual test secret key
+$secretKey = 'sk_test_your_secret_key_here';
+
+// Initialize the Paystack client
+$paystack = new PaystackClient([
+    'secretKey' => $secretKey,
+]);
+
+/**
+ * This example demonstrates a complete invoice workflow using Payment Requests:
+ * 1. Create a customer (if they don't exist)
+ * 2. Create a draft payment request
+ * 3. Update the payment request with additional line items
+ * 4. Finalize the payment request
+ * 5. Send notification to the customer
+ * 6. Check payment status later
+ */
+
+// Step 1: First, make sure we have a customer
+// Note: In a real application, you might want to check if the customer exists first
+try {
+    $customer = $paystack->customers->create([
+        'email' => 'john.doe@example.com',
+        'first_name' => 'John',
+        'last_name' => 'Doe',
+        'phone' => '+2348123456789'
+    ]);
+    
+    $customerCode = $customer['data']['customer_code'];
+    echo "Customer created with code: $customerCode\n";
+} catch (Exception $e) {
+    // Customer might already exist
+    echo "Note: " . $e->getMessage() . "\n";
+    
+    // In a real application, you would search for the customer here
+    $customerCode = 'CUS_existing_customer_code';
+}
+
+// Step 2: Create a draft payment request
+$draftPaymentRequest = $paystack->paymentRequests->create([
+    'description' => 'Monthly Service Invoice - June 2025',
+    'line_items' => [
+        ['name' => 'Basic Subscription', 'amount' => 30000, 'quantity' => 1]
+    ],
+    'customer' => $customerCode,
+    'due_date' => '2025-07-15',
+    'draft' => true, // Create as draft initially
+    'has_invoice' => true // Generate an invoice number
+]);
+
+$requestCode = $draftPaymentRequest['data']['request_code'];
+$invoiceNumber = $draftPaymentRequest['data']['invoice_number'];
+echo "Draft payment request created with code: $requestCode and invoice #$invoiceNumber\n";
+
+// Step 3: Update the payment request with additional items
+$updatedRequest = $paystack->paymentRequests->update($requestCode, [
+    'line_items' => [
+        ['name' => 'Basic Subscription', 'amount' => 30000, 'quantity' => 1],
+        ['name' => 'Premium Support', 'amount' => 15000, 'quantity' => 1],
+        ['name' => 'Additional Storage', 'amount' => 5000, 'quantity' => 2]
+    ],
+    'tax' => [
+        ['name' => 'VAT (7.5%)', 'amount' => 4125]
+    ],
+    'description' => 'Monthly Service Invoice - June 2025 (Updated)'
+]);
+
+echo "Payment request updated with additional items\n";
+
+// Step 4: Finalize the payment request
+$finalizedRequest = $paystack->paymentRequests->finalize($requestCode, [
+    'send_notification' => false // We'll send it manually in the next step
+]);
+
+echo "Payment request finalized\n";
+
+// Step 5: Send notification to the customer
+$notification = $paystack->paymentRequests->sendNotification($requestCode);
+echo "Payment notification sent to customer\n";
+
+// Step 6: Check payment status (this would typically happen later)
+echo "\nSimulating checking payment status after some time...\n";
+
+// In a real application, this would happen in a separate process or callback
+$verifiedRequest = $paystack->paymentRequests->verify($requestCode);
+$status = $verifiedRequest['data']['status'];
+$isPaid = $verifiedRequest['data']['paid'];
+
+echo "Current status: $status\n";
+echo "Paid: " . ($isPaid ? "Yes" : "No") . "\n";
+
+// Output the URL where the customer can view and pay the invoice (if available)
+if (isset($verifiedRequest['data']['pdf_url'])) {
+    echo "Invoice URL: " . $verifiedRequest['data']['pdf_url'] . "\n";
+}
+
+echo "\nPayment request workflow completed!\n";

examples/payment_request_demo.php

@@ -0,0 +1,103 @@
+<?php
+
+// Include Composer autoloader
+require_once __DIR__ . '/../vendor/autoload.php';
+
+// Import the Paystack Client
+use StarfolkSoftware\Paystack\Client as PaystackClient;
+
+// Replace with your actual test secret key
+$secretKey = 'sk_test_your_secret_key_here';
+
+// Initialize the Paystack client
+$paystack = new PaystackClient([
+    'secretKey' => $secretKey,
+]);
+
+// Helper function to display results in a readable format
+function displayResponse($title, $response) {
+    echo "=== {$title} ===\n";
+    echo json_encode($response, JSON_PRETTY_PRINT) . "\n\n";
+}
+
+try {
+    // Step 1: Create a payment request
+    echo "Creating a payment request...\n";
+    $createResponse = $paystack->paymentRequests->create([
+        'description' => 'Test Payment Request',
+        'line_items' => [
+            ['name' => 'Product A', 'amount' => 10000, 'quantity' => 2],
+            ['name' => 'Product B', 'amount' => 5000, 'quantity' => 1]
+        ],
+        'tax' => [
+            ['name' => 'VAT', 'amount' => 1000]
+        ],
+        'customer' => 'customer_email@example.com', // Can be customer code or email
+        'due_date' => date('Y-m-d', strtotime('+7 days')),
+        'draft' => true // Create as draft so we can test the finalize method later
+    ]);
+    displayResponse('Create Payment Request', $createResponse);
+    
+    // Save the request code for later use
+    $requestCode = $createResponse['data']['request_code'] ?? null;
+    if (!$requestCode) {
+        throw new Exception("Failed to get request code from the created payment request");
+    }
+    
+    // Step 2: List payment requests
+    echo "Listing payment requests...\n";
+    $listResponse = $paystack->paymentRequests->all([
+        'perPage' => 5,
+        'page' => 1
+    ]);
+    displayResponse('List Payment Requests', $listResponse);
+    
+    // Step 3: Fetch a specific payment request
+    echo "Fetching payment request with code: {$requestCode}...\n";
+    $fetchResponse = $paystack->paymentRequests->fetch($requestCode);
+    displayResponse('Fetch Payment Request', $fetchResponse);
+    
+    // Step 4: Verify a payment request
+    echo "Verifying payment request with code: {$requestCode}...\n";
+    $verifyResponse = $paystack->paymentRequests->verify($requestCode);
+    displayResponse('Verify Payment Request', $verifyResponse);
+    
+    // Step 5: Update the payment request
+    echo "Updating payment request with code: {$requestCode}...\n";
+    $updateResponse = $paystack->paymentRequests->update($requestCode, [
+        'description' => 'Updated Test Payment Request',
+        'due_date' => date('Y-m-d', strtotime('+10 days'))
+    ]);
+    displayResponse('Update Payment Request', $updateResponse);
+    
+    // Step 6: Finalize the draft payment request
+    echo "Finalizing draft payment request with code: {$requestCode}...\n";
+    $finalizeResponse = $paystack->paymentRequests->finalize($requestCode, [
+        'send_notification' => true
+    ]);
+    displayResponse('Finalize Payment Request', $finalizeResponse);
+    
+    // Step 7: Send a notification for the payment request
+    echo "Sending notification for payment request with code: {$requestCode}...\n";
+    $notificationResponse = $paystack->paymentRequests->sendNotification($requestCode);
+    displayResponse('Send Notification', $notificationResponse);
+    
+    // Step 8: Get payment requests totals
+    echo "Getting payment request totals...\n";
+    $totalsResponse = $paystack->paymentRequests->totals();
+    displayResponse('Payment Request Totals', $totalsResponse);
+    
+    // Step 9: Archive the payment request (uncommenting will archive the request)
+    /*
+    echo "Archiving payment request with code: {$requestCode}...\n";
+    $archiveResponse = $paystack->paymentRequests->archive($requestCode);
+    displayResponse('Archive Payment Request', $archiveResponse);
+    */
+    
+    echo "All payment request operations completed successfully!\n";
+    
+} catch (Exception $e) {
+    echo "Error: " . $e->getMessage() . "\n";
+    echo "File: " . $e->getFile() . " on line " . $e->getLine() . "\n";
+    echo "Stack trace:\n" . $e->getTraceAsString() . "\n";
+}