PayFast

https://github.com/zfhassaan/payfast
Admin
PayFast is a Laravel package for integrating the PayFast payment gateway, offering support for...
Tokens:70,102
Snippets:1,046
Trust Score:7.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and Configure Payfast Package

Source: https://github.com/zfhassaan/payfast/wiki/Understanding-the-Hosted-Checkout-Process-for-Payfast copy

Commands to install the package and publish the configuration file.

```bash
composer require zfhassaan/payfast
```

```bash
php artisan vendor:publish --tag=payfast-config
```

--------------------------------

### Install dependencies

Source: https://github.com/zfhassaan/payfast/wiki/Contributing

Install project dependencies using Composer.

```bash
composer install
```

--------------------------------

### Listen to PaymentInitiated Event

Source: https://github.com/zfhassaan/payfast/blob/main/wiki/Events-and-Listeners.md

Example listener for logging payment initiation details.

```php
use zfhassaan\Payfast\Events\PaymentInitiated;

Event::listen(PaymentInitiated::class, function ($event) {
    $paymentData = $event->paymentData;
    $response = $event->response;
    
    // Log payment initiation
    Log::info('Payment initiated', [
        'order' => $paymentData['orderNumber'],
        'amount' => $paymentData['transactionAmount'],
    ]);
});
```

--------------------------------

### Execute Full Payment Lifecycle Example

Source: https://github.com/zfhassaan/payfast/wiki/Models-and-Database

Demonstrates creating, updating, and querying a payment record.

```php
use zfhassaan\Payfast\Models\ProcessPayment;

// Create payment
$payment = ProcessPayment::create([
    'uid' => \Str::uuid(),
    'orderNo' => 'ORD-12345',
    'status' => ProcessPayment::STATUS_PENDING,
]);

// Update status
$payment->markAsValidated();

// Check status
if ($payment->isValidated()) {
    // Payment is validated
}

// Find and update
$payment = ProcessPayment::where('transaction_id', 'TXN123456')->first();
if ($payment) {
    $payment->markAsCompleted();
}
```

--------------------------------

### Install PayFast Package

Source: https://github.com/zfhassaan/payfast/wiki/Home copy

Use Composer to install the package into your Laravel project.

```bash
composer require zfhassaan/payfast
```

--------------------------------

### Verify Installation

Source: https://github.com/zfhassaan/payfast/wiki/Installation-Guide

Use tinker or a test route to verify the facade is correctly registered and functional.

```php
// In tinker or a test route
php artisan tinker

// Test facade
use zfhassaan\Payfast\Facades\PayFast;
PayFast::getToken();
```

--------------------------------

### Command Output Example

Source: https://github.com/zfhassaan/payfast/wiki/Console-Commands

Sample console output showing the processing status of individual payment records.

```text
Processing 5 payment(s)...
Checking payment: ORD-12345 (Status: validated)
✓ Payment ORD-12345 completed successfully
Checking payment: ORD-12346 (Status: validated)
✗ Payment ORD-12346 verification failed: Transaction not found
...

Processing complete!
Completed: 3
Processed: 5
Failed: 2
```

--------------------------------

### Controller IPN Implementation

Source: https://github.com/zfhassaan/payfast/blob/main/docs/content/API-Reference.md

Example of manual IPN handling within a controller.

```php
// In your controller
public function handleIPN(Request $request)
{
    $ipnData = $request->all();
    $response = PayFast::handleIPN($ipnData);
    return $response;
}
```

--------------------------------

### Load Migrations in TestCase

Source: https://github.com/zfhassaan/payfast/blob/main/TESTING.md

Use this in the setUp method to ensure database migrations are loaded during testing.

```php
$this->loadMigrationsFrom(__DIR__ . '/../../../packages/zfhassaan/payfast/src/database/migrations');
```

--------------------------------

### Implement Payment Controller

Source: https://github.com/zfhassaan/payfast/blob/main/PAYMENT_FLOW.md

A Laravel controller example demonstrating how to initiate payments, verify OTPs, and handle transaction callbacks using the PayFast facade.

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use zfhassaan\Payfast\Facades\PayFast;
use zfhassaan\Payfast\Models\ProcessPayment;

class PaymentController extends Controller
{
    public function initiatePayment(Request $request)
    {
        $paymentData = [
            'orderNumber' => $request->order_number,
            'transactionAmount' => $request->amount,
            'customerMobileNo' => $request->mobile,
            'customer_email' => $request->email,
            'cardNumber' => $request->card_number,
            'expiry_month' => $request->expiry_month,
            'expiry_year' => $request->expiry_year,
            'cvv' => $request->cvv,
        ];

        $response = PayFast::getOTPScreen($paymentData);
        $result = json_decode($response->getContent(), true);

        if ($result['status']) {
            return redirect('/otp-screen')->with([
                'transaction_id' => $result['data']['transaction_id'],
                'payment_id' => $result['data']['payment_id'],
            ]);
        }

        return back()->withErrors(['payment' => $result['message']]);
    }

