Sandbox Testing

The sandbox environment (https://api-sandbox.finperks.com) lets you build and test your integration without any monetary settlement. It offers the same API surface as the live environment and adds a few sandbox-only endpoints to simulate situations that would otherwise require action by finperks or real money movements.

Sandbox credentials are separate from live credentials: create a sandbox API key in the finperks Control Center and configure sandbox webhook subscriptions independently from your live setup.

Sandbox-Only Endpoints

Endpoint	Use it to
PATCH /balances/{currency}	Set your balance to any value — e.g. a high value for happy-path testing, or a low value to test insufficient_available_balance handling.
POST /products/{code}/actions/trigger_event	Trigger a product created or updated event to test your product webhook processing and cache refresh logic.
POST /client_partners/{id}/actions/trigger_event	Move a client partner through its lifecycle (created, updated, approved, rejected, revoked) without waiting for a manual review, e.g. to test that orders work once a partner is approved.
POST /orders/{id}/actions/refund	Simulate a refund of a completed order to test your handling of the refunded state and webhook event. In live mode, refunds are only triggered by finperks.

What to Test

Before going live, we recommend verifying at least the following flows in the sandbox:

• Order happy path — create orders in sync and async mode and process the delivery data, including the urls entries where available.
• Idempotent retries — send the same order creation request twice with the same Idempotency-Key and verify your system handles the replayed response correctly, see Idempotency.
• Invalidation — invalidate an order right after creation and verify your handling, including the error responses for orders that can no longer be invalidated, see Order Lifecycle.
• Insufficient balance — lower your balance via PATCH /balances/{currency} and verify your handling of the insufficient_available_balance error.
• Webhooks — subscribe to order and product events in the sandbox and verify signature validation, deduplication by webhook id, and your 2xx acknowledgment behavior, see Webhooks.
• Refunds — trigger a sandbox refund and verify the refunded state is reflected correctly in your system.
• Rate limiting — if you expect bursts of requests, verify your client-side rate limiting and Retry-After handling, see Rate Limiting.

Differences From Live

• Settlements do not exist in the sandbox. The settlement endpoints and settlement webhook events are only available in the live API.
• No real fulfillment. Sandbox orders deliver test data; codes cannot be redeemed.
• Data retention. Sandbox data is cleaned up periodically — do not treat sandbox orders as permanent records.