Integrate with your server

Use Orders created server-side and enable billing agreements during checkout.

iOS

Create order server-sideServer provided Order ID

You can integrate the PayPal Mobile Checkout SDK with your existing server-side PayPal integration. Server-side integrations offer greater flexibility and control than client-side integrations, enabling you to better ensure compatibility with your other integrations. A server-side integration also enables you to generate your own tokens.

Know before you code

Before integrating, determine which of the following server-side integrations you want to use:

You must complete the Initialize SDK instructions.

Launch the payment sheet

Launch the payment sheet by passing a CreateOrder callback into your Checkout.setCreateOrderCallback function. The only difference is that instead of creating an Order, you provide the order ID through the provided set function.

Checkout.setCreateOrderCallback { createOrderAction in
    // Retrieve order ID or EC-token from server-side integration
    createOrderAction.set(orderId: "EC-XXXXXXXXXXXXXXXXX")
}

Ensure the payment sheet launches as soon as the buyer selects the PaymentButton by making your server-side request from within the CreateOrder callback.

Capture or authorize an order

If you create an order through a server-side integration, you must capture or authorize the order using your own server-side integration.

This sample code uses yourAppsCheckoutRepository as an example. To capture or authorize an order, register the OnApprove callback through Checkout.setOnApproveCallback:

[PPCheckout setOnApproveCallback:^(PPCApproval *approval) {
    // Optional -- retrieve order details first
    [PPCheckoutRepository getEC approval.data.orderId]
    // Send the order ID to your own endpoint to capture or authorize the order
    [PPCheckoutRepository captureOrder approval.data.orderId]
}]

Test and go live

Use your client ID when adding the PayPal Mobile Checkout SDK to your app. Use your sandbox accounts when testing the SDK.

Next steps

Billing Agreements

Billing Agreements

You can enable billing agreements during checkout. Billing agreements create an agreement for a recurring PayPal payment for goods or services. After the buyers approve the transactions, you can use the billing agreement token returned by the SDK to create a billing agreement to be used for future payments.

Start checkout with a billing agreement token

You can start a checkout flow with a billing agreement token. Buyers will checkout without making a purchase. Future transactions for the billing agreement will use that funding instrument.

1. Create a billing agreement token in your server

See documentation for creating a billing agreement token for more details.

2. Pass the billing agreement token to the SDK

let config = CheckoutConfig(
    clientId: 'Client-ID',
    createOrder: { action in
      action.set(billingAgreementToken: 'BA-token')
    },
    onApprove: { approval in
      print("Billing agreement token: (approval.data.billingToken)")
    },
    environment: .sandbox
)
Checkout.set(config: config)
Checkout.start(presentingViewController: self)

Start checkout with an order with billing agreement context

Buyers can also checkout with a preferred funding instrument for the initial purchase. Future transactions for the billing agreement will use that funding instrument.

1. Create an order ID with billing agreement context in your server

Refer to the Vault PayPal section in the documentation for vaulting with the Orders API for more details.

2. Pass the order ID to the SDK

let config = CheckoutConfig(
  clientId: <Client-ID>,
  createOrder: { action in
    action.set(orderId: <Order-ID>)
  },
  onApprove: { approval in
    print("Order ID: (approval.data.payToken)")
    print("Billing agreement token: (approval.data.billingToken)")
  },
  environment: .sandbox
)
Checkout.set(config: config)
Checkout.start(presentingViewController: self)

Once the buyer checks out, the SDK will return a billing agreement token. The billing agreement token is considered sensitive data. We recommend to either:

Android

Create order server-side

Server provided Order ID

You can integrate the PayPal Mobile Checkout SDK with your existing server-side PayPal integration. Server-side integrations offer greater flexibility and control than client-side integrations, enabling you to better ensure compatibility with your other integrations. A server-side integration also enables you to generate your own tokens.

Know before you code

Before integrating, determine which of the following server-side integrations you want to use:

You must complete the Initialize SDK instructions.

Launch the payment sheet

You can launch the payment sheet by passing a CreateOrder callback into the setupfunction of your PaymentButtonContainer. The only difference is that instead of creating an Order, you generate the order ID from your own server-side integration and then provide the order ID through the provided set function.

paymentButtonContainer.setup(
  createOrder = CreateOrder { createOrderActions ->
    // Retrieve your order ID from your server-side integration
    val orderId: String
    createOrderActions.set(orderId)
  }
)

Ensure the payment sheet launches as soon as the buyer selects the PaymentButton by making your server-side request from within the CreateOrder callback.

Capture or authorize an order

If you create an order through a server-side integration, you must capture or authorize the order using your own server-side integration.

Sample code

This sample code uses yourAppsCheckoutRepository as an example. To capture or authorize an order register the OnApprove callback from the setup function of the PaymentButtonContainer:

paymentButtonContainer.setup(
  onApprove = OnApprove { approval ->
    // Optional -- retrieve order details first
    yourAppsCheckoutRepository.getEC(approval.data.orderId)
    // Send the order ID to your own endpoint to capture or authorize the order
    yourAppsCheckoutRepository.captureOrder(approval.data.orderId)
  }
)

Test and go live

Use your client ID when adding the PayPal Mobile Checkout SDK to your app. Use your sandbox accounts when testing the SDK.

Next steps

Billing Agreements

Billing Agreements

You can enable billing agreements during checkout. Billing agreements create an agreement for a recurring PayPal payment for goods or services. After the buyers approve the transactions, you can use the billing agreement token returned by the SDK to create a billing agreement to be used for future payments.

Start checkout with a billing agreement token

You can start a checkout flow with a billing agreement token. Buyers will checkout without making a purchase. Future transactions for the billing agreement will use that funding instrument.

1. Create a billing agreement token in your server

See documentation for creating a billing agreement token for more details.

2. Pass the billing agreement token to the SDK

PayPalCheckout.registerCallbacks(
  onApprove = OnApprove { approval ->
      Log.d(TAG, "Billing agreement token ${approval.data.billingToken}")
  },
  onCancel = null,
  onError = null
)
val billingToken = "BA-XXXXXXXXXXXX"
PayPalCheckout.startCheckout(
  CreateOrder { createOrderActions ->
      createOrderActions.setBillingAgreementId(billingToken)
  }
)

Start checkout with an order with billing agreement context

Buyers can also checkout with a preferred funding instrument for the initial purchase. Future transactions for the billing agreement will use that funding instrument.

1. Create an order ID with billing agreement context in your server

Refer to the Vault PayPal section in the documentation for vaulting with the Orders API for more details.

2. Pass the order ID to the SDK

PayPalCheckout.registerCallbacks(
  onApprove = OnApprove { approval ->
    Log.d(TAG, "Order ID: ${approval.data.orderId}")
    Log.d(TAG, "Billing agreement token: ${approval.data.billingToken}")
  },
  onCancel = null,
  onError = null
)
val orderId = "YOUR_ORDER_ID"
PayPalCheckout.startCheckout(
    CreateOrder { createOrderActions: CreateOrderActions ->
        createOrderActions.set(orderId)
    }
)

Once the buyer checks out, the SDK will return a billing agreement token. The billing agreement token is considered sensitive data. We recommend to either:

Next Step

Setup Shipping Options