How to Integrate PayPal REST API for Online Payments

Before diving into the main content of the article below, let's go through the previously created articles on this blog.

We have already created some articles that explain the classic PayPal API known as PayPal Express Checkout, also referred to as NVP/SOAP API. Most of the previous articles were based on the same API version but used different libraries built by developers using PHP.

Follow this link: PayPal Payment Gateway for Business to scroll through those articles.

Let's get started with the PayPal REST API, which we will cover in the article below.

PayPal is a globally recognized payment gateway service that is compatible for businesses of all sizes, whether small or large, to accept online payments. It is known for its security, reliability, and reputation as a trusted payment gateway, making it one of the most trusted in the world.

I recently released a new, framework-agnostic library for PHP to handle the PayPal REST API. You can view it on GitHub and explore the features it offers to meet your needs.

Furthermore, if you require any additional features for the package and have the ability to submit a pull request following the provided coding standards, your contributions are welcome.

# Prerequisites

A good understanding of PHP, some basic knowledge of the Laravel framework, familiarity with Composer, and proficiency in PHP, MySQL databases, as well as having a working environment ready to run the project are prerequisites.

# Composer

{
    "require": {
        "sudiptpa/paypal-rest": "~3.0"
    }
}

To add the library to your project, use the Composer package manager.

Now, you can set up your routes for your application and create a controller where you'll place your application logic for initiating payments.

use Omnipay\Omnipay;

$gateway = Omnipay::create('PayPalRest_Rest');

$gateway->setClientId('xxxxxxxxxxx');
$gateway->setSecret('xxxxxxxxxxx');
$gateway->setTestMode('xxxxxxxxxxx');

You can initiate the library with the above code snippet, and you will now have access to the features within the library.

Now, let's outline the requirements for how the payment flow works:

• When a user visits the ecommerce website, they can add items to their cart and proceed to the checkout process, where they provide billing and shipping information. Afterward, they proceed to the payment gateway service.
• The library currently provides an option for direct payment capture. In this method, the user is required to make the payment immediately, and it will be captured instantly if their PayPal account has authorized the payment to be captured.
• After the user is redirected to PayPal, PayPal accepts data from the website, validates it, and creates an order on their platform. PayPal then returns the order with an ID and links to redirect users to their secure hosted platform for making payments, ensuring customer security.
• After PayPal authorizes everything as valid, it redirects the user back to the merchant's website with certain parameters. The previously provided order ID must be stored in association with the order, allowing the merchant to reference it when necessary to capture the payment for that specific order.
• When the user comes back to the website, the system verifies and confirms the successful payment capture.It then:
  
  - Sends a confirmation email to the customer.
  - Changes the order status to payment successful and ready for fulfillment.
  - Shows a message welcoming the user to review their order.

# Create Order

Here, the process involves creating the order on the PayPal platform, not on the website itself. The assumption is that the order, awaiting payment, has already been established on the website. Now, it's time to direct the user to the PayPal hosted platform to provide their payment details.

Below is the code snippet offered by the library.

<?php
use Omnipay\Common\CreditCard;

...

$payload = [
    'amount' => 20,
    'transactionId' => '1001',
    'transactionReference' => 'INV-1001',
    'currency' => 'AUD',
    'card' => new CreditCard([
        'shippingFirstName' => 'First Name',
        'shippingLastName' => 'Last Name',
        'email' => 'Email Address',
        'shippingPhone' => 'Phone Number',
        'shippingAddress1' => 'Street Address',
        'shippingAddress2' => 'House Number, Apt.',
        'shippingCity' => 'City, Home Town',
        'shippingState' => 'State, Province',
        'shippingPostcode' => 'Postal code',
        'shippingCountry' => 'AU',
    ]),
    'shippingType' => 'SHIPPING',
    'items' => [
        [
            'name' => 'Test Product 1',
            'description' => 'A sample description',
            'quantity' => 1,
            'price' => 20,
            'sku' => 'ITEM-CODE1',
            'category' => 'PHYSICAL_GOODS',
            'reference' => 'ITEM',
        ]
    ],
    'cancelUrl' => 'https://example.com/cancel/url',
    'returnUrl' => 'https://example.com/return/url',
];

$response = $gateway->purchase($payload)->send();

if ($response && $response->isSuccessful()) {
    $order->update(['paypal_order_id' => $response->getTransactionReference()]);

    if ($response->isRedirect()) {
        $response->redirect();
    }

    // do something else
}

// handle the failure

You can send multiple items, but the item reference indicates whether it relates to shipping, tax, discount, handling, insurance, or the order line item. Please review the enum class to see the supported item references.

# Capture

After returning from PayPal, you need to complete the payment capture process for the order.

$response = $gateway->completePurchase([
    'transactionReference' => $order->paypal_order_id,
])->send();

if ($response && $response->isSuccessful() && $response->isCaptured()) {
    // handle the successful payment
}

if ($response && $response->isFailure()) {
    // show error message
}

Furthermore, this library also enables sending tracking information to PayPal for the order using the capture ID it provides after a successful payment capture.

Integrating a webhook is a good practice to automatically validate whether the website order has been marked as paid or refunded. There may be times where the website fails to update the database in real-time when the payment capture occurs. In such cases, a webhook becomes crucial for managing the order status effectively.

Also Read:

Stripe Payment Gateway Integration with Laravel
PayPal Integration – Omnipay PayPal PHP Library
PayPal Instant Payment Notification (IPN) Handling

# Closing

Thank you for following the article up to the end. If you found it interesting, please consider sharing it with others who might also find it worthwhile.

In our next article, we'll explain about webhook verification and handling. We request you to keep visiting our website for more insightful articles like this one in the future.