Skip to content

Installation

Install the iOS SDK library and start using PayPal payout components in your project.

Before you start

Make sure you meet the system requirements:

RequirementMinimum or notes
Xcode15.0 or later
iOS deployment target14.0 or later
Swift5.9+
UI frameworkSwiftUI (SDK UI is SwiftUI-based)

Step 1: Install the iOS SDK library

To install using Swift Package Manager:

  1. Open your Xcode project.
  2. Go to File > Add Package Dependencies....
  3. Enter the repository URL: https://github.com/PXP-IO/ios-components-sdk.git.
  4. Select a version rule (e.g., Up to Next Major Version).
  5. Click Add Package.
  6. Select the PXPCheckoutSDK library and add it to your app target.

Add only the PXPCheckoutSDK library to your app target. Don't add other products from the same package — dependencies such as Kount and PayPal are bundled inside PXPCheckoutSDK. Linking additional products can cause duplicate symbols and runtime crashes.

import PXPCheckoutSDK

Step 2: Get your API credentials

To initialise the SDK, you'll need to send authenticated requests to the PXP API.

To get your credentials:

  1. In the Unity Portal, go to Merchant setup > Merchant groups.
  2. Select a merchant group.
  3. Click the Inbound calls tab.
  4. Copy the Client ID in the top-right corner.
  5. Click New token.
  6. Choose a number of days before token expiry. For example, 30.
  7. Click Save to confirm. Your token is now created.
  8. Copy the token ID and token value. Make sure to keep these confidential to protect the integrity of your authentication process.

As best practice, we recommend regularly generating and implementing new tokens.

Step 3: Get the session data

Now that you have your credentials, you're ready to send an API request to the sessions endpoint. This allows you to retrieve the transaction session data from the back-end, so you can supply it when you initialise the SDK.

Our platform uses HMAC (Hash-based Message Authentication Code) with SHA256 for authentication to ensure secure communication and data integrity. This method involves creating a signature by hashing your request data with a secret key, which must then be included in the HTTP headers of your API request.

To create the HMAC signature, you need to prepare a string that includes four parts:

  • A timestamp, in Unix format. For example, 1754701373.

  • A unique request ID, in GUID format. For example, ce244054-b372-42c2-9102-f0d976db69f6.

  • The request path, which is api/v1/sessions.

  • The request body. For PayPal payouts, set transactionMethod.intent.paypal to Payout. For example:

    {
       "merchant": "MERCHANT-1",
       "site": "SITE-1",
       "sessionTimeout": 120,
       "merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
       "transactionMethod": {
         "intent": {
           "paypal": "Payout"
         }
       },
       "amounts": {
         "currencyCode": "USD",
         "transactionValue": 100
       },
       "allowTransaction": true
    }

Put these four parts together as one concatenated string with no separators: {timestamp}{requestId}{requestPath}{requestBody}. {requestBody} must be the exact JSON bytes you send in the POST body (typically minified, no extra whitespace). For example:

1754701373ce244054-b372-42c2-9102-f0d976db69f6api/v1/sessions{"merchant":"MERCHANT-1","site":"SITE-1","sessionTimeout":120,"merchantTransactionId":"0ce72cfd-014d-4256-a006-a56601b2ffc4","transactionMethod":{"intent":{"paypal":"Payout"}},"amounts":{"currencyCode":"USD","transactionValue":100},"allowTransaction":true}

Use your token value (secret) to HMAC-SHA256 this string. You can find your token ID in the Unity Portal. Here's an example of an hmacSignature after you've signed the data:

1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6

You can now put together your Authorization header. It follows this format: PXP-UST1 {tokenId}:{timestamp}:{hmacSignature}. For example:

PXP-UST1 9aac6071-38d0-4545-9d2f-15b936af6d7f:1754701373:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6

Lastly, send your request to the Sessions API. Include a request ID of your choice and your client ID from the Unity Portal.

