VoPay Sandbox FAQs

Getting started

Q: What is the VoPay sandbox?

A: The VoPay sandbox is a virtual testing environment that mirrors production. You can test payments, collections, onboarding, and reporting through the API or Portal without moving real money or completing a production compliance review.

Q: Does the sandbox cover the API as well as the Portal?

A: Yes. Your sandbox account can be set up for API access, Portal access, or both, based on your testing needs. The Sandbox Portal Guide covers the VoPay Merchant Account Portal, which requires no code. For API integration, use your API credentials and the technical documentation at docs.vopay.com.

Q: What works differently in Sandbox compared to production?

A: The main differences are:

See How sandbox decides transaction outcomes for the testing rules.

Q: Does my sandbox account include sample data?

A: Yes. Your sandbox account comes with sample data so you can explore the available features and start testing.

---

Access and credentials

Q: What do I need before I start?

A: You need the credentials for the access type you are testing:

VoPay provides your credentials in your welcome email or through your Account Representative.

Q: I cannot find my welcome email or my credentials. What do I do?

A: Contact your Account Representative. They can help you locate your welcome email or obtain your sandbox credentials.

Q: How do I request sandbox access?

A: Submit the sandbox access form. VoPay will review your request and create your account with API access, Portal access, or both, based on your testing needs.

Q: Do I need to reset my password?

A: Yes. You will be asked to reset your password the first time you log in to the Portal.

---

Connecting a test bank account

Q: Why can’t I fund my account or withdraw to my bank?

A: Connect a default test bank account before using bank-based Fund My Account or withdrawing to your own bank.

In production, VoPay connects your bank account during the application process. Sandbox skips that step, so you need to connect a test bank account yourself. Other activities depend on your available balance and enabled features.

Q: How do I connect a test bank account in Canada?

A: First, check whether Client Accounts appears in your left navigation.

If you see Client Accounts:

1. Go to Client Accounts > Client Accounts List.
2. Open [Your Account Name] Primary.
3. Select Payment Methods, then Add.

If you do not see Client Accounts:

1. Go to My Account > Operational Accounts.
2. Select Add Operational Account.
3. Select Add a Payment Method > Bank Account.

Then complete the connection form:

1. Choose VoPay Testing Bank.
2. Set Account Type to Business and Connection Type to Online.
3. Enter your company name as the Account Holder Name.
4. Sign in with username vopaydemo and password vopaydemo.
5. Answer the identity verification question.
6. Set the account as your default when prompted.

Q: How do I connect a test bank account in the US?

A: Enter test bank details manually. Your Account Representative will provide current test values.

Q: How do I confirm the connection worked?

A: Go to My Account > Fund My Account and submit a test amount. Choose a whole amount, such as $100.00, to test a successful outcome. Once the transaction succeeds, your connection is ready for funding and withdrawals.

---

Test balance and funding

Q: How much test money do I start with?

A: Your account starts with $50,000 in virtual test credits:

• $5,000 reserve: Held as a security deposit and shown as Reserve Amount in your Account Summary.

• $45,000 available: Ready to use for test transactions.

Q: Can I add more test funds later?

A: Yes. Once your default test bank account is connected:

• Portal: Use Fund My Account.

• API: Use Fund My Account, /account/fund-my-account. Set your default operational bank account using Set My Bank Account, /bank-account/set-my-bank-account.

The /eft/fund and /ach/fund endpoints collect funds from a customer’s bank account; they serve a different purpose.

---

Contacts, client accounts, and sub-accounts

Q: What is the difference between a contact, a client account, and a sub-account?

A: Each serves a different purpose:

The API also supports wallets within a client account. A client account and a wallet are distinct objects.

Q: Are client accounts and sub-accounts available on every account?

A: No. An account has either Contacts or Client Accounts enabled, never both, so which one you have depends on your account configuration. Sub-accounts are separate: they have to be enabled and approved for your account.

Q: Do new sub-accounts need approval in sandbox?

A: No. New sub-accounts activate immediately by default. To watch one move through the full approval process instead, add a workflow suffix when you create it, covered below under onboarding simulation.

Q: If client accounts are enabled, does that change where I go to connect a bank account?

A: Yes. If client accounts are enabled, the Portal’s bank-connection path differs from accounts configured with Contacts. Check whether you have a Client Accounts menu before you start any task.

Q: How do I transfer funds between client accounts?

A: Go to Client Accounts > Transfer Funds and choose a workflow:

• Fund and Transfer: Add funds to a client account, then transfer them to another client account.
• Fund, Transfer and Withdraw: Add funds, transfer them, then withdraw to the default bank account.
• Transfer and Withdraw: Transfer funds from a client account, then withdraw to the relevant bank account.

