The 2017 Ionic Developer Survey Results are in!

PayPal

Improve this doc

PayPal plugin for Cordova/Ionic Applications

Repo: https://github.com/paypal/PayPal-Cordova-Plugin

Installation

  1. Install the Cordova and Ionic Native plugins:
    $ ionic cordova plugin add com.paypal.cordova.mobilesdk
    $ npm install --save @ionic-native/paypal
    
  2. Add this plugin to your app's module

Supported platforms

Usage

import { PayPal, PayPalPayment, PayPalConfiguration } from '@ionic-native/paypal';

constructor(private payPal: PayPal) { }

...


this.payPal.init({
  PayPalEnvironmentProduction: 'YOUR_PRODUCTION_CLIENT_ID',
  PayPalEnvironmentSandbox: 'YOUR_SANDBOX_CLIENT_ID'
}).then(() => {
  // Environments: PayPalEnvironmentNoNetwork, PayPalEnvironmentSandbox, PayPalEnvironmentProduction
  this.payPal.prepareToRender('PayPalEnvironmentSandbox', new PayPalConfiguration({
    // Only needed if you get an "Internal Service Error" after PayPal login!
    //payPalShippingAddressOption: 2 // PayPalShippingAddressOptionPayPal
  })).then(() => {
    let payment = new PayPalPayment('3.33', 'USD', 'Description', 'sale');
    this.payPal.renderSinglePaymentUI(payment).then(() => {
      // Successfully paid

      // Example sandbox response
      //
      // {
      //   "client": {
      //     "environment": "sandbox",
      //     "product_name": "PayPal iOS SDK",
      //     "paypal_sdk_version": "2.16.0",
      //     "platform": "iOS"
      //   },
      //   "response_type": "payment",
      //   "response": {
      //     "id": "PAY-1AB23456CD789012EF34GHIJ",
      //     "state": "approved",
      //     "create_time": "2016-10-03T13:33:33Z",
      //     "intent": "sale"
      //   }
      // }
    }, () => {
      // Error or render dialog closed without being successful
    });
  }, () => {
    // Error in configuration
  });
}, () => {
  // Error in initialization, maybe PayPal isn't supported or something else
});

Instance Members

version()

Retrieve the version of the PayPal iOS SDK library. Useful when contacting support.

Returns: Promise<string>

init(clientIdsForEnvironments:)

You must preconnect to PayPal to prepare the device for processing payments. This improves the user experience, by making the presentation of the UI faster. The preconnect is valid for a limited time, so the recommended time to preconnect is on page load.

Param Type Details
clientIdsForEnvironments: PayPalEnvironment

set of client ids for environments

Returns: Promise<any>

prepareToRender(environment:, configuration:)

You must preconnect to PayPal to prepare the device for processing payments. This improves the user experience, by making the presentation of the UI faster. The preconnect is valid for a limited time, so the recommended time to preconnect is on page load.

Param Type Details
environment: String

available options are "PayPalEnvironmentNoNetwork", "PayPalEnvironmentProduction" and "PayPalEnvironmentSandbox"

configuration: PayPalConfiguration

PayPalConfiguration object, for Future Payments merchantName, merchantPrivacyPolicyURL and merchantUserAgreementURL must be set be set

Returns: Promise<any>

renderSinglePaymentUI(payment)

Start PayPal UI to collect payment from the user. See https://developer.paypal.com/webapps/developer/docs/integration/mobile/ios-integration-guide/ for more documentation of the params.

Param Type Details
payment PayPalPayment

PayPalPayment object

Returns: Promise<any>

clientMetadataID()

Once a user has consented to future payments, when the user subsequently initiates a PayPal payment from their device to be completed by your server, PayPal uses a Correlation ID to verify that the payment is originating from a valid, user-consented device+application. This helps reduce fraud and decrease declines. This method MUST be called prior to initiating a pre-consented payment (a “future payment”) from a mobile device. Pass the result to your server, to include in the payment request sent to PayPal. Do not otherwise cache or store this value.

Returns: Promise<any>

renderFuturePaymentUI()

Please Read Docs on Future Payments at https://github.com/paypal/PayPal-iOS-SDK#future-payments

Returns: Promise<any>

renderProfileSharingUI(scopes)

Please Read Docs on Profile Sharing at https://github.com/paypal/PayPal-iOS-SDK#profile-sharing

Param Type Details
scopes Array<string>

scopes Set of requested scope-values. Accepted scopes are: openid, profile, address, email, phone, futurepayments and paypalattributes See https://developer.paypal.com/docs/integration/direct/identity/attributes/ for more details

Returns: Promise<any>

PayPalPayment

Instance Members

amount()

The amount of the payment.

currency()

The ISO 4217 currency for the payment.

shortDescription()

A short description of the payment.

intent()

“Sale” for an immediate payment.

bnCode()

Optional Build Notation code (“BN code”), obtained from partnerprogram@paypal.com, for your tracking purposes.

invoiceNumber()

Optional invoice number, for your tracking purposes. (up to 256 characters)

custom()

Optional text, for your tracking purposes. (up to 256 characters)

softDescriptor()

