Test your Payout Drop-in integration in sandbox before enabling live withdrawals.
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.
Initialise Drop-in against the test environment:
PayoutDropIn.initialize({
environment: 'test',
// ... rest of config
});What the test environment gives you:
| Point | Detail |
|---|---|
| No live funds | Sandbox withdrawals follow test provider rules for your test site. |
| Same SDK behaviour | Method detection, filtering, and callbacks match live behaviour. |
| Credentials | Use inbound test tokens and the test Client ID from the Unity Portal. |
| Instruments | Prepare test shoppers with eligible stored cards, PayPal associations, or wallet device tokens. |
Switch to environment: 'live' only after completing the pre-production checklist.
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.
Run these scenarios in an approved test environment.
| Setup | The session includes allowedFundingTypes.cards. The shopper has a non-expired plain-card token. |
| Steps |
|
| Expect | If configured, onBeforeSubmit runs first, then onSubmit, then onSuccess with systemTransactionId and payoutMethod: 'Card'. Backend verification succeeds. |
| Setup | The session allows wallets.paypal. The shopper has an active PayPal wallet association. |
| Steps |
|
| Expect | onSuccess with payoutMethod: 'Paypal'. onBeforeSubmit and onSubmit aren't called for this panel. |
| Setup | The session allows the wallet. The shopper has a matching device token (walletType: ApplePay or GooglePay, panType: Device). |
| Expect | The method appears with filtered tokens. Submit reaches onSuccess, or fails with a clear SDK1703 if the provider rejects the payout. |
| Setup | The session allows one or more methods, but the shopper has no eligible tokens and no active PayPal link. |
| Expect | Methods stay hidden. After mount, onError receives SDK1701. |
| Setup | Payout Drop-in is disabled for the site, the environment is wrong, or configuration retrieval fails. |
| Expect | SDK1700, error shell in the container, and onError invoked. create() usually settles without throwing. |
| Setup | Card, Apple Pay, or Google Pay with onBeforeSubmit returning false. |
| Expect | No payout submission, no onSubmit, and no onSuccess. The UI remains usable for another attempt. |
| Setup | The callback throws or rejects (e.g., due to an unauthenticated shopper). |
| Expect | create() promise rejects. Handle this outside onError. |
| Setup | methodConfig blacklists the shopper's only card token, or blacklistedPayerId matches the linked PayPal payer. |
| Expect | That method is hidden. SDK1701 if no other methods remain. |
| Setup | The frontend transactionData.amount or currency differs from the values used to create the session. |
| Expect | A provider or API rejection, often SDK1703. Keep the session creation and SDK transactionData aligned on the server. |
| Steps | Mount Drop-in, leave the page calling destroy(), then remount. |
| Expect | No duplicate UI and no stale listeners. |
Force these failure modes and confirm the expected client behaviour:
| Technique | Expected 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 vault | The token is filtered out. The method may disappear. |
Offline network during create() | A mount failure or SDK1700. |
| Missing session ID or HMAC key | A synchronous throw from initialize(). |
| PayPal association inactive or missing | PayPal 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.
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:
- Transaction exists: Confirm the record for
systemTransactionId(or each ID inpayoutsfor closed-loop). - Amount and currency: Match the authorised withdrawal.
- Merchant transaction ID: Match your internal record.
- Idempotency: Duplicate webhook or callback delivery doesn't double-pay.
- 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.
With analyticsEvent registered:
- Initialise Drop-in: expect
DeviceTypeandBrowserDataonce. - Force a reproducible component failure in QA: expect
ComponentErrorwhere applicable.
Verify analytics payloads exclude secrets (hmacKey, inbound tokens, wallet JWTs, full card tokens). See Analytics.
Before going live, verify the following.
Confirm live configuration before cutover:
- Production builds use
environment: 'live'only. - Production inbound tokens and Client ID stay on the server.
- Correct merchant group
ownerIdfor token vault lookups. - Payout Drop-in enabled on the live site with the intended methods.
- Live sessions use
serviceType: 'PayoutDropIn'and intentPayout.
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). onBeforeSubmitreturningfalsetested for card-on-file methods.- PayPal path tested without assuming
onSubmit. - Destroy and remount leaves a clean UI.
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.
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.