Frequently Asked Questions

Use this page to answer common Verto integration questions across authentication, Atlas for Fintech, Atlas for Platforms, sub-accounts, compliance, webhooks, retries, settlement, and sandbox testing.

🔐 Authentication

Q: Why do you recommend Certificate-Based auth over API keys?

A: Certificate-based authentication encrypts the login payload and is the recommended method for all new integrations. API key-based authentication remains useful for legacy flows and sandbox testing, but it will be deprecated in a future release. See Certificate-Based Authentication and Authentication.

Q: How long is a JWT access token valid?

A: Standard bearer tokens are valid for 3,600 seconds (1 hour). Refresh or regenerate the token before it expires, and avoid reusing expired tokens on protected requests. See Authentication.

Q: Which login route should I use for new integrations?

A: Use the merged company login route for new integrations. In sandbox, authenticate through https://api-company-sandbox.vertofx.com/users/login, then use the returned bearer token and company context for service-specific requests. See Authentication, Environments, and Legacy Endpoint Migration Guide.

Q: Should every sub-account have its own API credentials?

A: No. Authenticate with your master account credentials, then route customer-specific actions using the approved sub-account context. Use X-Sub-Account-Id for server-side orchestration or a scoped sub-account token for a session limited to one customer. See Sub-Accounts and Login as Sub-Account.

---

🧭 Choosing an Atlas track

Q: What are the two Atlas tracks?

A: Atlas supports two tracks: Atlas for Fintech and Atlas for Platforms. Atlas for Fintech is for regulated financial institutions that own their downstream customer compliance controls. Atlas for Platforms is for non-financial businesses, marketplaces, SaaS platforms, payroll providers, and similar businesses where Verto performs downstream KYB or KYC. See Choose the right APIs.

Q: How do I know whether I should use Atlas for Fintech or Atlas for Platforms?

A: Choose Atlas for Fintech if you are a regulated FI, MSB, PSP, EMI, or similar institution and Verto has approved reliance on your compliance framework. Choose Atlas for Platforms if Verto needs to verify your downstream customers directly as referred clients. See KYC & Compliance Requirements.

Q: Can I switch tracks later?

A: A track change requires compliance and operational review because it changes who owns downstream customer verification and how sub-accounts are approved. Do not assume you can move from Platform to Fintech, or from Fintech to Platform, without Verto approval. See Go-Live Requirements.

Q: Do both tracks support sub-accounts?

A: Yes. Both tracks can use sub-accounts to isolate customer identity, balances, and activity. The main difference is who performs and owns downstream customer verification. See Verto Architecture Basics and Sub-Accounts.

---

🏦 Atlas for Fintech

Q: What is Atlas for Fintech designed for?

A: Atlas for Fintech is designed for regulated financial institutions that manage their own customer relationship and compliance program. Verto relies on your approved controls while providing global treasury, wallet, FX, receive, and payout rails. See Choose the right APIs.

Q: Who performs KYC or KYB in Atlas for Fintech?

A: You perform downstream customer KYC or KYB under the compliance tier Verto has approved for your program. Verto may require different levels of sub-account information depending on whether your integration is approved for Level 0, Level 1, or Level 2 KYC. See KYC & Compliance Requirements.

Q: What is the reliance model?

A: The reliance model means Verto relies on your compliance framework for downstream customer verification after assessing your AML, financial crime, MLRO, transaction monitoring, and audit controls. The result of that assessment determines the level of information Verto requires per sub-account. See KYC & Compliance Requirements.

Q: What happens if my compliance program does not qualify for the Fintech track?

A: If your downstream assessment does not qualify for reliance, you may be routed to Atlas for Platforms instead. In that model, Verto performs full direct KYC or KYB for each downstream customer before operational activation.

Q: Do Fintech sub-accounts need to wait for Verto approval before every action?

A: Operational access depends on your approved compliance tier and the sub-account state. Treat compliance status as a hard control in your application, and do not enable wallets, account issuance, or payouts until the sub-account is allowed to operate under your approved model.

