Contractor & Gig Worker Payouts

Use this flow when you need to pay contractors, freelancers, or gig workers across corridors, including instant local rails where available.

✅ Before you start

Complete these steps before you run a contractor payout cycle:

1. Authenticate with the merged Login service and store the returned token and companyId.
2. Confirm the source wallet has enough availableBalance for the planned run.
3. Collect contractor banking, mobile-money, or stablecoin wallet details for each corridor.
4. Create and store beneficiary records for repeat workers so you can reuse them across cycles.
5. Register webhook endpoints so you can reconcile each payout outcome asynchronously.
6. Generate a unique paymentId or idempotency key per worker payment.

📚 Use this page with the recipe

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

Contractor & Gig Worker Payouts Recipe →

The contractor payout workflow

This use case follows a simple sequence:

1. Create or validate beneficiary records for each worker with Create beneficiary.
2. Check beneficiary readiness before adding a worker to the payable run.
3. Choose the right rail for the corridor — instant local rails such as M-Pesa or FPS where supported, or standard bank transfer otherwise.
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. Track payout state through webhooks for each item.
6. Reconcile final state back into your contractor management system.

What makes this use case different?

Unlike B2B supplier flows, contractor payouts usually need to:

• support C2B routes such as mobile money and instant local rails
• capture personal identity data required by certain corridors
• prove individual payment outcomes per worker rather than per run
• refresh beneficiary readiness before each cycle for active contractors

Where to go deeper

• Beneficiary Management Guide
• Send
• Currency Guides
• Webhooks

Troubleshooting

Next steps