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.

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:

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.

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// 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 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.

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

To migrate to PaymentButtonContainer, follow these steps:

• Replace PayPalButton, PayPalCreditButton, and PayPalPayLaterButton references 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 PaymentButtonContainerDelegate section above.

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: