### Create Installation Directory

Source: https://docs.uddoktapay.com/installation/docker

Create the directory for UddoktaPay installation and navigate into it. This is the first step for manual Docker Compose setup.

```bash
mkdir -p /opt/uddoktapay && cd /opt/uddoktapay
```

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

### Start UddoktaPay Services

Source: https://docs.uddoktapay.com/installation/docker

Start all UddoktaPay services in detached mode. Use this to bring up the application after installation or stopping.

```bash
docker compose -f /opt/uddoktapay/compose.yml up -d
```

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

### Standard UddoktaPay Installation

Source: https://docs.uddoktapay.com/installation/docker

Use this command for the quickest installation with default settings, including port 80 and a local MariaDB instance.

```bash
curl -fsSL https://get.uddoktapay.com/install.sh | bash
```

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

### MFS Gateway Rendering Example

Source: https://docs.uddoktapay.com/developers/custom-themes

A comprehensive example of how to render MFS gateway details, including logos, account information, QR codes, discounts, fees, and the payment form.

```blade
<img src="{{ $gatewayLogo }}" alt="{{ $gatewayName }}" />
<h2>{{ $gatewayName }} — {{ $accountType }}</h2>
<p>Send <strong>{{ $mfsAmount }}</strong> {{ $currency }} to:</p>
<p>{{ $accountNumber }}</p>

@if ($hasQR && $qrCode)
    <img src="{{ $qrCode }}" alt="QR Code" />
@endif

@if ($gatewayDescription)
    <p>{{ $gatewayDescription }}</p>
@endif

@if ($hasDiscount)
    <p>Discount: {{ $discountFormatted }}</p>
@endif

@if ($hasFee)
    <p>Fee: {{ $feeFormatted }}</p>
@endif

<form method="POST" action="{{ $formActionUrl }}">
    @csrf
    <input type="text" name="transaction_id" placeholder="Transaction ID" required />

    @if ($numberInputEnabled)
        <input type="text" name="phone_number" placeholder="Your phone number" />
    @endif

    <button type="submit">Verify Payment</button>
</form>

<a href="{{ $gatewayHomeUrl }}">← Back</a>
<a href="{{ $gatewayCancelUrl }}">Cancel</a>
```

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

### Start UddoktaPay Services with Docker Compose

Source: https://docs.uddoktapay.com/installation/docker

Start all UddoktaPay services defined in the docker-compose.yml file in detached mode. This command is used after configuring the .env file.

```bash
docker compose up -d
```

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

### Bank Gateway Rendering Example

Source: https://docs.uddoktapay.com/developers/custom-themes

Example of rendering a bank gateway page, including logo, description, parameters, amount, fees, and a dynamic form.

```blade
<img src="{{ $gatewayLogo }}" alt="Bank Transfer" />

@if ($gatewayDescription)
    <div>{!! $gatewayDescription !!}</div>
@endif

<ul>
    @foreach ($parameters as $key => $value)
        <li>
            <span>{{ key_to_word($key) }}</span>
            <span>{{ $value }}</span>
        </li>
    @endforeach
</ul>

<p>Amount: {{ $amountFormatted }}</p>

@if ($hasDiscount)
    <p>Discount: {{ $discountFormatted }}</p>
@endif

@if ($hasFee)
    <p>Fee: {{ $feeFormatted }}</p>
@endif

<form method="POST" action="{{ $formActionUrl }}">
    @csrf
    <x-forms.bank :fields="$bankFormFields" />
    <button type="submit">Submit</button>
</form>
```

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

### Custom UddoktaPay Installation on a Custom Port

Source: https://docs.uddoktapay.com/installation/docker

Install UddoktaPay on a custom port (e.g., 8080) by injecting the APP_PORT environment variable.

```bash
curl -fsSL https://get.uddoktapay.com/install.sh | APP_PORT=8080 bash
```

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

### Checkout Page Rendering Example

Source: https://docs.uddoktapay.com/developers/custom-themes

A comprehensive example demonstrating how to render checkout page data, including formatted amounts, customer details, and conditional display of different gateway types (MFS, Global, Bank). It also includes rendering FAQs using `<details>` and `<summary>` elements.

```blade
<h1>{{ $amountFormatted }}</h1>
<p>{{ $customerName }} &mdash; {{ $customerEmail }}</p>

@if ($hasMfs)
    <h2>Mobile Banking</h2>
    @foreach ($mfsGateways as $gateway)
        <a href="{{ $gateway->url }}">
            <img src="{{ $gateway->logo }}" alt="{{ $gateway->displayName }}" />
            {{ $gateway->displayName }}
        </a>
    @endforeach
@endif

@if ($hasGlobal)
    <h2>International</h2>
    @foreach ($globalGateways as $gateway)
        <a href="{{ $gateway->url }}">
            <img src="{{ $gateway->logo }}" alt="{{ $gateway->displayName }}" />
            {{ $gateway->displayName }}
        </a>
    @endforeach
@endif

@if ($hasBank)
    <h2>Bank Transfer</h2>
    @foreach ($bankGateways as $gateway)
        <a href="{{ $gateway->url }}">
            <img src="{{ $gateway->logo }}" alt="{{ $gateway->displayName }}" />
            {{ $gateway->displayName }}
        </a>
    @endforeach
@endif

@if ($faqs->isNotEmpty())
    <section>
        @foreach ($faqs as $faq)
            <details>
                <summary>{{ $faq->title }}</summary>
                {!! $faq->content !!}
            </details>
        @endforeach
    </section>
@endif
```

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

### Get Configuration Values

Source: https://docs.uddoktapay.com/developers/custom-gateways

Retrieve configuration values for your gateway. You can get a specific value, a value with a default, or check for its existence.

```php
// Get config value
$apiKey = $this->getConfig('api_key');

// Get with default value
$mode = $this->getConfig('sandbox', 'disable');

// Check if config exists
if ($this->getConfig('api_key')) {
    // Config exists
}
```

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

