Using PayPal

PayPal REST APIs Integration

API credentials are essential for authenticating your Ubersmith application with PayPal's servers, allowing it to securely communicate and process payments. Follow the steps outlined in this guide to acquire and utilize API credentials effectively within your Ubersmith integration with the PayPal application.

Prerequisites

• A PayPal business account
• An Ubersmith Application

PayPal

Obtaining API Credentials
To obtain API credentials for PayPal integration, follow these steps:

1. Log in to Your PayPal Business Account
   Sign in to your PayPal Business account using your credentials.
   
   
2. Navigate to Developer Dashboard
   
   Proceed to the PayPal Developer Dashboard, which offers tools and resources for integrating PayPal into your applications.
   
   
3. Create a REST API App
   In the Developer Dashboard, create a new REST API app by clicking on the "My Apps & Credentials" tab and then selecting "Create App." Provide a name for your app (Example: Ubersmith) and select the appropriate sandbox (for testing) or live (production) environment.
   
   
4. Create a Webhook
   
   
   Configure webhooks to notify your Ubersmith application when certain events occur. To configure a webhook, define your webhook listener URL ([your_ubersmith_app_url]/ipn/paypal_webhook.php) and a list of events for which to listen (select All Events)
   
   
5. Retrieve Client ID and Secret Key
   
   Once your app is created, you'll be provided with a Client ID and a Secret Key. These credentials are used to authenticate your application with PayPal's servers.
   
   
6. Retrieve Account ID (Merchant ID) and Email Address
   
   
   
   To obtain your Account ID (Merchant ID) and Email Address from PayPal, please navigate to your account settings.
   Under the 'BUSINESS PROFILE' section, select 'Business Information' to find your Account ID (Merchant ID), and click on 'Account Owner Information' to locate your Email Address.

Sandbox vs. Live Credentials
PayPal provides separate sets of API credentials for sandbox (testing) and live (production) environments. Use sandbox credentials for testing, and switch to live credentials when deploying your application to production.

Ubersmith Application

Configuration
To configure PayPal API Credentials in your Ubersmith application, follow these steps:

1. Access the Payment Processing Options page 
   
   
2. Enable PayPal
   
   Locate the "PayPal" section under Payment Processing Options and check the box to enable it.
   
   
3. Provide API Information: Enter the following information obtained from the PayPal API:
   

   • Account ID: provide the Account ID obtained in step 6

   • Email Address: provide the Email obtained in step 6

   • API Client ID: provide the Client ID obtained in step 5

   • API Secret: provide the Secret key obtained in step 5

   • Webhook ID: provide the Webhook ID obtained in step 4

4. Additional Configuration:

   • Notification Email Address: Provide the email address that will receive the notifications from your Ubersmith application regarding PayPal activities

   • Notify unrecognized payments: Set it to "Yes" if you want to receive notifications about unrecognized payments.

   • Notify declined payments: Set it to "Yes" if you want to receive notifications about declined payments.

   • Notify pending payments: Set it to "Yes" if you want to receive notifications about pending payments.

   • Currency: Select the currency for PayPal transactions.

   • PayPal Mode: Choose between "Sandbox" for testing or "Live" for production. Ensure that the provided information corresponds to the selected mode.

What's Next?

Once your PayPal app is created and configured within your Ubersmith application, the following actions become available:

Client portal

• Pay invoices, orders, and quotes using their PayPal account.
• Pay invoices using a credit/debit card via PayPal. Note that the information of the credit/debit card will be processed only by PayPal and no data will be stored/processed in the Ubersmith application side.
• Create a subscription for one or more services.
• Cancel a subscription.

Admin Portal

• Create subscriptions for clients via both the UI and the API.
• Cancel or suspend subscriptions.
  
  

PayPal Integration for Ubersmith version 4.6.4 and earlier

Enabling PayPal Instant Payment Notification (IPN)

Ubersmith uses PayPal's Instant Payment Notification (IPN) system to stay informed of activity on your PayPal account. 

Applying Automatic PayPal Payments

PayPal payments are only automatically applied when the incoming payment email address matches the client’s email in Ubersmith. and the payment exactly matches the invoice amount. If these conditions are not me, the email address specified in the PayPal Notification Address configured in the Payment Processing page receives an email that the automatic payment did not receive and the payment is issued as an account credit. See Managing Invoices to apply the credit to the specific invoice.

Issuing PayPal Refunds

To process a refund for a PayPal payment, you have the option to automatically reverse the payment back to the client or to mark it as a manual refund. When you reverse the payment, Ubersmith connects to PayPal and directly immediately refunds the payment back to the client. Marking a manual refund only reverses the payment in Ubersmith, and returning any funds to the client needs to be done manually through PayPal.

Viewing Billing Agreement Pending Payments

Invoices paid with a PayPal billing agreement are marked as pending payments, until the payment clear. Ubersmith checks PayPal every hour to see if the payment has been processed. If several different forms of payment are used, the PayPal billing agreement amount is set aside as pending, and the rest of the invoice processes. If the payment does not clear within seven days, or the payment is denied for other reasons, the payment is deleted and the invoice balance is still due.