Sandbox

Audience: anyone integrating Mooov — platforms on Mooov Connect and merchants using a direct API key. Build and certify against the sandbox before you touch production.

The sandbox is a full deployment of the Mooov gateway wired to PSP test mode. Same API surface, same HMAC auth, same webhook envelopes, same state machine — no real money moves.

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://sandbox.api.mooov.money
Authorize   https://sandbox.connect.mooov.money/authorize     (Connect only)
Production  https://api.mooov.money

(The legacy staging.*.mooov.money hostnames remain permanent aliases for the same sandbox; existing integrations keep working.)

Sandbox and production are completely separate: separate keys, separate merchants, separate grants, separate webhook destinations. Nothing you create in the sandbox exists in production. 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, and a key only works against its own environment's hostname (use mk_test_* keys with sandbox.api.mooov.money). Test keys are visually distinct so a leaked-into-prod-config mistake is greppable:

• Merchants mint test keys from the merchant portal (mooov3.mooov.money → Developers → API keys). 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. Sandbox and prod 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.

4000 0000 0000 0341 is the important one for saved-method flows: it lets you exercise the payment.failed webhook path for POST /v1/charges/saved without manufacturing a real decline.

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. Sandbox tenants (Connect)

Sandbox merchants seed automatically when you exchange an auth code: run the consent flow from §3 of the Connect protocol against sandbox.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 sandbox tenant has not finished simulated PSP onboarding you get the same typed 422 merchant_not_charge_capable you'd see in production — see the error reference — so you can build your onboarding-incomplete UX against the sandbox too.

5. Webhooks in the sandbox

Register a sandbox webhook destination separately from production (platforms: part of the credential ceremony; merchants: portal → Developers → Webhooks). Deliveries are signed with your sandbox 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 sandbox endpoint and watching the redeliveries arrive with the same X-Mooov-Delivery semantics.

6. Go-live checklist

Before requesting production credentials, confirm in the sandbox:

• 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) and switch the base URL to https://api.mooov.money.