### Dynamic IPN URL Example

Source: https://docs.uddoktapay.com/developers/custom-gateways

Example of using a dynamic IPN URL, where a unique webhook URL is provided for each payment. This simplifies webhook handling as the payment reference is part of the URL, eliminating the need for resolvePaymentableFromIpn().

```php
// Pass IPN URL during checkout
'ipn_url' => $this->gateway->gatewayifyIpnUrl($payment)
// Result: https://yoursite.com/ipn/gateway-name/REF123

// No need for resolvePaymentableFromIpn() - payment is in the URL
```

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

### Binance Gateway Rendering Example

Source: https://docs.uddoktapay.com/developers/custom-themes

This snippet demonstrates how to render the Binance gateway page, displaying payment details, fees, discounts, and the verification form.

```blade
<img src="{{ $gatewayLogo }}" alt="Binance Pay" />
<p>Send <strong>{{ $amountFormatted }}</strong> to Binance ID:</p>
<p>{{ $config['binance_id'] }}</p>
<p>You have {{ $config['payment_timeout'] }} minutes to complete this payment.</p>

@if ($hasDiscount)
    <p>Discount: {{ $discountFormatted }}</p>
@endif

@if ($hasFee)
    <p>Fee: {{ $feeFormatted }}</p>
@endif

<form method="POST" action="{{ $formActionUrl }}">
    @csrf
    <input type="text" name="order_id" placeholder="Binance Order ID" required />
    <button type="submit">Verify Payment</button>
</form>

<a href="{{ $gatewayHomeUrl }}">← Back</a>
<a href="{{ $gatewayCancelUrl }}">Cancel</a>
```

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

### UddoktaPay Environment Variables for Remote Database

Source: https://docs.uddoktapay.com/installation/docker

Configure the .env file for UddoktaPay when using a remote database. This setup does not start the MariaDB container by default.

```env
APP_PORT=80
APP_NAME=UddoktaPay
APP_ENV=production
APP_DEBUG=false
APP_URL=https://pay.yourdomain.com
APP_KEY=

# Remote database
DB_CONNECTION=mariadb
DB_HOST=your-database-host.com
DB_PORT=3306
DB_DATABASE=uddoktapay
DB_USERNAME=uddoktapay_user
DB_PASSWORD=your-db-password
```

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

### Follow UddoktaPay Service Logs for Verification

Source: https://docs.uddoktapay.com/installation/docker

Monitor the logs of UddoktaPay services in real-time until the 'started successfully' message appears. This is a crucial step to verify successful startup.

```bash
# Follow logs until "started successfully"
docker compose logs -f
```

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

### Get Configuration Values in PHP

Source: https://docs.uddoktapay.com/developers/custom-notifications

Retrieve configuration values using the `config()` method. You can also provide a default value if the configuration key does not exist.

```php
// Get config value
$webhookUrl = $this->config('webhook_url');

// Get with default value
$timeout = $this->config('timeout', 30);

// Check if config exists
if ($this->config('api_token')) {
    // Config exists
}
```

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

### Static Webhook URL Example

Source: https://docs.uddoktapay.com/developers/custom-gateways

Demonstrates the use of a static webhook URL, which is a single URL configured in the gateway's dashboard. This requires implementing resolvePaymentableFromIpn() to extract the payment reference from the incoming payload.

```php
// Display in config form for admin to copy
Field::make('webhook_url')
    ->value($this->gateway->gatewayifyIpnUrl())  // No payment param
    ->suffixCopy()
// Result: https://yoursite.com/ipn/gateway-name

// ⚠️ Must implement resolvePaymentableFromIpn() - need to extract reference from payload
```

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

### Dropdown Select Field Example

Source: https://docs.uddoktapay.com/developers/custom-notifications

Use the select field for predefined options. It allows setting a default value and displays a list of choices for the user.

```php
Field::make('priority')
    ->select([
        'high' => 'High Priority',
        'normal' => 'Normal',
        'low' => 'Low Priority',
    ])
    ->default('normal')
```

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

### Custom UddoktaPay Installation with Remote PostgreSQL

Source: https://docs.uddoktapay.com/installation/docker

Connect UddoktaPay to a remote PostgreSQL database by setting DB_CONNECTION to 'pgsql' and providing database credentials.

```bash
curl -fsSL https://get.uddoktapay.com/install.sh | DB_CONNECTION=pgsql DB_HOST=db.example.com DB_USERNAME=remote_user DB_PASSWORD=strongpassword bash
```

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

### Example Invoice Reminder Email with Variables

Source: https://docs.uddoktapay.com/invoices

Demonstrates how to use variables like {name}, {invoice_id}, {amount}, {due_date}, {payment_url}, and {brand_name} to personalize an invoice reminder email.

```markdown
Dear {name},

This is a reminder that invoice {invoice_id} for {amount} is due on {due_date}.

Please complete payment at your earliest convenience: {payment_url}

Thank you,
{brand_name}
```

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

### Example Notification Data Structure

Source: https://docs.uddoktapay.com/developers/custom-notifications

Illustrates the complete payload structure returned by the `toArray()` method, including event and payment details.

```php
[
    'event' => 'payment.completed',
    'data' => [
        'payment_id' => 12345,
        'customer_name' => 'John Doe',
        'customer_email' => 'john@example.com',
        'amount' => 100.00,
        'currency' => 'USD',
        'transaction_id' => 'TXN123456',
        'gateway_name' => 'Stripe',
        'action_url' => 'https://yoursite.com/admin/payments/12345',
        'created_at' => '2025-10-08T10:30:00.000000Z',
    ],
]
```

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

### Get Product Name

Source: https://docs.uddoktapay.com/developers/custom-notifications

Retrieve the name of the product associated with the payment.

```php
// Get product name
$productName = $payment->paymentableProductName();
// Example: 'Premium Subscription'
```

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

### Payment Link Page Rendering Example

Source: https://docs.uddoktapay.com/developers/custom-themes