You can add multiple recipients and split the total equally or assign an amount to each recipient.

---

Payment links (eLinx)

Q: What is eLinx?

A: eLinx is VoPay’s payment link product. It has four modes:

Q: How can I see what my customer would see?

A: Send yourself a test eLinx request and complete the bank connection flow. Then go to eLinx > eLinx History to check the request status or export the results in PDF, CSV, XLS, JSON, or XML.

---

Payments, collections, and contacts

Q: Can I pay or collect from more than one person at a time?

A: Yes. You can do both through the Portal:

• Single Payment / Group Payment: Send funds to one or multiple contacts.
• Single Collection / Group Collection: Request funds from one or multiple payors.

Q: Does Interac e-Transfer® Bulk Payout work fully in sandbox?

A: You can create and track the transaction, but there is no recipient experience in sandbox. The recipient has no payment acceptance step to complete.

Q: How many contacts can I load at once?

A: Up to 5,000 contacts, added individually or through a bulk CSV upload.
For a bulk upload:

1. Download the template from Contacts.
2. Choose your payment method and complete the file.
3. Submit it through Bulk Contacts Upload.

---

Reports and statements

Q: Where do I see a full record of activity?

A: Transaction History, filterable by type, status, currency, and keyword, with export options.

Q: I do not see a Reports option. Why not?

A: Enable View and Create Transaction Report under User Management first. The Reports option will then appear, allowing you to create one-time reports or schedule daily, weekly, or monthly reports.

---

How sandbox decides transaction outcomes

Sandbox simulates transactions without moving real money. For funding, withdrawals, bulk payouts, and money requests, the cents value of the amount determines the outcome:

Testing other payment methods

• Credit and debit cards: Use test card numbers for successful payments, declines, and 3DS2 testing.
• Apple Pay and Google Pay: Ask your Implementation Specialist for the separate test amount tables.
• VoPay Instant™, RTP, FedNow, PayPal/Venmo, and Zelle: Ask your Implementation Specialist for the applicable sandbox testing instructions and test values.

Q: How quickly does a transaction change status?

A: For transactions covered by the cents-based rules, statuses update about once a minute. Allow a minute for the next update before checking for a problem.

Q: My transaction looks frozen. What should I check?

A: For transactions covered by the cents-based rules, check the cents value first. Amounts ending in .50–.59 are deliberately held and will not progress automatically. Ask support to move the transaction to the status you need to test.

Q: Do scheduled transactions behave differently?

A: Scheduled transactions run on the date you set, as they do in production. Once created, they follow the simulation rules for their payment method.

Q: How do webhooks behave in sandbox?

A: If you have configured a webhook, you will receive one for every status change. Since status changes occur about once a minute, expect roughly one webhook per minute per transaction until it reaches a final state.

---

Simulating account onboarding

New accounts and sub-accounts are activated immediately by default. To test an onboarding workflow instead, use one of the account-name suffixes below. For accounts created through /partner/account, append the suffix to the Name parameter.

• Name ends in -WF0: approves at every stage of the onboarding workflow.

• Name ends in -WF1: approves every stage except Application Pending.

• Name ends in -WF2: approves the early stages, then rejects at Compliance Review.

• No suffix: activates immediately.

Q: Can you give an example?

A: An account named Bruce Wayne-WF2 will walk through onboarding and then be rejected at compliance, which is useful for testing how your process handles a declined account.

---

API testing

Q: How does authentication work for the API?

A: Every request needs a signature you generate from your API key, your shared secret, and today's date. Sample code in PHP, C#, and JavaScript is here: Authentication and your first request.

Q: Where can I see complete flows instead of single endpoints?

A: Use the integration recipes to follow a complete workflow:

• Accounts Receivables: Collect payments owed to you.
• Accounts Payables: Pay vendors and suppliers.
• Subscription Service: Collect payments on a recurring schedule.
• Account Onboarding: Onboard a new account.
• Micro-Deposits: Verify a bank account before collecting funds.

The Recipes library also includes industry workflows such as Lending, Payroll, and Marketplace.

Q: Do the endpoints differ between Canada and the US?

A: Yes. The recipes use Canadian endpoints in their examples. For the US, the sequence is the same, with /ach/fund and /ach/withdraw in place of /eft/fund and /eft/withdraw. See Canadian and US bank payments for the full differences.

Q: What is the recommended order for testing across both the API and the Portal?

A: Test the same flow in both interfaces:

1. Connect your default test bank account in the Portal.

