[

Build marketplace seller payouts

]

Build a product

Build marketplace seller payouts

A copy-paste prompt that builds a marketplace where each seller is onboarded, the platform takes a fee on every sale and sellers settle in local currency.

// PROMPT

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

You are a senior backend engineer building seller payouts for a marketplace on Lumx. The platform takes a cut of every sale; each seller gets paid in their own local currency.

Ground truth. Read all three before writing any code and follow them over any prior knowledge:
1. https://docs.lumx.io/compliance/nested-payments — this decides whether the design is legal before it decides whether it works. Read it first.
2. https://docs.lumx.io/llms.txt — the documentation index; /guides/use-cases/marketplaces walks the same flow in prose.
3. https://lumx-docs-public-prod.s3.us-east-1.amazonaws.com/api-production.yaml — the OpenAPI 3.1 spec, for every field, enum and required flag.

1. Settle the structure first. Every seller must be onboarded as its own Lumx customer and receive funds in its own wallet. A design where buyer money pools in the platform's account and the platform distributes it is nesting and is not allowed. If the product spec requires that, stop and report it.
2. Configure the platform's cut once with POST /partner-fees: a name, the platform's own walletAddress, and rate in basis points plus flatAmount for onRamp and offRamp. Keep the id.
3. Onboard each seller with POST /customers — BUSINESS for incorporated sellers, INDIVIDUAL for sole traders — and pass the accounts array only for sellers who receive fiat from outside your checkout. Sellers paid through your own checkout need no account; the on-ramp credits their wallet directly.
4. Take the money in. For a buyer paying on your checkout, create POST /transactions/on-ramp on the seller's behalf with your partnerFeeId, then render state.payment for the buyer. For a seller collecting from an external platform into a virtual account, the deposit arrives on the account instead.
5. Pay the seller out. Register the seller's own bank account with POST /destinations using holder.relationship SELF — the seller is paying itself — and settle with POST /transactions/off-ramp.
6. Reconcile three ledgers per sale: what the buyer paid, what the seller received, and what the platform kept. Read the fee breakdown from the locked-rate response or the transaction receipt; never compute the platform's revenue by subtraction.

Constraints:
- A seller who has not reached APPROVED cannot receive funds. Read the status from GET /customers/{id} and model it as a product state with its own screen, not as an error.
- Purpose comes from the request enum and must describe the real trade. PERSONAL_ACCOUNT is only valid with a SELF destination.
- Do not state a rate limit while paying a batch of sellers. None is published. Handle 429 TOO_MANY_REQUESTS with exponential backoff.

Deliverables:
- A seller onboarding flow with the pending and rejected states handled.
- Checkout and external-collection paths, both carrying partnerFeeId.
- A three-way reconciliation per sale, read from API data rather than derived.
- A written answer to the nesting question in step 1.

  1. Answer the nesting question with whoever owns compliance before building. It decides the product, and no amount of code fixes a pooled design.

  2. Set the platform rate with whoever owns pricing; it lands in every buyer-facing quote.

  3. Onboard two sandbox sellers in different countries. One seller hides every problem this flow has.

TALK TO OUR TEAM

Ready to transform your business with stablecoins?

Discover how our infrastructure can seamlessly integrate stablecoins into your financial operations quickly, securely, and efficiently.

©2026. All rights reserved.

LUMX SOCIEDADE PRESTADORA DE SERVIÇOS DE ATIVOS VIRTUAIS LTDA., a private legal entity, enrolled with the CNPJ/MF under No. 42.887.120/0001-00 ("Lumx"), acts as a virtual asset service provider and is in the process of adapting to the regulatory regime for Virtual Asset Service Provider Companies (SPSAV), pursuant to Central Bank of Brazil (BCB) Resolution No. 520/2025, currently being subject to the transition regime set forth in Article 88 thereof.


Lumx US OP LLC ("Lumx") is a financial technology and payments infrastructure company. Lumx US OP LLC is a Money Service Business (MSB) registered with the Financial Crimes Enforcement Network (FinCEN) (MSB #31000316459619). Lumx is not a state-licensed money transmitter and does not, in its own capacity, engage in the provision of regulated money transmission services. All such regulated activities are conducted exclusively through, and under the licenses of, duly authorized financial-institution partners.


Lumx is not a bank, financial institution, payment institution, or custodian of client funds. Certain services made available through the Platform may be provided by duly authorized and regulated third-party partners, in accordance with applicable laws and regulations.

Please refer to Lumx’s Terms of Use and Privacy Notice for further information regarding the conditions governing the use of the Platform and the processing of your personal data.