How to Accept Payments in an iOS App Using MPL

Important: Adaptive Payments is now a limited release product. It is restricted to select partners for approved use cases and should not be used for new integrations without guidance from PayPal.

Learn how to add a Pay with PayPal button to an iOS app by using the PayPal Mobile Payment Libraries (MPL).

Process overview

To integrate the MPL into an iOS app, you need to:

  1. Download the iOS Mobile Payments Library SDK from PayPal and include the necessary MPL components in your app.

  2. Obtain an AppID (for testing purposes, use the PayPal Sandbox AppID).

  3. Specify the PayPal environment you're addressing (for example, ENV_SANDBOX) and the business' PayPal Account as the receiver.

  4. Calculate the price of the item(s) or service to be purchased and input that value into your MPL call.

  5. Set the Payment Type (for example, PAYMENT_TYPE_SERVICE or PAYMENT_TYPE_PERSONAL).

  6. Make the payment call.

    When you call the MPL, the customer is presented with an in-app PayPal log in screen and the payment processing is completed within your app (there is no browser or webview involved).

  7. When the payment flow is complete, the MPL returns control to your app.

Note: For instructions on using the PayPal APIs, how to use the Sandbox for testing, and how to move your app into production, see Apps 101.

Do it

To integrate the MPL into an iOS app:

  1. Set up your sandbox environment.

    To test MPL calls, you need three sandbox accounts:

    • API caller, whose credentials your app uses to make the Pay call.
    • Sender, the entity making the payment.
    • Receiver, the entity receiving the payment.

    You'll also need an AppID to make MPL calls. For the PayPal Sandbox, the AppID is static:

    APP-80W284485P519543T
    
  2. Download the iOS Mobile Payment Libraries package from the PayPal SDK page.

  3. Add the library to your project, as follows:

    #import "PayPal.h"              // imports the PayPal library header file
                // PayPal.h includes the statement #import UIKit/UIKit.h
    
    @interface PaymentViewController : UIViewController
    PayPalPaymentDelegate {       // this class implements the PayPalPaymentDelegate protocol
    }
    
    -(void)payWithPayPal;           // called when the user clicks the "Pay with PayPal" button
    @end
    
  4. Add the necessary PayPal header files to your project.

    The iOS Mobile Payment Libraries package contains the following header files and static library file:

    PayPal.h
    PayPalAddress.h
    PayPalAdvancedPayment.h
    PayPalAmounts.h
    PayPalContext.h
    PayPalInvoiceData.h
    PayPalInvoiceItem.h
    PayPalPayment.h
    PayPalPreapprovalDetails.h
    PayPalReceiverAmounts.h
    PPReceiverPaymentDetails.h
    
    libPayPalMEP.a
    

    To add these files to your Xcode project:

    1. Open your Xcode project.
    2. CONTROL+Click your project, then select Add > Existing Files.
    3. Select the .h and .a files, and then click Add.
  5. Call initializeWithAppID to initialize the library.

    You can initialize the library on the main thread, or on a separate thread. When initializing the library, specify the environment. The default environment is the PayPal production servers.

    This snippet initializes the library on the main thread, and uses the test servers in the PayPal Sandbox:

    [PayPal initializeWithAppID:@"APP-80W284485P519543T" forEnvironment:ENV_SANDBOX];

  6. Generate a pay button using the getPayButton method.

    UIButton *button = [[PayPal getInstance]
    getPayButtonWithTarget:self
    andAction:@selector(payWithPayPal)
    andButtonType:BUTTON_278x43
    andButtonText:BUTTON_TEXT_PAY];
    
    [self.view addSubview:button];
    
  7. Add the checkout call to the pay button, using the payWithPayPal method, specifying parameters for the checkout.

    [ppMEP checkoutWithPayment:currentPayment];
    
  8. Add a delegate to handle the response returned by the library. The handler will call one of three types (paymentSuccess, paymentCancel, paymentFailed) based on the result.

    Here is a simple implementation of the PaypalPaymentDelegate method:

    //PayPalPaymentDelegate methods:
    
    //paymentSuccessWithKey:andStatus: is required. Record the payment status
    // as successful and perform associated bookkeeping. Make no UI updates.
    //
    //payKey is a string that uniquely identifies the transaction.
    //paymentStatus is an enum: STATUS_COMPLETED, STATUS_CREATED, or STATUS_OTHER
    - (void)paymentSuccessWithKey:
    (NSString *)payKey andStatus:
    (PayPalPaymentStatus)paymentStatus {
    status = PAYMENTSTATUS_SUCCESS;
    }
    
    //paymentFailedWithCorrelationID:andErrorCode:andErrorMessage:
    // Record the payment as failed and perform associated bookkeeping.
    // Make no UI updates.
    //
    //correlationID is a string that uniquely identifies to PayPal the failed transaction.
    //errorCode is generally (but not always) a numerical code associated with the error.
    //errorMessage is a human-readable string describing the error that occurred.
    - (void)paymentFailedWithCorrelationID:
    (NSString *)correlationID andErrorCode:
    (NSString *)errorCode andErrorMessage:
    (NSString *)errorMessage {
    status = PAYMENTSTATUS_FAILED;
    }
    
    //paymentCanceled is required. Record the payment as canceled by
    // the user and perform associated bookkeeping. No UI updates.
    - (void)paymentCanceled {
    status = PAYMENTSTATUS_CANCELED;
    }
    

    Here's a callback example:

    -(void)paymentSuccessWithKey:(NSString *)payKey
    andStatus:(PayPalPaymentStatus)paymentStatus;
    

Voilà! You've set up your first Mobile Payment Libraries calls.

Learn more

To continue learning about how PayPal works with iOS apps: