UddoktaPay

https://docs.uddoktapay.com
Admin
UddoktaPay is a comprehensive self-hosted payment management platform designed to simplify payment...
Tokens:39,897
Snippets:604
Trust Score:7.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### 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)
```

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

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

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

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

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

### 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'
```

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

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

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

### 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
}
```

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

### 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
  }
}
```

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

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

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

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

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

### 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()
```

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

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

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

### 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);
```

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

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

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

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

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

### 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',
    ])
```

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

### 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)
```

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

### 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)
```

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

### 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.');
    }
}
```
Tokens:
Raw