---

🏢 Atlas for Platforms

Q: What is Atlas for Platforms designed for?

A: Atlas for Platforms is designed for non-financial businesses that want to embed global accounts, wallets, collections, FX, or payouts for downstream business users. Verto handles downstream customer verification, while your platform orchestrates the customer experience. See Build Marketplace Payment Flows with Atlas.

Q: Can I create sub-accounts for individuals or retail users?

A: Currently, Atlas focuses on Business-to-Business (B2B) and Business-to-Merchant (B2M) flows. Platform users must be registered legal entities or sole traders.

Q: Who is responsible for KYC on my Platform sub-accounts?

A: Verto is responsible for downstream customer verification in Atlas for Platforms. Platform sub-accounts are treated as direct referred clients of Verto and must complete the required review before they become operationally active. See KYC & Compliance Requirements.

Q: What is Level 3 KYC?

A: Level 3 KYC is the full direct KYC model used for Atlas for Platforms. Every sub-account must submit the required information and documents, pass Verto Compliance review, and complete any required T&C acceptance before operational activation.

Q: Why does a director need to accept Verto terms?

A: In the Platform model, the downstream customer has a direct regulated relationship with Verto. A company director may need to accept the relevant Verto Terms & Conditions and Partner Access Agreement before the sub-account becomes active.

Q: Can a Platform sub-account transact while KYC is pending?

A: No. Treat pending, in-review, T&C pending, rejected, or suspended states as blockers for operational actions. Do not allow wallet creation, account issuance, FX, receive, or payout flows until the sub-account reaches the approved active state.

---

🧩 Sub-accounts and context

Q: When should I create a sub-account?

A: Create a sub-account when a downstream customer needs isolated identity, compliance state, balances, account details, statements, beneficiaries, or payouts. Use your master account for your own funds and use sub-account context for downstream customer funds. See Sub-Accounts.

Q: When should I use X-Sub-Account-Id instead of a scoped sub-account token?

A: Use master auth + X-Sub-Account-Id for server-side orchestration across many downstream customers. Use a scoped sub-account token when you want a session limited to one customer context, such as a customer-specific dashboard. See Login as Sub-Account and Sub-Accounts.

Q: What happens if I omit X-Sub-Account-Id?

A: The request may run in the master account context instead of the intended downstream customer context. For customer-owned wallets, beneficiaries, statements, receive flows, FX, or payouts, include the correct sub-account context to avoid creating or moving resources in the wrong account.

Q: Should I store the sub-account ID?

A: Yes. Store the returned sub-account ID in your system and map it to your internal customer record. You need it to route wallet, receive, exchange, beneficiary, statement, and payout actions to the correct customer context.

Q: Can one customer have multiple wallets?

A: Yes. A sub-account can use wallets for the currencies and flows your account is approved to support. Create wallets only after the customer is operationally eligible, and keep wallet IDs mapped to the correct sub-account. See Wallets and Create Wallets.

---

✅ KYC, KYB, and compliance state

Q: Does the parent entity need to complete onboarding first?

A: Yes. Your parent entity must complete Verto compliance clearance, standard onboarding requirements, and platform registration before downstream sub-accounts can be activated. See Go-Live Requirements.

Q: What compliance states should block customer actions?

A: Block operational actions while a sub-account is pending, in review, T&C pending, rejected, or suspended. Only allow wallet creation, account issuance, receive, FX, and payout flows after the customer reaches the approved active state for your integration.

Q: What should my application do when a sub-account is pending review?

A: Keep the customer in onboarding, display the next required step, and prevent money movement actions. Store the compliance state in your system so your UI and operations team do not treat the customer as ready before Verto or your approved compliance process allows it.

Q: What is an RFI?

A: An RFI is a request for information. It means more details or documents are required before a compliance review, payout, account issuance, or related operation can continue. Pause the affected workflow, collect the requested information, and resume only after the issue is resolved. See Handle RFIs and Compliance Exceptions.

