Environments, mock and collections

RevKeen has three places to send API requests: production for live traffic, staging for persisted pre-production testing, and a stateless mock for exploring response shapes.

Environment matrix

Keys belong to one environment. An rk_live_* key does not work on staging, and an rk_sandbox_* key does not work on production.

Recommended promotion path

1. Start in Mock when you only need response shapes, frontend prototyping, or a first client skeleton.
2. Move to Staging when you need persisted data, webhook delivery, and realistic lifecycle testing.
3. Promote to Production only after the same flows are stable in staging.

Choosing the right environment

Production

Production creates live side effects: real charges, real customer records and real notifications. Use it only with live keys and real workflows.

Staging

Staging is a separate environment, not a test mode of production. It has its own data, its own keys and its own webhook endpoints, and nothing created there appears in production.

• Data persists between requests.
• Webhooks are delivered to the endpoints you register in staging.
• Side effects depend on how the connected payment and messaging providers are configured for staging. Check that configuration before testing a payment or messaging flow; staging does not guarantee that every provider is simulated.

Mock

The mock answers every documented /v2 operation with the example response from the API specification. It is stateless.

• No persistence. A POST returns the example object, not what you sent, and a later GET will not find it.
• No webhooks. Nothing is ever delivered.
• A key is required but never checked. Send any non-empty x-api-key, for example mock-key. A missing key returns 401, as the real API does. Never send a real key to the mock.
• Requests are validated against the specification. A body that breaks the schema returns a 4xx validation error rather than the success example. Validation errors on staging carry RevKeen's full error shape; the mock's do not.
• Only public operations. Anything not in the public API returns 404.
• Same data every time. IDs and field values are fixed examples, not realistic or unique values.
• Rate limited per IP address. It is a shared public service, so don't use it for load testing.

Postman and Bruno

The public API specification is published as an OpenAPI 3.1 document:

https://docs.revkeen.com/api/openapi-spec

Both Postman and Bruno can import an OpenAPI document as a collection:

• Postman: Import, paste the URL above, and choose to generate a collection.
• Bruno: Import collection, choose OpenAPI V3, and select the downloaded file.

After importing, create one environment per base URL in the matrix. Store your key as an environment variable (for example apiKey), send it in the x-api-key header, and keep secret values out of anything you share or commit. For the mock, use any placeholder such as mock-key.

Ready-made RevKeen collections for Postman and Bruno, generated from the same specification, are being prepared. This page will link to them when they are published.

Rate limits

Each API key may make 600 requests per minute. The same limit applies in production and staging. Some endpoints apply their own, lower limits.

• An over-limit request returns 429 Too Many Requests with type: rate_limit_error and code: rate_limit_exceeded.
• Every 429 carries a Retry-After header in whole seconds. Wait that long, then retry.
• An over-limit key is still valid. It receives 429, never 401, so don't re-authenticate or rotate the key.

Build your client on Retry-After. See Errors and the API reference for the full error shape.

Trying requests in the API reference

The playground defaults to Demo (Mock). It never sends your credentials: it sends the placeholder key mock-key, and its code samples show the same placeholder. It is useful for exploring response shapes. Use HTTP examples in Demo; the named SDK clients require a secret key.

Choose Staging for authenticated pre-production testing with your own rk_sandbox_* key. All methods are available there, and the data persists.

Choose Production with your own rk_live_* key to read live merchant data. Production in the playground is read-only: only GET requests can be sent. Make state-changing production calls from your own server.

Staging and production keys are held separately in panel memory and cleared when the panel is closed. Switching environments clears the displayed result; every completed result is labelled with the environment used for that request. No key you enter is copied into generated code snippets, saved to browser storage, or sent to Demo.

Next Steps

Owner: david · Reviewed 7 Oct 2026