Launch The Paysheet

SDK

Last updated: Feb 6th, 9:34am

Follow these steps to add payment buttons to your app or programmatically start the SDK

iOS

Payment Buttons

PaymentButtonContainer

The PaymentButtonContainer is responsible for displaying the payment buttons. This container can display three different buttons: the PayPal button, the PayPal Credit button, and the Pay Later button. By default the PaymentButtonContainer displays the PayPal button.

The PaymentButtonContainer provides the callbacks needed to integrate with the native checkout experience: CreateOrder, OnApprove, OnError, OnCancel, and OnShippingChange.

Customize the buttons

Each button type has a corresponding configuration object. To customize the buttons' appearance, you can instantiate PayPalButtonUIConfiguration, PayPalCreditButtonUIConfiguration, and PayLaterButtonUIConfiguration objects with custom parameters. Finally, you instantiate the PaymentButtonContainer passing in these configuration instances. If you don't pass any configuration objects to the PaymentButtonContainer initializer, it will use default configuration values.

  1. Swift
  2. Obj-C
1// Create custom configuration objects
2let attributes = PaymentButtonAttributes(
3 edges: .softEdges,
4 size: .expanded,
5 isEnabled: true
6)
7let payPalUIConfig = PayPalButtonUIConfiguration(
8 color: .blue,
9 label: nil,
10 attributes: attributes
11)
12let payPalCreditUIConfig = PayPalCreditButtonUIConfiguration(
13 color: .white,
14 attributes: attributes
15)
16let payLaterUIConfig = PayLaterButtonUIConfiguration(
17 color: .black,
18 attributes: attributes
19)
20// Instantiate the container passing the configuration objects
21let container = PaymentButtonContainer(
22 payPalButtonUIConfiguration: payPalUIConfig,
23 payPalCreditButtonUIConfiguration: payPalCreditUIConfig,
24 payLaterButtonUIConfiguration: payLaterUIConfig,
25)
26// Display the container
27view.addSubview(container)
28NSLayoutConstraint.activate(
29 [
30 container.centerYAnchor.constraint(equalTo: view.centerYAnchor),
31 container.centerXAnchor.constraint(equalTo: view.centerXAnchor)
32 ]
33)

Attributes

The PaymentButtonAttributes class contains the three properties that are common to all button types:

Property Description
edges Overrides the shape of the button. The default value is softEdges, but you can also set it to hardEdges or rounded.
size Adjusts the size of the button. The default value is collapsed, but you can also set it to: expanded, full, or mini.
isEnabled Determines whether or not to show this button. If this button type is ineligible, this flag will be ignored and the button won't be showed.

PayPal button

You can customize the appearance of the PayPal button via the PayPalButtonUIConfiguration, which contains the following attributes:

Property Description
color Changes the background color of the button and adjusts the wordmark color to be visible. The default value is gold, but you can also set it to: white, black, silver, or blue.
label Adds a label next to the button logo. The default value is no label, but you can also set it to: checkout, buyNow, or payWith.
attributes The button attributes defined by PaymentButtonAttributes.

PayPal Credit button

You can customize the appearance of the PayPal Credit button via the PayPalCreditButtonUIConfiguration, which contains the following attributes:

Property Description
color Changes the background color of the button and adjusts the wordmark color to be visible. The default value is darkBlue, but you can also set it to: white or black.
attributes The button attributes defined by PaymentButtonAttributes.

Pay Later button

You can customize the appearance of the Pay Later button via the PayLaterButtonUIConfiguration, which contains the following attributes:

Property Description
color Changes the background color of the button and adjusts the wordmark color to be visible. The default value is gold, but you can also set it to: white, black, silver, or blue.
attributes The button attributes defined by PaymentButtonAttributes.

Callbacks

The PaymentButtonContainer provides the callbacks needed to integrate with the native checkout experience: createOrder, onApproval, onError, onCancel, and onShippingChange.

  1. Swift
  2. Obj-C
1let container = PaymentButtonContainer(delegate: self)
2container.createOrder = { action in
3 print("Create order here from (action)")
4}
5container.onCancel = {
6 print("Cancelled")
7}
8container.onError = { error in
9 print("Failed with error: (error)")
10}
11container.onApproval = { approval in
12 print("Got approval: (approval)")
13}
14container.onShippingChange = { change, action in
15 print("Shipping changed: (change) (action)")
16}

Delegate functions

You can also observe the view state of the PaymentButtonContainer using the PaymentButtonContainerDelegate's onLoading() and onFinish() callbacks.

  • The onLoading and onFinish callbacks are invoked during the network call to check for buyer eligibility.
  • The onLoading callback is invoked at the start of the eligibility network call and the PaymentButtonContainer view begins loading.
  • The onFinish callback is invoked when the eligibility network call has completed.

