README

PayPal gateway for the Omnipay payment processing library

This package implements PayPal REST API v2 (Orders API) support for Omnipay.

Installation

Install the gateway using Composer:

composer require futureecom/omnipay-paypal

Configuration

First, you need to obtain your PayPal API credentials:

Go to PayPal Developer Dashboard
Create or select your app
Copy your Client ID and Client Secret

Usage

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

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)

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
}

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

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

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 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

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

All responses support these methods:

Method	Description
`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.)
`getData()`	Full response data array

Sandbox Testing

Create sandbox accounts at PayPal Developer Dashboard
Use sandbox credentials with setTestMode(true)
Test with sandbox buyer accounts

Support

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

License

This package is open-sourced software licensed under the MIT license.

futureecom / omnipay-paypal

Maintainers

Details