Optional text which will appear on the customer’s credit card statement. (up to 22 characters)

items()

Optional array of PayPalItem objects.

shippingAddress()

Optional customer shipping address, if your app wishes to provide this to the SDK.

details()

Optional PayPalPaymentDetails object

PayPalItem

Instance Members

name()

Name of the item. 127 characters max

quantity()

Number of units. 10 characters max.

price()

Unit price for this item 10 characters max.

currency()

ISO standard currency code.

sku()

The stock keeping unit for this item. 50 characters max (optional)

PayPalPaymentDetails

Instance Members

subtotal()

Sub-total (amount) of items being paid for. 10 characters max with support for 2 decimal places.

shipping()

Amount charged for shipping. 10 characters max with support for 2 decimal places.

tax()

Amount charged for tax. 10 characters max with support for 2 decimal places.

PayPalShippingAddress

Instance Members

recipientName()

Name of the recipient at this address. 50 characters max.

line1()

Line 1 of the address (e.g., Number, street, etc). 100 characters max.

line2()

Line 2 of the address (e.g., Suite, apt #, etc). 100 characters max. Optional.

city()

City name. 50 characters max.

state()

2-letter code for US states, and the equivalent for other countries. 100 characters max. Required in certain countries.

postalCode()

ZIP code or equivalent is usually required for countries that have them. 20 characters max. Required in certain countries.

countryCode()

2-letter country code. 2 characters max.

PayPalEnvironment

Param Type Details
PayPalEnvironmentProduction string
PayPalEnvironmentSandbox string

PayPalConfigurationOptions

Param Type Details
defaultUserEmail string

Will be overridden by email used in most recent PayPal login.

(optional)
defaultUserPhoneCountryCode string

Will be overridden by phone country code used in most recent PayPal login

(optional)
defaultUserPhoneNumber string

Will be overridden by phone number used in most recent PayPal login.

(optional)
merchantName string

Your company name, as it should be displayed to the user when requesting consent via a PayPalFuturePaymentViewController.

(optional)
merchantPrivacyPolicyURL string

URL of your company's privacy policy, which will be offered to the user when requesting consent via a PayPalFuturePaymentViewController.

(optional)
merchantUserAgreementURL string

URL of your company's user agreement, which will be offered to the user when requesting consent via a PayPalFuturePaymentViewController.

(optional)
acceptCreditCards boolean

If set to NO, the SDK will only support paying with PayPal, not with credit cards. This applies only to single payments (via PayPalPaymentViewController). Future payments (via PayPalFuturePaymentViewController) always use PayPal. Defaults to true

(optional)
payPalShippingAddressOption number

For single payments, options for the shipping address.

  • 0 - PayPalShippingAddressOptionNone: no shipping address applies.
  • 1 - PayPalShippingAddressOptionProvided: shipping address will be provided by your app, in the shippingAddress property of PayPalPayment.
  • 2 - PayPalShippingAddressOptionPayPal: user will choose from shipping addresses on file for their PayPal account.
  • 3 - PayPalShippingAddressOptionBoth: user will choose from the shipping address provided by your app, in the shippingAddress property of PayPalPayment, plus the shipping addresses on file for the user's PayPal account. Defaults to 0 (PayPalShippingAddressOptionNone).
(optional)
rememberUser boolean

If set to YES, then if the user pays via their PayPal account, the SDK will remember the user's PayPal username or phone number; if the user pays via their credit card, then the SDK will remember the PayPal Vault token representing the user's credit card.

If set to NO, then any previously-remembered username, phone number, or credit card token will be erased, and subsequent payment information will not be remembered.

Defaults to YES.

(optional)
languageOrLocale string

If not set, or if set to nil, defaults to the device's current language setting.

Can be specified as a language code ("en", "fr", "zh-Hans", etc.) or as a locale ("en_AU", "fr_FR", "zh-Hant_HK", etc.). If the library does not contain localized strings for a specified locale, then will fall back to the language. E.g., "es_CO" -> "es". If the library does not contain localized strings for a specified language, then will fall back to American English.

If you specify only a language code, and that code matches the device's currently preferred language, then the library will attempt to use the device's current region as well. E.g., specifying "en" on a device set to "English" and "United Kingdom" will result in "en_GB".

(optional)
disableBlurWhenBackgrounding boolean

Normally, the SDK blurs the screen when the app is backgrounded, to obscure credit card or PayPal account details in the iOS-saved screenshot. If your app already does its own blurring upon backgrounding, you might choose to disable this. Defaults to NO.

(optional)
presentingInPopover boolean

If you will present the SDK's view controller within a popover, then set this property to YES. Defaults to NO. (iOS only)

(optional)
forceDefaultsInSandbox boolean

Sandbox credentials can be difficult to type on a mobile device. Setting this flag to YES will cause the sandboxUserPassword and sandboxUserPin to always be pre-populated into login fields.

(optional)
sandboxUserPassword string

Password to use for sandbox if 'forceDefaultsInSandbox' is set.

(optional)
sandboxUserPin string

PIN to use for sandbox if 'forceDefaultsInSandbox' is set.

(optional)

API

Native

General