Install the iOS SDK library and start using PayPal payout components in your project.
Make sure you meet the system requirements:
| Requirement | Minimum or notes |
|---|---|
| Xcode | 15.0 or later |
| iOS deployment target | 14.0 or later |
| Swift | 5.9+ |
| UI framework | SwiftUI (SDK UI is SwiftUI-based) |
To install using Swift Package Manager:
- Open your Xcode project.
- Go to File > Add Package Dependencies....
- Enter the repository URL:
https://github.com/PXP-IO/ios-components-sdk.git. - Select a version rule (e.g., Up to Next Major Version).
- Click Add Package.
- 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 PXPCheckoutSDKTo initialise the SDK, you'll need to send authenticated requests to the PXP API.
To get your credentials:
- In the Unity Portal, go to Merchant setup > Merchant groups.
- Select a merchant group.
- Click the Inbound calls tab.
- Copy the Client ID in the top-right corner.
- Click New token.
- Choose a number of days before token expiry. For example,
30. - Click Save to confirm. Your token is now created.
- 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.
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.paypaltoPayout. 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:
1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6You 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:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6Lastly, 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
}'Use these fields in the Sessions API request body. Required fields are merchant, site, merchantTransactionId, amounts, and transactionMethod.
| Parameter | Description |
|---|---|
merchantstring (≤ 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. |
sitestring (≤ 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. |
merchantTransactionIdstring (≤ 50 characters) required | A unique identifier for this transaction. |
sessionTimeoutinteger (≥ 1) | The duration of the session, in minutes. |
transactionMethodobject required | Details about the transaction method. |
transactionMethod.intentobject required | Details about the intent for different payment methods. |
transactionMethod.intent.paypalstring | The intent for PayPal. For PayPal payouts, set this to Payout. Possible values: Authorisation, Purchase, Payout. |
amountsobject required | Details about the transaction amount. |
amounts.currencyCodestring (3 characters) required | The currency code associated with the transaction, in ISO 4217 format. See Supported currencies. |
amounts.transactionValuenumber (≥ 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). |
allowTransactionboolean 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"
}
}
}
}Map these response fields into your SDK SessionData. The Sessions API response always includes sessionId, hmacKey, encryptionKey, and sessionExpiry.
| Parameter | Description |
|---|---|
sessionIdstring (UUID) | The unique identifier for the created session. Required for SDK initialisation. |
hmacKeystring | The HMAC key generated for securing session communications. Required for SDK initialisation. |
encryptionKeystring | A key used for encrypting sensitive session data during communication. Required for SDK initialisation. |
sessionExpirystring (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. |
allowedFundingTypesobject | Details about the funding types allowed for this session. |
allowedFundingTypes.walletsobject | Details about the wallets allowed for this session. |
allowedFundingTypes.wallets.paypalobject | The PayPal configuration settings. |
allowedFundingTypes.wallets.paypal.allowedFundingOptionsarray of strings | The list of allowed funding options for PayPal. |
allowedFundingTypes.wallets.paypal.merchantIdstring or null | The PayPal merchant identifier. |
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.
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.
Pass these values when you build CheckoutConfig:
| Parameter | Description |
|---|---|
environmentEnvironment required | The environment type. Possible values:
|
sessionSessionData 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. |
transactionDataTransactionData required | Details about the payout. |
transactionData.amountDecimal required | The payout amount (e.g., Decimal(100.00)). |
transactionData.currencyString required | The currency code associated with the payout, in ISO 4217 format (e.g., "USD", "GBP", "EUR"). |
transactionData.entryTypeEntryType required | The entry type for the payout. For PayPal payouts, use .ecom. |
transactionData.intentTransactionIntentData required | The transaction intents. For PayPal payouts, set paypal to .payout. |
transactionData.intent.paypalPayPalIntentType? | The intent for PayPal. For payouts, use .payout.Other possible values:
|
transactionData.merchantTransactionIdString 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. |
merchantShopperIdString required | A unique identifier for this shopper or customer. |
ownerIdString required | The identifier of the owner related to the ownerType. Get this from the Unity Portal. |
ownerTypeString? | The type of owner. For merchant-group credentials, use "MerchantGroup". |
paypalConfigPayPalConfig? | PayPal-specific configuration. Required for PayPal payout transactions. Set payout.paypalWallet with email, payerId, and proceedPayoutWithSdk. See How it works. |
paypalConfig.payoutPayPalPayoutConfig? | The payout-specific settings. |
paypalConfig.payout.paypalWalletPayPalWallet? | 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.proceedPayoutWithSdkBool | 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. |
localeString? | Optional locale for UI localisation (e.g., "en-US", "es-ES"). |
localisationLocalisation? | Optional string overrides for component text. |
kountDisabledBool | 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. |
That's it for SDK installation. Next, follow the guide for PayPal payouts, and see Error handling for payout error codes and callbacks.