These callbacks can be implemented like so

  1. Swift
  2. Obj-C
1// MARK: - PaymentButtonContainerDelegate
2 func onLoading() {
3 print("PaymentButtonContainer is loading...")
4 }
5 func onFinish(fundingEligibilityState: PaymentFundingEligibilityState?) {
6 print("PaymentButtonContainer finished loading")
7 }

The fundingEligibilityState contains a map of each PaymentButtonFundingSourceavailable. This includes the default PayPal payment funding type as well as PayPal Credit and Pay Later. A PaymentButtonFundingSource may not be eligible for the buyer to use. The payment button for the funding type will not be visible if the funding type is not eligible. If there's a failure in the request, the error object within fundingEligibilityState will contain the error.

PaymentButtonContainer does not support PayPal Credit and Pay Later. Those buttons will return as not eligible.

Payment Buttons (Deprecated)

Migrating to PaymentButtonContainer

To migrate to PaymentButtonContainer, follow these steps:

  • Replace PayPalButton, PayPalCreditButton, and PayPalPayLaterButtonreferences with PaymentButtonContainer.
  • Instead of setting up each payment button individually, you now only need to call PaymentButtonContainer initializer passing your custom configuration objects.
  • Instead of observing the eligibilityStatus for a payment button with onEligibilityStatusChanged, use the onLoading() and onFinish() callbacks provided by the PaymentButtonContainerDelegate for the PaymentButtonContainer as detailed in the PaymentButtonContainerDelegatesection above.

PayPal button

You can customize the appearance of the PayPalButton in the following ways: 

Property Description
color Changes the background color of the button and adjusts the wordmark color to be visible. The default value is gold, but you can also set it to: black, blue, silver, or white.
edges Overrides the shape of the button. The default value is softEdges, but you can also set it to hardEdges or rounded.
label Adds a label next to the button logo. The default value is no label, but you can also set it to: checkout, buyNow, or payWith.
size Adjusts the size of the button. The default value is collapsed, but you can also set it to: expanded, full, or mini.

Pay Later button

You can customize the appearance of the PayPalPayLaterButton in the following ways: 

Property Description
color Changes the background color of the button and adjusts the wordmark color to be visible. The default value is gold, but you can also set it to: black, blue, silver, or white.
edges Overrides the shape of the button. The default value is softEdges, but you can also set it to hardEdges or rounded.
size Adjusts the size of the button. The default value is collapsed, but you can also set it to: expanded, full, or mini.

PayPal Credit button

Property Description
color Changes the background color of the button and adjust the wordmark color to be visible. The default value is darkBlue, but you can also set it to black or white.
edges Overrides the shape of the button. The default value is softEdges, but you can also set it to hardEdges or rounded.
size Adjusts the size of the button. The default value is collapsed, but you can also set it to: expanded, full, or mini.

Payment button eligibility

To ensure buyers have an optimal experience, every PaymentButton adheres to strict eligibility requirements. Generally, the PayPalButton is always Eligible so it's safe to fallback for other buttons.

