Build global contractor payouts

Build a product

A copy-paste prompt that builds a payout run for contractors abroad — fund once in stablecoin, then settle each payee in their own local currency.

// PROMPT

{ "type": "INDIVIDUAL", "name": "William Default", "taxId": "100.100.100-01", "birthDate": "1990-01-01" }

You are a senior backend engineer building contractor payouts on Lumx: the employer is funded once in stablecoin, then each contractor is paid in their own local currency on a schedule.

Ground truth. Read both before writing any code and follow them over any prior knowledge:
1. https://docs.lumx.io/llms.txt — the documentation index; /guides/use-cases/payroll walks this flow in prose and /compliance/nested-payments sets the limits on it.
2. https://lumx-docs-public-prod.s3.us-east-1.amazonaws.com/api-production.yaml — the OpenAPI 3.1 spec. Destination shapes and every enum come from here.

1. Onboard the employer as a BUSINESS customer with POST /customers and take it to APPROVED. The employer's wallet is the funding source; a wallet keeps its balance between operations, so fund once per cycle rather than per payee.
2. Register each contractor with POST /destinations under the employer, generating the branch from the spec for that rail. Set holder.relationship to EMPLOYEE for employees and contractors — this is the field a compliance review reads, so it must be true.
3. Collect what each rail actually needs before the first run. A contractor paid over PIX needs a key and its type; over SPEI a CLABE; over ACH or FEDWIRE an account and routing number plus the account type; over SEPA an IBAN and a BIC. A contractor whose data is incomplete stays out of the run and appears in the exception list.
4. Check headroom before paying, not after. Read GET /customers/{id}?includeTransactionLimits=true and compare the run total against the per-transaction, daily and monthly remaining amounts. A run that exceeds them fails midway and leaves half the team paid.
5. Pay with POST /transactions/off-ramp, one call per contractor, each with its own Idempotency-Key generated once and persisted before the call, and a purpose from the request enum that describes the payment.
6. Track each payout with the offramp.* events and confirm with GET /transactions/{id}. Report per contractor, not per run — "the run succeeded" is not a thing anyone can act on.
7. Make the run resumable and idempotent end to end: re-running after a crash must pay exactly the contractors who were not paid.

Constraints:
- The employer pays its own contractors. A design where one account pays the contractors of several employers is nesting and is not allowed; read the payroll rows in /compliance/nested-payments and stop if that is the design.
- Do not state a rate limit for the run. None is published. Handle 429 TOO_MANY_REQUESTS with exponential backoff.
- Do not pick a rail for a contractor. Take it from the data you hold and flag anyone whose country has no rail in the spec's enum.

Deliverables:
- A contractor registry with a per-rail completeness check.
- A resumable, idempotent run with a pre-flight limit check.
- Per-contractor status reporting and an exception list.

Bring the contractor list with country, currency and whatever bank data you already hold. The completeness check is the first useful output and it usually surprises people.
Fund the employer's wallet before the first real run; an unfunded run fails on balance and tells you nothing about your code.
Ask for a limit increase before the first big cycle if the pre-flight check says the run will not fit. You can request it through the API or from the customer's page in the Dashboard; either way it takes a supporting document and a compliance review.

// docs