Setup a sandbox environment

Stables provides a sandbox environment that lets you quickly test your integration without moving real money. To get started, create a Stables Developer account, where you can generate your sandbox API keys.

Step 1: Generate a Sandbox KeyCopy Anchor Link

• Login to the your Stables Developer Platform on Sandbox
• Navigate to API Keys section from the left sidebar navigation.
• Sandbox keys should be prefixed with sti_test_

Step 2: Hit an APICopy Anchor Link

Stables sandbox is currently functional with the customer creation and KYC process. For example, here is how you can create a Stables customer.

curl -X POST "https://api.sandbox.stables.money/api/v1/customer" \
  -H "Authorization: Bearer YOUR_JWT_OR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \ # or any UUID v4
  -d '{
    "customer_type": "individual",
    "external_customer_id": "your",
    "email": "[email protected]",
    "phone": "+14155552671",
    "entitlements": ["base_payout", "virtual_account"],
    "metadata": {
      "source": "api",
      "ref": "order-123"
    },
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "Michael",
    "dob": "1990-01-15",
    "nationality": "US",
    "address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "id_documents": [
      {
        "document_type": "PASSPORT",
        "front_image_data": "BASE64_ENCODED_FRONT_IMAGE_DATA",
        "back_image_data": "BASE64_ENCODED_BACK_IMAGE_DATA",
        "country": "US"
      }
    ],
    "selfie_photo": {
      "data": "BASE64_ENCODED_SELFIE_IMAGE_DATA"
    }
  }'

Differences with ProductionCopy Anchor Link

The Sandbox is best suited for validating API request and response schemas. For all other testing scenarios, we recommend using the Production environment directly.

Onboarding/KYC

• Individual customers are automatically approved in sandbox, provided you use the correct sample documents
• Business customers are NOT automatically approved and require manual review in sandbox
• Stables uses Sumsub for verification processing. See Sandbox Test Documents for the specific sample documents that simulate approval, resubmission, and rejection
• Sandbox is subject to arbitrary rate limits; we may drop your requests anytime.

Payments

• There is no real money movement in Sandbox.
• Testnets are not supported

If you have suggestions on how to improve our sandbox experience, please reach out to us at [email protected]!

Simulating Payment Route DepositsCopy Anchor Link

The sandbox exposes a deposit simulation endpoint that lets you trigger payment route deposit events without moving real money. This is essential for testing payment route flows end-to-end.

POST /api/v1/customers/{customerId}/virtual-accounts/{virtualAccountId}/sandbox/simulate-deposit

Request fields

Example

curl -X POST "https://api.sandbox.stables.money/api/v1/customers/{customerId}/virtual-accounts/va_123/sandbox/simulate-deposit" \
  -H "Authorization: Bearer YOUR_JWT_OR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "250.00",
    "scenario": "completed",
    "sender_name": "Jane Smith",
    "sender_reference": "Invoice #42"
  }'