This snippet demonstrates rendering the payment link page, displaying product details and a form with dynamic fields for payment.

```blade
<h1>{{ $productName }}</h1>
<p>{{ $productDescription }}</p>
<p>Currency: {{ $currency }}</p>

<form method="POST" action="{{ $formActionUrl }}">
    @csrf
    <x-forms.paymentlink :fields="$formFields" />
    <button type="submit">Pay Now</button>
</form>
```

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

### Custom UddoktaPay Installation with Remote MySQL/MariaDB

Source: https://docs.uddoktapay.com/installation/docker

Configure UddoktaPay to use a remote MySQL or MariaDB database by specifying DB_HOST, DB_USERNAME, and DB_PASSWORD.

```bash
curl -fsSL https://get.uddoktapay.com/install.sh | DB_HOST=db.example.com DB_USERNAME=remote_user DB_PASSWORD=strongpassword bash
```

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

### Example Invoice Reminder Email with Shortcodes

Source: https://docs.uddoktapay.com/invoices

Shows how to incorporate shortcodes such as {payment_button}, {divider}, and {signature} to add pre-formatted HTML elements to an invoice reminder email.

```markdown
Dear {name},

Your invoice {invoice_id} for {amount} is now due.

{payment_button}

{divider}

If you have any questions, please contact us.

{signature}
```

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

### Upgrade UddoktaPay

Source: https://docs.uddoktapay.com/installation/docker

Use this command to update your UddoktaPay installation to the latest version, preserving data and restarting containers.

```bash
curl -fsSL https://get.uddoktapay.com/upgrade.sh | bash
```

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

### Toggle Switch Field Example

Source: https://docs.uddoktapay.com/developers/custom-notifications

Use the toggle field for boolean settings. It provides a simple on/off switch and can have a default state.

```php
Field::make('enabled')
    ->toggle()
    ->default(true)
```

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

### Get Payment Amount and Currency

Source: https://docs.uddoktapay.com/developers/custom-notifications

Fetch the payment amount and the associated gateway currency.

```php
// Get payment amount
$amount = $payment->paymentableAmount();
// Returns: '100.50', '250.00'

// Get gateway currency
$currency = $payment->gatewayCurrency();
// Returns: 'USD', 'EUR', 'BDT'
```

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

### Example CSV for Customer Import

Source: https://docs.uddoktapay.com/customers

This CSV format includes headers for customer name, email, phone, address, city, state, postcode, and country. Ensure your CSV file adheres to this structure for successful import.

```csv
name,email,phone,address,city,state,postcode,country
Jane Doe,jane@example.com,+1 555 0100,221B Baker Street,London,,NW1,GB
John Smith,john@example.com,+8801712345678,House 12,Dhaka,Dhaka,1207,BD
Alice Johnson,alice@example.com,+44 20 7946 0958,10 Downing Street,London,,SW1A 2AA,GB
```

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

### Cancel Page Rendering Example

Source: https://docs.uddoktapay.com/developers/custom-themes

This snippet shows the rendering for the payment cancelled page, informing the user that no charges were made.

```blade
<h1>Payment Cancelled</h1>
<p>Your payment was cancelled. No charges were made.</p>
```

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

### Pending Page Rendering Example

Source: https://docs.uddoktapay.com/developers/custom-themes

This snippet shows the rendering for the pending payment page, displaying basic transaction details while the payment is under review.

```blade
<h1>Payment Pending</h1>
<p>Your payment is under review. Please wait while we verify your transaction.</p>

<ul>
    <li>Gateway: {{ $gatewayName }}</li>
    <li>Amount: {{ $amountFormatted }}</li>
    @if ($transactionIdFormatted)
        <li>Transaction: {{ $transactionIdFormatted }}</li>
    @endif
    @if ($sender)
        <li>Phone: {{ $sender }}</li>
    @endif
</ul>
```

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

### Verify UddoktaPay Services Status

Source: https://docs.uddoktapay.com/installation/docker

Check the running status of UddoktaPay services using 'docker compose ps'. This helps confirm that all containers have started correctly.

```bash
# Check services are running
docker compose ps
```

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

### Number Input Field Example

Source: https://docs.uddoktapay.com/developers/custom-notifications

Use the number field for numerical inputs. It supports minimum and maximum value constraints, a default value, and can have a unit suffix.

```php
Field::make('timeout')
    ->number()
    ->min(5)
    ->max(60)
    ->suffix('seconds')
    ->default(30)
```

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

### Webhook Payload Structure

Source: https://docs.uddoktapay.com/brand-settings/notifications

Example JSON payload structure for webhook notifications. This structure includes event details and associated data.

```json
{
  "event": "payment.completed",
  "data": {
    "payment_id": "...",
    "amount": "...",
    "customer": "..."
    // Additional payment details
  }
}
```

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

### Get Notification Event and Payment Details

Source: https://docs.uddoktapay.com/developers/custom-notifications

Retrieve the event key, payment model, complete notification data, and payment URLs from a notification object.

```php
// Get event identifier
$eventKey = $notification->getEventKey();
// Returns: 'payment.completed', 'payment.pending', etc.

// Get payment model
$payment = $notification->getPayment();

// Get complete notification data
$data = $notification->toArray($notifiable);

// Get payment view URL
$url = $notification->getPaymentUrl();
$absoluteUrl = $notification->getPaymentUrl(isAbsolute: true);
```

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

### Text Input Field Example

Source: https://docs.uddoktapay.com/developers/custom-notifications

Use the text field for standard string inputs. It supports placeholders, maximum length constraints, and can be used for various identifiers.

```php
Field::make('channel_id')
    ->text()
    ->placeholder('#general or C1234567890')
    ->maxLength(100)
```

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

### Textarea Field Example

Source: https://docs.uddoktapay.com/developers/custom-notifications

Use the textarea field for multi-line text inputs. It can span the full width of the form and specify the number of rows.

```php
Field::make('message_template')
    ->textarea(rows: 4)
    ->columnSpanFull()
```

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

