Legacy Endpoint Migration Guide

Use this guide to migrate your integration from legacy Verto sandbox endpoints to the new service-specific sandbox endpoints.

The legacy sandbox routes use https://api-v3-sandbox.vertofx.com as the shared host. The new routes split traffic across service-specific hosts for company authentication, beneficiaries, payments, currencies, and wallets.

Prerequisites

Before you start the migration:

1. Review your current integration and list every request that uses https://api-v3-sandbox.vertofx.com.
2. Confirm which service each request belongs to: authorization, beneficiary, listing, withdrawal, or wallet.
3. Update your environment configuration so base URLs can be changed per service instead of stored as one shared API host.
4. Test each migrated route in sandbox before moving the same pattern to production.

Migration steps

1. Replace the shared legacy host

Replace the shared legacy sandbox host with the new host for each service.

2. Update endpoint paths

Update each legacy path to its new service-specific path. Some resources also use new naming conventions.

For beneficiary endpoints, beneficiaries becomes recipients, and path parameters change from {beneficiaryId} to {recipientId}.

For wallet endpoints, include {companyId} in the route before the wallet path.

3. Keep authentication separate from service calls

Use the migrated company login route to authenticate first:

POST https://api-company-sandbox.vertofx.com/users/login

After login, use the returned authentication context required by your integration when calling the service-specific APIs.

4. Test migrated requests by service

Migrate and test one service at a time:

1. Start with authorization so your bearer token flow works.
2. Migrate read-only listing routes, such as purpose codes and currencies.
3. Migrate beneficiary read operations before create, update, or delete operations.
4. Migrate wallet list and detail routes.
5. Migrate payment request creation and lookup routes last, after dependency services are working.

Endpoint mapping

Use this table to replace each legacy sandbox route with its new sandbox route.

Route changes to account for

Beneficiary routes now use recipients

Beneficiary routes now use /recipients on the beneficiary service host.

Update any route builders, logs, retry metadata, and reconciliation records that store the old beneficiary route or path parameter name.

Wallet routes now include companyId

Wallet routes now include {companyId} in the path:

GET https://api-wallet-sandbox.vertofx.com/{companyId}/wallets
GET https://api-wallet-sandbox.vertofx.com/{companyId}/wallets/{walletId}

Store companyId from your authentication flow and pass it when building wallet service requests.

Payment request lookup route changed

The legacy single payment request route included {requestID} in the path:

GET https://api-v3-sandbox.vertofx.com/profile/v2.1/request/{requestID}

The new route points to the payment list endpoint:

GET https://api-payment-preview.vertofx.dev/payments/list

Update your client code so payment request lookups use the new payment service route.

Migration checklist

Before you finish the migration, confirm that you have:

• Replaced the shared legacy host with service-specific hosts.
• Updated beneficiary paths from /beneficiaries to /recipients.
• Updated beneficiary path parameters from {beneficiaryId} to {recipientId}.
• Added {companyId} to wallet list and detail routes.
• Updated payment request creation to use /payments/create.
• Updated payment request listing and lookup calls to use /payments/list.
• Tested authorization before testing dependent service requests.
• Verified that sandbox configuration uses the new hosts consistently across environments.

Open questions

The following details are not yet confirmed. Reach out to your Verto contact before completing migration:

• Production hosts. This guide currently lists sandbox hosts only. Production equivalents will be published before the January 30, 2027 sunset.
• Authentication scope. Confirm whether the bearer token returned by https://api-company-sandbox.vertofx.com/users/login works unchanged across all new service hosts, or whether each service requires its own token.
• Request and response payloads. Path parameter renames are documented (for example, {beneficiaryId} → {recipientId}), but body field, response field, and error code changes are not yet confirmed for each migrated route.
• No-replacement endpoints. Named Enquiry, FX Service routes, and proof-of-payment retrieval do not yet have new-host equivalents. Continue calling the legacy host until a replacement is announced.

Related guides

• Authentication: Choose an authentication method and obtain a bearer token.
• Environments: Review sandbox and production environment details.
• Beneficiary Management Guide: Create and manage beneficiary records with the merged Beneficiary service.
• Wallets: Manage wallets and use the migrated wallet routes.
• Send: Send funds to beneficiaries and track payout state changes.
• Currency Guides: Review supported currencies and corridor guidance.