    public function verifyOTP(Request $request)
    {
        $response = PayFast::verifyOTPAndStorePares(
            $request->transaction_id,
            $request->otp,
            $request->pares
        );

        $result = json_decode($response->getContent(), true);

        if ($result['status']) {
            return response()->json([
                'message' => 'OTP verified. Waiting for payment confirmation...',
                'pares' => $request->pares,
            ]);
        }

        return response()->json($result, 400);
    }

    public function handleCallback(Request $request)
    {
        $response = PayFast::completeTransactionFromPares($request->pares);
        $result = json_decode($response->getContent(), true);

        if ($result['status']) {
            $payment = ProcessPayment::where('data_3ds_pares', $request->pares)->first();
            
            // Update your order
            // Send confirmation email
            // etc.
            
            return response()->json([
                'status' => 'success',
                'transaction_id' => $payment->transaction_id,
            ]);
        }

        return response()->json($result, 400);
    }
}
```

--------------------------------

### Configure test environment

Source: https://github.com/zfhassaan/payfast/wiki/Testing-Guide

Set the necessary Payfast configuration values within the TestCase setup method.

```php
config([
    'payfast.api_url' => 'https://api.payfast.test',
    'payfast.merchant_id' => 'test_merchant_id',
    'payfast.secured_key' => 'test_secured_key',
    'payfast.mode' => 'sandbox',
]);
```

--------------------------------

### Configuring Test Environment

Source: https://github.com/zfhassaan/payfast/blob/main/TESTING.md

Set package configuration values within the TestCase setup method.

```php
config([
    'payfast.api_url' => 'https://api.payfast.test',
    'payfast.merchant_id' => 'test_merchant_id',
    // ...
]);
```

--------------------------------

### Install PHP cURL Extension

Source: https://github.com/zfhassaan/payfast/wiki/Installation-Guide

Commands to install the required cURL extension for different operating systems.

```bash
# Ubuntu/Debian
sudo apt-get install php-curl

# macOS (Homebrew)
brew install php-curl

# Windows (XAMPP/WAMP)
# Enable extension=curl in php.ini
```

--------------------------------

### Implement Custom Console Command

Source: https://github.com/zfhassaan/payfast/wiki/Console-Commands

Example of a custom command class that checks payment statuses and updates records using the PayFast facade.

```php
<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use zfhassaan\Payfast\Models\ProcessPayment;
use zfhassaan\Payfast\Facades\PayFast;

class CheckPayments extends Command
{
    protected $signature = 'payments:check {--status=}';
    protected $description = 'Check payment status';

    public function handle()
    {
        $status = $this->option('status') ?? 'validated';
        
        $payments = ProcessPayment::where('status', $status)
            ->limit(10)
            ->get();

        foreach ($payments as $payment) {
            $response = PayFast::getTransactionDetails($payment->transaction_id);
            $result = json_decode($response->getContent(), true);
            
            if ($result['status']) {
                $payment->markAsCompleted();
                $this->info("Payment {$payment->orderNo} completed");
            }
        }
    }
}
```

--------------------------------

### Listen to PaymentCompleted Event

Source: https://github.com/zfhassaan/payfast/blob/main/wiki/Events-and-Listeners.md

Example listener for updating order status and sending confirmation emails.

```php
use zfhassaan\Payfast\Events\PaymentCompleted;

Event::listen(PaymentCompleted::class, function ($event) {
    $paymentData = $event->paymentData;
    $response = $event->response;
    
    // Update order status
    $order = Order::where('order_number', $paymentData['orderNumber'])->first();
    if ($order) {
        $order->update(['status' => 'paid']);
    }
    
    // Send confirmation email
    Mail::to($paymentData['customer_email'])->send(new PaymentConfirmationMail($order));
});
```

--------------------------------

### Process Card Payment

Source: https://github.com/zfhassaan/payfast/blob/main/docs/index.html

Example of retrieving an authentication token and initiating a card payment request using the PayFast facade.

```php
use zfhassaan\Payfast\Facades\PayFast;

// Get authentication token
$response = PayFast::getToken();

// Process card payment
$paymentData = [
    'orderNumber' => 'ORD-12345',
    'transactionAmount' => 1000.00,
    'customerMobileNo' => '03001234567',
    'customer_email' => 'customer@example.com',
    'cardNumber' => '4111111111111111',
    'expiry_month' => '12',
    'expiry_year' => '2025',
    'cvv' => '123',
];

$response = PayFast::getOTPScreen($paymentData);
```

--------------------------------

### Initiate Transaction Directly

Source: https://github.com/zfhassaan/payfast/wiki/API-Reference

Start a transaction directly without going through the OTP flow.

```php
$response = PayFast::initiateTransaction($data);
```

```php
$data = [
    'orderNumber' => 'ORD-12345',
    'transactionAmount' => 1000.00,
    // ... other payment data
];
```

```php
$response = PayFast::initiateTransaction($paymentData);
$result = json_decode($response, true);
```

--------------------------------

### Mocking HTTP Client Service

Source: https://github.com/zfhassaan/payfast/wiki/Testing-Guide

Example of mocking an HTTP client interface and binding the mock instance into the application container.

```php
use zfhassaan\Payfast\Services\Contracts\HttpClientInterface;

