Guides

Stablecoin API sandbox testing: the checklist before production

Stablecoin API sandbox testing checklist: keys and hosts, KYB test data, pay-in and payout runs, failure statuses, webhooks, idempotency and go-live gates.

Caio Barbosa

Founder & CO-CEO

Forbes Under 30. One of the leading voices in Fintech & Crypto in Brazil. Writes weekly about stablecoins, payments, and the future of financial infrastructure in Latin America.

Cover image for Lumx blog article: Stablecoin API sandbox testing: the checklist before production
Cover image for Lumx blog article: Stablecoin API sandbox testing: the checklist before production

Stablecoin API sandbox testing means running every money path against test stablecoins and mock banks before real funds move: keys and hosts, each verification outcome, a pay-in and a payout end to end, every failure status, webhook signatures and redelivery, idempotent retries, expired quotes and a daily reconciliation. Pass all of them, then flip the environment.

What should a stablecoin API sandbox test cover?

A sandbox proves that your code handles the states of a payment, not that the payment works. The provider already knows a Pix (Brazil's instant payment system) transfer settles. What it cannot know is whether your ledger credits a user twice when a webhook arrives late, or whether your screen freezes on a status nobody showed in the demo.

The checklist follows the order you will meet each area:

Area

What passes

What it protects

Keys and hosts

Host and key come from config; the sandbox call never reaches production code

A test call that moves real money

Customer verification

Every verification outcome drives the right screen

A customer stuck with no next step

Pay-in and payout

One full round trip, status by status

A ledger that credits before the money is final

Failures

Every terminal status has a handler, tested

Silent losses and support tickets

Webhooks

Signature, replay window, dedupe, retry

Forged events and double credits

Idempotency and quotes

A retried write never pays twice; an expired quote fails cleanly

Duplicate payouts and wrong rates

Reconciliation

API records match your ledger every day

Drift you find at month end

Checklist areas for a stablecoin payments API sandbox, built from the Lumx docs pages listed under Methodology, read November 17, 2026.

If you are still choosing the order of the whole build, the seven-step integration guide covers scope and compliance; this post is the test plan that sits inside it.

Keys, hosts and environments

Start with the boring part, because it is where a sandbox test turns into a real payment.

  1. Two hosts, both from configuration. On Lumx, sandbox runs at api-sandbox.lumx.io on testnet stablecoins with mock banking partners, and production runs at api.lumx.io on mainnet and live rails. Same API surface, separate data. Neither host should be a literal in your code.

  2. Keys on the server only. A key belongs in a secret store, never in a client bundle or in version control. Lumx shows a key once at creation, so store it before you close the page, and rotate it from the Dashboard if it leaks.

  3. Sandbox-only calls stay out of shared paths. Lumx has a simulate-deposit endpoint that exists only in sandbox and returns 404 in production. Keep it in test code.

  4. The IP allowlist. It applies to production only; sandbox accepts any IP. Register your server addresses before go-live, and read the authentication page on the day you switch to see whether enforcement is on.

New Lumx accounts start in sandbox. Production access comes through a conversation with the team, not a setting, so book that call before the code is finished.

KYB and KYC test data: how do you force each outcome?

Verification is the first branch the happy path hides. KYB (know your business, the verification of a company and its owners) and KYC (know your customer, the verification of an individual) can each end in more than one state, and your onboarding screen needs a next step for every one. The KYB onboarding flow walks through the screens.

The Lumx sandbox drives the outcome from the last digit of the customer's tax ID:

Tax ID ends in

Simulated status

What your app should do

1

NOT_STARTED

Show the verification link and wait

2

RFI

Ask for the missing information and resubmit

3

FINAL_REJECTION

Stop onboarding and explain the next step

Any other digit

APPROVED

Open the account flow

Sandbox verification outcomes, from the Lumx identity verification page, read November 17, 2026.

An RFI (request for information, a compliance hold that asks for a document before a customer or transaction clears) is the case worth the most attention. The customer can resubmit, so your app needs a path back in, not a dead end. Our post on answering an RFI covers what the reviewer usually wants.

Two sandbox details save an afternoon. The terms-of-service call is a POST with an empty JSON body; a POST with no body at all is rejected with 411. And after approval, an account moves from REQUESTED to PROVISIONING to ACTIVE in about a minute in sandbox, so your test should wait for ACTIVE rather than assume it.

Pay-in and payout happy paths

Run one complete round trip before anything else, and assert every status in between, not only the last one.

Pay-in. Create an approved customer with a BRL account, start an on-ramp and follow it. On Lumx the on-ramp moves through AWAITING_FUNDS, TRANSFERRING_FIAT, TRADING and TRANSFERRING_STABLECOIN to SUCCESS. In sandbox the Pix payment is simulated and the on-ramp completes on its own, crediting test stablecoin to the customer's wallet. The on-ramp integration guide explains what each status means for the payer.

Payout. Use that balance to test the other direction. Register a destination, wait until its holder is verified, then run the off-ramp through TRANSFERRING_STABLECOIN, TRADING and TRANSFERRING_FIAT to SUCCESS. Our guide to payout statuses by rail maps each status to what the recipient sees.

What to assert on each run:

  • Your ledger moves only on the final status, never on an intermediate one.

  • The required purpose field is set on every transaction.

  • The status screen shows each intermediate state with a plain-language label.

  • Each customer has a wallet on every supported network, and the network you pass on the request, or the project default, is the one the funds land on.

Then reconcile the run, the test that keeps going after launch. Each day, pull the day's transactions through the paginated list call, match each one to your ledger by ID and status, and flag anything that is in one and not the other. Never assume a list fits on one page. The virtual account reconciliation guide shows the matching rules for deposits.

Failure statuses the sandbox will not produce for you

This is the gap to plan for. The Lumx sandbox has documented triggers for verification outcomes, but no documented trigger that forces a transaction to fail. You cannot make an off-ramp end in failed or expired on demand, and mangling a request to provoke one only tests the validation layer.

So test failures another way:

  1. List every terminal status from the docs. For on-ramps, off-ramps and transfers, the end states are success, failure and expiry, each with its own webhook event.

  2. Replay recorded events. Capture real sandbox webhook payloads from a successful run, then change the event type and status to build failed and expired versions. Feed them through the same signature-checked handler your production code uses.

  3. Assert the money side. A failed payout must release the reserved balance in your ledger. An expired on-ramp must never credit the user.

  4. Test the late deposit. On Lumx, a fiat deposit that lands after the on-ramp expired is refunded to the sender on the same rail. Your app should show that refund, not a missing payment.

  5. Match on the error code, never the message. The Lumx error catalog includes INSUFFICIENT_BALANCE, TRANSACTION_LIMIT_EXCEEDED, KYC_NOT_APPROVED, RAIL_NOT_ENABLED, BLOCKCHAIN_NOT_ENABLED, STABLECOIN_NOT_ENABLED and INVALID_PAYMENT_DESTINATION. A few come from a valid request the provider refuses, such as USDT on Base, which Lumx does not carry; trigger those in sandbox. An unknown code should degrade to a generic error, not throw.

I would write the failure handlers before the happy path is polished. Teams that test success first tend to ship failure screens nobody has seen, and those are the screens a customer meets on the worst day of their month. If a status has no test, I treat it as unhandled.

Webhooks: signatures, retries, duplicates

Webhooks are the easiest part to test badly. The checks below follow the Lumx webhook spec; the webhooks guide explains the reasoning behind each one.

  • Signature on the raw body. Lumx signs each message with HMAC-SHA256 over the message ID, the timestamp and the body, sent in the webhook-id, webhook-timestamp and webhook-signature headers. Verify against the raw bytes before any JSON parsing. Strip the whsec_ prefix and base64-decode the secret first.

  • A forged event fails. Send one with a wrong signature and assert a rejection.

  • A stale event fails. The Lumx example rejects messages more than five minutes old. Test one just outside your window.

  • Rotation does not drop events. After a secret rotation both secrets sign for 24 hours, so accept any valid signature in the header and test with two.

  • The same event twice changes nothing. Deduplicate on webhook-id and replay one event. Your ledger should move once.

  • Out of order happens. Deliver success before an intermediate status and check that your state does not move backwards.

  • Your endpoint can go down. Lumx retries immediately, then after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours, then marks the message failed for a manual retry from the Dashboard. Return an error from your endpoint in sandbox and watch the retry arrive.

A webhook is a notification, not the record. When in doubt, read the transaction from the API.

How do you test idempotency and expiring quotes?

A retried write is where a sandbox bug turns into a duplicate payout. The idempotency keys guide covers the design; these are the tests.

Idempotency. On Lumx, every write that moves money or creates a customer takes an Idempotency-Key header, and a UUID v4 is the recommended format.

  • Store the key before the first call, then retry with the same key and body. You should get the cached response back, with the X-Idempotent-Cached header set to true.

  • Retry with the same key and a different body. Expect a 409 with IDEMPOTENCY_KEY_CONFLICT.

  • Fire two calls with the same key at once. Expect a 409 with IDEMPOTENCY_KEY_IN_FLIGHT on the second, and make sure your code waits and reads rather than generating a new key.

  • Failed responses are cached too, except a 400 VALIDATION_ERROR. Assert that a retry after a business failure returns the same failure.

  • Keys expire after 24 hours. A retry queue that can hold a request longer needs another guard, such as checking the transaction list first.

Quotes. A locked rate has an expiry. Request a quote, let it lapse, then use it, and assert you handle EXCHANGE_RATE_EXPIRED by requesting a fresh quote and showing the new rate. Use the same quote twice and handle EXCHANGE_RATE_ALREADY_USED. The quote errors guide lists what each code means. On Lumx, a locked-rate on-ramp expires with its quote, while a floating-rate on-ramp expires after one day on Pix and SPEI (Mexico's interbank transfer system) and after seven days on other rails.

Rate limits. Lumx does not publish a rate limit, and its error catalog lists TOO_MANY_REQUESTS with a 429. Make sure every retry backs off, and ask for the limit before a bulk run.

When sandbox testing is the wrong place to look

A sandbox answers questions about your code, not about the real world.

Sandbox will not tell you how long a real verification takes, because the sandbox returns the outcome at once. It will not show a bank's own review on the receiving side, real settlement windows and cut-offs, or the liquidity behind a large conversion. A mock bank will not reject a destination the way a real one can. And testnet tokens have no financial value, so a test balance tells you nothing about funding.

Those questions belong to a small production pilot and a call with the provider, not to more sandbox runs.

Go-live gates, in order:

  1. Every item above passes, and each failure test has a named owner.

  2. Hosts and keys come from production config, and the simulate-deposit call is unreachable there.

  3. Server IPs are on the production allowlist.

  4. The production webhook endpoint is registered, and its secret is stored.

  5. Production customers and destinations exist, created again, since sandbox data does not carry over.

  6. The first real payment is small, watched end to end, and reconciled the same day.

Testing against the Lumx sandbox

Lumx is stablecoin payments infrastructure for businesses that move money between Latin America and the rest of the world: one API to collect, hold, convert, and pay out in BRL, MXN, COP, USD, EUR, and GBP or in USDC and USDT, over local rails such as PIX, SPEI, PSE, Bre-B, ACH, FEDWIRE, SEPA, and Faster Payments, with SWIFT and on-behalf-of payments and collections (POBO and COBO) in USD, EUR, and GBP, plus named virtual accounts, custodial wallets, and KYB/KYC built in.

The sandbox is self-serve: create a key in the Dashboard under Developers, then API Keys, and point your code at api-sandbox.lumx.io. The docs ship two prompts for coding agents, a sandbox quickstart that runs a converted deposit end to end and a production readiness checklist that audits what changes when the environment does.

Each customer gets a custodial wallet on Ethereum, Polygon, Base, Tron and Stellar, and Lumx covers the network fee on its own legs, so your test customer does not need to hold ETH or TRX. See custodial wallets for how they work. The rates for a first pay-in test are on BRL to USDC, every currency and rail is on the payment coverage page, and the full product is in global payments.

Methodology and sources

Lumx facts come from our public documentation, all read November 17, 2026: Environments, Authentication, Identity verification, Transactions, Wallets, Webhooks, Idempotency, Errors, Simulate a deposit, the pay-in quickstart, the payout quickstart, the sandbox quickstart prompt and the production readiness checklist.

The statement that testnet tokens have no financial value comes from Circle's USDC contract addresses page, read the same day.

Two negatives were checked: the Lumx pages read give no documented way to force a transaction failure in sandbox, and no published rate limit. If either appears in the docs, this post is out of date.

Verified on November 17, 2026. Operational context, not legal, tax, or investment advice.

Cover photo: Isis França on Unsplash.

  • What is stablecoin API sandbox testing?

    It is running every payment path of a stablecoin API against test stablecoins and mock banks before real money moves. A complete test covers keys and hosts, each verification outcome, a pay-in and a payout end to end, every failure status, webhook signatures and retries, idempotent retries, expired quotes and reconciliation.

  • Can you test failed payouts in a stablecoin API sandbox?

    On Lumx there is no documented trigger that forces a transaction to fail in sandbox. Test failures by replaying recorded webhook events with failed and expired statuses through your real handler, and by triggering honest error codes, such as asking for a token on a network that does not carry it.

  • How do you test KYB outcomes in sandbox?

    In the Lumx sandbox the last digit of the customer's tax ID sets the outcome: 1 gives NOT_STARTED, 2 gives RFI, 3 gives FINAL_REJECTION and any other digit approves. Run one customer per outcome and check that your app shows a next step for each.

  • Does sandbox data carry over to production?

    No. Sandbox and production have the same API but separate data, so every customer and destination created in sandbox has to be created again in production. Keys are separate too, and the production IP allowlist applies only to production.

  • When is a stablecoin integration ready for production?

    When every checklist item passes and the environment switch is clean: production hosts and keys come from config, the sandbox-only deposit call is unreachable, server IPs are allowlisted and the webhook endpoint is registered. Then send a small first payment, watch it end to end and reconcile it the same day.

Stay up to date with what Lumx is developing.

Sign up to receive them by email.

Share on socials:

stablecoin-payments-api-sandbox-testing-checklist

A

stablecoin-payments-api-sandbox-testing-checklist

Stablecoin API sandbox testing: the checklist before production

Copy link

Copied!

stablecoin-payments-api-sandbox-testing-checklist

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.

Guides

In this page

©2026. All rights reserved.

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.