Payments & Donations

SilkPanel CMS has a built-in donation system that allows server owners to accept payments and automatically distribute Silk (premium currency) to players. It supports multiple online payment providers and ePin redemption.

Supported Payment Providers

Provider	Type	Method
PayPal	Online Payment	Redirect to PayPal Checkout
Stripe	Online Payment	Redirect to Stripe Checkout
HipoPay	Online Payment	Redirect to HipoPay Gateway
Fawaterk	Online Payment	Redirect to Fawaterk Invoice
HipoCard	ePin	Synchronous code redemption
MaxiCard	ePin	Synchronous code redemption (XML API)
PaymentWall	Online Payment	Placeholder — not yet implemented
CoinPayments	Online Payment	Placeholder — not yet implemented

How It Works

Online Payments (PayPal, Stripe, HipoPay, Fawaterk)

1. User selects a Payment Provider in the dashboard
2. User selects a Donation Package (e.g., "100 Silk for $5.00")
3. System creates a Donation record with status PENDING
4. User is redirected to the payment gateway
5. After payment, the gateway sends a webhook callback to SilkPanel
6. Webhook controller verifies the signature, finds the donation, marks it COMPLETED
7. Silk is automatically granted to the user's game account via SilkHelper::addSilk()

ePin Redemption (HipoCard / MaxiCard)

1. User selects the ePin provider
2. User is shown a form to enter ePin Code and Secret
3. System calls the provider's API synchronously
4. If valid: Donation is marked COMPLETED, Silk is granted based on denomination config
5. If invalid: Error message is shown

TIP

ePin redemption happens instantly — there's no redirect or webhook involved. The API call and silk grant happen in a single request.

Frontend Routes

All donation pages require authentication (auth middleware):

Route	Description
/dashboard/donate	List active payment providers
/dashboard/donate/{provider}	Show packages for a provider
/dashboard/donate/{package}/checkout	Initiate checkout
/dashboard/donate/redeem-epin/{provider}	ePin form (HipoCard/MaxiCard)
/dashboard/donate/success	Success confirmation
/dashboard/donate/cancel	Cancellation page

Environment Configuration

All provider credentials are configured via .env:

# PayPal
PAYPAL_CLIENT_ID=your-client-id
PAYPAL_CLIENT_SECRET=your-client-secret
PAYPAL_MODE=sandbox          # sandbox or live

# Stripe
STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# HipoPay
HIPOPAY_MERCHANT_ID=your-merchant-id
HIPOPAY_SECRET_KEY=your-secret-key

# Fawaterk
FAWATERK_API_KEY=your-api-key
FAWATERK_VENDOR_KEY=your-vendor-key

# HipoCard (ePin)
HIPOCARD_API_KEY=your-api-key
HIPOCARD_API_SECRET=your-api-secret

# MaxiCard (ePin)
MAXICARD_API_KEY=your-api-key
MAXICARD_API_SECRET=your-api-secret

WARNING

Always use sandbox/test credentials during setup. Only switch to live credentials after you've verified the full payment flow end-to-end.

Webhook URLs

These URLs must be configured in each payment provider's dashboard:

Provider	Webhook URL
PayPal	https://yourdomain.com/webhook/paypal
Stripe	https://yourdomain.com/webhook/stripe
HipoPay	https://yourdomain.com/webhook/hipopay
Fawaterk	https://yourdomain.com/webhook/fawaterk

TIP

Webhook routes are automatically excluded from CSRF protection — no additional configuration needed.

Database Models

Donation

Individual payment transaction record:

• Links to user, package, and provider
• Tracks: amount, currency, silk_amount, silk_type, status, transaction_id, ip_address
• Status flow: PENDING → COMPLETED / FAILED / REFUNDED

DonationPackage

Purchasable silk bundles configured in the admin panel:

• Fields: name, description, silk_amount, silk_type, price, currency
• Assigned to specific payment providers (many-to-many)
• Can be active/inactive, sorted by sort_order

PaymentProvider

Payment gateway configuration:

• Pre-seeded from PaymentProviderEnum (PayPal, Stripe, etc.)
• Fields: slug, name, description, is_active, sort_order
• ePin providers (HipoCard, MaxiCard) have denomination_silks config for mapping card values to silk amounts

Admin Panel (Filament)

Under the Donations navigation group:

Payment Providers

• List all providers with active toggle
• Edit: name, description, active status, sort order
• Assign packages to providers
• Configure ePin denomination → silk mappings
• View masked API credentials (read-only)

Donations

• Read-only log of all transactions
• Filterable by status and provider
• View details: transaction info, payment details, timestamps

Donation Packages

• Full CRUD for packages
• Configure: name, description, price, currency, silk amount, silk type, image
• Assign to payment providers

Silk Distribution

When a donation is completed (via webhook or ePin):

1. SilkHelper::addSilk($jid, $amount, $silk_type) is called
2. Handles both VSRO and ISRO server versions (based on config('silkpanel.version'))
3. For ISRO: uses pjid (portal JID), for default: uses jid

Available silk types (configurable per package):

Silk Type	Description
silk_own	Regular silk for the player
silk_gift	Gift silk (tradeable)
silk_point	Silk points

Security

• Webhook signatures are verified (HMAC-SHA256 for Stripe and HipoPay; PayPal API verification)
• Idempotent processing — duplicate webhook callbacks are safely ignored
• IP address logging for all donations
• CSRF excluded for webhook routes only
• ePin codes validated server-side via provider APIs

WARNING

Never expose your webhook secrets or API keys in client-side code. All payment verification happens server-side.

Step-by-Step Setup Guide

1. Configure provider API credentials in .env
2. Run migrations — donation tables are included in default migrations
3. Go to Admin Panel → Payment Providers → Activate desired providers
4. Create Donation Packages (Admin → Donation Packages → Create)
5. Assign packages to providers
6. For ePin providers: configure denomination → silk mappings
7. Configure webhook URLs in each provider's dashboard
8. Test with sandbox/test mode before going live

ePin Denomination Mapping

For HipoCard and MaxiCard, you need to map card denominations to silk amounts. This is configured per provider in the admin panel:

Card Value	Silk Amount
5.00	50
10.00	110
25.00	300
50.00	650

TIP

You can offer bonus silk for higher denominations to incentivize larger purchases.

Troubleshooting

Payments stuck in PENDING status

• Verify your webhook URL is correctly configured in the provider's dashboard
• Check that your server is reachable from the internet (webhooks need to reach your server)
• Review storage/logs/laravel.log for webhook errors
• For Stripe: check the webhook events in your Stripe Dashboard → Developers → Webhooks

Webhook returns 403 or 500 errors

• Verify your webhook secret matches between .env and the provider dashboard
• Ensure webhook routes are excluded from CSRF (this is automatic, but check if you've modified middleware)
• Check that the provider's API credentials are correct

Silk not granted after successful payment

• Verify the game database connection is configured correctly
• Check that the user has a valid jid (game account ID) linked
• Review the donation record in Admin → Donations for error details

ePin "Invalid Code" errors

• Double-check the ePin code and secret — they are case-sensitive
• Verify the ePin provider API credentials in .env
• The card may already be redeemed — check with the ePin provider