$httpClient = Mockery::mock(HttpClientInterface::class);
$httpClient->shouldReceive('post')
    ->once()
    ->andReturn(['code' => '00', 'token' => 'test_token']);

$this->app->instance(HttpClientInterface::class, $httpClient);
```

--------------------------------

### PayFast Command Usage Examples

Source: https://github.com/zfhassaan/payfast/wiki/Console-Commands

Various ways to invoke the check-pending-payments command using status filters, limits, and notification toggles.

```bash
# Check all pending and validated payments
php artisan payfast:check-pending-payments

# Check specific status
php artisan payfast:check-pending-payments --status=otp_verified

# Limit results
php artisan payfast:check-pending-payments --limit=10

# Skip email notifications
php artisan payfast:check-pending-payments --no-email

# Combine options
php artisan payfast:check-pending-payments --status=validated --limit=20 --no-email
```

--------------------------------

### Initialize PayFast Migrations

Source: https://github.com/zfhassaan/payfast/blob/main/FINAL_IMPLEMENTATION.md

Commands to publish and run the necessary database migrations for the package.

```bash
php artisan vendor:publish --tag=payfast-migrations
php artisan migrate
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/zfhassaan/payfast/wiki/Contributing

Examples of commit messages following the conventional commits specification.

```text
feat: Add new payment method
fix: Fix token refresh issue
docs: Update installation guide
test: Add tests for new feature
refactor: Refactor payment service
chore: Update dependencies
```

--------------------------------

### GET /payment/status/{transactionId}

Source: https://github.com/zfhassaan/payfast/wiki/Getting-Started

Checks the status of a specific transaction.

```APIDOC
## GET /payment/status/{transactionId}

### Description
Retrieves the status of a transaction by its ID.

### Method
GET

### Endpoint
/payment/status/{transactionId}

### Parameters
#### Path Parameters
- **transactionId** (string) - Required - The unique identifier of the transaction.
```

--------------------------------

### Publish Configuration and Migrations

Source: https://github.com/zfhassaan/payfast/wiki/Understanding-the-Direct-Checkout-Process copy

Publish the necessary configuration files and database migrations for the package.

```bash
php artisan vendor:publish --tag=payfast-config
php artisan vendor:publish --tag=payfast-migrations
php artisan migrate
```

--------------------------------

### IPN Data Structure

Source: https://github.com/zfhassaan/payfast/blob/main/docs/content/API-Reference.md

Example array structure for IPN notification data.

```php
$ipnData = [
    'transaction_id' => 'TXN123456',
    'order_no' => 'ORD-12345',
    'status' => '00',
    'amount' => '1000.00',
    'currency' => 'PKR',
];
```

--------------------------------

### Listen to TokenRefreshed Event

Source: https://github.com/zfhassaan/payfast/blob/main/wiki/Events-and-Listeners.md

Example listener for updating the cached authentication token.

```php
use zfhassaan\Payfast\Events\TokenRefreshed;

Event::listen(TokenRefreshed::class, function ($event) {
    $oldToken = $event->oldToken;
    $newToken = $event->newToken;
    
    // Update token in cache or database
    Cache::put('payfast_token', $newToken, 3600);
});
```

--------------------------------

### Migrate PayFast Initialization

Source: https://github.com/zfhassaan/payfast/blob/main/REFACTORING_SUMMARY.md

Update legacy instantiation to use the service container or facade pattern.

```php
$payfast = new PayFast();
$result = $payfast->GetToken();
```

```php
$payfast = app('payfast'); // or use facade
$result = $payfast->getToken();
```

--------------------------------

### View Project File Structure

Source: https://github.com/zfhassaan/payfast/blob/main/REFACTORING_SUMMARY.md

Overview of the refactored directory layout for the PayFast package.

```text
src/
├── DTOs/
│   └── PaymentRequestDTO.php
├── Events/
│   ├── PaymentCompleted.php
│   ├── PaymentFailed.php
│   ├── PaymentInitiated.php
│   ├── PaymentValidated.php
│   └── TokenRefreshed.php
├── Listeners/
│   ├── LogPaymentActivity.php
│   └── StorePaymentRecord.php
├── Repositories/
│   ├── Contracts/
│   │   └── ProcessPaymentRepositoryInterface.php
│   └── ProcessPaymentRepository.php
├── Services/
│   ├── Contracts/
│   │   ├── AuthenticationServiceInterface.php
│   │   ├── HttpClientInterface.php
│   │   ├── PaymentServiceInterface.php
│   │   └── TransactionServiceInterface.php
│   ├── AuthenticationService.php
│   ├── ConfigService.php
│   ├── HttpClientService.php
│   ├── PaymentService.php
│   └── TransactionService.php
├── Helpers/
│   └── Utility.php (refactored)
├── Interfaces/
│   └── PaymentInterface.php (updated)
├── Models/
│   └── ProcessPayment.php (updated)
├── Facade/
│   └── Payfast.php (updated)
├── Provider/
│   └── PayFastServiceProvider.php (refactored)
└── PayFast.php (completely refactored)
```

