PayPal

API Version

Minimum required API version: 1.2.0

Payment Methods

The following table lists all supported payment methods.

Currencies

See PayPal Currency Codes.

Requests

The following table lists all supported requests for ewallet-based transactions.

Use the bodybuilder to create a sample request body for each request type.

Setup Procedures

The following table lists the setup procedures that are specific to this provider.

Response Data

The response of a completed transaction request will include the following PayPal-specific data.

Integration Procedures

The following sections list the integration procedures that are specific to this provider.

Authenticating PaymentsOS with PayPal

By authenticating PaymentsOS with PayPal, you allow PaymentsOS to act on your behalf when transacting against PayPal.

To get started, create a business account with PayPal (if you do not already have one). For help in creating a business account in the PayPal sandbox environment, see how to Create a sandbox account.

Then open a browser and browse to one of the following URLs:

• For the PayPal sandbox environment: https://www.sandbox.paypal.com/signin/authorize?client_id=AaclA7DW4Uh2PwnB4pfpMi8bpv5XIKcTjUiwMhc6nX7cQ45NTH-d5a2sN-J6z9uDaMJ_5fbwiA-cJ1Fk&prompt=login&response_type=code&scope=https://api.paypal.com/v1/payments/.*&redirect_uri=https://api.paymentsos.com/callbacks/paypal/test/login

• For the PayPal live environment: https://www.paypal.com/signin/authorize?client_id=Ac5RX5_HRrPue7Je66u89wTkwurIR3BB0tx-emhpUOOv8OPzv-8LquxcgtazvUQtjLNul2xrTw1TgHuo&prompt=login&response_type=code&scope=https://api.paypal.com/v1/payments/.*&redirect_uri=https://api.paymentsos.com/callbacks/paypal/live/login

Your browser will display the PayPal login dialog. Login and follow the instructions on screen to authenticate PaymentsOS.

Implementing a PayPal Express Checkout Transaction Flow

PayPal Express Checkout allows customers to pay using any of the payment methods associated with their PayPal account, or as a guest if they do not have an account (Guest Checkout). A transaction flow with PayPal Express Checkout is not quite the same as that of card-based transactions, since:

• You do not need to create a token. Credit card details, for example, are stored with PayPal and customers choose to pay with their credit card as part of the PayPal Express Checkout experience.

• The transaction flow is always asynchronous. As part of the payment flow, you must redirect customers to the PayPal page on which they can approve the transaction and then handle the remainder of the flow accordingly.

The steps in the flow are as follows:

1. Create a Payment.

2. Implement a redirection flow. This involves invoking the Create Authorization API or Create Charge API, and redirecting customers to the PayPal page on which they can approve the transaction (we provide you with the PayPal site URL in the Redirection object of the authorization or charge response data.)

3. If you invoked a Create Authorization request, invoke a Create Capture request after the user approved the transaction.

After completing the flow, users will be redirected to your merchant_site_url on which you can display a payment completed message.

Implementing a PayPal Billing Agreement Transaction Flow

PayPal’s billing agreement is a reference to a customer’s preferred PayPal payment method.

When a customer wants to make a purchase on your site, you can choose to create a PayPal billing agreement between you and your customer. This allows you to charge your customer against that billing agreement in future transactions, so that your customer does not have to login to PayPal to select a preferred payment method and approve the transaction.

A billing agreement transaction flow is similar to the flow followed by card transactions, in that you must first create a token which you then use in a subsequent Authorization or Charge request. It differs, however, in that:

• The token represents a billing agreement, rather than a credit card.

• After invoking the Create Token request, you need to redirect the user to PayPal for approving the creation of the billing agreement. You will receive a token only after this approval has been granted. After you receive the token, you must store it in a customer object so that the token can be reused in future transactions.

Let’s lay it out in steps. Use the Bodybuilder to generate sample request bodies for each of the requests outlined below.

1. First invoke the Create Token request, passing in a token_type of billing_agreement and a vendor value of PayPal. From the response of the request, grab the redirection.url and redirect the user to PayPal for approving the creation of the billing agreement. Note that at this stage, the token will have a state of pending.

2. Once approval has been granted, the user will be redirected to the merchant_site_url you passed in the Create Token) request. Notice that PaymentsOS adds a payment_method_token parameter to the merchant_site_url. Here’s an example merchant_site_url:

  https://mysiteurl.com?status=Succeed&payment_method_token=4f281fb8-7a63-480c-a0a6-1224a6a087e4

3. Grab the token identifier from the payment_method_token parameter in the merchant_site_url. Then store it in a customer object, as explained in Saving the Token.

After you created a billing agreement (token) and stored it in a customer object, you can prompt users to use it in a next transaction. For more information, see how to Use the Saved Token to Accept a Payment.

Integrating with Mobile Apps

The procedures for integrating PaymentsOS with PayPal in a mobile app are similar to the ‘regular’ integration procedures. The main difference is in the manner in which you return users to your app after they complete the checkout flow.

Integrating with Android Apps

