Skip to content

Testing

Test your Payout Drop-in integration in sandbox before enabling live withdrawals.

Overview

Use the test environment with sandbox Unity configuration, sandbox API credentials, and test shoppers that already have eligible stored payout instruments. Backend reconciliation tests are required even in sandbox: treat onSuccess as submission acknowledgement, not settlement.

Use the test environment

Initialise Drop-in against the test environment:

PayoutDropIn.initialize({
  environment: 'test',
  // ... rest of config
});

What the test environment gives you:

PointDetail
No live fundsSandbox withdrawals follow test provider rules for your test site.
Same SDK behaviourMethod detection, filtering, and callbacks match live behaviour.
CredentialsUse inbound test tokens and the test Client ID from the Unity Portal.
InstrumentsPrepare test shoppers with eligible stored cards, PayPal associations, or wallet device tokens.

Switch to environment: 'live' only after completing the pre-production checklist.

Prepare stored instruments

Prepare instruments with your platform's approved sandbox flows before mounting Drop-in, for example:

  • Tokenise cards through a payment flow or vault onboarding that stores plain-card tokens for the test shopper.
  • Link PayPal accounts with your sandbox linking journey (activeStatus: Active, recipientWallet: Paypal).
  • Vault Apple Pay or Google Pay device tokens (panType: Device) through a supported wallet payment or onboarding flow.

Document test shopper IDs and instrument IDs in your team runbook.

For card, the payout session must include allowedFundingTypes.cards (including an empty array). cardSchemes alone doesn't enable card in this Drop-in.

Integration test scenarios

Run these scenarios in an approved test environment.

Happy paths

Card

SetupThe session includes allowedFundingTypes.cards. The shopper has a non-expired plain-card token.
Steps
  1. The authenticated shopper opens the payout page.
  2. The backend creates a payout session with matching amount and currency.
  3. Drop-in mounts and Card appears.
  4. Select the stored card and submit.
ExpectIf configured, onBeforeSubmit runs first, then onSubmit, then onSuccess with systemTransactionId and payoutMethod: 'Card'. Backend verification succeeds.

PayPal

SetupThe session allows wallets.paypal. The shopper has an active PayPal wallet association.
Steps
  1. Mount Drop-in with onGetShopper.
  2. Confirm PayPal shows the linked email.
  3. Submit the payout.
ExpectonSuccess with payoutMethod: 'Paypal'. onBeforeSubmit and onSubmit aren't called for this panel.

Apple Pay or Google Pay

SetupThe session allows the wallet. The shopper has a matching device token (walletType: ApplePay or GooglePay, panType: Device).
ExpectThe method appears with filtered tokens. Submit reaches onSuccess, or fails with a clear SDK1703 if the provider rejects the payout.

No methods available

SetupThe session allows one or more methods, but the shopper has no eligible tokens and no active PayPal link.
ExpectMethods stay hidden. After mount, onError receives SDK1701.

Configuration failure

SetupPayout Drop-in is disabled for the site, the environment is wrong, or configuration retrieval fails.
ExpectSDK1700, error shell in the container, and onError invoked. create() usually settles without throwing.

onBeforeSubmit cancellation

SetupCard, Apple Pay, or Google Pay with onBeforeSubmit returning false.
ExpectNo payout submission, no onSubmit, and no onSuccess. The UI remains usable for another attempt.

onGetShopper rejection

SetupThe callback throws or rejects (e.g., due to an unauthenticated shopper).
Expectcreate() promise rejects. Handle this outside onError.

Blacklist

SetupmethodConfig blacklists the shopper's only card token, or blacklistedPayerId matches the linked PayPal payer.
ExpectThat method is hidden. SDK1701 if no other methods remain.

Amount or session mismatch

SetupThe frontend transactionData.amount or currency differs from the values used to create the session.
ExpectA provider or API rejection, often SDK1703. Keep the session creation and SDK transactionData aligned on the server.

Destroy and remount

StepsMount Drop-in, leave the page calling destroy(), then remount.
ExpectNo duplicate UI and no stale listeners.

Test error handling

Force these failure modes and confirm the expected client behaviour:

TechniqueExpected result
Provider decline (if your sandbox can force one)SDK1703 through onError. Show a shopper-safe message, and inspect message and details.
Expired token in vaultThe token is filtered out. The method may disappear.
Offline network during create()A mount failure or SDK1700.
Missing session ID or HMAC keyA synchronous throw from initialize().
PayPal association inactive or missingPayPal is hidden. SDK1701 is possible if nothing else remains.