--------------------------------

### Listen to PaymentFailed Event

Source: https://github.com/zfhassaan/payfast/blob/main/wiki/Events-and-Listeners.md

Example listener for logging errors and notifying administrators.

```php
use zfhassaan\Payfast\Events\PaymentFailed;

Event::listen(PaymentFailed::class, function ($event) {
    $paymentData = $event->paymentData;
    $errorCode = $event->errorCode;
    $errorMessage = $event->errorMessage;
    
    // Log failure
    Log::error('Payment failed', [
        'order' => $paymentData['orderNumber'],
        'error_code' => $errorCode,
        'error_message' => $errorMessage,
    ]);
    
    // Notify admin
    Mail::to(config('payfast.admin_emails'))->send(new PaymentFailureMail($paymentData, $errorMessage));
});
```

--------------------------------

### Listen to PaymentValidated Event

Source: https://github.com/zfhassaan/payfast/blob/main/wiki/Events-and-Listeners.md

Example listener for sending a validation notification email.

```php
use zfhassaan\Payfast\Events\PaymentValidated;

Event::listen(PaymentValidated::class, function ($event) {
    $paymentData = $event->paymentData;
    $response = $event->validationResponse;
    
    // Send validation notification
    Mail::to($paymentData['customer_email'])->send(new PaymentValidatedMail($paymentData));
});
```

--------------------------------

### Publish Command for Customization

Source: https://github.com/zfhassaan/payfast/wiki/Console-Commands

Execute this command to publish the package's console command file to the local application directory.

```bash
php artisan vendor:publish --tag=payfast-command
```

--------------------------------

### Set Up Merchant Data

Source: https://github.com/zfhassaan/payfast/wiki/Understanding-the-Hosted-Checkout-Process-for-Payfast copy

Retrieving merchant credentials from the configuration file.

```php
$merchant_id = config('payfast.merchant_id');
$secured_key = config('payfast.secured_key');
$merchant_name = 'Your Merchant Name'; // Your registered merchant name
```

--------------------------------

### Get Authentication Token

Source: https://github.com/zfhassaan/payfast/wiki/API-Reference

Retrieves the current authentication token as a string or null.

```php
$token = PayFast::getAuthToken();
```

--------------------------------

### Handle EasyPaisa Response

Source: https://github.com/zfhassaan/payfast/blob/main/docs/content/API-Reference.md

Example of decoding the JSON response from an EasyPaisa payment request.

```php
$response = PayFast::payWithEasyPaisa($paymentData);
$result = json_decode($response, true);
```

--------------------------------

### Configure PayFast Environment Variables

Source: https://github.com/zfhassaan/payfast/blob/main/README.md

Add these keys to your .env file to authenticate and configure the PayFast gateway.

```text
PAYFAST_API_URL=
PAYFAST_SANDBOX_URL=
PAYFAST_GRANT_TYPE=
PAYFAST_MERCHANT_ID=
PAYFAST_MODE=
PAYFAST_SECURED_KEY=
PAYFAST_RETURN_URL=
```

--------------------------------

### Using ProcessPaymentRepository

Source: https://github.com/zfhassaan/payfast/wiki/Models-and-Database

Demonstrates creating, finding, and updating payment records via the repository interface.

```php
use zfhassaan\Payfast\Repositories\Contracts\ProcessPaymentRepositoryInterface;

$repository = app(ProcessPaymentRepositoryInterface::class);

// Create payment
$payment = $repository->create([
    'orderNo' => 'ORD-12345',
    'status' => 'validated',
]);

// Find by transaction ID
$payment = $repository->findByTransactionId('TXN123456');

// Find by basket ID
$payment = $repository->findByBasketId('ORD-12345');

// Update payment
$repository->update($payment->id, [
    'status' => 'completed',
]);
```

--------------------------------

### Example IPN Data Structure

Source: https://github.com/zfhassaan/payfast/wiki/IPN-Handling

The expected format of the data payload received from PayFast.

```php
[
    'transaction_id' => 'TXN123456',
    'order_no' => 'ORD-12345',
    'status' => '00',
    'amount' => '1000.00',
    'currency' => 'PKR',
]
```

--------------------------------

### Run tests

Source: https://github.com/zfhassaan/payfast/wiki/Contributing

Execute the test suite using Artisan.

```bash
php artisan test
```

--------------------------------

### Run PayFast Tests

Source: https://github.com/zfhassaan/payfast/blob/main/IMPLEMENTATION_COMPLETE.md

Commands to execute the test suite from either the package directory or the project root.

