Testing

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

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
  }
};

1. Log in to PayPal Developer Dashboard.
2. Go to Sandbox > Accounts.
3. Click Create Account.
4. Configure your account:
   • Account Type: Business
   • Email: business-sender@example.com
   • Password: Choose a password
   • Account balance: $10,000 (for testing)
   • Country: United States
5. Click Create Account.

Create multiple recipient accounts to test different scenarios:

• Account type: Personal
• Email: recipient1@example.com
• Balance: $0
• Status: Verified

• Account type: Personal
• Email: recipient2@example.com
• Balance: $0
• Status: Unverified (don't complete email verification)

• Account type: Personal
• Email: recipient3@example.com
• Balance: $0
• Status: Limited (simulate by restricting in sandbox)

To log in to sandbox accounts:

1. Go to PayPal Sandbox.
2. Use the sandbox account credentials.
3. Verify account status and balance.

Configuration: proceedPayoutWithSdk: true

1. Initiate the withdrawal flow with pre-configured payer ID.
2. Verify: onPrePayoutSubmit callback triggered.
3. Show approval UI: Display confirmation to user.
4. Return approval: isApproved: true with payer ID.
5. Observe: SDK executes payout.
6. Wait: For payout to process (typically < 30 seconds in sandbox).
7. Verify: onPostPayout callback triggered with transaction IDs.
8. Check sandbox: Log into recipient1@example.com account.
9. Verify balance: $100 added to account balance.

Expected result: The payout completes and funds appear in the recipient account.

1. Initiate the withdrawal flow.
2. In onPrePayoutSubmit callback, show the approval UI.
3. Return rejection: isApproved: false.
4. Verify: No payout executed.
5. Check: No error callback triggered.

Expected result: The payout is cancelled gracefully and no funds are transferred.

Configuration: proceedPayoutWithSdk: false

1. Initiate the withdrawal flow with pre-configured credentials.
2. Call the backend endpoint: POST /api/payouts/execute.
3. Verify: Backend calls the Unity Payout API.
4. Check response: Payout transaction ID returned.
5. Log into sandbox: Verify funds transferred.

Expected result: Backend successfully triggers payout.

// 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: onError callback with error code SDK0818 (PayoutPayerIdInvalidException).

// 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: onError callback with error code SDK0809 (PayoutPayerIdRequiredException)

// 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: onError callback with error code SDK0817 (PayoutPayerIdMaxLengthException)

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: onError callback with error code SDK0811 (PayoutAmountNotPositiveException)

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: onError callback with error code SDK0811 (PayoutAmountNotPositiveException) - amount must be greater than zero

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: onError callback with error code SDK0810 (PayoutAmountInvalidException)

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: onError callback with error code SDK0814 (PayoutCurrencyInvalidLengthException).

let transactionData = TransactionData(
    amount: Decimal(100.00),
    currency: "XXX",  // Invalid ISO 4217 code
    entryType: .ecom,
    intent: TransactionIntentData(card: nil, paypal: .payout),
    merchantTransactionId: "test-\(UUID().uuidString)",
    merchantTransactionDate: { Date() }
)

Expected result: onError callback with error code SDK0815 (PayoutCurrencyInvalidException).

1. Create a session.
2. Wait for the session timeout (typically 2 hours).
3. Attempt a payout.
4. Verify: Unity API returns session error.

Expected result: onError callback with Unity API error response (not SDK error code)

Setup: Configure your sandbox PayPal business account (the payout sender) with $0 balance.

1. Attempt payout of $100 to recipient.
2. Verify: PayPal API rejects payout due to insufficient merchant funds.
3. SDK behaviour: Error forwarded as SDK0819 (PayoutFailedException).

Expected result: onError callback with error code SDK0819 and PayPal error details in message.

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:

1. Execute a payout.
2. Wait: For webhook delivery (1-5 minutes in sandbox).
3. Check backend: Webhook received.
4. Verify: Event type is PAYMENT.PAYOUTS-ITEM.SUCCEEDED.
5. Verify: Signature validation passes.
6. Check: Payout status updated in database.

Expected result: Webhook received and processed correctly.

1. Trigger payout that will fail (e.g., to blocked account).
2. Wait for webhook.
3. Verify: Event type is PAYMENT.PAYOUTS-ITEM.FAILED.
4. Check: Error handling logic executes.

Expected result: Failure webhook handled correctly.

Use PayPal's webhook simulator:

1. Go to Developer Dashboard > Webhooks.
2. Click on your webhook.
3. Click "Simulator".
4. Select event type to simulate.
5. Click "Send Test".

1. Execute payout #1 to recipient1 ($50).
2. Immediately execute payout #2 to recipient1 ($50).
3. Verify: Both complete successfully.
4. Check balance: $100 total received.

1. Execute payout to recipient1 ($50).
2. Simultaneously execute payout to recipient2 ($50).
3. Verify: Both complete successfully.

1. Start payout process.
2. Disable network mid-transaction.
3. Verify: Error handling activates.
4. Check: Transaction not partially completed.

Use this checklist to ensure comprehensive testing:

• 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

• Network errors
• API errors
• Validation errors
• User-facing error messages
• Error logging

• Backend API calls
• Session creation
• Webhook delivery (if implemented)
• Webhook signature validation

• Button rendering
• Loading states
• Success messages
• Error messages
• Cancellation flow
• Retry options

Once all tests pass in sandbox:

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'
  }
};

let config = CheckoutConfig(
    environment: .live,  // Switch to live
    // ...
)

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:

1. Execute test payout of $1.00 to your own PayPal account.
2. Verify funds received.
3. Verify transaction appears in PayPal reports.
4. Test refund flow if applicable.

• Set up error tracking (e.g., Sentry, Datadog).
• Configure alerts for payout failures.
• Monitor webhook delivery rates.
• Track payout completion times.

1. Beta users: Release to small group (5-10%).
2. Monitor: Watch for errors and user feedback.
3. Iterate: Fix any issues discovered.
4. Expand: Gradually increase rollout percentage.
5. 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.