### Conditional Field Visibility

Source: https://docs.uddoktapay.com/developers/custom-notifications

Use `visibleWhen()` to control field visibility based on the value of another field. This example shows a sandbox token appearing only when the 'environment' is set to 'staging'.

```php
Field::make('sandbox_token')
    ->visibleWhen('environment', 'staging')  // Show only when staging selected
```

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

### Gateway Initialization with Validation

Source: https://docs.uddoktapay.com/developers/custom-gateways

Implements the `Initializable` interface to validate API credentials and set up gateway configurations like base URLs and headers before payment processing.

```php
use Revoltify\Gatewayify\Contracts\Initializable;
use Revoltify\Gatewayify\Exceptions\ApiCredentialException;

class ProcessPayment extends BaseGatewayProvider implements Initializable
{
    private string $baseUrl;
    private array $headers;

    public function init(): void
    {
        // Validate required credentials
        ApiCredentialException::throwIfEmpty(
            $this->getConfig('api_key'),
            $this->getConfig('api_secret')
        );

        // Set API endpoint based on mode
        $this->baseUrl = $this->getConfig('sandbox') === 'enable'
            ? 'https://sandbox.gateway.com/api/'
            : 'https://api.gateway.com/';

        // Prepare headers for requests
        $this->headers = [
            'Authorization' => 'Bearer ' . $this->getConfig('api_key'),
            'Content-Type' => 'application/json',
        ];
    }
}
```

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

### Troubleshoot Container Startup Failures

Source: https://docs.uddoktapay.com/installation/docker

Check Docker Compose logs for errors and fix common permission issues within the application container. Restart the services after making changes.

```bash
docker compose -f /opt/uddoktapay/compose.yml logs
```

```bash
docker exec uddoktapay-app chmod -R 775 /var/www/html/storage
```

```bash
docker compose -f /opt/uddoktapay/compose.yml restart
```

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

### Implement IPNCapable Interface

Source: https://docs.uddoktapay.com/developers/custom-gateways

Shows how to implement the IPNCapable interface in a custom gateway class to enable Instant Payment Notifications (webhooks). This is crucial for reliable, server-to-server payment status updates.

```php
use Revoltify\Gatewayify\Contracts\IPNCapable;

class ProcessPayment extends BaseGatewayProvider implements IPNCapable
{
    // ... your methods
}
```

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

### View UddoktaPay Service Logs

Source: https://docs.uddoktapay.com/installation/docker

Follow the logs of all UddoktaPay services in real-time. This is useful for monitoring and debugging.

```bash
docker compose -f /opt/uddoktapay/compose.yml logs -f
```

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

### Download Docker Compose File

Source: https://docs.uddoktapay.com/installation/docker

Download the UddoktaPay Docker Compose file from the official source. This file defines the services and configurations for running UddoktaPay.

```bash
curl -fsSL https://get.uddoktapay.com/compose.yml -o compose.yml
```

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

### UddoktaPay Environment Variables for Local Database

Source: https://docs.uddoktapay.com/installation/docker

Configure the .env file for UddoktaPay using a local MariaDB database. Ensure DB_PASSWORD and MARIADB_PASSWORD match.

```env
APP_PORT=80
APP_NAME=UddoktaPay
APP_ENV=production
APP_DEBUG=false
APP_URL=https://pay.yourdomain.com
APP_KEY=your-generated-key-here

# Database
DB_CONNECTION=mariadb
DB_HOST=mariadb
DB_PORT=3306
DB_DATABASE=uddoktapay
DB_USERNAME=uddoktapay
DB_PASSWORD=your-secure-password

# MariaDB container
MARIADB_DATABASE=uddoktapay
MARIADB_USER=uddoktapay
MARIADB_PASSWORD=your-secure-password
MARIADB_RANDOM_ROOT_PASSWORD=1

# Enable local database
COMPOSE_PROFILES=local-db
```

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

### Troubleshoot Application Inaccessibility

Source: https://docs.uddoktapay.com/installation/docker

Verify that Docker containers are running using 'docker ps'. Check the firewall settings and allow traffic on port 80. Test local access using 'curl'.

```bash
docker compose -f /opt/uddoktapay/compose.yml ps
```

```bash
sudo ufw allow 80/tcp
```

```bash
curl http://localhost
```

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

### Troubleshoot Local Database Connection Failed

Source: https://docs.uddoktapay.com/installation/docker

Check the health status of the MariaDB container. Restart all services using Docker Compose and verify that the necessary Docker volumes exist.

```bash
docker inspect uddoktapay-db --format='{{.State.Health.Status}}'
```

```bash
docker compose -f /opt/uddoktapay/compose.yml restart
```

```bash
docker volume ls | grep uddoktapay
```

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

### Dropdown Field

Source: https://docs.uddoktapay.com/developers/custom-gateways

Configures a dropdown selection for gateway settings, allowing predefined options.

```php
Field::make('mode')
    ->select([
        'test' => 'Test',
        'live' => 'Live',
    ])
```

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

### Displaying FAQ Items

Source: https://docs.uddoktapay.com/developers/custom-themes

Iterate over FAQ entries to display their titles and content. The content is rendered as HTML, so ensure it's properly sanitized if necessary.

```blade
@foreach ($faqs as $faq)
    {{ $faq->title }}
    {!! $faq->content !!}
@endforeach
```

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

### Create Payment Session with Laravel HTTP Client

Source: https://docs.uddoktapay.com/developers/custom-gateways

Initiates a payment session by sending payment details to the gateway API. Includes error handling for API failures and connection issues. Ensure the paymentableIsAlreadyCompleted() method prevents double processing.