```bash
# Run tests from package directory
cd packages/zfhassaan/payfast
composer install
./vendor/bin/phpunit

# Or from root
php artisan test --filter PayFast
```

--------------------------------

### Clone the repository

Source: https://github.com/zfhassaan/payfast/wiki/Contributing

Commands to clone the PayFast repository and navigate into the project directory.

```bash
git clone https://github.com/zfhassaan/payfast.git
cd payfast
```

--------------------------------

### Get OTP Screen for Card Payments

Source: https://github.com/zfhassaan/payfast/wiki/API-Reference

Validate customer details and retrieve the OTP screen for card payments.

```php
$response = PayFast::getOTPScreen($paymentData);
```

```php
$paymentData = [
    'orderNumber' => 'ORD-12345',        // Required
    'transactionAmount' => 1000.00,      // Required
    'customerMobileNo' => '03001234567', // Required
    'customer_email' => 'customer@example.com', // Required
    'cardNumber' => '4111111111111111',  // Required
    'expiry_month' => '12',              // Required
    'expiry_year' => '2025',             // Required
    'cvv' => '123',                      // Required
];
```

```json
{
    "status": true,
    "data": {
        "token": "abc123...",
        "customer_validate": {...},
        "transaction_id": "TXN123456",
        "payment_id": 1,
        "redirect_url": "https://..."
    },
    "message": "OTP screen retrieved successfully",
    "code": "00"
}
```

```php
$paymentData = [
    'orderNumber' => 'ORD-12345',
    'transactionAmount' => 1000.00,
    'customerMobileNo' => '03001234567',
    'customer_email' => 'customer@example.com',
    'cardNumber' => '4111111111111111',
    'expiry_month' => '12',
    'expiry_year' => '2025',
    'cvv' => '123',
];

$response = PayFast::getOTPScreen($paymentData);
```

--------------------------------

### Publish Configuration File

Source: https://github.com/zfhassaan/payfast/wiki/Configuration-Guide

Command to generate the configuration file in the config directory.

```bash
php artisan vendor:publish --tag=payfast-config
```

--------------------------------

### Importing the PayFast Facade

Source: https://github.com/zfhassaan/payfast/wiki/Getting-Started

Use the Facade to access PayFast functionality within your application.

```php
use zfhassaan\Payfast\Facades\PayFast;
```

--------------------------------

### Publish Package Resources

Source: https://github.com/zfhassaan/payfast/blob/main/IMPLEMENTATION_COMPLETE.md

Use artisan commands to publish configuration, migrations, email templates, and console commands to your application.

```bash
php artisan vendor:publish --tag=payfast-config
```

```bash
php artisan vendor:publish --tag=payfast-migrations
php artisan migrate
```

```bash
php artisan vendor:publish --tag=payfast-email-templates
```

```bash
php artisan vendor:publish --tag=payfast-command
```

--------------------------------

### PSR-12 Compliant Class Structure

Source: https://github.com/zfhassaan/payfast/wiki/Contributing

Example of a class following PSR-12 standards, including strict types, namespace declaration, and DocBlocks.

```php
<?php

declare(strict_types=1);

namespace zfhassaan\Payfast\Services;

/**
 * Service description.
 */
class MyService
{
    /**
     * Method description.
     *
     * @param string $param Parameter description
     * @return array<string, mixed>
     */
    public function myMethod(string $param): array
    {
        // Implementation
    }
}
```

--------------------------------

### Test PayFast Configuration

Source: https://github.com/zfhassaan/payfast/wiki/Configuration-Guide

Verify that the package is correctly configured by attempting to retrieve a token.

```php
use zfhassaan\Payfast\Facades\PayFast;

// This will use your configuration
$response = PayFast::getToken();

if ($response->getStatusCode() === 200) {
    // Configuration is correct
}
```

--------------------------------

### Run Database Migrations

Source: https://github.com/zfhassaan/payfast/blob/main/IMPLEMENTATION_SUMMARY.md

Command to apply the new database schema changes for status tracking and payment processing.

```bash
php artisan migrate
```

--------------------------------

### Define PayFast Routes

Source: https://github.com/zfhassaan/payfast/wiki/Getting-Started

Register the necessary POST and GET routes in your Laravel web.php file to handle payment initiation, OTP verification, callbacks, and status checks.

```php
Route::post('/payment/initiate', [PaymentController::class, 'initiatePayment']);
Route::post('/payment/verify-otp', [PaymentController::class, 'verifyOTP']);
Route::post('/payment/callback', [PaymentController::class, 'handleCallback']);
Route::get('/payment/status/{transactionId}', [PaymentController::class, 'checkStatus']);
```

--------------------------------

### PaymentInitiated Event Data and Listener

Source: https://github.com/zfhassaan/payfast/wiki/Events-and-Listeners

Defines the structure of the PaymentInitiated event data and demonstrates how to listen for it to log payment initiation.

```php
[
    'paymentData' => [...],  // Payment request data
    'response' => [...],      // API response
]
```

