Test your payout integration thoroughly before going live.
Always test payout functionality in PayPal's sandbox environment before deploying to production.
This guide covers:
- Setting up sandbox accounts
- Testing the complete payout flow
- Common test scenarios
- Troubleshooting failed tests
- Moving to production
Ensure you have:
- Completed PayPal onboarding with sandbox credentials.
- Implemented the withdrawal flow including backend setup.
- Created PayPal sandbox test accounts.
Import the SDK and set it to use the test environment:
import PXPCheckoutSDK
let config = CheckoutConfig(
environment: .test, // Environment.test (sandbox)
session: sessionData,
transactionData: transactionData,
merchantShopperId: "test_shopper_01",
ownerId: "Unity"
)Available environment values:
.test: Sandbox environment for testing.live: Production environment
The SDK automatically uses sandbox PayPal endpoints and the test Unity API when environment: .test is set.
This is backend server configuration (not iOS code):
// Environment configuration
const ENVIRONMENT = 'sandbox';
const config = {
paypal: {
clientId: process.env.PAYPAL_SANDBOX_CLIENT_ID,
secret: process.env.PAYPAL_SANDBOX_SECRET,
apiBaseUrl: 'https://api-m.sandbox.paypal.com'
},
unity: {
apiBaseUrl: 'https://api-services-test.pxp.io',
clientId: process.env.UNITY_TEST_CLIENT_ID,
tokenId: process.env.UNITY_TEST_TOKEN_ID,
tokenValue: process.env.UNITY_TEST_TOKEN_VALUE
}
};To create the business account that sends your test payouts, follow these steps.
- Log in to PayPal Developer Dashboard.
- Go to Sandbox > Accounts.
- Click Create Account.
- Configure your account:
- Account Type: Business
- Email: business-sender@example.com
- Password: Choose a password
- Account balance: $10,000 (for testing)
- Country: United States
- Click Create Account.
Create multiple recipient accounts to test different scenarios.
Create this account with the following settings:
- Account type: Personal
- Email:
recipient1@example.com - Balance: $0
- Status: Verified
Create this account with the following settings:
- Account type: Personal
- Email:
recipient2@example.com - Balance: $0
- Status: Unverified (don't complete email verification)
Create this account with the following settings:
- Account type: Personal
- Email:
recipient3@example.com - Balance: $0
- Status: Limited (simulate by restricting in sandbox)
To log in to sandbox accounts:
- Go to PayPal Sandbox.
- Use the sandbox account credentials.
- Verify account status and balance.
Configuration: proceedPayoutWithSdk: true
Follow these steps to test a payout that the SDK executes.
- Initiate the withdrawal flow with a pre-configured email and payer ID.
- Verify:
onPrePayoutSubmitcallback triggered. - Show approval UI: Display confirmation to user.
- Return approval:
PrePayoutSubmitResult(isApproved: true). The payer ID comes fromPayPalWallet, not from this result. - Observe: The SDK executes the payout.
- Wait: For payout to process (typically < 30 seconds in sandbox).
- Verify:
onPostPayoutcallback triggered with transaction IDs. - Check sandbox: Log in to the
recipient1@example.comaccount. - Verify balance: $100 added to account balance.
Expected result: The payout completes and funds appear in the recipient account.
Follow these steps to test a rejected payout.
- Initiate the withdrawal flow.
- In
onPrePayoutSubmitcallback, show the approval UI. - Return rejection:
isApproved: false. - Verify: No payout executed.
- Check: No error callback triggered.
Expected result: The payout is cancelled gracefully and no funds are transferred.
Configuration: proceedPayoutWithSdk: false
Follow these steps to test a payout that your backend executes.
- Initiate the withdrawal flow with pre-configured credentials. Only the
onClickcallback runs in this mode. - Call the backend endpoint from
onClick:POST /api/payouts/execute. - Verify: Backend calls the Unity Payout API.
- Check response: Payout transaction ID returned.
- Log in to sandbox: Verify funds transferred.
Expected result: Backend successfully triggers payout.
The SDK validates your payout configuration when you create the components. If validation fails, pxpCheckout.create throws an error, so catch it with try-catch. These errors aren't delivered to onError. Use onError to test failures during payout execution, such as insufficient funds or an expired session.
The following configuration uses a payer ID that contains characters other than letters and numbers.
// Configure SDK with invalid payer ID (contains non-alphanumeric characters)
let paypalConfig = PayPalConfig(
payout: PayPalPayoutConfig(
paypalWallet: PayPalWallet(
email: "user@example.com",
payerId: "INVALID@ID!", // Contains non-alphanumeric characters
proceedPayoutWithSdk: true
)
)
)Expected result: pxpCheckout.create(.payoutSubmission, ...) throws error code SDK0818 (PayoutPayerIdInvalidException).
To test an ID that has a valid format but doesn't exist in PayPal, the SDK passes validation but the payout fails. The onError callback receives a PayoutFailedException whose errorCode and errorMessage are the code and reason returned by the API.
The following configuration passes an empty string as the payer ID.
// Configure SDK with empty payer ID
let paypalConfig = PayPalConfig(
payout: PayPalPayoutConfig(
paypalWallet: PayPalWallet(
email: "user@example.com",
payerId: "", // Empty payer ID
proceedPayoutWithSdk: true
)
)
)Expected result: pxpCheckout.create(.payoutSubmission, ...) throws error code SDK0809 (PayoutPayerIdRequiredException).
If payerId or email is nil instead of an empty string, create throws PaypalPayoutReceiverRequiredException (SDK0803).
The following configuration uses a payer ID that is one character longer than the maximum.
// Configure SDK with payer ID exceeding max length
let paypalConfig = PayPalConfig(
payout: PayPalPayoutConfig(
paypalWallet: PayPalWallet(
email: "user@example.com",
payerId: "ABCDEFGHIJKLMN", // 14 characters, max is 13
proceedPayoutWithSdk: true
)
)
)Expected result: pxpCheckout.create(.payoutSubmission, ...) throws error code SDK0817 (PayoutPayerIdMaxLengthException).
The following transaction data uses a negative payout amount.
let transactionData = TransactionData(
amount: Decimal(-50.00), // Negative amount
currency: "USD",
entryType: .ecom,
intent: TransactionIntentData(card: nil, paypal: .payout),
merchantTransactionId: "test-\(UUID().uuidString)",
merchantTransactionDate: { Date() }
)Expected result: pxpCheckout.create(.payoutAmount, ...) throws error code SDK0811 (PayoutAmountNotPositiveException).
The following transaction data uses a payout amount of zero.
let transactionData = TransactionData(
amount: Decimal(0.00), // Zero amount
currency: "USD",
entryType: .ecom,
intent: TransactionIntentData(card: nil, paypal: .payout),
merchantTransactionId: "test-\(UUID().uuidString)",
merchantTransactionDate: { Date() }
)Expected result: pxpCheckout.create(.payoutAmount, ...) throws error code SDK0811 (PayoutAmountNotPositiveException). The amount must be greater than zero.
The following transaction data uses a value that isn't a valid number.
let transactionData = TransactionData(
amount: Decimal(Double.nan), // Not a number
currency: "USD",
entryType: .ecom,
intent: TransactionIntentData(card: nil, paypal: .payout),
merchantTransactionId: "test-\(UUID().uuidString)",
merchantTransactionDate: { Date() }
)Expected result: pxpCheckout.create(.payoutAmount, ...) throws error code SDK0810 (PayoutAmountInvalidException).
The following transaction data uses a currency code that is too short.
let transactionData = TransactionData(
amount: Decimal(100.00),
currency: "US", // Only 2 characters, must be 3
entryType: .ecom,
intent: TransactionIntentData(card: nil, paypal: .payout),
merchantTransactionId: "test-\(UUID().uuidString)",
merchantTransactionDate: { Date() }
)Expected result: pxpCheckout.create(.payoutAmount, ...) throws error code SDK0814 (PayoutCurrencyLengthInvalidException).
The following transaction data uses a three-letter code that isn't a valid currency.
let transactionData = TransactionData(
amount: Decimal(100.00),
currency: "ZZZ", // Three letters, but not a valid ISO 4217 code
entryType: .ecom,
intent: TransactionIntentData(card: nil, paypal: .payout),
merchantTransactionId: "test-\(UUID().uuidString)",
merchantTransactionDate: { Date() }
)Expected result: pxpCheckout.create(.payoutAmount, ...) throws error code SDK0815 (PayoutCurrencyCodeInvalidException).
Follow these steps to test an expired session.
- Create a session.
- Wait for the session timeout (typically 2 hours).
- Attempt a payout.
- Verify: Unity API returns session error.
Expected result: onError callback with Unity API error response (not SDK error code)
Session expiry is validated by the Unity backend, not the iOS SDK. The SDK will forward the API error. We recommend prompting the customer to refresh the session or re-authenticate.
Setup: Configure your sandbox PayPal business account (the payout sender) with a $0 balance.
- Attempt a payout of $100 to the recipient.
- Verify: PayPal API rejects payout due to insufficient merchant funds.
- SDK behaviour: The error is forwarded as a
PayoutFailedException.
Expected result: onError callback with a PayoutFailedException. Its errorCode and errorMessage contain the code and reason returned by the API.
This tests your business account balance, not the recipient's balance.
Webhooks are received by your backend server, not the iOS app. This testing is for backend integration. The iOS SDK doesn't interact with webhooks directly. Webhook processing happens entirely on your backend.
If you implemented backend webhooks, run the following tests.
Follow these steps to test a successful payout webhook.
- Execute a payout.
- Wait: For webhook delivery (1-5 minutes in sandbox).
- Check backend: Webhook received.
- Verify: Event type is
PAYMENT.PAYOUTS-ITEM.SUCCEEDED. - Verify: Signature validation passes.
- Check: Payout status updated in database.
Expected result: Webhook received and processed correctly.
Follow these steps to test a failed payout webhook.
- Trigger payout that will fail (e.g., to blocked account).
- Wait for webhook.
- Verify: Event type is
PAYMENT.PAYOUTS-ITEM.FAILED. - Check: Error handling logic executes.
Expected result: Failure webhook handled correctly.
Use PayPal's webhook simulator:
- Go to Developer Dashboard > Webhooks.
- Click on your webhook.
- Click "Simulator".
- Select event type to simulate.
- Click "Send Test".
Follow these steps to test two payouts sent one after the other.
- Execute payout #1 to recipient1 ($50).
- Immediately execute payout #2 to recipient1 ($50).
- Verify: Both complete successfully.
- Check balance: $100 total received.
Follow these steps to test two payouts sent at the same time.
- Execute payout to recipient1 ($50).
- Simultaneously execute payout to recipient2 ($50).
- Verify: Both complete successfully.
Follow these steps to test how your app handles a network failure.
- Start payout process.
- Disable network mid-transaction.
- Verify: Error handling activates.
- Check: Transaction not partially completed.
Use this checklist to ensure comprehensive testing.
Make sure you have tested each of these payout scenarios:
- Successful payout (SDK-managed)
- Successful payout (backend-managed)
- Merchant approval flow
- Merchant rejection
- Invalid payer ID
- Empty payer ID
- Payer ID too long
- Invalid amount
- Negative amount
- Zero amount
- Invalid currency
- Session expired
Make sure you have tested how your app handles each of these error types:
- Network errors
- API errors
- Validation errors
- User-facing error messages
- Error logging
Make sure you have tested each of these integration points:
- Backend API calls
- Session creation
- Webhook delivery (if implemented)
- Webhook signature validation
Make sure you have checked each of these parts of the user experience:
- Button rendering
- Loading states
- Success messages
- Error messages
- Cancellation flow
- Retry options
Once all tests pass in sandbox, complete the following steps.
Replace sandbox credentials with live credentials:
const config = {
paypal: {
clientId: process.env.PAYPAL_LIVE_CLIENT_ID,
secret: process.env.PAYPAL_LIVE_SECRET,
apiBaseUrl: 'https://api-m.paypal.com'
}
};Set the SDK to use the live environment in your iOS app.
let config = CheckoutConfig(
environment: .live, // Switch to live
// ...
)Then point your backend configuration at the live Unity API.
const config = {
unity: {
apiBaseUrl: 'https://api-services.pxp.io',
clientId: process.env.UNITY_LIVE_CLIENT_ID,
tokenId: process.env.UNITY_LIVE_TOKEN_ID,
tokenValue: process.env.UNITY_LIVE_TOKEN_VALUE
}
};Before full rollout:
- Execute test payout of $1.00 to your own PayPal account.
- Verify funds received.
- Verify transaction appears in PayPal reports.
- Test refund flow if applicable.
Set up monitoring so you can spot problems as soon as they occur:
- Set up error tracking (e.g., Sentry, Datadog).
- Configure alerts for payout failures.
- Monitor webhook delivery rates.
- Track payout completion times.
Release your integration in stages.
- Beta users: Release to small group (5-10%).
- Monitor: Watch for errors and user feedback.
- Iterate: Fix any issues discovered.
- Expand: Gradually increase rollout percentage.
- Full release: Roll out to all users.
If you encounter issues during testing, see the Troubleshooting guide for solutions to common problems including production vs sandbox issues, webhook delivery problems, and SDK error codes.