Integrate with your server

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

iOS

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:

NVP/SOAP

REST v1

REST v2

Note: If you're integrating for the first time, we recommend using the REST v2 server-side integration.

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.

Swift
Obj-C

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

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

Note: The CreateOrder callback invokes from the main thread. Ensure all server-side requests execute from a background thread.

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:

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

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

Enable shipping change

Billing Agreements

Note: The Billing Agreement feature is available on a limited use basis to select merchants for approved use cases. For more information, reach out to your PayPal account manager.

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

Swift
Obj-C

1let config = CheckoutConfig(
2    clientId: 'Client-ID',
3    createOrder: { action in
4      action.set(billingAgreementToken: 'BA-token')
5    },
6    onApprove: { approval in
7      print("Billing agreement token: (approval.data.billingToken)")
8    },
9    environment: .sandbox
10)
11Checkout.set(config: config)
12Checkout.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

Swift
Obj-C

1let config = CheckoutConfig(
2  clientId: <Client-ID>,
3  createOrder: { action in
4    action.set(orderId: <Order-ID>)
5  },
6  onApprove: { approval in
7    print("Order ID: (approval.data.payToken)")
8    print("Billing agreement token: (approval.data.billingToken)")
9  },
10  environment: .sandbox
11)
12Checkout.set(config: config)
13Checkout.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:

Store the billing agreement token securely on disk

Encrypt the billing agreement token when passing it from the SDK to another service.

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:

NVP/SOAP

REST v1

REST v2

Note: If you're integrating for the first time, we recommend using the REST v2 server-side integration.

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.

Kotlin
Java

1paymentButtonContainer.setup(
2  createOrder = CreateOrder { createOrderActions ->
3    // Retrieve your order ID from your server-side integration
4    val orderId: String
5    createOrderActions.set(orderId)
6  }
7)

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

Note: The CreateOrder callback invokes from the main thread. Ensure all server-side requests execute from a background thread.

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:

Kotlin
Java

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

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

Enable shipping changes

Billing Agreements

Note: The Billing Agreement feature is available on a limited use basis to select merchants for approved use cases. For more information, reach out to your PayPal account manager.

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

Kotlin
Java

1PayPalCheckout.registerCallbacks(
2  onApprove = OnApprove { approval ->
3      Log.d(TAG, "Billing agreement token ${approval.data.billingToken}")
4  },
5  onCancel = null,
6  onError = null
7)
8val billingToken = "BA-XXXXXXXXXXXX"
9PayPalCheckout.startCheckout(
10  CreateOrder { createOrderActions ->
11      createOrderActions.setBillingAgreementId(billingToken)
12  }
13)

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

Kotlin
Java

1PayPalCheckout.registerCallbacks(
2  onApprove = OnApprove { approval ->
3    Log.d(TAG, "Order ID: ${approval.data.orderId}")
4    Log.d(TAG, "Billing agreement token: ${approval.data.billingToken}")
5  },
6  onCancel = null,
7  onError = null
8)
9val orderId = "YOUR_ORDER_ID"
10PayPalCheckout.startCheckout(
11    CreateOrder { createOrderActions: CreateOrderActions ->
12        createOrderActions.set(orderId)
13    }
14)

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:

Store the billing agreement token securely on disk

Encrypt the billing agreement token when passing it from the SDK to another service.

Next Step

Setup Shipping Options

Integrate with your server

iOS

Create order server-sideServer provided Order ID

Know before you code

Launch the payment sheet

Capture or authorize an order

Test and go live

Next steps

Billing Agreements

Billing Agreements

Start checkout with a billing agreement token

1. Create a billing agreement token in your server

2. Pass the billing agreement token to the SDK

Start checkout with an order with billing agreement context

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

2. Pass the order ID to the SDK

Android

Create order server-side

Server provided Order ID

Know before you code

Launch the payment sheet

Capture or authorize an order

Sample code

Test and go live

Next steps

Billing Agreements

Billing Agreements

Start checkout with a billing agreement token

1. Create a billing agreement token in your server

2. Pass the billing agreement token to the SDK

Start checkout with an order with billing agreement context

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

2. Pass the order ID to the SDK

Next Step

Create order server-side
Server provided Order ID