```php
use zfhassaan\Payfast\Events\PaymentInitiated;

Event::listen(PaymentInitiated::class, function ($event) {
    $paymentData = $event->paymentData;
    $response = $event->response;
    
    // Log payment initiation
    Log::info('Payment initiated', [
        'order' => $paymentData['orderNumber'],
        'amount' => $paymentData['transactionAmount'],
    ]);
});
```

--------------------------------

### Initiate Payment with PayFast

Source: https://github.com/zfhassaan/payfast/blob/main/IMPLEMENTATION_SUMMARY.md

Initiates a payment request by passing customer and card details to the getOTPScreen method.

```php
$response = PayFast::getOTPScreen([
    'orderNumber' => 'ORD-123',
    'transactionAmount' => 1000,
    'customerMobileNo' => '03001234567',
    'customer_email' => 'customer@example.com',
    'cardNumber' => '4111111111111111',
    'expiry_month' => '12',
    'expiry_year' => '2025',
    'cvv' => '123',
]);
```

--------------------------------

### Using ActivityLogRepository

Source: https://github.com/zfhassaan/payfast/wiki/Models-and-Database

Creates a new activity log entry using the repository interface.

```php
use zfhassaan\Payfast\Repositories\Contracts\ActivityLogRepositoryInterface;

$repository = app(ActivityLogRepositoryInterface::class);

// Create log
$repository->create([
    'transaction_id' => 'TXN123456',
    'status' => 'completed',
]);
```

--------------------------------

### Interact with ActivityLog Model

Source: https://github.com/zfhassaan/payfast/wiki/Models-and-Database

Demonstrates creating log entries and querying logs by transaction or order identifiers.

```php
use zfhassaan\Payfast\Models\ActivityLog;

// Create activity log
ActivityLog::create([
    'user_id' => 1,
    'transaction_id' => 'TXN123456',
    'order_no' => 'ORD-12345',
    'status' => 'completed',
    'amount' => 1000.00,
    'details' => json_encode(['message' => 'Payment completed']),
]);

// Find by transaction ID
$logs = ActivityLog::where('transaction_id', 'TXN123456')->get();

// Find by order number
$logs = ActivityLog::where('order_no', 'ORD-12345')->get();
```

--------------------------------

### Publish PayFast test files

Source: https://github.com/zfhassaan/payfast/wiki/Testing-Guide

Executes the artisan command to copy test files into the local tests directory.

```bash
php artisan vendor:publish --tag=payfast-tests
```

--------------------------------

### Register PayFast Facade Alias

Source: https://github.com/zfhassaan/payfast/blob/main/README.md

Add the Payfast facade to your aliases array in the configuration file.

```php
  'aliases' => Facade::defaultAliases()->merge([
        'Payfast' => \zfhassaan\Payfast\Facade\Payfast::class,
    ])->toArray(),
```

--------------------------------

### Wallet Initiation Response Format

Source: https://github.com/zfhassaan/payfast/blob/main/docs/content/API-Reference.md

Expected JSON structure returned after initiating a wallet transaction.

```json
{
  "code": "00",
  "message": "Wallet transaction initiated",
  "transaction_id": "TXN123456"
}
```

--------------------------------

### Configure PayFast Environment Mode

Source: https://github.com/zfhassaan/payfast/wiki/Configuration-Guide

Set the PAYFAST_MODE variable to toggle between sandbox and production environments.

```env
PAYFAST_MODE=sandbox
```

```env
PAYFAST_MODE=production
```

--------------------------------

### Configuration File Structure

Source: https://github.com/zfhassaan/payfast/wiki/Configuration-Guide

The PHP array structure used to map environment variables to package settings.

```php
return [
    // API Configuration
    'api_url' => env('PAYFAST_API_URL', ''),
    'sandbox_api_url' => env('PAYFAST_SANDBOX_URL', ''),
    
    // Authentication
    'grant_type' => env('PAYFAST_GRANT_TYPE', ''),
    'merchant_id' => env('PAYFAST_MERCHANT_ID', ''),
    'secured_key' => env('PAYFAST_SECURED_KEY', ''),
    
    // Application Settings
    'store_id' => env('PAYFAST_STORE_ID', ''),
    'return_url' => env('PAYFAST_RETURN_URL', ''),
    'mode' => env('PAYFAST_MODE', 'sandbox'),
    'transaction_check' => env('PAYFAST_VERIFY_TRANSACTION', ''),
    
    // Email Configuration
    'admin_emails' => env('PAYFAST_ADMIN_EMAILS', ''),
    'email_templates' => [
        'status_notification' => 'payfast::emails.status-notification',
        'payment_completion' => 'payfast::emails.payment-completion',
        'admin_notification' => 'payfast::emails.admin-notification',
        'payment_failure' => 'payfast::emails.payment-failure',
    ],
    'email_subjects' => [
        'payment_completion' => env('PAYFAST_EMAIL_SUBJECT_COMPLETION', 'Payment Completed Successfully'),
        'admin_notification' => env('PAYFAST_EMAIL_SUBJECT_ADMIN', 'New Payment Completed'),
        'payment_failure' => env('PAYFAST_EMAIL_SUBJECT_FAILURE', 'Payment Failed'),
    ],
];
```

