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:

1. Go to PayPal Developer Dashboard
2. Create or select your app
3. 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:

Sandbox Testing

1. Create sandbox accounts at PayPal Developer Dashboard
2. Use sandbox credentials with setTestMode(true)
3. 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.