How to Use PayPal REST API for Subscription Billing in PHP

Initialize the PayPal API Client

• Create a PayPal API client using the `PayPal\Rest\ApiContext` class. This requires your Client ID and Client Secret, which you obtain when you set up your application on the PayPal Developer site.

 

• Configure the `ApiContext` with the appropriate credentials and environment settings.

use PayPal\Rest\ApiContext;
use PayPal\Auth\OAuthTokenCredential;

$apiContext = new ApiContext(
    new OAuthTokenCredential(
        'YOUR_CLIENT_ID',     // Replace with your client ID
        'YOUR_CLIENT_SECRET'  // Replace with your client secret
    )
);

$apiContext->setConfig([
    'mode' => 'sandbox', // You can set this to 'live' when you're ready for production
    'http.ConnectionTimeOut' => 30,
    'log.LogEnabled' => true,
    'log.FileName' => '../PayPal.log',
    'log.LogLevel' => 'FINE', // Available options: 'FINE', 'INFO', 'WARN' or 'ERROR'
    'cache.enabled' => true,
]);

Create a Product

• Products are created to represent the physical or digital goods being sold. You must configure these products before you create a subscription plan.

 

• Define the product's name, description, type, and category.

use PayPal\Api\Product;

$product = new Product();
$product->setName('Sample Product')
    ->setDescription('This is a test product')
    ->setType('SERVICE')
    ->setCategory('SOFTWARE');

try {
    $product->create($apiContext);
    $productId = $product->getId(); // Save this ID to create a plan
} catch (Exception $ex) {
    // Handle exception
}

Create a Subscription Plan

• Plans are associated with products and define the billing frequency, intervals, pricing, and other subscription details.

 

• Create a plan and set the appropriated properties, linking it to the created product.

use PayPal\Api\Plan;
use PayPal\Api\PaymentDefinition;

$plan = new Plan();
$plan->setName('Sample Plan')
    ->setDescription('This is a test plan')
    ->setType('FIXED')
    ->setProductId($productId);

$paymentDefinition = new PaymentDefinition();
$paymentDefinition->setName('Regular Payments')
    ->setType('REGULAR')
    ->setFrequency('MONTH')
    ->setFrequencyInterval('1')
    ->setAmount(new Currency(['value' => 10, 'currency' => 'USD']));

$plan->setPaymentDefinitions([$paymentDefinition]);

try {
    $plan->create($apiContext);
    $planId = $plan->getId();
} catch (Exception $ex) {
    // Handle exception
}

Activate the Subscription Plan

• A new plan is created in an INACTIVE state. You must activate it before creating subscriptions.

 

• Use the `Patch` object to change its state to ACTIVE.

use PayPal\Api\Patch;
use PayPal\Api\PatchRequest;
use PayPal\Common\PayPalModel;

$patch = new Patch();
$patch->setOp('replace')
    ->setPath('/')
    ->setValue(new PayPalModel('{"state":"ACTIVE"}'));

$patchRequest = new PatchRequest();
$patchRequest->addPatch($patch);

try {
    $plan->update($patchRequest, $apiContext);
    $plan = Plan::get($planId, $apiContext); // Fetch the updated plan to confirm activation
} catch (Exception $ex) {
    // Handle exception
}

Create a Subscription

• With an ACTIVE plan, you can now create subscriptions for your customers.

 

• Collect payment details from the user and create a new subscription using the plan ID.

use PayPal\Api\Agreement;
use PayPal\Api\Payer;

$agreement = new Agreement();
$agreement->setName('Sample Agreement')
    ->setDescription('This is a test agreement')
    ->setStartDate('2023-12-01T00:00:00Z')
    ->setPlan(['id' => $planId]);

$payer = new Payer();
$payer->setPaymentMethod('paypal');

$agreement->setPayer($payer);

try {
    $agreement->create($apiContext);

    $approvalUrl = $agreement->getApprovalLink();
    // Redirect the user to $approvalUrl to approve the subscription
} catch (Exception $ex) {
    // Handle exception
}

Execute the Subscription

• Once the user approves the subscription, execute the agreement to begin billing.

 

• Use the token returned in the approval process to complete the subscription setup.

if (isset($_GET['success']) && $_GET['success'] === 'true') {
    $token = $_GET['token'];

    $agreement = new Agreement();
    try {
        $agreement->execute($token, $apiContext);
        $agreementDetails = Agreement::get($agreement->getId(), $apiContext);
        // Subscription is now active
    } catch (Exception $ex) {
        // Handle exception
    }
}

Handle Webhooks

• Set up webhooks to automatically handle events like subscription renewals, payments, or cancellations.

 

• Ensure your server handles these events securely by verifying the payload from PayPal.

// Retrieve the request's body and check whether it's an event from PayPal.
$bodyReceived = file_get_contents('php://input');
$headers = getallheaders();
$sigHeader = $headers['Paypal-Transmission-Sig'];

// Validate the webhook event
$webhookEvent = new \PayPal\Api\WebhookEvent();
try {
    $webhookEvent->verify($sigHeader, $bodyReceived, $apiContext);
    // Handle the event based on its type (e.g., PAYMENT.SALE.COMPLETED)
} catch (Exception $ex) {
    // Handle exception
}

Conclusion

• Using PayPal's REST API for managing subscription billing can automate the invoicing process for your services, streamline customer management, and enhance overall user experience.

 

• While setting up subscriptions is straightforward, always ensure you handle user data securely and in compliance with the necessary data protection laws.