# Integrate with your server (/limited-release/paypal-mobile-checkout/server-integration)



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

## iOS [#ios]

## Create order server-sideServer provided Order ID [#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 [#know-before-you-code]

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

* [NVP/SOAP](/api/nvp-soap/)
* [REST v1](/api/deprecated/payments/v1)
* [REST v2](/api/orders/v2)

> **Note:** **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](/limited-release/paypal-mobile-checkout).

#### Launch the payment sheet [#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

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

#### Obj-C

```text lineNumbers
[PPCheckout setCreateOrderCallback:^(PPCCreateOrderAction *action) {
      // Retrieve order ID or EC-token from server-side integration
      [PPCCreateOrderAction setOrderID:"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.

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

#### Capture or authorize an order [#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`:

```javascript lineNumbers
[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 [#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 [#next-steps]

* [Enable shipping change](/limited-release/paypal-mobile-checkout/shipping-options/)

## Billing Agreements [#billing-agreements]

> **Note:** **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 [#billing-agreements-1]

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 [#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 [#1-create-a-billing-agreement-token-in-your-server]

See documentation for [creating a billing agreement token](/limited-release/reference-transactions/) for more details.

##### 2. Pass the billing agreement token to the SDK [#2-pass-the-billing-agreement-token-to-the-sdk]

#### Swift

```text lineNumbers
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)
```

#### Obj-C

```text lineNumbers
PPCheckoutConfig *config = [
    [PPCheckoutConfig alloc] initWithClientID:'Client-ID'
createOrder:^(PPCCreateOrderAction*action) {
      [action setWithBillingAgreementToken:'BA-token'];
    }
    onApprove:^(PPCApproval *approval) {
           NSLog(@"Billing agreement token:" %@, approval.data.billingToken);
    }
[PPCheckoutConfig environment:PPCEnvironmentSandbox];
[PPCheckout setConfig:config];
[PPCheckout startWithPresentingViewController:self];
];
```

#### Start checkout with an order with billing agreement context [#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 [#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](/limited-release/vault-payment-methods/orders-api/#vault-the-payment-method) for more details.

##### 2. Pass the order ID to the SDK [#2-pass-the-order-id-to-the-sdk]

#### Swift

```text lineNumbers
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)
```

#### Obj-C

```text lineNumbers
PPCheckoutConfig *config = [[PPCheckoutConfig alloc] initWithClientID:<Client-ID>
createOrder:^(PPCCreateOrderAction*action) {
  [action setWithOrderId:<Order-ID>];
}
onApprove:^(PPCApproval *approval) {
  NSLog(@"Order ID:" %@, approval.data.payToken);
  NSLog(@"Billing agreement token:" %@, approval.data.billingToken);
  }
  environment:PPCEnvironmentSandbox];
[PPCheckout setConfig:config];
[PPCheckout startWithPresentingViewController: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 [#android]

## Create order server-side [#create-order-server-side]

### Server provided Order ID [#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 [#know-before-you-code-1]

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

* [NVP/SOAP](/api/nvp-soap/)
* [REST v1](/api/deprecated/payments/v1)
* [REST v2](/api/orders/v2)

> **Note:** **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](/limited-release/paypal-mobile-checkout).

#### Launch the payment sheet [#launch-the-payment-sheet-1]

You can launch the payment sheet by passing a `CreateOrder` callback into the `setup`function 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

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

#### Java

```text lineNumbers
paymentButtonContainer.setup(
  createOrderActions -> {
    // Retrieve your order ID from your server-side integration
    String orderId;
    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.

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

#### Capture or authorize an order [#capture-or-authorize-an-order-1]

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 [#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

```text lineNumbers
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)
  }
)
```

#### Java

```text lineNumbers
paymentButtonContainer.setup(
  (OnApprove) approval -> {
    // Optional -- retrieve order details first
    yourAppsCheckoutRepository.getEC(approval.getData().getOrderId());
    // Send the order ID to your own endpoint to capture or authorize the order
    yourAppsCheckoutRepository.captureOrder(approval.getData().getOrderId());
  }
);
```

#### Test and go live [#test-and-go-live-1]

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

#### Next steps [#next-steps-1]

* [Enable shipping changes](/limited-release/paypal-mobile-checkout/shipping-options/)

## Billing Agreements [#billing-agreements-2]

> **Note:** **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 [#billing-agreements-3]

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 [#start-checkout-with-a-billing-agreement-token-1]

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 [#1-create-a-billing-agreement-token-in-your-server-1]

See documentation for [creating a billing agreement token](/limited-release/reference-transactions/) for more details.

##### 2. Pass the billing agreement token to the SDK [#2-pass-the-billing-agreement-token-to-the-sdk-1]

#### Kotlin

```text lineNumbers
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)
  }
)
```

#### Java

```text lineNumbers
PayPalCheckout.registerCallbacks(approval ->
  Log.d(TAG, "Billing agreement token " + approval.getData().getBillingToken()),
  null, null
);
String billingToken = "BA-XXXXXXXXXXXX";
PayPalCheckout.startCheckout(createOrderActions ->
  createOrderActions.setBillingAgreementId(billingToken)
);
```

#### Start checkout with an order with billing agreement context [#start-checkout-with-an-order-with-billing-agreement-context-1]

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 [#1-create-an-order-id-with-billing-agreement-context-in-your-server-1]

Refer to the `Vault PayPal` section in the documentation for [vaulting with the Orders API](/limited-release/vault-payment-methods/orders-api/#vault-the-payment-method) for more details.

##### 2. Pass the order ID to the SDK [#2-pass-the-order-id-to-the-sdk-1]

#### Kotlin

```text lineNumbers
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)
    }
)
```

#### Java

```text lineNumbers
PayPalCheckout.registerCallbacks(
  approval -> {
      Log.d(TAG, "Order ID: " + approval.getData().getOrderId());
      Log.d(TAG, "Billing agreement token: "+ approval.getData().getBillingToken());
  },
  null, null);
String orderId = "YOUR_ORDER_ID";
PayPalCheckout.startCheckout(
  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:

* Store the billing agreement token securely on disk
* Encrypt the billing agreement token when passing it from the SDK to another service.

## Next Step [#next-step]

[Setup Shipping Options](/limited-release/paypal-mobile-checkout/shipping-options/)