2. Use Fund My Account and watch the transaction change status.

3. Submit another funding transaction through /account/fund-my-account and check that it appears in the Portal.

If you are testing only through the API, you can connect your default test bank account and fund your account through the API.

Q: What should my first API call be?

A: Call POST /auth/ping with your Sandbox Account ID, Key, and Signature to check your credentials before submitting a transaction.

Q: Which API base URL should I use?

A: Use https://earthnode-dev.vopay.com/api/v2 for Sandbox. Your Implementation Specialist will confirm the production base URL and provide separate production credentials before you go live.

Q: What request format should I use?

A: Follow the method and parameter placement on each endpoint’s reference page:

• POST: Send form-encoded parameters using application/x-www-form-urlencoded.

• GET: Send parameters in the query string.

• Responses: Returned as JSON.

A JSON response does not mean the endpoint accepts a JSON request body.

Q: Why is my signature invalid?

A: Check that the Account ID, API key, and shared secret belong to the same environment. Generate the SHA1 hash from the API key, shared secret, and current date in YYYY-MM-DD format, concatenated in that order, and pass it as Signature. You can use any timezone: VoPay’s signature validation accounts for date differences caused by timezones.

Q: Do I need to whitelist IP addresses in sandbox?

A: No. IP whitelisting is optional in both sandbox and production. You can start sandbox testing without configuring an authorized IP list.

If you choose to use IP whitelisting, manage the list through /account/authorized-ips. The POST operation replaces the list, so retrieve the existing list before adding an IP.

Q: How can I test retries without creating duplicate payments?

A: Include an IdempotencyKey when creating a transaction and keep the same key when retrying that same operation. The docs describe duplicate-key retries as returning an error rather than creating another transaction. Check the original transaction before creating a new operation with a new key. See Idempotent Requests.

Q: How do I configure and troubleshoot webhooks?

A: Start by registering a publicly reachable URL, then test delivery:

Your endpoint must respond with HTTP 200. Failed deliveries are retried at 15-minute intervals, with three attempts in total.

A localhost URL cannot receive notifications directly. Use a public test URL or a tunnel. See Signature Verification to check that a notification came from VoPay.

Q: Can I simulate funds arriving in a virtual account?

A: Use /virtual-account/simulate-credit, supplying the virtual account ID and amount. This is a virtual-account testing endpoint.

Q: Can I simulate receiving an inbound Interac e-Transfer®?

A: No. Inbound Interac e-Transfer® simulation is not supported in sandbox. This is separate from the simulated Interac e-Transfer® Money Request experience.

Q: How can I test cancellations, refunds, returns, and flagged transactions?

A: Use the relevant endpoint and check its supported payment types and transaction-state requirements:

• Cancel a transaction: /account/transactions/cancel, before processing begins. Later cancellation requests depend on the payment rail.
• Refund a completed transaction: /account/transactions/refund, documented for EFT, ACH, Interac, and credit cards.
• Return a completed EFT or ACH transaction: /account/transaction/return.
• Confirm a legitimate flagged transaction: /account/transaction/confirm. Review the flag before releasing it; see Flagged Transactions.

For the transaction types covered by the cents rules, .20–.29 tests a failure after success, useful for return handling.

Q: Does the return simulation produce a return code?

A: Yes. For transactions covered by the cents-based rules, amounts ending in .20–.29 fail after reaching Successful status and generate a randomly selected return code. You can find the code in the webhook notification or by fetching the transaction details. The amount does not select a specific return code.

Q: Can partner-created accounts use the onboarding workflow suffixes?

A: Yes. When creating an account through /partner/account, add -WF0, -WF1, or -WF2 to the end of the Name parameter. For example, Name=Bruce Wayne-WF2 tests rejection at Compliance Review. The suffix belongs in Name; it does not need to be added to the legal name.

---

Going live

Q: What should I expect when moving from sandbox to production?

A: Your Implementation Specialist will guide you through the launch requirements:

• Integration certification: The integration team reviews your requests and responses before you go live.
• Production setup: Switch to the production base URL and credentials. Sandbox credentials and test data do not carry over.
• Optional IP whitelisting: If you choose to restrict API access by IP address, configure your production authorized IP list before launch.
• Portal readiness: Complete the compliance review and confirm your settings and transaction limits.

---

Account lifecycle and support

Q: What happens if I stop using my sandbox account?

A: Sandbox accounts with no activity for 30 days are deactivated. If you need longer, just ask and it will be kept open.

Q: Who do I contact for anything sandbox-related?

A: Your Account Representative. They are your contact for test bank details, questions about what is enabled on your account, and moving toward production.