Verify loading overlays clear on both onSuccess and onError. For PayPal, drive loading from those callbacks because onSubmit doesn't run.

Test backend verification

Always verify payouts on your backend before marking withdrawals complete. Frontend callbacks can be manipulated.

Use merchant transaction webhooks (or the Transactions API) as the source of truth. A successful payout webhook looks like this:

{ "eventDate": "2025-12-16T07:37:11.1613200Z", "eventCategory": "transaction", "eventData": { "state": "Authorised", "amount": { "transaction": 100, "currencyCode": "USD" }, "transactionMethod": "Payout", "merchant": "merchant-1", "site": "site-1", "merchantTransactionDate": "2025-12-16T07:37:11.1613200Z", "merchantTransactionId": "PAYOUT_001", "systemTransactionId": "787ebfee-c0ce-497a-82c3-265d1bf19b0c", "providerTransactionId": "PAYPAL_PAYOUT_ITEM_ID", "fundingData": { "paypal": { … } } } }

Essential checks:

  1. Transaction exists: Confirm the record for systemTransactionId (or each ID in payouts for closed-loop).
  2. Amount and currency: Match the authorised withdrawal.
  3. Merchant transaction ID: Match your internal record.
  4. Idempotency: Duplicate webhook or callback delivery doesn't double-pay.
  5. Payout state: Accept only successful states defined for your programme (the documented examples use Authorised).

Example backend verification handler:

app.post('/api/verify-payout', async (req, res) => {
  const { systemTransactionId, merchantTransactionId } = req.body;
  const withdrawal = await db.withdrawals.findOne({ merchantTransactionId });
  const transaction = await unityApi.getTransaction(systemTransactionId);

  if (!withdrawal || !transaction) {
    return res.json({ success: false });
  }

  if (await db.processedTx.exists({ systemTransactionId })) {
    return res.json({
      success: true,
      withdrawalId: withdrawal.id,
      duplicate: true,
    });
  }

  // Use successful payout states from your Payout API documentation
  if (!isSuccessfulPayoutState(transaction.state)) {
    return res.json({ success: false, error: 'Invalid state' });
  }

  if (transaction.amounts.transactionValue !== withdrawal.amount) {
    return res.json({ success: false, error: 'Amount mismatch' });
  }

  if (transaction.amounts.currencyCode !== withdrawal.currency) {
    return res.json({ success: false, error: 'Currency mismatch' });
  }

  await markWithdrawalPaid(withdrawal.id);
  await db.processedTx.insert({ systemTransactionId });

  res.json({ success: true, withdrawalId: withdrawal.id });
});

Confirm acceptable payout states for each method you enable. Don't treat card payment-capture states such as Captured as universal payout success. See Manage webhooks for subscription and signature validation.

Test analytics

With analyticsEvent registered:

  1. Initialise Drop-in: expect DeviceType and BrowserData once.
  2. Force a reproducible component failure in QA: expect ComponentError where applicable.

Verify analytics payloads exclude secrets (hmacKey, inbound tokens, wallet JWTs, full card tokens). See Analytics.

Pre-production checklist

Before going live, verify the following.

Configuration

Confirm live configuration before cutover:

  • Production builds use environment: 'live' only.
  • Production inbound tokens and Client ID stay on the server.
  • Correct merchant group ownerId for token vault lookups.
  • Payout Drop-in enabled on the live site with the intended methods.
  • Live sessions use serviceType: 'PayoutDropIn' and intent Payout.

Functional testing

Confirm these functional paths in sandbox or a controlled live dry run:

  • Each enabled method tested with eligible stored instruments.
  • Empty-state path tested (SDK1701).
  • Configuration failure path understood (SDK1700).
  • onBeforeSubmit returning false tested for card-on-file methods.
  • PayPal path tested without assuming onSubmit.
  • Destroy and remount leaves a clean UI.

Security

Confirm these security controls are in place:

  • Backend verification before marking withdrawals complete.
  • Replay protection on systemTransactionId.
  • HTTPS on payout pages.
  • No secrets or full instrument payloads in client logs.

User experience

Confirm the shopper experience before go-live:

  • Mobile layout verified.
  • Loading and disabled states during submit.
  • Post-verification confirmation page.
  • Shopper-safe error copy. See Error handling.