Run Cross-Border Payroll Payouts

Use this flow when you need to fund a payroll run, reuse approved beneficiaries, convert balances into payout currencies, and reconcile salary or contractor disbursements through webhook-driven status updates.

✅ Before you start

Complete these steps before you run payroll through Verto:

1. Authenticate with the merged Login service and store the returned token and companyId.
2. Decide whether you are sending payouts from your own wallet or on behalf of downstream customers.
3. Collect the beneficiary and bank-routing or stablecoin wallet data for every employee or contractor you need to pay.
4. Create and store beneficiary records so you can reuse them across recurring pay runs.
5. Make sure the source wallet has enough availableBalance for the full payroll run or planned batch segment.
6. Register webhook endpoints so you can reconcile each payout outcome asynchronously.
7. Generate a unique paymentId or idempotency key for every worker payment, not only for the run as a whole.

Use Environments to configure the merged service hosts for Login, Wallet, Beneficiary, and Exchange.

📚 Use this page with the recipe

This guide explains when to use the payroll payout flow and the minimum sequence. For the implementation walkthrough, use the recipe:

Run Cross-Border Payroll Payouts Recipe →

The payroll payout workflow

This use case follows a simple sequence:

1. Create or validate beneficiary records for each worker with Create beneficiary and Fetch beneficiary by ID.
2. Check beneficiary readiness before adding a worker to the payable batch.
3. Confirm wallet balance with Get all Wallets before each batch segment.
4. Get an FX rate and create the FX trade with Get FX rate and Create FX trade when the payout currency differs from the source wallet currency.
5. Store paymentId and trade reference for each worker payment.
6. Track payout states through webhooks instead of polling for each item.
7. Reconcile completed, failed, rejected, or refunded outcomes back into your payroll or finance system.

Before you submit a worker payment, check:

What makes this use case different?

Unlike a one-off payout flow, payroll usually needs you to:

• reuse beneficiary records safely across recurring cycles
• apply deterministic reconciliation for every worker payment
• isolate failures so one bad item does not force a full rerun
• refresh beneficiary readiness before each pay cycle because a beneficiary can later require updates or become inactive
• create a new FX rate token for each execution window because vfx_token values are short-lived

Optional: Run payroll in batches

If your payroll run contains many payouts, process the run in smaller batches and keep the paymentId or idempotency key at the individual payment level.

This helps you retry only the affected items when a timeout or route-specific delay occurs.

Where to go deeper

Use the product guides when you need implementation detail for a specific step:

• Beneficiary Management Guide
• Exchange
• Send
• Bulk Supplier Disbursement
• Webhooks

Troubleshooting

Next steps