PayPal

PayPal has some special integration requirements. Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications described below.

Specifications for eWallet-based Transactions

The following table lists the integration specifications for PayPal.

SpecificationsDetails
Minimum PaymentsOS API Version1.2.0
Requests
  • Authorize
  • Capture (including multiple/partial)
  • Charge
  • Void
  • Refund (including multiple/partial)
Limitations:
Multiple refunds can be made as long as the cumulative refunded amount does not exceed the original transaction value.
CurrenciesSee PayPal Currency Codes.
Payment Methods
  • PayPal Billing Agreement
  • PayPal Express Checkout

Configurations

The following table lists the configurations that are specific to PayPal.

ConfigurationRequired/Optional
In the PaymentsOS Control Center, configure the following credentials:
  • Merchant ID. This ID is listed in your PayPal account.
For your test credentials, login to your sandbox account. For your live credentials, login to your business account.
Required
In the PaymentsOS Control Center, register webhooks to be notified when a transaction changes its status.The payment flows for PayPal are asynchronous, which return responses with the pendingstatus.Required
Authenticate PaymentsOS with PayPal. For help, see Authenticating PaymentsOS with PayPal below.Required

Sample Requests

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

PayPal Fraud

If you’re using PayPal Fraud, contact your PayPal account representative to obtain the list of required fields that you need to pass in each request. These fields must be passed in the provider_specific_data.paypal.additional_details object of the Create Authorization or Create Charge request and must have the same name as the field name specified by PayPal, prefixed with stc_.

If you integrated the PayPal Billing Agreement payment method, then you must use PayPal Fraudnet. This means that all PayPal Fraudnet requirements must be met. For help, contact your PayPal account representative.

Response Data

The response of a completed transactions requests will include the following PayPal-specific data.

Request Attribute Name Description
Authorize, Charge additional_details.payer_id The ID of the payer.
Authorize, Charge additional_details.payer_status Whether the customer has a verified PayPal account. Either verified (Customer has a verified PayPal account) or unverified (Customer has an unverified PayPal account.)
Capture, Charge additional_details.processing_fee The processing fee that (as the merchant) paid for the transaction. In major currency units.
Refund additional_details.refund_from_processing_fee The processing fee returned to you following the refund to the customer. In major currency units.

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:

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.

Note

When implementing the redirection flow with PayPal, you do not need to configure an IPN (Instant Payment Notification ) URL. PaymentsOS passes the IPN URL to PayPal under the hood.

Implementing a PayPal Billing Agreement Transaction Flow

Enabling Reference Transactions

Reference transactions must be enabled in your PayPal account before you can execute a PayPal Billing Agreement transaction flow. Ask PayPal support to enable reference transactions in your PayPal account.

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

PayPal Fraud

Contact your PayPal account representative for help with integrating PayPal fraud in your mobile app.

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)!)
}

results matching ""

    No results matching ""