Sandbox

Audience: anyone integrating Mooov — platforms on Mooov Connect and merchants using a direct API key. Build and certify with test keys before you touch live money.

Test mode uses the same canonical API host and the same HMAC auth, webhook envelopes, and state machine as live — no real money moves. The API key environment is authoritative.

Building with an AI agent or MCP-capable editor? It can pull these docs and schemas itself; see Connect your AI agent.

1. Base URLs

API         https://api.mooov.money
Authorize   https://connect.mooov.money/authorize     (Connect only)

Use mk_test_* (or a Mooov-Test-Mode platform key) against the canonical host. https://sandbox.api.mooov.money remains a temporary compatibility alias only; it does not select the request environment.

Test and live objects are completely separate: separate keys, separate merchants, separate grants, separate webhook destinations. Nothing you create with a test key exists in live. The full hostname matrix (portals, docs, MCP) is on the environments page.

2. Test credentials

The environment is baked into your API key at minting time. Call https://api.mooov.money with mk_test_* keys while building. Test keys are visually distinct so a leaked-into-live-config mistake is greppable:

• Merchants mint test keys from the merchant portal (mooov3.mooov.money → Developers → API keys, Test mode). The secret is shown once at creation; store it in your secret manager.
• Platforms receive a Mooov-Test-Mode platform key during the credential ceremony described in §9 of the Connect protocol. Test and live platform keys are different secrets and never share grants.

Signing is identical in both environments — the four-line canonical string and headers from §2 of the Connect protocol.

3. Test cards

Which test cards work depends on how your charge routes. Mooov picks the acquiring route per merchant; you don't choose it per request. Most merchants route to Stripe test mode (§3.1). Merchants approved for Mooov's high-risk acquiring route (you'll know — it involves an eligibility review) route to the high-risk sandbox (§3.2).

3.1 Stripe-routed merchants

The standard Stripe test PANs drive every outcome you need to handle:

Use any future expiry date, any 3-digit CVC, and any postcode. On a hosted checkout (flow: "redirect" / flow: "embedded") you type these into the Stripe-hosted form; for server flow you tokenise them first via a test-mode Setup Intent or Payment Element.

Customer-backed and saved-method flows are temporarily unavailable with test credentials because customer/provider mappings are not yet environment-scoped. customer_ref, POST /v1/charges/saved, POST /v1/subscription_checkouts, and GET /v1/customers/by_ref return test_customer_mappings_unavailable without reading live mappings. Direct tokenized test payments remain supported through POST /v1/payment_intents when customer_ref is omitted.

3.2 High-risk-routed merchants (high-risk sandbox)

Three things are different from Stripe before you reach for a card:

• HKD only. The high-risk sandbox accepts currency: "HKD" exclusively. A test charge in GBP/EUR/USD will be rejected at creation. (Production supports more currencies; the sandbox does not.)
• Hosted checkout only. Use flow: "redirect" and send the customer to hosted_url. Card entry happens on the acquirer-hosted page; there is no test-token server flow.
• Some cards require an exact amount to trigger their 3DS scenario — see the table.

Any future expiry and any 3-digit CVV work for all of the above. If the hosted form asks for billing address fields, any plausible values are accepted.

Refunds work the same as Stripe-routed merchants — full and partial via POST /v1/payment_intents/{id}/refund — with one provider rule that also applies in production: the refund window is six months from capture, and the refund currency must match the charge currency.

4. Test tenants (Connect)

Test merchants seed automatically when you exchange an auth code with a Mooov-Test-Mode platform key: run the consent flow from §3 of the Connect protocol against connect.mooov.money/authorize and the resulting merch_test_* merchant is ready to charge immediately. A fresh CI run can spin up tenants without any manual seeding on Mooov's side.

If a test tenant has not finished simulated PSP onboarding you get the same typed 422 merchant_not_charge_capable you'd see in live — see the error reference — so you can build your onboarding-incomplete UX against test mode too.

5. Webhooks in test mode

Register a test webhook destination separately from live (platforms: part of the credential ceremony; merchants: portal → Developers → Webhooks in Test mode). Deliveries are signed with your test webhook secret using the same t=<unix>,v1=<hex> scheme documented in §6 of the Connect protocol.

Two practical ways to trigger events:

1. Drive a real test payment. Complete a 4242… checkout and you'll receive payment.succeeded within a couple of seconds; refund it via POST /v1/payment_intents/{id}/refund to receive payment.refunded. This exercises the full pipeline end to end and is what we recommend for CI.
2. Decline paths. Use the decline PANs above to receive payment.failed with a populated failure_code / failure_category.

The full event list and payload shapes are in the webhook event catalog.

Webhook retries behave exactly as in production (exponential backoff: 1s, 5s, 30s, 5m, 30m, 2h, 12h), so you can verify your dedupe logic by returning a 500 from your test endpoint and watching the redeliveries arrive with the same X-Mooov-Delivery semantics.

6. Go-live checklist

Before minting live credentials, confirm with test keys:

• Signature verification rejects a tampered body and a stale timestamp (>5 min skew).
• Idempotent retries: replaying a POST with the same Idempotency-Key and body returns the original result; a reused key with a different body returns 409.
• payment.succeeded, payment.failed, and payment.refunded handlers are idempotent on event.id.
• The 422 merchant_not_charge_capable path surfaces the setup_url to the merchant instead of erroring blindly.
• (Connect) Grant revocation: after POST /v1/grants/{id}/revoke your system marks the tenant disconnected on the next 403 GRANT_NOT_FOUND.

Then follow §9 of the Connect protocol (platforms) or mint a live key from the portal (merchants). Keep the base URL as https://api.mooov.money; only the key (and webhook secret) changes.