README

Unified payment gateway for cards and PayPal.

Accept credit cards (via Stripe) and PayPal through a single API. Funds settle directly into the merchant's own connected account — GembaPay never holds your money.

Features

One API, two payment methods — Stripe (cards/Apple Pay/Google Pay) and PayPal
Direct settlement — Payments route straight into your own Stripe or PayPal account
51+ currencies — Price in any supported currency
Test mode built-in — Stripe and PayPal sandbox environments for development
Zero dependencies — Uses only PHP built-in curl and json extensions
Laravel & WordPress compatible — Works with any PHP framework

Install

composer require gembapay/gembapay-php

Quick Start

use GembaPay\GembaPay;

$gembapay = new GembaPay(
    apiKey: 'gembapay_test_your_key',  // test key for development
    webhookSecret: 'your_webhook_secret'
);

// Create a payment
$payment = $gembapay->createPayment(
    orderId: 'ORDER-123',
    amount: 100.00,
    currency: 'EUR'
);

echo $payment['paymentUrl'];
// → https://payment.gembapay.com/checkout/ORDER-123

echo implode(', ', $payment['allowedMethods']);
// → stripe, paypal

Usage

Create Payment

$payment = $gembapay->createPayment(
    orderId: 'ORDER-456',
    amount: 49.99,
    currency: 'USD',
    description: 'Premium Plan'
);

// Redirect customer to unified checkout (use paymentUrl as-is — it carries an unguessable token).
// The page follows the customer's browser language (en/bg/es) and device theme;
// to fix them: $payment['paymentUrl'] . '?lang=bg&theme=light'
header('Location: ' . $payment['paymentUrl']);
exit;

Check Status

$status = $gembapay->getPaymentStatus('ORDER-456');

echo $status['status'];   // 'completed'
echo $status['network'];  // 'stripe' or 'paypal'

Webhook Handling

// webhook.php
$gembapay = new GembaPay(
    apiKey: $_ENV['GEMBAPAY_API_KEY'],
    webhookSecret: $_ENV['GEMBAPAY_WEBHOOK_SECRET']
);

try {
    $event = $gembapay->parseWebhookFromGlobals();

    if ($event['event'] === 'payment.completed') {
        $orderId = $event['payment']['orderId'];
        $amount = $event['payment']['usdAmount'];
        $method = $event['payment']['network'];

        // Fulfill the order
        fulfillOrder($orderId);
    }

    http_response_code(200);
    echo json_encode(['received' => true]);

} catch (\GembaPay\GembaPayException $e) {
    http_response_code(401);
    echo json_encode(['error' => $e->getMessage()]);
}

Or verify manually:

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GEMBAPAY_SIGNATURE'] ?? '';

if ($gembapay->verifyWebhook($payload, $signature)) {
    $data = json_decode($payload, true);
    // Process event...
}

Transactions & Stats

$transactions = $gembapay->listTransactions();
$stats = $gembapay->getStats();

Laravel Integration

// config/services.php
'gembapay' => [
    'api_key' => env('GEMBAPAY_API_KEY'),
    'webhook_secret' => env('GEMBAPAY_WEBHOOK_SECRET'),
],

// app/Providers/AppServiceProvider.php
$this->app->singleton(GembaPay::class, function () {
    return new GembaPay(
        apiKey: config('services.gembapay.api_key'),
        webhookSecret: config('services.gembapay.webhook_secret')
    );
});

// In your controller
public function checkout(Request $request, GembaPay $gembapay)
{
    $payment = $gembapay->createPayment(
        orderId: $request->order_id,
        amount: $request->amount,
        currency: $request->currency ?? 'USD'
    );

    return redirect($payment['paymentUrl']);
}

Test Mode

Use test API keys (gembapay_test_...) for development. Test mode automatically uses:

Method	Test Environment
Stripe	Test cards (`4242 4242 4242 4242`)
PayPal	Sandbox accounts

$gembapay = new GembaPay(apiKey: 'gembapay_test_your_key');
var_dump($gembapay->isTestMode()); // true

API Reference

Constructor

new GembaPay(
    string $apiKey,               // Required
    ?string $webhookSecret = null, // For webhook verification
    ?string $baseUrl = null,       // Custom API URL
    int $timeout = 30              // Timeout in seconds
)

Methods

Method	Description
`createPayment($orderId, $amount, $currency, $description)`	Create payment → returns array with `paymentUrl`
`getPayment($orderId)`	Get one of your orders (status, amounts, customer email, payment)
`getPaymentStatus($orderId)`	Status of one of your orders
`listTransactions($params)`	List merchant transactions
`getStats()`	Get merchant statistics
`verifyWebhook($payload, $signature)`	Verify webhook signature → bool
`parseWebhookFromGlobals()`	Parse & verify from PHP globals
`isTestMode()`	Check if using test mode

Fee Structure

Method	Fee
Stripe (Cards, Apple Pay, Google Pay)	1% + €0.20 + Stripe fees
PayPal (Balance, Bank, Pay Later)	1% + €0.20 + PayPal fees

gembapay / gembapay-php

Package info

Security

Statistics