Steps to Connect to the PayPal API

PayPal is a well-known payment service that allows easy, immediate, and secure online payments. High encryption technologies make it possible to make financial transactions or online purchases on the site with just one click. Card details are automatically saved and protected from fraudsters, so buyers don't have to enter them every time.

Today, PayPal is a popular service in more than 200 countries, offers support for more than 25 currencies, and is regarded as the gold standard for e-commerce. This service can be used for any online store with so many integration options.

Tasks achievable with the PayPal API

• The PayPal API allows you to accept payments from customers on your website;
• It provides capabilities for handling disputes and resolving issues between buyers and sellers;
• You can process refunds or cancel unconfirmed transactions;
• You can use the API to check the status of payments;
• The PayPal API allows you to retrieve detailed information about each transaction, including the amount, date, etc.;
• You can check the balance on your account or users' accounts.

The PayPal API is flexible and multifunctional, making it suitable for integration into various businesses and platforms to improve user experience and simplify financial transactions.

Connecting to the PayPal API

PayPal provides two APIs: REST and IPN. We will focus on the REST API, which we will simply refer to as ‘API’. This API facilitates convenient interaction with necessary entities and uses the JSON data format for exchanging information. PayPal offers two environments: live and sandbox. To ensure the security of requests, PayPal uses OAuth 2.0 authentication. Therefore, to interact with the API, you need to obtain an access token. To obtain the token, you should send a POST request to the path "v1/oauth2/token" with the parameter "grant_type" having the value "client_credentials", and pass the "Authorization" header with the value "Basic ". base64_encode("$clientId:$secret").

The received token can be used to sign all subsequent requests within a certain time. The $clientId and $secret data can be obtained directly from the PayPal account. There you can also change the mode of operation of the application. Except for the access token request, all other requests can be sent in JSON format.

Usually, the obtained token is sufficient for processing payments, viewing payment history, and other operations. However, the default history is not available, and to use it, you need to enable the corresponding option in your PayPal account settings. In the test environment, the payment history is empty by default, and to work with existing payments, you need to create them.

For certain requests, an elevated level of protection is required, and to perform specific operations, such as processing a payment refund, an additional signature is necessary. To achieve this, you need to pass the "PayPal-Auth-Assertion" header with a value that is a concatenation of base64-encoded JSON strings obtained from the arrays ['alg' => 'none'] and ['iss' => $clientId, 'email' => $email]. The parameter $clientId was mentioned earlier, and $email represents the e-mail address of the PayPal user, registered on their account. It is essential to note that when using the "sandbox" environment, PayPal generates a test e-mail, so please exercise caution during testing operations.

Additionally, instead of using an e-mail in the second array, you can use 'payer_id' with the value of the user's payer_id account. It should also be noted that there must be a period between the two encrypted strings in the resulting string, which PayPal will use as a delimiter.

For example, in the PHP programming language, generating the second signature will look like this:

private function getPaypalAuthAssertion($email, $clientId) {
   $joseHeader = base64_encode(json_encode(['alg' => 'none']));
   $payload = base64_encode(json_encode([
        'iss' => $clientId,
        'email' => $email,
   ]));
   return $joseHeader . '.' . $payload;
}

For proper error handling, it is important to consider two types of situations: access errors that may occur when an attempt to obtain a token fails, and validation errors. Therefore, your system will require two mechanisms to handle errors with different formats.

Implementing PayPal webhooks

Webhooks are a mechanism that allows the PayPal API to send real-time event notifications to your server. With webhooks, your application can automatically receive information about various events related to your transactions and PayPal account, without the need to constantly poll the API for updates. When an event occurs, to which a webhook is attached, PayPal sends a POST request with event data to the URL on your server that you specified. Consequently, your server can respond to these notifications and perform necessary actions according to the event.

For example, you can use webhooks for the following scenarios:

• Upon receiving a notification of completed payment, you can update the order status in your system or provide the user access to your content or services;
• If a buyer requests a refund, you can receive a notification of the refund and update the transaction status in your system;
• When disputes or conflicts arise, you can receive notifications about them and take appropriate action.

To use webhooks, you need to follow these steps:

• Create an endpoint on your server (URL) where PayPal will send event notifications;
• You need to subscribe to specific events that you want to track, such as payment confirmation, refund, subscription cancellation, etc.;
• When creating a webhook, you must specify a webhook verification token to allow your server to verify the authenticity of notifications from PayPal;
• After setting up the webhook, it is recommended to test it in the sandbox environment to ensure that your server correctly handles the notifications.

PayPal provides detailed documentation on working with webhooks, including a list of supported events and data formats you will receive for each event. Make sure that your server handles notifications securely and reliably to avoid data loss or incorrect actions.

Asabix company has experience in connecting PayPal API and other services. If you need help or services with API connection, contact us in any convenient way or leave a request on the integration page of any complexity.