```php
use Illuminate\Support\Facades\Http;

public function checkout(Paymentable $payment): GatewayResponse
{
    // Prevent double processing
    if ($payment->paymentableIsAlreadyCompleted()) {
        return GatewayResponse::error('Payment already completed');
    }

    try {
        // Create payment with gateway API
        $response = Http::timeout(30)
            ->withHeaders($this->headers)
            ->post($this->baseUrl . 'payments', [
                'amount' => $payment->paymentableAmount(),
                'currency' => 'USD',
                'reference' => $payment->paymentableReferenceId(),
                'customer' => [
                    'name' => $payment->paymentableCustomerName(),
                    'email' => $payment->paymentableCustomerEmail(),
                    'phone' => $payment->paymentableCustomerPhone(),
                ],
                // Callback URLs
                'success_url' => $this->gateway->gatewayifySuccessUrl($payment),
                'cancel_url' => $this->gateway->gatewayifyCancelUrl($payment),
                'ipn_url' => $this->gateway->gatewayifyIpnUrl($payment),
            ]);

        // Handle API errors
        if ($response->failed()) {
            return GatewayResponse::error('Payment creation failed');
        }

        $data = $response->json();

        // Redirect to checkout
        return GatewayResponse::redirect($data['checkout_url']);

    } catch (\Exception $e) {
        return GatewayResponse::error('Connection failed. Please try again.');
    }
}
```

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

### Uninstall UddoktaPay

Source: https://docs.uddoktapay.com/installation/docker

Run this command to uninstall UddoktaPay. The script will prompt before deleting data, so ensure you have backups if needed.

```bash
curl -fsSL https://get.uddoktapay.com/uninstall.sh | bash
```

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

### Basic Custom Notification Provider Structure

Source: https://docs.uddoktapay.com/developers/custom-notifications

Implement a custom notification provider by extending AbstractNotificationProvider and defining configuration fields and the notification handling logic.

```php
<?php

declare(strict_types=1);

namespace App\Modules\Notifications\Webhook;

use Illuminate\Support\Facades\Http;
use Revoltify\Notificationify\AbstractNotificationProvider;
use Revoltify\Notificationify\Contracts\NotificationChannelInterface;
use Revoltify\Notificationify\Contracts\NotificationInterface;
use Revoltify\Support\Forms\Components\Field;
use Revoltify\Support\Forms\Form;

class Webhook extends AbstractNotificationProvider
{
    // Define configuration fields
    public function form(): Form
    {
        return Form::make([
            Field::make('webhook_url')
                ->text()
                ->label('Webhook URL')
                ->placeholder('https://example.com/webhook')
                ->helperText('The URL where notifications will be sent')
                ->required()
                ->url(),
        ]);
    }

    // Handle notification delivery
    public function handle(
        NotificationChannelInterface $notifiable,
        NotificationInterface $notification
    ): void {
        $url = $this->config('webhook_url');
        $payload = $notification->toArray($notifiable);
        
        Http::timeout(30)->asJson()->post($url, $payload);
    }
}
```

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

### Theme Configuration Class

Source: https://docs.uddoktapay.com/developers/custom-themes

Defines the theme's name, description, version, author, logo, and admin settings form. Use `Field::make()` with appropriate types like `color()` or `codeEditor()` to define form inputs.

```php
<?php

declare(strict_types=1);

namespace Themes\MyTheme;

use Revoltify\Support\Forms\Components\Field;
use Revoltify\Support\Forms\Form;
use Revoltify\Themeify\AbstractTheme;

final class Config extends AbstractTheme
{
    public function name(): string
    {
        return 'My Theme';
    }

    public function description(): string
    {
        return 'A custom theme for UddoktaPay';
    }

    public function version(): string
    {
        return '1.0.0';
    }

    public function author(): string
    {
        return 'Your Name';
    }

    public function authorUrl(): string
    {
        return 'https://yourwebsite.com';
    }

    /**
     * Path relative to public/themes/{themeslug}/ — shown as the thumbnail in the admin panel.
     */
    public function logo(): string
    {
        return 'assets/thumbnail.png';
    }

    public function form(): Form
    {
        return Form::make([
            Field::make('primary_color')
                ->color()
                ->label('Primary Color'),

            Field::make('button_text_color')
                ->color()
                ->label('Button Text Color'),

            Field::make('custom_css')
                ->codeEditor()
                ->language('css')
                ->label('Custom CSS')
                ->columnSpanFull(),

            Field::make('custom_js')
                ->codeEditor()
                ->language('javascript')
                ->label('Custom JS')
                ->columnSpanFull(),
        ]);
    }
}

```

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

### Access Gateway Instance Properties

Source: https://docs.uddoktapay.com/developers/custom-gateways

Access properties and status of the current gateway instance. This includes its name, display name, ID, and operational status.

```php
// Get gateway name
$name = $this->gateway->name;

// Get gateway display name
$name = $this->gateway->display_name;

// Get gateway ID
$id = $this->gateway->id;

// Check if gateway is enabled
if ($this->gateway->status()) {
    // Gateway is active
}
```

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

### Access Callback URLs

Source: https://docs.uddoktapay.com/developers/custom-notifications

Obtain the success, cancel, and IPN/webhook URLs configured for the payment.

```php
// Get success redirect URL
$successUrl = $payment->paymentableSuccessUrl();

// Get cancel redirect URL
$cancelUrl = $payment->paymentableCancelUrl();

// Get IPN/webhook URL (if configured)
$ipnUrl = $payment->paymentableIPNUrl();
```

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

### Displaying IPN URL in Config

Source: https://docs.uddoktapay.com/developers/custom-gateways

Shows how to display the gateway's IPN (Instant Payment Notification) or webhook URL within the configuration form, making it easy for admins to copy and paste into their gateway dashboard settings.

```php
// Use ->value($this->gateway->gatewayifyIpnUrl()) to get the static IPN URL
// Add ->suffixCopy() for easy copying
// Make it ->disabled() so it's read-only
// Add helpful text telling admins where to paste it
```

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

### Gateway Metadata Configuration

Source: https://docs.uddoktapay.com/developers/custom-gateways

Configure how your gateway appears and behaves in the system, including its display name, supported currency, group, type, and operation mode.

