PHPackages                             futureecom/omnipay-paypal - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. futureecom/omnipay-paypal

ActiveLibrary[Payment Processing](/categories/payments)

futureecom/omnipay-paypal
=========================

PayPal driver for the Omnipay payment processing library.

1.2.1(3w ago)1118MITPHPPHP ^8.3

Since Jan 5Pushed 3w agoCompare

[ Source](https://github.com/futureecom/omnipay-paypal)[ Packagist](https://packagist.org/packages/futureecom/omnipay-paypal)[ Docs](https://www.futureecom.com)[ RSS](/packages/futureecom-omnipay-paypal/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (4)Dependencies (23)Versions (5)Used By (0)

Omnipay: PayPal
===============

[](#omnipay-paypal)

**PayPal gateway for the Omnipay payment processing library**

This standalone package implements PayPal Orders v2 and Vault/Payment Method Tokens v3 for Omnipay using PSR-compatible HTTP and cache interfaces.

Installation
------------

[](#installation)

Install the gateway using Composer:

```
composer require futureecom/omnipay-paypal
```

Configuration
-------------

[](#configuration)

First, you need to obtain your PayPal API credentials:

1. Go to [PayPal Developer Dashboard](https://developer.paypal.com/dashboard/)
2. Create or select your app
3. Copy your **Client ID** and **Client Secret**

Usage
-----

[](#usage)

### Initialize the Gateway

[](#initialize-the-gateway)

```
use Omnipay\Omnipay;

$gateway = Omnipay::create('PayPal');
$gateway->setClientId('your-client-id');
$gateway->setClientSecret('your-client-secret');
$gateway->setTestMode(true); // Set to false for live transactions
```

OAuth tokens are cached in memory by default and are isolated by environment and client ID. Long-running or multi-process applications can provide any PSR-16 cache:

```
/** @var \Psr\SimpleCache\CacheInterface $cache */
$gateway->setCache($cache);
```

The gateway retries a PayPal operation once when PayPal rejects an expired access token with HTTP 401.

### Create an Authorization (Auth Only)

[](#create-an-authorization-auth-only)

Creates a PayPal order with intent to authorize. The customer must approve the order before you can authorize.

```
$response = $gateway->authorize([
    'amount' => '100.00',
    'currency' => 'USD',
    'returnUrl' => 'https://example.com/payment/return',
    'cancelUrl' => 'https://example.com/payment/cancel',
    'transactionId' => 'ORDER-123',
    'description' => 'Order #123',
    'brandName' => 'My Store',
])->send();

if ($response->isRedirect()) {
    // Redirect the customer to PayPal for approval
    $redirectUrl = $response->getRedirectUrl();
    $orderId = $response->getTransactionReference(); // Save this!

    // Redirect to $redirectUrl
} else {
    echo "Error: " . $response->getMessage();
}
```

### Create a Purchase (Auth + Capture)

[](#create-a-purchase-auth--capture)

Creates a PayPal order with intent to capture. Similar flow as authorize.

```
$response = $gateway->purchase([
    'amount' => '50.00',
    'currency' => 'USD',
    'returnUrl' => 'https://example.com/payment/return',
    'cancelUrl' => 'https://example.com/payment/cancel',
])->send();

if ($response->isRedirect()) {
    $redirectUrl = $response->getRedirectUrl();
    $orderId = $response->getTransactionReference();

    // Redirect to $redirectUrl
}
```

For non-vaulted Standard Checkout, provide explicit identifiers and PayPal experience context. No Vault v3 operation or vault attribute is used:

```
$response = $gateway->purchase([
    'amount' => '100.00',
    'currency' => 'ILS',
    'referenceId' => 'internal-attempt-id',
    'invoiceId' => 'unique-invoice-id',
    'customId' => 'cart:cart-id',
    'payPalRequestId' => 'stable-create-idempotency-key',
    'returnUrl' => 'https://example.com/paypal/return',
    'cancelUrl' => 'https://example.com/paypal/cancel',
    'userAction' => 'PAY_NOW',
    'shippingPreference' => 'NO_SHIPPING',
])->send();
```

### Retrieve an Order

[](#retrieve-an-order)

Retrieve an order after an interrupted or ambiguous capture:

```
$response = $gateway->fetchOrder([
    'transactionReference' => $orderId,
])->send();
```

### Advanced Checkout and Vault v3

[](#advanced-checkout-and-vault-v3)

Advanced integrations can create and confirm Vault v3 setup tokens, retrieve or delete payment tokens, and then pass a token as `cardReference` to an Orders v2 request. These operations are opt-in; Orders v2 requests do not invoke Vault v3 automatically.

```
$setup = $gateway->createSetupToken([
    'paymentSource' => ['card' => []],
    'payPalRequestId' => 'stable-setup-token-key',
])->send();

$token = $gateway->confirmSetupToken([
    'transactionReference' => $setup->getSetupTokenId(),
    'payPalRequestId' => 'stable-confirm-key',
])->send();
```

### Verify a REST Webhook

[](#verify-a-rest-webhook)

The library verifies signatures through PayPal. Persisting and reconciling events remains the consuming application's responsibility.

```
$response = $gateway->verifyWebhookSignature([
    'webhookId' => $webhookId,
    'transmissionId' => $headers['PAYPAL-TRANSMISSION-ID'],
    'transmissionTime' => $headers['PAYPAL-TRANSMISSION-TIME'],
    'certUrl' => $headers['PAYPAL-CERT-URL'],
    'authAlgo' => $headers['PAYPAL-AUTH-ALGO'],
    'transmissionSignature' => $headers['PAYPAL-TRANSMISSION-SIG'],
    'webhookEvent' => $decodedEvent,
])->send();

if (!$response->isWebhookSignatureValid()) {
    // Reject the event.
}
```

### Capture an Order

[](#capture-an-order)

After the customer approves the order, capture the payment:

```
$response = $gateway->capture([
    'transactionReference' => $orderId, // Order ID from authorize/purchase
])->send();

if ($response->isSuccessful()) {
    echo "Payment captured successfully!";
    $captureId = $response->getCaptureId(); // Save for refunds
} else {
    echo "Capture failed: " . $response->getMessage();
}
```

### Partial Capture

[](#partial-capture)

```
$response = $gateway->capture([
    'transactionReference' => $orderId,
    'amount' => '50.00',
    'currency' => 'USD',
])->send();
```

### Refund a Payment

[](#refund-a-payment)

Refund a captured payment using the capture ID:

```
// Full refund
$response = $gateway->refund([
    'transactionReference' => $captureId, // Capture ID from capture response
])->send();

// Partial refund
$response = $gateway->refund([
    'transactionReference' => $captureId,
    'amount' => '25.00',
    'currency' => 'USD',
])->send();

if ($response->isSuccessful()) {
    echo "Refund successful!";
    echo "Refund ID: " . $response->getTransactionReference();
} else {
    echo "Refund failed: " . $response->getMessage();
}
```

### Void an Authorization

[](#void-an-authorization)

Void an authorized payment (must be done before capture):

```
$response = $gateway->void([
    'transactionReference' => $authorizationId, // Authorization ID
])->send();

if ($response->isSuccessful()) {
    echo "Authorization voided successfully!";
}
```

Complete Payment Flow Example
-----------------------------

[](#complete-payment-flow-example)

```
use Omnipay\Omnipay;

// 1. Initialize gateway
$gateway = Omnipay::create('PayPal');
$gateway->setClientId('your-client-id');
$gateway->setClientSecret('your-client-secret');
$gateway->setTestMode(true);

// 2. Create order
$response = $gateway->purchase([
    'amount' => '99.99',
    'currency' => 'USD',
    'returnUrl' => 'https://example.com/payment/complete',
    'cancelUrl' => 'https://example.com/payment/cancel',
    'transactionId' => 'ORDER-456',
    'description' => 'Premium subscription',
    'brandName' => 'My Store',
    'locale' => 'en-US',
    'landingPage' => 'LOGIN',
    'userAction' => 'PAY_NOW',
])->send();

// 3. Redirect customer to PayPal
if ($response->isRedirect()) {
    // Store order ID in session
    $_SESSION['paypal_order_id'] = $response->getTransactionReference();

    header('Location: ' . $response->getRedirectUrl());
    exit;
}

// 4. On return URL, capture the payment
$orderId = $_SESSION['paypal_order_id'];

$captureResponse = $gateway->capture([
    'transactionReference' => $orderId,
])->send();

if ($captureResponse->isSuccessful()) {
    // Payment successful!
    $captureId = $captureResponse->getCaptureId();

    // Store capture ID for potential refunds
    // Update order status
    // Send confirmation email
} else {
    // Handle error
    $error = $captureResponse->getMessage();
}
```

Response Methods
----------------

[](#response-methods)

All responses support these methods:

MethodDescription`isSuccessful()`Whether the request was successful`isRedirect()`Whether a redirect is required`getRedirectUrl()`The PayPal approval URL`getTransactionReference()`Order ID or Refund ID`getAuthorizationId()`Authorization ID (after authorize)`getCaptureId()`Capture ID (after capture)`getMessage()`Error message if failed`getCode()`Status code (CREATED, COMPLETED, etc.)`getHttpStatus()`PayPal HTTP response status`getDebugId()`PayPal diagnostic debug ID`getDetails()`Structured PayPal error details`getIssues()`PayPal issue codes`isWebhookSignatureValid()`Whether PayPal verified a REST webhook`getData()`Full response data arraySandbox Testing
---------------

[](#sandbox-testing)

1. Create sandbox accounts at [PayPal Developer Dashboard](https://developer.paypal.com/dashboard/accounts)
2. Use sandbox credentials with `setTestMode(true)`
3. Test with sandbox buyer accounts

Support
-------

[](#support)

If you have any questions or issues, please open an issue on GitHub.

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance95

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~67 days

Total

4

Last Release

22d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/547790?v=4)[futureavi](/maintainers/futureavi)[@futureavi](https://github.com/futureavi)

---

Top Contributors

[![futureecomavi](https://avatars.githubusercontent.com/u/48889697?v=4)](https://github.com/futureecomavi "futureecomavi (5 commits)")

---

Tags

paymentgatewaypaypalpaymerchantomnipay

###  Code Quality

TestsPHPUnit

Static AnalysisRector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/futureecom-omnipay-paypal/health.svg)

```
[![Health](https://phpackages.com/badges/futureecom-omnipay-paypal/health.svg)](https://phpackages.com/packages/futureecom-omnipay-paypal)
```

###  Alternatives

[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.8M674](/packages/shopware-core)[omnipay/paypal

PayPal gateway for Omnipay payment processing library

3147.2M61](/packages/omnipay-paypal)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)