Q: Can compliance review affect settlement or payout timing?

A: Yes. Compliance review, RFIs, corridor rules, and bank rail processing can affect timing. Design your integration to show pending states clearly and reconcile final outcomes through webhooks instead of assuming a fixed completion time.

---

💳 Wallets, payments, and payouts

Q: Should I create wallets before or after sub-account approval?

A: Create wallets only when the sub-account is operationally eligible under your approved model. For Platform integrations, wait until the customer has completed the required Verto review and activation steps.

Q: How should I decide whether a wallet belongs to the master account or a sub-account?

A: Use the master account wallet when the funds belong to your own business. Use a sub-account wallet when the funds, account details, statements, or payouts belong to a downstream customer.

Q: Do I need a beneficiary before creating a payout?

A: Yes. Create and validate the beneficiary first, then reuse the approved beneficiary for payout flows. Keep the beneficiary in the same account context as the wallet and customer that will fund the payout. See Beneficiary Management Guide and Send.

Q: Can I create a payout immediately after creating a beneficiary?

A: Only proceed when the beneficiary, funding wallet, account context, and compliance state are ready. If the beneficiary or customer is under review, wait for the approved state before initiating the payout.

Q: Should I create a new payout if I do not receive a response?

A: No. Retry only with the same Idempotency-Key, then reconcile the final result through webhook events or follow-up reads. Do not send a new payout request with a new key unless you have confirmed the first request did not create an operation. See Errors and Retries and Send.

---

🔔 Webhooks & retries

Q: Should I poll for payout or receive status?

A: No. Use webhooks to track receive, FX, refund, statement, and payout state changes, then update your internal ledger from those events. See Webhooks and Webhook Event Handling.

Q: What should I do if a payout request times out?

A: Retry only with the same Idempotency-Key, then reconcile the final result through webhook events or follow-up reads. Do not send a new payout request with a new key unless you have confirmed the first request did not create an operation. See Errors and Retries and Send.

Q: Which webhook events should platforms care about most?

A: Prioritize events that change customer access or ledger state, such as sub-account approval, inbound payments, transaction state changes, payout status changes, FX state changes, and RFI-related updates. Use those events to update your internal customer state and ledger records.

Q: Why should I acknowledge webhooks quickly?

A: Acknowledge webhook delivery quickly so the sender does not retry the same event unnecessarily. Process longer business logic asynchronously after storing the event and checking whether you have already handled it.

Q: How do I avoid processing the same webhook twice?

A: Store a unique event identifier or idempotency marker for each webhook before running business logic. If the same event arrives again, return a successful acknowledgement without applying the same ledger or status update twice.

---

💰 Settlement and sandbox testing

Q: Are wallet-to-wallet transfers instant?

A: Yes. Internal wallet-to-wallet transfers happen on the Verto ledger and typically settle in real time (< 100ms) because they do not use external payment rails. See Wallets.

Q: Does sandbox prove production settlement timing?

A: No. Sandbox is useful for testing authentication, webhook handling, retries, and logic flows, but live settlement timing can vary by corridor, bank rail, and compliance review. See Testing and Testing & Sandbox Guide.

Q: What should I test in sandbox before going live?

A: Test authentication, service-specific routes, sub-account creation, compliance-state handling, wallet setup, receive flows, beneficiary creation, payout initiation, idempotent retries, webhook processing, and reconciliation. See Testing & Sandbox Guide.

Q: Should I use sandbox data as proof that a corridor is production-ready?

A: No. Sandbox validates your integration behavior, not live bank rail performance or final corridor approval. Confirm production readiness through your go-live process and any corridor-specific requirements.

Q: Where should I start if my integration is failing in sandbox?

A: Start with authentication, then confirm the service-specific base URL, account context, sub-account status, wallet ID, beneficiary ID, and idempotency key. If the issue involves an asynchronous state change, check webhook delivery and your internal event logs before retrying.

---