Launch The Paysheet
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.
Note: PaymentButtonContainer
does not support PayPal Credit and Pay Later. Those buttons will return as not eligible. No matter how you configure the PaymentButtonContainer
, you will only see 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.
- Swift
- Obj-C
1// Create custom configuration objects2let attributes = PaymentButtonAttributes(3 edges: .softEdges,4 size: .expanded,5 isEnabled: true6)7let payPalUIConfig = PayPalButtonUIConfiguration(8 color: .blue,9 label: nil,10 attributes: attributes11)12let payPalCreditUIConfig = PayPalCreditButtonUIConfiguration(13 color: .white,14 attributes: attributes15)16let payLaterUIConfig = PayLaterButtonUIConfiguration(17 color: .black,18 attributes: attributes19)20// Instantiate the container passing the configuration objects21let container = PaymentButtonContainer(22 payPalButtonUIConfiguration: payPalUIConfig,23 payPalCreditButtonUIConfiguration: payPalCreditUIConfig,24 payLaterButtonUIConfiguration: payLaterUIConfig,25)26// Display the container27view.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
.
- Swift
- Obj-C
1let container = PaymentButtonContainer(delegate: self)2container.createOrder = { action in3 print("Create order here from (action)")4}5container.onCancel = {6 print("Cancelled")7}8container.onError = { error in9 print("Failed with error: (error)")10}11container.onApproval = { approval in12 print("Got approval: (approval)")13}14container.onShippingChange = { change, action in15 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
andonFinish
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 thePaymentButtonContainer
view begins loading. - The
onFinish
callback is invoked when the eligibility network call has completed.
These callbacks can be implemented like so
- Swift
- Obj-C
1// MARK: - PaymentButtonContainerDelegate2 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 PaymentButtonFundingSource
available. 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.
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.
- Swift
- Obj-C
1func triggerPayPalCheckout() {2 Checkout.start(3 createOrder: { createOrderAction in4 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 in9 // Optionally use this closure to respond to the order approval10 }, onCancel: {11 // Optionally use this closure to respond to the user canceling the paysheet12 }, onError: { error in13 // Optionally use this closure to respond to the user experiencing an error in14 // the payment experience15 }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.
Note: PaymentButtonContainer
does not support PayPal Credit and Pay Later. Those buttons will return as not eligible. No matter how you configure the PaymentButtonContainer
, you will only see 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.
- Kotlin
- Java
1paymentButtonContainer.setPayPalButtonUi(2 paypalButtonUi = PayPalButtonUi(3 PayPalButtonColor.BLUE,4 PayPalButtonLabel.CHECKOUT,5 PaymentButtonAttributes(6 PaymentButtonShape.ROUNDED,7 PaymentButtonSize.LARGE,8 isEnabled = true9 )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
andonFinish
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 thePaymentButtonContainer
view begins loading. - The
onFinish
callback is invoked when the eligibility network call has completed.
These callbacks can be implemented like so:
- Kotlin
- 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.key10 val fundingEligibilityItem = it.value11 val eligibility = fundingEligibilityItem.eligible12 val reasons = fundingEligibilityItem.reasons13 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 FundingEligibilityState
contains 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)
Note: PayPalButton
, PayPalCreditButton
, and PayPalPayLaterButton
are deprecated in favor of PaymentButtonContainer
. This section is provided as a reference to those using previous versions.
Migrating to PaymentButtonContainer
- Replace
PayPalButton
,PayPalCreditButton
, andPayLaterButton
references withPaymentButtonContainer
in your layout.
Before
1<com.paypal.checkout.paymentbutton.PayPalButton2 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" />78<com.paypal.checkout.paymentbutton.PayPalCreditButton9 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" />1415<com.paypal.checkout.paymentbutton.PayLaterButton16 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.PaymentButtonContainer2 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 paymentButtonEligibilityStatusChanged
in Java, use the onLoading()
and onFinish()
callbacks provided by the PaymentButtonContainerViewState
for the PaymentButtonContainer
as detailed in the PaymentButtonContainerViewState
section above.
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
-
Register all callbacks to the
onCreate()
method of your activity (or to theonAttach()
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.Note: If the activity is destroyed or re-created, you must register the callbacks again.
- Kotlin
- 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 approved6 },7 onCancel = OnCancel {8 // Optional callback for when a buyer cancels the paysheet9 },10 onError = OnError { errorInfo ->11 // Optional error callback12 },13 onShippingChange = OnShippingChange { shippingChangeData, shippingChangeActions ->14 // Optional onShippingChange callback.15 }16 )17 setupButtons()18 }19}
- 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.
- Kotlin
- Java
1PayPalCheckout.startCheckout(2 CreateOrder { createOrderActions ->3 val order = OrderRequest(4 intent = OrderIntent.CAPTURE,5 appContext = AppContext(6 userAction = UserAction.PAY_NOW7 ),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
Register all callbacks in the ViewModel constructor.
Note: Don't reference UI objects in your callbacks that might get destroyed by Android.
- Kotlin
- Java
1class MyViewModel: ViewModel() {2 val _message = MutableLiveData<String>()3 val message: LiveData<String>4 get() =_message5 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}
- 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.
- Kotlin
- 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_NOW10 ),11 purchaseUnitList = items12 )13 createOrderActions.create(order)14 }15 )16 }17}