```php
public static function metadata(): GatewayMetadata
{
    return GatewayMetadata::make()
        ->name('Stripe')                 // Display name
        ->currency('USD', '$')           // Supported currency
        ->group('stripe')                // Group identifier (used in logo path)
        ->global()                       // Gateway type
        ->live();                        // Operation mode
}
```

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

### Implement Refund Capable Interface

Source: https://docs.uddoktapay.com/developers/custom-gateways

Implement the `RefundCapable` interface to enable refund functionality for your custom gateway. This involves defining the `refund` method to interact with the gateway's refund API.

```php
use Revoltify\Gatewayify\Contracts\RefundCapable;
use Revoltify\Gatewayify\Exceptions\ProviderException;
use Illuminate\Support\Facades\Http;

class ProcessPayment extends BaseGatewayProvider implements RefundCapable
{
    public function refund(
        Paymentable $payment,
        string|float|int $amount,
        ?string $reason = null
    ): ?string {
        try {
            // Call gateway refund API
            $response = Http::timeout(30)
                ->withHeaders($this->headers)
                ->post($this->baseUrl . 'refunds', [
                    'payment_id' => $payment->paymentableGatewayReferenceId(),
                    'amount' => $amount,
                    'reason' => $reason ?? 'Refund requested',
                ]);

            // Handle errors
            if ($response->failed()) {
                $errorMessage = $response->json('message') ?? 'Refund failed';
                throw ProviderException::make($errorMessage);
            }

            $refundId = $response->json('refund_id');

            // Return refund transaction ID
            return $refundId;

        } catch (\Exception $e) {
            throw ProviderException::make('Refund failed: ' . $e->getMessage());
        }
    }
}
```

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

### Troubleshoot Remote Database Connection Failed

Source: https://docs.uddoktapay.com/installation/docker

Verify database credentials by checking the application container's environment variables. Ensure that your remote database allows connections from the Docker host's IP address.

```bash
docker exec uddoktapay-app env | grep DB_
```

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

### Generate Application Key

Source: https://docs.uddoktapay.com/installation/docker

Generate a base64 encoded application key required for UddoktaPay's encryption. This key is essential for security and should be kept confidential.

```bash
echo "base64:$(openssl rand -base64 32)"
```

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

### Cron Job Full Path Command

Source: https://docs.uddoktapay.com/system-settings/cron-job

Use this command in your crontab for direct server access. Ensure you copy the exact command from the Cron Job page as it includes unique server paths and security tokens.

```bash
* * * * * [your-full-path-command-here] >> /dev/null 2>&1
```

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

### Generate Callback URLs

Source: https://docs.uddoktapay.com/developers/custom-gateways

Constructs necessary callback URLs for payment success, cancellation, and IPN (Instant Payment Notification) or webhooks. Supports adding custom query parameters to these URLs.

```php
// Basic callback URLs
$successUrl = $this->gateway->gatewayifySuccessUrl($payment);
$cancelUrl = $this->gateway->gatewayifyCancelUrl($payment);

// IPN/Webhook URL (if gateway supports it)
$ipnUrl = $this->gateway->gatewayifyIpnUrl($payment);  // Per-payment IPN URL

// Static IPN URL (for config form display)
$staticIpnUrl = $this->gateway->gatewayifyIpnUrl();  // Without payment param

// With query parameters
$successUrl = $this->gateway->gatewayifySuccessUrl($payment, [
    'session_id' => $response['session'],
    'payment_ref' => $response['id'],
]);
```

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

### Basic Gateway Provider Structure

Source: https://docs.uddoktapay.com/developers/custom-gateways

This is the fundamental structure for a custom gateway provider, extending BaseGatewayProvider and implementing essential methods like metadata, config, checkout, and success.

```php
<?php

namespace App\Modules\Gateways\ExampleGateway;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
use Revoltify\Gatewayify\BaseGatewayProvider;
use Revoltify\Gatewayify\Config\GatewayMetadata;
use Revoltify\Gatewayify\Contracts\Paymentable;
use Revoltify\Gatewayify\Response\GatewayResponse;
use Revoltify\Support\Forms\Components\Field;
use Revoltify\Support\Forms\Form;

class ProcessPayment extends BaseGatewayProvider
{
    // Define gateway info and appearance
    public static function metadata(): GatewayMetadata
    {
        return GatewayMetadata::make()
            ->name('Example Gateway')
            ->currency('USD', '$')
            ->group('example')
            ->global()
            ->live();
    }

    // Define admin configuration fields
    public function config(): Form
    {
        return Form::make([
            Field::make('api_key')->required(),
            Field::make('api_secret')->password()->required(),
        ]);
    }

    // Initiate payment with gateway
    public function checkout(Paymentable $payment): GatewayResponse
    {
        // 1. Call gateway API to create payment
        // 2. Return redirect URL to checkout page
    }

    // Handle return after payment
    public function success(Request $request, Paymentable $payment): GatewayResponse
    {
        // 1. Verify payment status with gateway
        // 2. Mark payment as completed or pending
        // 3. Always return redirectToSuccessURL
    }
}
```

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

### Gateway Directory Structure

Source: https://docs.uddoktapay.com/developers/custom-gateways

Place your custom gateway files within the app/Modules/Gateways/YourGateway/ directory. Ensure your namespace matches this directory structure for auto-discovery.

```php
namespace App\Modules\Gateways\YourGateway;
```

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

### Build Custom Notification Messages in PHP

Source: https://docs.uddoktapay.com/developers/custom-notifications

Construct formatted messages for notifications, including payment details, and send them via HTTP POST requests. Ensure the `NotificationChannelInterface` and `NotificationInterface` are implemented.

```php
public function handle(
    NotificationChannelInterface $notifiable,
    NotificationInterface $notification
): void {
    $payment = $notification->getPayment();
    
    // Build formatted message
    $message = sprintf(
        "Payment of %s %s received from %s\nTransaction ID: %s\nGateway: %s",
        $payment->gatewayCurrency(),
        number_format((float) $payment->paymentableAmount(), 2),
        $payment->paymentableCustomerName(),
        $payment->paymentableGatewayTransactionId(),
        $payment->gateway->name ?? 'N/A'
    );
    
    // Send message
    Http::post($this->config('webhook_url'), ['text' => $message]);
}
```

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