--------------------------------

### Monitor Application Logs

Source: https://github.com/zfhassaan/payfast/wiki/Troubleshooting

Use tail to monitor Laravel and PayFast specific log files in real-time.

```bash
# Laravel logs
tail -f storage/logs/laravel.log

# PayFast specific logs
tail -f storage/logs/Payfast/*.log
```

--------------------------------

### POST /payment/initiate

Source: https://github.com/zfhassaan/payfast/wiki/Getting-Started

Initiates a new payment process.

```APIDOC
## POST /payment/initiate

### Description
Initiates a payment transaction.

### Method
POST

### Endpoint
/payment/initiate
```

--------------------------------

### Configuration File Structure

Source: https://github.com/zfhassaan/payfast/blob/main/docs/content/Configuration-Guide.md

The internal structure of the config/payfast.php file, which maps environment variables to package settings.

```php
return [
    // API Configuration
    'api_url' => env('PAYFAST_API_URL', ''),
    'sandbox_api_url' => env('PAYFAST_SANDBOX_URL', ''),
    
    // Authentication
    'grant_type' => env('PAYFAST_GRANT_TYPE', ''),
    'merchant_id' => env('PAYFAST_MERCHANT_ID', ''),
    'secured_key' => env('PAYFAST_SECURED_KEY', ''),
    
    // Application Settings
    'store_id' => env('PAYFAST_STORE_ID', ''),
    'return_url' => env('PAYFAST_RETURN_URL', ''),
    'checkout_url' => env('PAYFAST_CHECKOUT_URL', ''),
    'mode' => env('PAYFAST_MODE', 'sandbox'),
    'transaction_check' => env('PAYFAST_VERIFY_TRANSACTION', ''),
    
    // Email Configuration
    'admin_emails' => env('PAYFAST_ADMIN_EMAILS', ''),
    'email_templates' => [
        'status_notification' => 'payfast::emails.status-notification',
        'payment_completion' => 'payfast::emails.payment-completion',
        'admin_notification' => 'payfast::emails.admin-notification',
        'payment_failure' => 'payfast::emails.payment-failure',
    ],
    'email_subjects' => [
        'payment_completion' => env('PAYFAST_EMAIL_SUBJECT_COMPLETION', 'Payment Completed Successfully'),
        'admin_notification' => env('PAYFAST_EMAIL_SUBJECT_ADMIN', 'New Payment Completed'),
        'payment_failure' => env('PAYFAST_EMAIL_SUBJECT_FAILURE', 'Payment Failed'),
    ],
];
```

--------------------------------

### Implement Payment Controller

Source: https://github.com/zfhassaan/payfast/wiki/Understanding-the-Hosted-Checkout-Process-for-Payfast copy

A complete controller implementation for handling hosted checkout initiation, success callbacks, and failure scenarios.

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use zfhassaan\Payfast\Facades\PayFast;

class PaymentController extends Controller
{
    public function initiateHostedCheckout(Request $request)
    {
        // Validate request
        $request->validate([
            'order_id' => 'required|string',
            'amount' => 'required|numeric|min:0.01',
            'mobile' => 'required|string',
            'email' => 'required|email',
        ]);

        // Get merchant data
        $merchant_id = config('payfast.merchant_id');
        $secured_key = config('payfast.secured_key');
        $merchant_name = 'Your Merchant Name';

        // Customer data
        $order_id = $request->order_id;
        $amount = $request->amount;
        $mobile = $request->mobile;
        $email = $request->email;

        // Get access token
        $tokenResponse = PayFast::getToken();
        $tokenData = json_decode($tokenResponse->getContent(), true);

        if (!$tokenData['status'] || $tokenData['code'] !== '00') {
            return back()->withErrors(['payment' => 'Failed to get authentication token']);
        }

        $ACCESS_TOKEN = $tokenData['data']['token'];

        // Create signature
        $signature = md5($merchant_id . ":" . $merchant_name . ":" . $amount . ":" . $order_id);
        $backend_callback = "signature=" . $signature . "&order_id=" . $order_id;

        // Build payload
        $successUrl = route('payment.success');
        $failUrl = route('payment.failure');
        $payment_url = config('payfast.mode') === 'production' 
            ? config('payfast.api_url') . '/checkout' 
            : config('payfast.sandbox_api_url') . '/checkout';

        $payload = [
            'MERCHANT_ID' => $merchant_id,
            'MERCHANT_NAME' => $merchant_name,
            'TOKEN' => $ACCESS_TOKEN,
            'PROCCODE' => '00',
            'TXNAMT' => $amount,
            'CUSTOMER_MOBILE_NO' => $mobile,
            'CUSTOMER_EMAIL_ADDRESS' => $email,
            'SIGNATURE' => $signature,
            'VERSION' => 'WOOCOM-APPS-PAYMENT-0.9',
            'TXNDESC' => 'Products purchased from ' . $merchant_name,
            'SUCCESS_URL' => urlencode($successUrl),
            'FAILURE_URL' => urlencode($failUrl),
            'BASKET_ID' => $order_id,
            'ORDER_DATE' => date('Y-m-d H:i:s', time()),
            'CHECKOUT_URL' => urlencode($backend_callback),
        ];

        return view('payment.hosted-checkout', [
            'payment_url' => $payment_url,
            'payload' => $payload,
        ]);
    }

