EDPay PHP & Laravel SDK

Biblioteca oficial para integração em PHP e suporte nativo ao ecossistema Laravel com Service Provider, Facade Edpay, publicação de configurações, migrações de base de dados e rota automática de webhooks.

edutecka/edpay-php-sdk

Suporte Laravel 9.x, 10.x & 11.x

Código aberto sob licença MIT com suporte a auto-discovery no Laravel.

Ver no GitHub

Instalação via Composer

Adicione o pacote às dependências do seu projecto:

Terminal

composer require edutecka/edpay-php-sdk

Integração com Laravel (Configurações & Migrações)

O pacote inclui auto-discovery para o EdpayServiceProvider e a Facade Edpay. Tal como na biblioteca oficial do Stripe Cashier, pode publicar o ficheiro de configuração e executar as migrações para gerir pagamentos e registo de webhooks na base de dados do Laravel:

1. Publicação de Configuração e Migrações

Terminal — Artisan

# 1. Publicar ficheiro de configuração config/edpay.php
php artisan vendor:publish --tag=edpay-config

# 2. Publicar migrações das tabelas edpay_payments e edpay_webhook_events
php artisan vendor:publish --tag=edpay-migrations

# 3. Executar as migrações na base de dados
php artisan migrate

2. Configurar Variáveis de Ambiente no .env

.env

# Ficheiro .env do Laravel
EDPAY_PUBLIC_KEY=pk_test_019313264c8f74a0...
EDPAY_PRIVATE_KEY=sk_test_982f1b4c7a10ed...
EDPAY_ENVIRONMENT=sandbox # ou production
EDPAY_WEBHOOK_SECRET=whsec_884120...
EDPAY_CURRENCY=MZN

3. Utilização via Facade Edpay no Controller

app/Http/Controllers/OrderPaymentController.php

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use EDPay\Laravel\Facades\Edpay;

class OrderPaymentController extends Controller
{
    /**
     * Cria intenção de pagamento unificada e regista a cobrança na base de dados.
     */
    public function charge(Request $request)
    {
        $validated = $request->validate([
            'amount' => 'required|numeric|min:1',
            'phone'  => 'required|string',
            'method' => 'nullable|string', // ex: mpesa, emola, card ou omitir para todos
        ]);

        $reference = 'ORD-' . strtoupper(uniqid());

        // Chamada à API unificada EDPay via Facade
        $response = Edpay::payments()->create([
            'amount'      => (float) $validated['amount'],
            'currency'    => 'MZN',
            'reference'   => $reference,
            'description' => 'Pagamento de Pedido ' . $reference,
            'methods'     => !empty($validated['method']) ? [$validated['method']] : null,
            'customer'    => [
                'phone' => $validated['phone'],
            ],
            'return_url'  => url('/pedidos/' . $reference . '/confirmado'),
        ], $request->header('X-Idempotency-Key') ?? 'req_' . uniqid());

        return response()->json($response, 201);
    }
}

4. Tratamento Automático de Webhooks via Eventos

A rota /edpay/webhook valida automaticamente a assinatura criptográfica HMAC-SHA256 e emite o evento edpay.webhook.payment_succeeded:

app/Providers/AppServiceProvider.php

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\DB;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Ouve o webhook de pagamento bem-sucedido
        Event::listen('edpay.webhook.payment_succeeded', function (array $event) {
            $data = $event['data'];
            
            DB::table('edpay_payments')
                ->where('reference', $data['reference'])
                ->update([
                    'status'       => 'succeeded',
                    'trans_id'     => $data['id'],
                    'completed_at' => now(),
                ]);
        });
    }
}

Utilização em PHP Puro (Sem Framework)

Pode instanciar o EDPayClient diretamente em qualquer script ou aplicação PHP padrão:

index.php

<?php

use EDPay\EDPayClient;

require_once __DIR__ . '/vendor/autoload.php';

// Inicializar cliente em PHP puro
$client = new EDPayClient(
    publicKey: getenv('EDPAY_PUBLIC_KEY'),
    privateKey: getenv('EDPAY_PRIVATE_KEY'),
    environment: 'sandbox' // 'sandbox' ou 'production'
);

// Criar intenção de pagamento unificada
$payment = $client->payments()->create([
    'amount'      => 1500.0, // 1.500,00 MZN
    'currency'    => 'MZN',
    'reference'   => 'ORD-2026-9901',
    'description' => 'Serviço de Faturação Digital',
    'customer'    => [
        'phone'   => '+25884xxxxxxx',
    ],
]);

echo "Payment ID: " . $payment['data']['id'] . "\n";
echo "Checkout URL: " . $payment['data']['checkout_url'] . "\n";