### Configuration Form Definition

Source: https://docs.uddoktapay.com/developers/custom-gateways

Defines the settings fields that administrators need to configure for the gateway, including environment toggles, API credentials, and webhook URLs.

```php
public function config(): Form
{
    return Form::make([
        // Environment toggle
        Field::make('sandbox')
            ->select([
                'enable' => 'Sandbox Mode',
                'disable' => 'Live Mode',
            ])
            ->default('disable')
            ->required(),

        // API credentials
        Field::make('api_key')
            ->placeholder('sk_live_...')
            ->helperText('Find in your dashboard under API Keys')
            ->required(),

        Field::make('api_secret')
            ->password()
            ->revealable()  // Show/hide toggle
            ->required(),

        // IPN/Webhook URL (if gateway requires manual setup)
        Field::make('webhook_url')
            ->value($this->gateway->gatewayifyIpnUrl())
            ->suffixCopy()  // Copy button
            ->disabled()    // Read-only
            ->columnSpanFull()
            ->helperText('Copy this URL and paste it in your gateway dashboard webhook settings'),
    ]);
}
```

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

### Custom Theme Directory Structure

Source: https://docs.uddoktapay.com/developers/custom-themes

Defines the standard directory layout for a custom UddoktaPay theme, including configuration files, Blade views for different checkout stages, gateway-specific views, and reusable components. Also shows the public assets directory.

```directory structure
themes/
└── MyTheme/
    ├── Config.php
    └── views/
        ├── layouts/
        │   └── app.blade.php
        ├── checkout/
        │   ├── checkout.blade.php
        │   ├── success.blade.php
        │   ├── pending.blade.php
        │   ├── cancel.blade.php
        │   ├── paymentlink.blade.php
        │   └── liquid.blade.php
        ├── gateways/
        │   ├── mfs.blade.php
        │   ├── bank.blade.php
        │   └── binance.blade.php
        └── components/
            └── fields/
                ├── text.blade.php
                ├── select.blade.php
                ├── textarea.blade.php
                ├── checkbox.blade.php
                ├── radio.blade.php
                └── file.blade.php

public/
└── themes/
    └── mytheme/
        └── assets/
            ├── thumbnail.png
            ├── css/
            ├── js/
            └── images/
```

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

### Access UddoktaPay Application Shell

Source: https://docs.uddoktapay.com/installation/docker

Open an interactive bash shell inside the UddoktaPay application container. This is useful for debugging or running commands within the app's environment.

```bash
docker exec -it uddoktapay-app bash
```

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

### Number Input Field

Source: https://docs.uddoktapay.com/developers/custom-gateways

Sets up a number input field with specified minimum and maximum values and a unit suffix.

```php
Field::make('timeout')
    ->number()
    ->min(10)
    ->max(300)
    ->suffix('seconds')
```

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

### Additional Gateway Features

Source: https://docs.uddoktapay.com/developers/custom-gateways

Enables additional features for the gateway, such as QR code display.

```php
->qr()  // Enable QR code display
```

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

### Restart UddoktaPay Services

Source: https://docs.uddoktapay.com/installation/docker

Restart all running UddoktaPay services. This command is useful for applying configuration changes or recovering from issues.

```bash
docker compose -f /opt/uddoktapay/compose.yml restart
```

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

### Testing PHP Version

Source: https://docs.uddoktapay.com/system-settings/cron-job

Verify the PHP version being used by your server or cron environment. This is important for ensuring compatibility with requirements like PHP 8.2+.

```bash
/path/to/php -v
```

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

### Testing Artisan File Permissions

Source: https://docs.uddoktapay.com/system-settings/cron-job

This command checks and sets executable permissions for the artisan file, which is crucial for cron job execution.

```bash
chmod +x artisan
```

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

### Operation Mode Options

Source: https://docs.uddoktapay.com/developers/custom-gateways

Defines the operational mode for the gateway, ranging from automated live API integration to manual modes for personal, agent, or merchant accounts.

```php
->live()      // Automated API integration
->personal()  // Manual personal account
->agent()     // Manual agent account
->merchant()  // Manual merchant account
```

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

### Bank Gateway Parameters Display

Source: https://docs.uddoktapay.com/developers/custom-themes

Iterates through bank parameters to display key-value pairs, using a helper function `key_to_word` for formatting keys.

```blade
@foreach ($parameters as $key => $value)
    <span>{{ key_to_word($key) }}</span>
    <span>{{ $value }}</span>
@endforeach
```

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

### Handle Specific Notification Events

Source: https://docs.uddoktapay.com/developers/custom-notifications

Check the event key to determine the type of notification received and execute appropriate logic.

```php
$eventKey = $notification->getEventKey();

if ($eventKey === 'payment.completed') {
    // Handle completed payment notification
}
```

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

### Check Port Usage and Stop Conflicting Service

Source: https://docs.uddoktapay.com/installation/docker

Use 'lsof' to find processes using a specific port and 'systemctl' to stop services like Apache or Nginx. Alternatively, change the APP_PORT in your .env file and restart Docker Compose.

```bash
sudo lsof -i :80
```

```bash
sudo systemctl stop apache2  # or nginx
```

```bash
docker compose -f /opt/uddoktapay/compose.yml up -d
```

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

### Display Static Webhook URL in Config Form

Source: https://docs.uddoktapay.com/developers/custom-gateways

In the static webhook URL scenario, display the gateway's required webhook URL in the configuration form for the administrator to copy and configure in the gateway's dashboard.

```php
public function config(): Form
{
    return Form::make([
        Field::make('api_key')->required(),
        
        // Show static webhook URL for admin to copy
        Field::make('webhook_url')
            ->value($this->gateway->gatewayifyIpnUrl())
            ->suffixCopy()
            ->disabled()
            ->columnSpanFull()
            ->helperText('Copy this URL and paste it in your gateway dashboard webhook settings'),
    ]);
}
```

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