Use the production host https://api-services.pxp.io/api/v1 or the sandbox host https://api-services.test.pxp.io/api/v1.

curl -i -X POST \
  'https://api-services.test.pxp.io/api/v1/sessions' \
  -H 'Authorization: PXP-UST1 9aac6071-38d0-4545-9d2f-15b936af6d7f:1754701373:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6' \
  -H 'X-Request-Id: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'X-Client-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -H 'Content-Type: application/json' \
  -d '{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "sessionTimeout": 120,
  "merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
  "transactionMethod": {
    "intent": {
      "paypal": "Payout"
    }
  },
  "amounts": {
    "currencyCode": "USD",
    "transactionValue": 100
  },
  "allowTransaction": true
}'

Body parameters

Use these fields in the Sessions API request body. Required fields are merchant, site, merchantTransactionId, amounts, and transactionMethod.

ParameterDescription
merchant
string (≤ 20 characters)
required
Your unique merchant identifier, as assigned by PXP. You can find it in the Unity Portal, by going to Merchant setup > Merchants and checking the Merchant ID column or by clicking on a merchant and checking the General information section.
site
string (≤ 20 characters)
required
Your unique site identifier, as assigned by PXP. You can find it in the Unity Portal, by going to Merchant setup > Sites and checking the Site ID column or by clicking on a site and checking the General information section.
merchantTransactionId
string (≤ 50 characters)
required
A unique identifier for this transaction.
sessionTimeout
integer (≥ 1)
The duration of the session, in minutes.
transactionMethod
object
required
Details about the transaction method.
transactionMethod.intent
object
required
Details about the intent for different payment methods.
transactionMethod.intent.paypal
string
The intent for PayPal. For PayPal payouts, set this to Payout. Possible values: Authorisation, Purchase, Payout.
amounts
object
required
Details about the transaction amount.
amounts.currencyCode
string (3 characters)
required
The currency code associated with the transaction, in ISO 4217 format. See Supported currencies.
amounts.transactionValue
number (≥ 0)
required
The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected currencyCode exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected currencyCode exponent (e.g., GBP 1.234), or if a decimal is supplied when the currencyCode of the exponent does not require it (e.g., JPY 1.0).
allowTransaction
boolean or null
Whether the transaction is allowed to proceed. If not provided, defaults to null (no decision made yet).

If your request is successful, you'll receive a 200 response containing the session data.

{
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "hmacKey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "encryptionKey": "k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z",
  "sessionExpiry": "2025-05-19T13:39:20.3843454Z",
  "allowedFundingTypes": {
    "wallets": {
      "paypal": {
        "allowedFundingOptions": [
          "paypal"
        ],
        "merchantId": "PayPalMerchant123"
      }
    }
  }
}

Response parameters

Map these response fields into your SDK SessionData. The Sessions API response always includes sessionId, hmacKey, encryptionKey, and sessionExpiry.

ParameterDescription
sessionId
string (UUID)
The unique identifier for the created session. Required for SDK initialisation.
hmacKey
string
The HMAC key generated for securing session communications. Required for SDK initialisation.
encryptionKey
string
A key used for encrypting sensitive session data during communication. Required for SDK initialisation.
sessionExpiry
string (date-time)
The timestamp indicating when the session will expire, in ISO 8601 format. Optional on the iOS SessionData model; the SDK doesn't use this field for payout flows.
allowedFundingTypes
object
Details about the funding types allowed for this session.
allowedFundingTypes.wallets
object
Details about the wallets allowed for this session.
allowedFundingTypes.wallets.paypal
object
The PayPal configuration settings.
allowedFundingTypes.wallets.paypal.allowedFundingOptions
array of strings
The list of allowed funding options for PayPal.
allowedFundingTypes.wallets.paypal.merchantId
string or null
The PayPal merchant identifier.

Step 4: Configure your iOS project

PayPal payout components don't require special Xcode capabilities. You don't need to register a custom URL scheme for the withdrawal flow.