In Android apps, you must use a Chrome Custom Tab for presenting the checkout journey. Simply grab the redirection URL from the response of the Create Authorization or Create Charge request and open the URL in a Chrome Custom Tab.

After the user completes the payment on the PayPal site, we will redirect the user to the merchant_site_url that you passed in the Create Authorization or Create Charge request. To ensure that the user is redirected to a screen in your app (rather than to an external website), define a custom scheme and pass it as the merchant_site_url.

To get started, edit your Manifest.xml file and add an Intent Filter with a custom URL Scheme for the Activity that will handle PayPal payments:

<activity android:name=".CompletePayPalPaymentActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="com.merchant.merchantapp.paypalreturn"
            android:scheme="merchant" />
    </intent-filter>
</activity>

You can now pass the custom scheme as the merchant_site_url in the Create Authorization or Create Charge request. Here’s an example request body (truncated for brevity):

{
  "merchant_site_url": "merchant://com.merchant.merchantapp.paypalreturn://return", // Here's our custom scheme. Notice that we added a 'return' parameter.
  "payment_method": {
    "source_type": "ewallet",
    "type": "untokenized",
    "vendor": "paypal"
  }
  ...
}

As a last step, make sure to handle the custom URL scheme when loaded by the Chrome Custom Tab:

public class CompletePayPalPaymentActivity extends AppCompatActivity {
 @Override
 protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_complete_pay_pal_payment);
  List < String > params = getIntent().getData().getPathSegments();
  if (params.get(0).equals("return")) {
   // complete PayPal checkout
  } else {
   // cancel PayPal checkout
  }
 }
}

Integrating with iOS Apps

In iOS apps, you must use a Safari View Controller for presenting the checkout journey.

Opening the PayPal Approval Page

Simply grab the redirection URL from the response of the Create Authorization or Create Charge request and open the URL in a Safari View Controller (SVC):

// Create an instance of SFSafariViewController
var svc: SFSafariViewController!
// Pass the URL to SFSafariViewController
svc = SFSafariViewController(url: URL(string: url)!);
self.present(svc, animated: true, completion: nil);

To dismiss the SVC when a user clicks the Done button in the Safari View, implement the SFSafariViewControllerDelegate Protocol:

class ViewController: UIViewController, SFSafariViewControllerDelegate
{
...
}

Add svc.delegate = self before opening the url:

svc = SFSafariViewController(url: URL(string: url)!);
     svc.delegate = self
self.present(svc, animated: true, completion: nil);

Then add the delegate method to the ViewController:

class ViewController: UIViewController, SFSafariViewControllerDelegate
func safariViewControllerDidFinish(controller: SFSafariViewController)
{
    controller.dismissViewControllerAnimated(true, completion: nil)
}

Redirecting Users Back to your App

After the user completes the payment on the PayPal site, we will redirect the user to the merchant_site_url that you passed in the Create Authorization or Create Charge request. To ensure that the user is redirected to a screen in your app (rather than to an external website), define a custom URL type and pass it as the merchant_site_url.

To get started, register a URL type:

1. In XCode, click on your project in the Project Navigator and navigate to App Target > Info > URL Types.
2. Click [+] to add a new URL type.
3. Enter your Bundle ID as Identifier and Under URL Schemes, enter your app switch return URL scheme. This scheme must be unique. It can be the same Bundle ID (or any value starting with your app’s Bundle ID) and must be dedicated to payment app switch returns. For example, if the app bundle ID is com.your-company.Your-App, then your URL scheme could be com.your-company.Your-App.payments.

You can now pass the custom scheme as the merchant_site_url in the Create Authorization or Create Charge request. Here’s an example request body (truncated for brevity):

{
  "merchant_site_url": "com.your-company.Your-App.payments://success", // Here's our custom scheme. Notice that we added a 'success' parameter.
  "payment_method": {
    "source_type": "ewallet",
    "type": "untokenized",
    "vendor": "paypal"
  }
  ...
}

Now handle the opening of the custom URL in the Application Delegate. In the AppDelegate.swift class, implement the application method to extract the query parameter from the merchant_site_url that you passed in:

func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any]) -> Bool {
let urlComponents = NSURLComponents.init(url: url, resolvingAgainstBaseURL: false)
let items = (urlComponents?.queryItems)! as [NSURLQueryItem]
 if url.host == "success" {
 <Launch your storyboard on payment success>
}

As a last step, create a storyboard ID. Based on this ID, get the instance of corresponding controller and navigate to the same/new viewController.

if url.host == "success" {
    let mainStoryboardIpad : UIStoryboard = UIStoryboard(name: "Main", bundle: nil)
    let viewController : ViewController = mainStoryboardIpad.instantiateViewController(withIdentifier : "<your storyboard id>") as! ViewController
    self.window = UIWindow(frame: UIScreen.main.bounds) 
    self.window?.rootViewController = viewController 
    self.window?.makeKeyAndVisible()
    viewController.success(paymentId: (items.first?.value)!)
}