Navigating The Sandbox

Overview

The Rollfi sandbox lets you test company onboarding, employee onboarding, bank account linking, and payroll before going live. Sandbox-only methods let you refresh Know Your Business (KYB), Know Your Customer (KYC), and bank account statuses yourself, so you can move through successful test scenarios without waiting for support at every step. This guide covers positive testing: progressing through verification and preparing your test company for payroll. For negative testing, support can help set up the statuses you need.

Use sandbox credentials and synthetic test data only. These methods are not available in production and do not replace production verification requirements.

Test data

EINs and SSNs

We simulate KYB and KYC against other companies and identities in the sandbox. Reusing common test identifiers can create conflicts with records already used by another sandbox company or tester, preventing verification from progressing smoothly.

Generate a random, synthetic Employer Identification Number (EIN) for each new test company.
Generate random, synthetic Social Security Numbers (SSNs) for test employees and beneficial owners.

Do not use real customer or employee EINs or SSNs in the sandbox. Random identifiers help avoid collisions, but do not bypass other onboarding requirements.

Routing numbers

We validate routing numbers for bank accounts in the sandbox. Use a valid routing number even when the rest of the account information is synthetic test data. Invalid routing numbers can lead to account-linking failures or increased approval times. Do not generate routing numbers at random or assume any nine-digit value will work. If you need suitable bank test details, contact support. The status-refresh methods below do not bypass routing-number validation or replace the bank account linking and verification steps.

Sandbox methods

Method	When to use it	Required inputs
refreshCompanyKybStatus	Refresh a test company’s KYB status after submitting its business verification information.	`companyId`
refreshUserKycStatus	Refresh a test employee’s KYC status after submitting their identity information.	`userId`
refreshCompanyBankAccountStatus	Refresh linked company bank account statuses before testing payroll funding.	`companyId`
refreshUserBankAccountStatus	Refresh employee bank account status after linking an account.	`userId`, `userPayAccountEntityId`
addFundsToLedger	Add simulated funds to a company’s sandbox ledger for funded payroll scenarios.	`companyId`, `amount`

Company KYB

{
  "method": "refreshCompanyKybStatus",
  "companyId": "8b2f4a91-6c35-4d7e-9a10-2f83c5e6b074"
}

Example successful response:

{
  "success": true,
  "kycStatus": "passed",
  "message": "Company kyb status is passed."
}

Complete the required KYB submission first. Company verification is returned as kycStatus; passed indicates success.

Employee KYC

{
  "method": "refreshUserKycStatus",
  "userId": "c4e7b290-1a63-4f85-b902-6d38a1e5f047"
}

Example successful response:

{
  "success": true,
  "kycStatus": "passed",
  "message": "Employee kyc status is passed."
}

Complete the employee’s KYC submission first. Confirm success: true and kycStatus: passed before continuing.

Company bank accounts

{
  "method": "refreshCompanyBankAccountStatus",
  "companyId": "8b2f4a91-6c35-4d7e-9a10-2f83c5e6b074"
}

Example successful response:

{
  "success": true,
  "bankAccountStatus": "ready",
  "message": "Company bank account status is ready."
}

Link and verify a company account first. A successful response means at least one active funding source is ready or active, not that every account is approved.

Employee bank accounts

{
  "method": "refreshUserBankAccountStatus",
  "userId": "c4e7b290-1a63-4f85-b902-6d38a1e5f047",
  "userPayAccountEntityId": "3f9a6d12-8b40-4e57-a631-7c02d5b8e094"
}

Example successful response:

{
  "success": true,
  "bankAccountStatus": "ready",
  "message": "Employee bank account status is ready."
}

Call getUser to retrieve the employee’s bank accounts and their userPayAccountEntityId values, then use the ID for the account you want to refresh. Confirm ready or active; an empty status is not approval, even when success is true.

Test funds

{
  "method": "addFundsToLedger",
  "companyId": "8b2f4a91-6c35-4d7e-9a10-2f83c5e6b074",
  "amount": 10000.0
}

An example successful response:

{
  "success": true,
  "message": "Funds added successfully."
}

Adds simulated funds to the company’s first active funding source, not a real bank transfer or verification approval. Each successful call adds funds again. Plaid-linked balances are checked periodically and when running payroll; contact support for balance-related sandbox errors.

Troubleshooting

Verification has not passed: Inspect success, the returned status, and message. Confirm that required onboarding information is complete and that your test EINs and SSNs do not reuse other test identities. If the response asks you to try again shortly, allow processing time before retrying. Contact support if the issue persists.
Bank account is not ready: Confirm the routing number is valid and the account has been linked and verified through the appropriate flow. Status refreshes do not fix invalid bank details.

Do not assume that a completed HTTP request means verification succeeded. Check the response body for success, status fields, and any error details before continuing. KYB/KYC and bank account statuses may also take up to 15 minutes to be approved by the system. If the sandbox update methods do not immediately reflect the expected status, allow some time before retrying.

Negative testing

Although this guide focuses on positive testing, you can also test how your integration handles unsuccessful verification and account states. Reach out to Rollfi support, and we can flip the relevant sandbox statuses for you to conduct negative testing. Provide the relevant companyId, userId, or bank account ID, the status or scenario you want to test, and the behavior you expect your integration to handle. Support can coordinate the scenario and help restore the records when you are ready to resume positive testing. Use support-assisted status changes rather than invalid routing numbers or conflicting EINs and SSNs to create negative test scenarios. This keeps your tests intentional and easier to troubleshoot.

​Overview

​Test data

​EINs and SSNs

​Routing numbers

​Sandbox methods

​Company KYB

​Employee KYC

​Company bank accounts

​Employee bank accounts

​Test funds

​Troubleshooting

​Negative testing

Overview

Test data

EINs and SSNs

Routing numbers

Sandbox methods

Company KYB

Employee KYC

Company bank accounts

Employee bank accounts

Test funds

Troubleshooting

Negative testing