For portal onboarding and PayPal Developer Dashboard setup, see Onboarding.

Step 5: Initialise the SDK and create components

To initialise the SDK, pass the session data from Step 3 into your iOS application, along with the environment, owner ID, merchant shopper ID, payout transaction data, and paypalConfig.

The following example initialises the SDK for a returning customer and creates the amount, receiver, and submission components:

import SwiftUI
import PXPCheckoutSDK

struct PayoutScreen: View {
    @State private var pxpCheckout: PxpCheckout?
    @State private var amountComponent: BaseComponent?
    @State private var receiverComponent: BaseComponent?
    @State private var submissionComponent: BaseComponent?
    @State private var isLoading = true
    @State private var errorMessage: String?

    var body: some View {
        VStack(spacing: 16) {
            if isLoading {
                ProgressView("Initialising payouts...")
            } else if let errorMessage {
                Text(errorMessage)
                    .foregroundColor(.red)
            } else {
                amountComponent?.buildContent()
                receiverComponent?.buildContent()
                submissionComponent?.buildContent()
            }
        }
        .padding()
        .task {
            await initialisePayoutSdk()
        }
    }

    private func initialisePayoutSdk() async {
        do {
            let sessionData = try await fetchSessionDataFromBackend()

            let transactionData = TransactionData(
                amount: Decimal(100.00),
                currency: "USD",
                entryType: .ecom,
                intent: TransactionIntentData(paypal: .payout),
                merchantTransactionId: UUID().uuidString,
                merchantTransactionDate: { Date() }
            )

            let paypalConfig = PayPalConfig(
                payout: PayPalPayoutConfig(
                    paypalWallet: PayPalWallet(
                        email: "customer@example.com",
                        payerId: "PAYERID123ABC",
                        proceedPayoutWithSdk: true
                    )
                )
            )

            let checkoutConfig = CheckoutConfig(
                environment: .test,
                session: sessionData,
                transactionData: transactionData,
                merchantShopperId: "customer-123",
                ownerType: "MerchantGroup",
                ownerId: "your-merchant-group-id",
                paypalConfig: paypalConfig
            )

            let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)

            let amountConfig = PayoutAmountComponentConfig(label: "Withdrawal Amount")
            let receiverConfig = PayPalPayoutReceiverComponentConfig(
                label: "PayPal Account",
                applyMask: true,
                showMaskToggle: true
            )
            let submissionConfig = PayoutSubmissionComponentConfig(
                submitText: "Withdraw with",
                onPrePayoutSubmit: {
                    PrePayoutSubmitResult(isApproved: true)
                },
                onPostPayout: { result in
                    // Handle successful payout
                },
                onError: { error in
                    guard let error = error as? BaseSdkException else { return }
                    // error.errorCode and error.errorMessage
                    showErrorDialog(error.errorMessage)
                }
            )

            let amount = try pxpCheckout.create(.payoutAmount, componentConfig: amountConfig)
            let receiver = try pxpCheckout.create(.paypalPayoutReceiver, componentConfig: receiverConfig)
            let submission = try pxpCheckout.create(.payoutSubmission, componentConfig: submissionConfig)

            await MainActor.run {
                self.pxpCheckout = pxpCheckout
                self.amountComponent = amount
                self.receiverComponent = receiver
                self.submissionComponent = submission
                self.isLoading = false
            }
        } catch let error as BaseSdkException {
            await MainActor.run {
                errorMessage = "\(error.errorCode): \(error.errorMessage)"
                isLoading = false
            }
        } catch {
            await MainActor.run {
                errorMessage = error.localizedDescription
                isLoading = false
            }
        }
    }

    private func fetchSessionDataFromBackend() async throws -> SessionData {
        // Call your backend. Your backend should call the PXP Sessions API
        // with intent.paypal set to "Payout". See Step 3.
        return SessionData(
            sessionId: "session-id-from-backend",
            hmacKey: "hmac-key-from-backend",
            encryptionKey: "encryption-key-from-backend",
            allowedFundingTypes: AllowedFundingType(
                wallets: Wallets(
                    paypal: Paypal(
                        allowedFundingOptions: ["paypal"],
                        merchantId: "paypal-merchant-123"
                    )
                )
            )
        )
    }

    private func showErrorDialog(_ message: String) {
        // Present your app's error UI
        print(message)
    }
}