Eligibility updates are communicated through a delegate property of the PaymentButton. To receive these events, conform to PaymentButtonDelegate:

    1class CheckoutView: UIView, PaymentButtonDelegate {
    2
    3 var payPalButton = PayPalButton()
    4
    5 func configurePayPalButton() {
    6 payPalButton.delegate = self
    7 }
    8
    9 func onButtonStart(_ button: PaymentButton) {
    10 // Invoked when the button is selected, before the checkout process begins.
    11 }
    12
    13 func onButtonFinish(_ button: PaymentButton) {
    14 // Invoked when the checkout process has finished
    15 }
    16
    17 func button(_ button: PaymentButton, changedEligibilityStatus status: PaymentButtonEligibilityStatus) {
    18 // Invoked when the eligibility status of the button has changed
    19 }
    20}

    Both properties emit one value at a minimum, as the current value is emitted when either property is set. This is useful because the SDK retrieves funding eligibility requirements as soon as PayPalCheckout.setConfig is invoked. Usually, the funding eligibility retrieves by the time the PaymentButton renders. If funding eligibility isn't retrieved, the buttons are disabled and display a loading state.

    You can also retrieve the current status through the eligibilityStatus property. The following are possible values:

    Status Description
    eligible The button is visible and enabled, so buyers can interact with it.
    error The button is disabled and the visibility is hidden. This status only returns if there's an error retrieving the eligibility status.
    ineligible The button is disabled and the visibility is hidden.
    loading The button is disabled and the visibility is hidden.

    Custom UI

    If you use a custom UI to launch the PayPal Checkout experience, you need to programmatically start the PayPal Mobile Checkout SDK.

    Launch the SDK

    Instead of invoking the payment sheet by adding a button with the event closures set on the Checkout type, provide the closures directly to the SDK through Checkout.start.

    This sample code creates an order of a single item for $10.00 USD.

    1. Swift
    2. Obj-C
    1func triggerPayPalCheckout() {
    2 Checkout.start(
    3 createOrder: { createOrderAction in
    4 let amount = PurchaseUnit.Amount(currencyCode: .usd, value: "10.00")
    5 let purchaseUnit = PurchaseUnit(amount: amount)
    6 let order = OrderRequest(intent: .capture, purchaseUnits: [purchaseUnit])
    7 createOrderAction.create(order: order)
    8 }, onApprove: { approval in
    9 // Optionally use this closure to respond to the order approval
    10 }, onCancel: {
    11 // Optionally use this closure to respond to the user canceling the paysheet
    12 }, onError: { error in
    13 // Optionally use this closure to respond to the user experiencing an error in
    14 // the payment experience
    15 }
    16 )
    17}

    Android

    Payment Buttons

    PaymentButtonContainer

    The PaymentButtonContainer is responsible for displaying the payment buttons. This container can display three different buttons: the PayPal button, the PayPal Credit button, and the Pay Later button. By default the PaymentButtonContainer displays the PayPal button.

    The PaymentButtonContainer provides the callbacks needed to integrate with the native checkout experience: CreateOrder, OnApprove, OnError, OnCancel, and OnShippingChange.

    Customize the buttons

    For most integrations, the default PaymentButtonContainer is sufficient. However, if you want greater control over your buttons customization, you can customize the buttons. You can change the payment button's style. This includes the button's label, color, shape, and size. You can also enable or disable the payment button. The payment button will only be shown if the button is enabled and that funding option is eligible for the buyer.


    1. Kotlin
    2. Java
    1paymentButtonContainer.setPayPalButtonUi(
    2 paypalButtonUi = PayPalButtonUi(
    3 PayPalButtonColor.BLUE,
    4 PayPalButtonLabel.CHECKOUT,
    5 PaymentButtonAttributes(
    6 PaymentButtonShape.ROUNDED,
    7 PaymentButtonSize.LARGE,
    8 isEnabled = true
    9 )
    10 )
    11)
    12paymentButtonContainer.setup(
    13 createOrder = CreateOrder { createOrderActions ->
    14 createOrderActions.create(OrderRequest())
    15 },
    16 onApprove = OnApprove { approval ->
    17 Log.d(TAG, "orderId: ${approval.data.orderId}")
    18 },
    19 onError = OnError { errorInfo ->
    20 Log.e(TAG, errorInfo.reason, errorInfo.error)
    21 },
    22 onCancel = OnCancel {
    23 Log.i(TAG, "cancelled")
    24 },
    25 onShippingChange = OnShippingChange { shippingChangeData, shippingChangeActions ->
    26 Log.i(TAG, "Shipping type change: ${shippingChangeData.shippingChangeType}")
    27 }
    28)

    Payment Button Container View State

    You can also observe the view state of the PaymentButtonContainer using the PaymentButtonContainerViewState's onLoading() and onFinish() callbacks.

    • The onLoading and onFinish callbacks are invoked during the network call to check for buyer eligibility.
    • The onLoading callback is invoked at the start of the eligibility network call and the PaymentButtonContainer view begins loading.
    • The onFinish callback is invoked when the eligibility network call has completed.

    These callbacks can be implemented like so:

    1. Kotlin
    2. Java
    1paymentButtonContainer.viewState = PaymentButtonContainerViewState.invoke(
    2 onLoading = {
    3 Log.d(TAG, "Loading")
    4 },
    5 onFinish = { fundingEligibilityState, exception ->
    6 fundingEligibilityState?.let { state ->
    7 state.paymentsButtonMap?.let { map ->
    8 map.entries.forEach {
    9 val paymentFundingType = it.key
    10 val fundingEligibilityItem = it.value
    11 val eligibility = fundingEligibilityItem.eligible
    12 val reasons = fundingEligibilityItem.reasons
    13 val eligibilityStatus = if (eligibility)
    14 "is eligible" else "is not eligible"
    15 Log.d(TAG,
    16 "$paymentFundingType $eligibilityStatus. $reasons"
    17 )
    18 }
    19 }
    20 }
    21 exception?.let { e ->
    22 Log.e(TAG, "Error", e)
    23 }
    24 }
    25)

    If the call failed, then the Exception parameter will not be null. If the call succeeded, then the FundingEligibilityState parameter will not be null. The FundingEligibilityStatecontains a map of each PaymentFundingType available. This includes the default PayPal payment funding type as well as PayPal Credit and Pay Later. A PaymentFundingType may not be eligible for the buyer to use. The payment button for the funding type will not be visible if the funding type is not eligible.

    PaymentButtonContainer does not support PayPal Credit and Pay Later. Those buttons will return as not eligible.

    Payment Buttons (Deprecated)

    Migrating to PaymentButtonContainer

    • Replace PayPalButton, PayPalCreditButton, and PayLaterButton references with PaymentButtonContainer in your layout.

    Before

      1<com.paypal.checkout.paymentbutton.PayPalButton
      2 android:id="@+id/payPalButton"
      3 android:layout_width="match_parent"
      4 android:layout_height="wrap_content"
      5 android:layout_marginTop="@dimen/margin_16x"
      6 android:tag="PayPal" />
      7
      8<com.paypal.checkout.paymentbutton.PayPalCreditButton
      9 android:id="@+id/payPalCreditButton"
      10 android:layout_width="match_parent"
      11 android:layout_height="wrap_content"
      12 android:layout_marginTop="@dimen/margin_16x"
      13 android:tag="PayPal Credit" />
      14
      15<com.paypal.checkout.paymentbutton.PayLaterButton
      16 android:id="@+id/payLaterButton"
      17 android:layout_width="match_parent"
      18 android:layout_height="wrap_content"
      19 android:layout_marginTop="@dimen/margin_16x"
      20 android:tag="Pay Later" />

      After

        1<com.paypal.checkout.paymentbutton.PaymentButtonContainer
        2 android:id="@+id/payment_button_container"
        3 android:layout_width="match_parent"
        4 android:layout_height="wrap_content"
        5 app:pay_later_button_color="silver"
        6 app:pay_later_button_enabled="true"
        7 app:pay_later_button_shape="pill"
        8 app:pay_later_button_size="medium"
        9 app:paypal_button_color="silver"
        10 app:paypal_button_enabled="true"
        11 app:paypal_button_label="pay"
        12 app:paypal_button_shape="rectangle"
        13 app:paypal_button_size="large"
        14 app:paypal_credit_button_color="black"
        15 app:paypal_credit_button_enabled="true"
        16 app:paypal_credit_button_shape="rounded"
        17 app:paypal_credit_button_size="small" />

        Instead of setting up each payment button individually, you now only need to call PaymentButtonContainer.setup().

        Before

          1payPalButton.setup()
          2payLaterButton.setup()
          3payPalCreditButton.setup()

          After

            1paymentButtonContainer.setup()

            Instead of observing the eligibilityStatus for a payment button with onEligibilityStatusChanged in Kotlin or paymentButtonEligibilityStatusChangedin Java, use the onLoading() and onFinish() callbacks provided by the PaymentButtonContainerViewState for the PaymentButtonContainer as detailed in the PaymentButtonContainerViewState section above.

            Payment button

            The PaymentButton is the parent for all other buttons in the PayPal Mobile Checkout SDK for Android. The following attributes are available for use on every child button:

            Attribute Property Description
            payment_button_size size Adjusts the minimum height of the button. The default value is medium, but can also be set to: large or small.
            payment_button_shape shape Overrides the shape of the button. The default shape derives from the theme of your app, but you can set it to: pill, rectangle, or rounded.

            Payment button eligibility

            To ensure buyers have an optimal experience, every PaymentButton adheres to strict eligibility requirements. Generally, the PayPalButton is always Eligible so it's safe to fallback for other buttons. The button offers functional and non-functional properties to observe on the status. For example:

            1. Kotlin
            2. Java
            1val paymentButton: PaymentButton //...
            2// Functional
            3paymentButton.onEligibilityStatusChanged = { buttonEligibilityStatus: PaymentButtonEligibilityStatus ->
            4 Log.i("PaymentButtonEligibility", "eligibility: $buttonEligibilityStatus")
            5}
            6// Non-functional
            7paymentButton.paymentButtonEligibilityStatusChanged = object : PaymentButtonEligibilityStatusChanged {
            8 override fun onPaymentButtonEligibilityStatusChanged(paymentButtonEligibilityStatus: PaymentButtonEligibilityStatus) {
            9 Log.i("PaymentButtonEligibility", "$paymentButton : $paymentButtonEligibilityStatus")
            10 }
            11}

            Both properties emit one value at a minimum, as the current value is emitted when either property is set. This is useful because the SDK retrieves funding eligibility requirements as soon as PayPalCheckout.setConfig is invoked. Usually, the funding eligibility retrieves by the time the PaymentButton renders. If funding eligibility isn't retrieved, the buttons are disabled and display a loading state.

            You can also retrieve the current status through the eligibilityStatus property. The following are possible values:

            Status Description
            Eligible The button is visible and enabled, so buyers can interact with it.
            Error The button is disabled and the visibility is set hidden. This status only returns if there's an error retrieving the eligibility status.
            Ineligible The button is disabled and the visibility is set to hidden.
            Loading The button is visible, but disabled and displaying a loading indicator.

            PayPal button

            Attribute Property Description
            paypal_color color Changes the background color of the button and adjusts the wordmark color to be visible. The default value is gold, but you can also set it to: black, blue, silver, or white.
            paypal_label label Adds a label on the button itself. The default value is no label, which is set with paypal, but you can also set it to: checkout, buy_now, or pay.

            Pay Later button

            The PayLaterButton overrides the PayPalButton and always displays the Pay Later branding on the button as a label. You can't modify the label, but you can change the colorto any color available for the PayPalButton.

            PayPal Credit button

            Attribute Property Description
            paypal_credit_color color Changes the background color of the button and adjusts the wordmark to be visible. You can set it to dark_blue or black.

            Custom UI

            If you use a custom UI to launch the PayPal Checkout experience, you need to programmatically start the PayPal Mobile Checkout SDK.

            Launch the SDK from an activity

            1. Register all callbacks to the onCreate() method of your activity (or to the onAttach()method of your fragment). This enables you to listen to certain key events in the checkout process, such as order approvals, orders cancellations, or errors.


            1. Kotlin
            2. Java
            1class YourActivity: Activity {
            2 override fun onCreate(savedInstanceState: Bundle?) {
            3 PayPalCheckout.registerCallbacks(
            4 onApprove = OnApprove { approval ->
            5 // Optional callback for when an order is approved
            6 },
            7 onCancel = OnCancel {
            8 // Optional callback for when a buyer cancels the paysheet
            9 },
            10 onError = OnError { errorInfo ->
            11 // Optional error callback
            12 },
            13 onShippingChange = OnShippingChange { shippingChangeData, shippingChangeActions ->
            14 // Optional onShippingChange callback.
            15 }
            16 )
            17 setupButtons()
            18 }
            19}
            1. Launch the PayPal Checkout process by invoking PayPalCheckout.startCheckout(createOrderActions -> {}); when users select your custom UI button.

            This sample code creates an order of a single item for $10.00 USD.

            1. Kotlin
            2. Java
            1PayPalCheckout.startCheckout(
            2 CreateOrder { createOrderActions ->
            3 val order = OrderRequest(
            4 intent = OrderIntent.CAPTURE,
            5 appContext = AppContext(
            6 userAction = UserAction.PAY_NOW
            7 ),
            8 purchaseUnitList = listOf(
            9 PurchaseUnit(
            10 amount = Amount(
            11 currencyCode = CurrencyCode.USD,
            12 value = "10.00"
            13 )
            14 )
            15 )
            16 )
            17 createOrderActions.create(order)
            18 }
            19)

            Launch the SDK from a ViewModel

            1. Register all callbacks in the ViewModel constructor.

            1. Kotlin
            2. Java
            1class MyViewModel: ViewModel() {
            2 val _message = MutableLiveData<String>()
            3 val message: LiveData<String>
            4 get() =_message
            5 init {
            6 PayPalCheckout.registerCallbacks(
            7 onApprove = OnApprove { approval ->
            8 _message.value = "Order approved"
            9 },
            10 onCancel = OnCancel {
            11 _message.value = "Order cancelled"
            12 },
            13 onError = OnError { errorInfo ->
            14 _message.value = "Error creating order"
            15 }
            16 )
            17 }
            18}
            1. Launch the PayPal Checkout process by invoking a method in your ViewModel when users select your custom UI button.

            Our example receives a list of items to add to the order.

            1. Kotlin
            2. Java
            1class MyViewModel: ViewModel() {
            2 ...
            3 fun startCheckout(items: List<PurchaseUnit>) {
            4 PayPalCheckout.startCheckout(
            5 CreateOrder { createOrderActions ->
            6 val order = OrderRequest(
            7 intent = OrderIntent.CAPTURE,
            8 appContext = AppContext(
            9 userAction = UserAction.PAY_NOW
            10 ),
            11 purchaseUnitList = items
            12 )
            13 createOrderActions.create(order)
            14 }
            15 )
            16 }
            17}

            If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more