Skip to main content

Test Cashout

The cashout / settlement API has no sandbox simulator — a settlement moves real funds on-chain. Test it against staging, which settles on test networks, so a rehearsal spends only testnet value.

warning

There is no isSandbox for settlements. On staging the payout is a real testnet transaction; on production it moves real funds. Always rehearse on staging first.

Setup​

  • Have Finomesh enable the cashout API on your staging gateway, generate a signing secret, and allowlist your test server's IP.
  • Accumulate a matured testnet balance (run some sandbox/testnet payments and let them mature).
Sandbox-simulated payments don't fund a cashout balance

Simulated outcomes never credit your staging settlement balance — balances are built only from real swept transactions. To accumulate a cashout-able balance, run real testnet deposits (non-sandbox payments on staging), not sandbox simulations.

What to test​

  • Signing — a correctly signed request succeeds; a stale timestamp returns signature_stale; a tampered body returns signature_invalid.
  • IP gate — a call from a non-allowlisted IP returns ip_not_allowlisted.
  • Balances — GET balances reports your matured totalAvailable.
  • Create — request a small settlement ≤ totalAvailable; confirm it starts REQUESTED. Requesting more than available returns a 409 conflict.
  • Idempotency — replay the same Idempotency-Key with the identical body (safe retry, no second settlement); replay it with a different body and confirm 409 idempotency_conflict.
  • Status — poll GET /:id to SETTLED (there is no settlement webhook); confirm txHash and blockchainUrl populate.