Providing paypalWallet supplies the stored PayPal email and payer ID for the withdrawal components. On iOS, email has a maximum length of 127 characters and payer ID has a maximum length of 13 characters. See How it works and Withdrawal flow.

With proceedPayoutWithSdk set to true, the SDK executes the payout after onPrePayoutSubmit returns PrePayoutSubmitResult(isApproved: true). With proceedPayoutWithSdk set to false, the SDK calls onClick (if configured) and does not run onPrePayoutSubmit or execute the payout — your backend must call the payout API. Defaults to false.

Configuration parameters

Pass these values when you build CheckoutConfig:

ParameterDescription
environment
Environment
required
The environment type.

Possible values:
  • .test
  • .live
session
SessionData
required
Details about the payout session. Map sessionId, hmacKey, encryptionKey, and optional allowedFundingTypes from the Sessions API response (see Step 3). sessionExpiry is optional on SessionData and unused by the SDK for payouts.
transactionData
TransactionData
required
Details about the payout.
transactionData.amount
Decimal
required
The payout amount (e.g., Decimal(100.00)).
transactionData.currency
String
required
The currency code associated with the payout, in ISO 4217 format (e.g., "USD", "GBP", "EUR").
transactionData.entryType
EntryType
required
The entry type for the payout. For PayPal payouts, use .ecom.
transactionData.intent
TransactionIntentData
required
The transaction intents. For PayPal payouts, set paypal to .payout.
transactionData.intent.paypal
PayPalIntentType?
The intent for PayPal.

For payouts, use .payout.

Other possible values:
  • .authorisation
  • .purchase
transactionData.merchantTransactionId
String
required
A unique identifier for this payout. Use UUID().uuidString.
transactionData.merchantTransactionDate
() -> Date
required
A closure that returns the transaction date. Use { Date() } for the current date.
merchantShopperId
String
required
A unique identifier for this shopper or customer.
ownerId
String
required
The identifier of the owner related to the ownerType. Get this from the Unity Portal.
ownerType
String?
The type of owner. For merchant-group credentials, use "MerchantGroup".
paypalConfig
PayPalConfig?
PayPal-specific configuration. Required for PayPal payout transactions. Set payout.paypalWallet with email, payerId, and proceedPayoutWithSdk. See How it works.
paypalConfig.payout
PayPalPayoutConfig?
The payout-specific settings.
paypalConfig.payout.paypalWallet
PayPalWallet?
The stored PayPal wallet details for the withdrawal flow (email and payerId). Email maximum length is 127 characters. Payer ID maximum length is 13 characters.
paypalConfig.payout.paypalWallet.proceedPayoutWithSdk
Bool
When true, the SDK executes the payout after onPrePayoutSubmit approves it. When false, the SDK calls onClick (if configured) and doesn't run onPrePayoutSubmit or execute the payout. Your backend must call the payout API. Defaults to false.
locale
String?
Optional locale for UI localisation (e.g., "en-US", "es-ES").
localisation
Localisation?
Optional string overrides for component text.
kountDisabled
Bool
Whether to disable the Kount fraud detection service. Defaults to false (fraud detection enabled).
onGetShopper
(() async -> TransactionShopper?)?
Optional async callback that returns shopper information.
analyticsEvent
((BaseAnalyticsEvent) -> Void)?
Optional callback to receive analytics events from the SDK.

What's next?

That's it for SDK installation. Next, follow the guide for PayPal payouts, and see Error handling for payout error codes and callbacks.