    public function handleSuccess(Request $request)
    {
        // Verify signature
        $signature = $request->input('signature');
        $order_id = $request->input('order_id');

        // Verify the signature matches
        // Update order status
        // Send confirmation email
        // etc.

        return view('payment.success', [
            'order_id' => $order_id,
        ]);
    }

    public function handleFailure(Request $request)
    {
        // Handle payment failure
        // Log the failure
        // Notify customer
        // etc.

        return view('payment.failure');
    }
}
```

--------------------------------

### Implement OTP Verification Route and Controller

Source: https://github.com/zfhassaan/payfast/blob/main/PAYMENT_FLOW.md

Define the route and controller logic to verify the OTP and store the 3DS pares received from PayFast.

```php
// routes/web.php
Route::post('/payment/verify-otp', [PaymentController::class, 'verifyOTP']);

// app/Http/Controllers/PaymentController.php
public function verifyOTP(Request $request)
{
    $request->validate([
        'transaction_id' => 'required|string',
        'otp' => 'required|string',
        'pares' => 'required|string', // Received from PayFast 3DS
    ]);

    $response = PayFast::verifyOTPAndStorePares(
        $request->transaction_id,
        $request->otp,
        $request->pares
    );

    $result = json_decode($response->getContent(), true);

    if ($result['status']) {
        // Payment updated with status: 'otp_verified' and pares stored
        return response()->json([
            'message' => 'OTP verified successfully',
            'pares' => $request->pares,
        ]);
    }

    return response()->json($result, 400);
}
```

--------------------------------

### Configure Production Mode

Source: https://github.com/zfhassaan/payfast/blob/main/wiki/Configuration-Guide.md

Sets the environment to production mode for processing real transactions.

```env
PAYFAST_MODE=production
```

--------------------------------

### Publish Database Migrations

Source: https://github.com/zfhassaan/payfast/wiki/Installation-Guide

Copies the required database migration files to the application's migration directory.

```bash
php artisan vendor:publish --tag=payfast-migrations
```

--------------------------------

### Initiate Mobile Wallet Transaction

Source: https://github.com/zfhassaan/payfast/blob/main/README.md

Demonstrates how to initiate a mobile wallet transaction, such as Easy Paisa, using the Payfast package.

```php
/**
 * Mobile Wallet Account Initiate Transaction 
 * This is demo function for Easy Paisa. 
 * 
 */

public function payfast(Request $request)
{
    $payfast = new Payfast();
    $response = $payfast->getToken();
    if($response != null && $response->code == "00" ){
        $payfast->setAuthToken($response->token);
    } else {
        abort(403, 'Error: Auth Token Not Generated.');
    }
    $show_otp = $payfast->wallet($request->all());
    return $show_otp;
}
```

--------------------------------

### Required Environment Variables

Source: https://github.com/zfhassaan/payfast/wiki/Configuration-Guide

Essential settings for API connectivity and authentication.

```env
# API URLs
PAYFAST_API_URL=https://api.payfast.com
PAYFAST_SANDBOX_URL=https://sandbox.payfast.com

# Authentication
PAYFAST_GRANT_TYPE=client_credentials
PAYFAST_MERCHANT_ID=your_merchant_id
PAYFAST_SECURED_KEY=your_secured_key

# Application Settings
PAYFAST_RETURN_URL=https://yourdomain.com/payment/callback
PAYFAST_MODE=sandbox
```

--------------------------------

### Manage Credentials via Environment Variables

Source: https://github.com/zfhassaan/payfast/wiki/Security-Best-Practices

Avoid hardcoding sensitive credentials by utilizing configuration files that pull from environment variables.

```php
// Don't hardcode credentials
$merchantId = '12345';
$securedKey = 'secret_key';
```

```php
// Use environment variables
$merchantId = config('payfast.merchant_id');
$securedKey = config('payfast.secured_key');
```

--------------------------------

### PayFast::walletTransactionInitiate()

Source: https://github.com/zfhassaan/payfast/wiki/API-Reference

Initiates a wallet transaction after successful validation.

```APIDOC
## PayFast::walletTransactionInitiate($data)

### Description
Initiate wallet transaction after validation.

### Parameters
- **$data** (array) - Required - Transaction data array.

### Returns
- **string|bool** - JSON string or boolean result.
```
Tokens:
Raw