Launch The Paysheet

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.

// Create custom configuration objects
let attributes = PaymentButtonAttributes(
    edges: .softEdges,
    size: .expanded,
    isEnabled: true
)
let payPalUIConfig = PayPalButtonUIConfiguration(
    color: .blue,
    label: nil,
    attributes: attributes
)
let payPalCreditUIConfig = PayPalCreditButtonUIConfiguration(
    color: .white,
    attributes: attributes
)
let payLaterUIConfig = PayLaterButtonUIConfiguration(
    color: .black,
    attributes: attributes
)
// Instantiate the container passing the configuration objects
let container = PaymentButtonContainer(
    payPalButtonUIConfiguration: payPalUIConfig,
    payPalCreditButtonUIConfiguration: payPalCreditUIConfig,
    payLaterButtonUIConfiguration: payLaterUIConfig,
)
// Display the container
view.addSubview(container)
NSLayoutConstraint.activate(
    [
        container.centerYAnchor.constraint(equalTo: view.centerYAnchor),
        container.centerXAnchor.constraint(equalTo: view.centerXAnchor)
    ]
)

Attributes

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

PayPal button

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

PayPal Credit button

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

Pay Later button

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

Callbacks

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

let container = PaymentButtonContainer(delegate: self)
container.createOrder = { action in
    print("Create order here from (action)")
}
container.onCancel = {
    print("Cancelled")
}
container.onError = { error in
    print("Failed with error: (error)")
}
container.onApproval = { approval in
    print("Got approval: (approval)")
}
container.onShippingChange = { change, action in
    print("Shipping changed: (change) (action)")
}

Delegate functions

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

These callbacks can be implemented like so

// MARK: - PaymentButtonContainerDelegate
    func onLoading() {
        print("PaymentButtonContainer is loading...")
    }
    func onFinish(fundingEligibilityState: PaymentFundingEligibilityState?) {
        print("PaymentButtonContainer finished loading")
    }

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:

PayPal button

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

Pay Later button

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

PayPal Credit button

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:

class CheckoutView: UIView, PaymentButtonDelegate {

    var payPalButton = PayPalButton()

    func configurePayPalButton() {
        payPalButton.delegate = self
    }

    func onButtonStart(_ button: PaymentButton) {
        // Invoked when the button is selected, before the checkout process begins.
    }

    func onButtonFinish(_ button: PaymentButton) {
        // Invoked when the checkout process has finished
    }

    func button(_ button: PaymentButton, changedEligibilityStatus status: PaymentButtonEligibilityStatus) {
        // Invoked when the eligibility status of the button has changed
    }
}

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:

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.

func triggerPayPalCheckout() {
    Checkout.start(
        createOrder: { createOrderAction in
            let amount = PurchaseUnit.Amount(currencyCode: .usd, value: "10.00")
            let purchaseUnit = PurchaseUnit(amount: amount)
            let order = OrderRequest(intent: .capture, purchaseUnits: [purchaseUnit])
            createOrderAction.create(order: order)
        }, onApprove: { approval in
            // Optionally use this closure to respond to the order approval
        }, onCancel: {
            // Optionally use this closure to respond to the user canceling the paysheet
        }, onError: { error in
            // Optionally use this closure to respond to the user experiencing an error in
            // the payment experience
        }
    )
}

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.

paymentButtonContainer.setPayPalButtonUi(
    paypalButtonUi = PayPalButtonUi(
        PayPalButtonColor.BLUE,
        PayPalButtonLabel.CHECKOUT,
        PaymentButtonAttributes(
            PaymentButtonShape.ROUNDED,
            PaymentButtonSize.LARGE,
            isEnabled =  true
        )
    )
)
paymentButtonContainer.setup(
    createOrder = CreateOrder { createOrderActions ->
        createOrderActions.create(OrderRequest())
    },
    onApprove = OnApprove { approval ->
        Log.d(TAG, "orderId: ${approval.data.orderId}")
    },
    onError = OnError { errorInfo ->
        Log.e(TAG, errorInfo.reason, errorInfo.error)
    },
    onCancel = OnCancel {
        Log.i(TAG, "cancelled")
    },
    onShippingChange = OnShippingChange { shippingChangeData, shippingChangeActions ->
        Log.i(TAG, "Shipping type change: ${shippingChangeData.shippingChangeType}")
    }
)

Payment Button Container View State

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

These callbacks can be implemented like so:

paymentButtonContainer.viewState = PaymentButtonContainerViewState.invoke(
    onLoading = {
        Log.d(TAG, "Loading")
    },
    onFinish = { fundingEligibilityState, exception ->
        fundingEligibilityState?.let { state ->
            state.paymentsButtonMap?.let { map ->
                map.entries.forEach {
                    val paymentFundingType = it.key
                    val fundingEligibilityItem = it.value
                    val eligibility = fundingEligibilityItem.eligible
                    val reasons = fundingEligibilityItem.reasons
                    val eligibilityStatus = if (eligibility)
                            "is eligible" else "is not eligible"
                    Log.d(TAG,
                        "$paymentFundingType $eligibilityStatus. $reasons"
                    )
                }
            }
        }
        exception?.let { e ->
            Log.e(TAG, "Error", e)
        }
    }
)

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

Before

<com.paypal.checkout.paymentbutton.PayPalButton
    android:id="@+id/payPalButton"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginTop="@dimen/margin_16x"
    android:tag="PayPal" />

<com.paypal.checkout.paymentbutton.PayPalCreditButton
    android:id="@+id/payPalCreditButton"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginTop="@dimen/margin_16x"
    android:tag="PayPal Credit" />

<com.paypal.checkout.paymentbutton.PayLaterButton
    android:id="@+id/payLaterButton"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginTop="@dimen/margin_16x"
    android:tag="Pay Later" />

After

<com.paypal.checkout.paymentbutton.PaymentButtonContainer
    android:id="@+id/payment_button_container"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:pay_later_button_color="silver"
    app:pay_later_button_enabled="true"
    app:pay_later_button_shape="pill"
    app:pay_later_button_size="medium"
    app:paypal_button_color="silver"
    app:paypal_button_enabled="true"
    app:paypal_button_label="pay"
    app:paypal_button_shape="rectangle"
    app:paypal_button_size="large"
    app:paypal_credit_button_color="black"
    app:paypal_credit_button_enabled="true"
    app:paypal_credit_button_shape="rounded"
    app:paypal_credit_button_size="small" />

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

Before

payPalButton.setup()
payLaterButton.setup()
payPalCreditButton.setup()

After

paymentButtonContainer.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:

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:

val paymentButton: PaymentButton //...
// Functional
paymentButton.onEligibilityStatusChanged = { buttonEligibilityStatus: PaymentButtonEligibilityStatus ->
    Log.i("PaymentButtonEligibility", "eligibility: $buttonEligibilityStatus")
}
// Non-functional
paymentButton.paymentButtonEligibilityStatusChanged = object : PaymentButtonEligibilityStatusChanged {
    override fun onPaymentButtonEligibilityStatusChanged(paymentButtonEligibilityStatus: PaymentButtonEligibilityStatus) {
        Log.i("PaymentButtonEligibility", "$paymentButton : $paymentButtonEligibilityStatus")
    }
}

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:

PayPal button

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

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

class YourActivity: Activity {
    override fun onCreate(savedInstanceState: Bundle?) {
        PayPalCheckout.registerCallbacks(
            onApprove = OnApprove { approval ->
                // Optional callback for when an order is approved
            },
            onCancel = OnCancel {
                // Optional callback for when a buyer cancels the paysheet
            },
            onError = OnError { errorInfo ->
                // Optional error callback
            },
            onShippingChange = OnShippingChange { shippingChangeData, shippingChangeActions ->
                // Optional onShippingChange callback.
            }
        )
        setupButtons()
    }
}

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

PayPalCheckout.startCheckout(
    CreateOrder { createOrderActions ->
        val order = OrderRequest(
            intent = OrderIntent.CAPTURE,
            appContext = AppContext(
                userAction = UserAction.PAY_NOW
            ),
            purchaseUnitList = listOf(
                PurchaseUnit(
                    amount = Amount(
                        currencyCode = CurrencyCode.USD,
                        value = "10.00"
                    )
                )
            )
        )
        createOrderActions.create(order)
    }
)

Launch the SDK from a ViewModel

class MyViewModel: ViewModel() {
    val _message = MutableLiveData<String>()
    val message: LiveData<String>
        get() =_message
    init {
        PayPalCheckout.registerCallbacks(
            onApprove = OnApprove { approval ->
                _message.value = "Order approved"
            },
            onCancel = OnCancel {
                _message.value = "Order cancelled"
            },
            onError = OnError { errorInfo ->
                _message.value = "Error creating order"
            }
        )
    }
}

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

class MyViewModel: ViewModel() {
    ...
    fun startCheckout(items: List<PurchaseUnit>) {
        PayPalCheckout.startCheckout(
            CreateOrder { createOrderActions ->
                val order = OrderRequest(
                    intent = OrderIntent.CAPTURE,
                    appContext = AppContext(
                        userAction = UserAction.PAY_NOW
                    ),
                    purchaseUnitList = items
                )
                createOrderActions.create(order)
            }
        )
    }
}

Next Step

Server-side integration