astral-php / astral-paypal

0.1.0 2026-10-23 15:37 UTC

Requires

• php: ^8.1
• ext-curl: *
• ext-json: *
• astral-php/astral-core: ^1.2

Requires (Dev)

• phpunit/phpunit: ^10.0 || ^11.0

MIT

• astral-php

• php
• payment
• checkout
• paypal
• webhook
• astral

Published on Packagist.org on 2026-10-23 15:50 UTC

README

Paiement PayPal pour Astral — Orders API v2 (create → approve → capture), webhooks, remboursements.

Statut : 0.1.0 — MVP sandbox. Package dédié (option A), miroir conceptuel de astral-payment (Stripe).
UX MVP = redirect vers le lien approve (JS Buttons = backlog).

Installation

composer require astral-php/astral-paypal

1. ServiceProvider — config/dependencies.php

return [
    // …
    AstralPaypal\PaypalServiceProvider::class,
];

2. Variables d’environnement

Copier stubs/.env.paypal.example :

PAYPAL_MODE=sandbox
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
# PAYPAL_WEBHOOK_ID=...   # requis pour parseWebhook()

Clés : Developer Dashboard → Apps & Credentials → Sandbox.

3. Usage

use AstralPaypal\PaypalService;

/** @var PaypalService $paypal */
$order = $paypal->createOrder(
    amountCents: 2880,
    currency: 'EUR',
    shopOrderReference: (string) $shopOrderId,
    context: [
        'return_url' => 'https://shop.example/checkout/paypal/return',
        'cancel_url' => 'https://shop.example/checkout/paypal/cancel',
        'brand_name' => 'Ma boutique',
    ],
);

// Rediriger le client :
header('Location: ' . $order->approveUrl());

// Sur return_url ?token=PAYPAL_ORDER_ID :
$captured = $paypal->captureOrder($_GET['token']);
if ($captured->isCompleted()) {
    // marquer la commande payée + $captured->captureId pour refunds
}

4. Webhook

$event = $paypal->parseWebhook($rawBody, $requestHeaders);
// event_type : PAYMENT.CAPTURE.COMPLETED, …

Endpoint shop typique : POST /webhooks/paypal (sans CSRF).

5. Remboursement

$paypal->refundCapture($captureId, amountCents: null); // total

Événements

Classe	Quand
AstralPaypal\Events\PaymentSucceeded	Capture OK (shop peut dispatcher)
AstralPaypal\Events\PaymentFailed	Échec / annulation
AstralPaypal\Events\PaymentRefunded	Refund API OK

Le package ne branche pas automatiquement les mails / stock : l’app hôte écoute ou appelle ses services (comme pour Stripe côté shop).

Tests

composer install
composer test

Hors scope 0.1

• PayPal JS Buttons / Pay Later / Venmo
• Abonnements
• Marketplace Platforms

Licence

MIT