### Password Field with Reveal

Source: https://docs.uddoktapay.com/developers/custom-gateways

Creates a password input field that allows users to reveal the entered text.

```php
Field::make('secret')
    ->password()
    ->revealable()
```

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

### Define Notification Configuration Form

Source: https://docs.uddoktapay.com/developers/custom-notifications

Use this to define the structure of a configuration form for custom notifications. It includes fields for webhook URL, API token, environment selection, minimum amount, and custom headers.

```php
public function form(): Form
{
    return Form::make([
        // Webhook URL
        Field::make('webhook_url')
            ->text()
            ->label('Webhook URL')
            ->placeholder('https://your-app.com/webhook')
            ->helperText('The endpoint where notifications will be sent')
            ->required()
            ->url(),

        // API Token
        Field::make('api_token')
            ->password()
            ->label('API Token')
            ->placeholder('Enter your API token')
            ->revealable()  // Show/hide toggle
            ->required(),

        // Environment Selection
        Field::make('environment')
            ->select([
                'production' => 'Production',
                'staging' => 'Staging',
                'development' => 'Development',
            ])
            ->default('production')
            ->label('Environment'),

        // Minimum Amount Filter
        Field::make('minimum_amount')
            ->number()
            ->label('Minimum Amount')
            ->helperText('Only notify for payments above this amount')
            ->min(0)
            ->suffix('USD'),

        // Custom Headers (JSON)
        Field::make('custom_headers')
            ->textarea(rows: 3)
            ->label('Custom Headers')
            ->placeholder('{"X-Custom-Header": "value"}')
            ->helperText('JSON object of custom headers to include')
            ->columnSpanFull(),
    ]);
}
```

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

### Implement IPN Webhook Handler

Source: https://docs.uddoktapay.com/developers/custom-gateways

Handles incoming IPN notifications from a payment gateway to verify authenticity and update payment status. Use this to process webhook events for completed, pending, or failed payments.

```php
use Illuminate\Support\Facades\Http;

public function ipn(Request $request, Paymentable $payment): GatewayResponse
{
    try {
        // Verify webhook authenticity with gateway
        $response = Http::timeout(30)
            ->asForm()
            ->post($this->baseUrl . 'ipn/verify', $request->all());

        if ($response->failed()) {
            return GatewayResponse::error('Verification failed');
        }

        $data = $response->json();

        // Handle completed payment
        if ($data['status'] === 'completed') {
            $this->markAsCompleted(
                payment: $payment,
                transactionId: $data['transaction_id'],
                gatewayReferenceId: $data['payment_id'],
                senderNumber: $data['customer_phone'] ?? null,
                additionalData: [
                    'fee' => $data['fee'] ?? 0,
                    'net_amount' => $data['net_amount'] ?? 0,
                ]
            );

            return GatewayResponse::success('Payment completed');
        }

        // Handle pending payment
        if ($data['status'] === 'pending') {
            $this->markAsPending(
                payment: $payment,
                transactionId: $data['transaction_id'],
                gatewayReferenceId: $data['payment_id']
            );

            return GatewayResponse::success('Payment pending');
        }

        return GatewayResponse::error('Payment failed');

    } catch (\Exception $e) {
        return GatewayResponse::error('IPN processing error');
    }
}
```

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

### Verify Payment Status Callback

Source: https://docs.uddoktapay.com/developers/custom-gateways

Handles the success callback from the payment gateway to verify the payment status. It retrieves the reference, calls the gateway API for verification, and updates the payment status accordingly (completed, pending, or failed).

```php
use Illuminate\Support\Facades\Http;

public function success(Request $request, Paymentable $payment): GatewayResponse
{
    // Get payment reference from URL
    $reference = $request->get('reference');
    
    if (!$reference) {
        return GatewayResponse::error('Reference required');
    }

    try {
        // Verify with gateway API
        $response = Http::timeout(30)
            ->withHeaders($this->headers)
            ->get($this->baseUrl . "payments/{$reference}");

        if ($response->failed()) {
            return GatewayResponse::error('Verification failed');
        }

        $data = $response->json();

        // Payment successful
        if ($data['status'] === 'completed') {
            $this->markAsCompleted(
                payment: $payment,
                transactionId: $data['transaction_id'],
                gatewayReferenceId: $data['payment_id'],
                senderNumber: $data['customer_phone'] ?? null
            );

            return $this->redirectToSuccessURL($payment);
        }

        // Payment pending
        if ($data['status'] === 'pending') {
            $this->markAsPending(
                payment: $payment,
                transactionId: $data['transaction_id'],
                gatewayReferenceId: $data['payment_id']
            );

            return $this->redirectToSuccessURL($payment);
        }

        // Payment failed
        return GatewayResponse::error('Payment failed');

    } catch (\Exception $e) {
        return GatewayResponse::error('Verification error');
    }
}
```

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

### Text Input Field

Source: https://docs.uddoktapay.com/developers/custom-gateways

Defines a standard text input field for gateway configuration.

```php
Field::make('merchant_id')
    ->placeholder('Enter ID')
    ->maxLength(50)
```

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

### Payment Data Access Methods

Source: https://docs.uddoktapay.com/developers/custom-gateways

Provides access to essential payment details required for creating a payment session or processing callbacks. Use these methods to retrieve customer information, amounts, and payment status.

```php
$payment->paymentableReferenceId()        // Unique reference
$payment->paymentableAmount()             // Amount to charge
$payment->paymentableCustomerName()       // Customer name
$payment->paymentableCustomerEmail()      // Customer email
$payment->paymentableCustomerPhone()      // Customer phone
$payment->paymentableProductName()        // Product description
$payment->paymentableIsAlreadyCompleted() // Check if paid
$payment->paymentableGatewayReferenceId() // Gateway payment ID (after completion)
```