Sandbox & Testing

Test your integration safely with sandbox wallets, test funds, and simulated error scenarios.

Sandbox vs Production

Wallgent runs two fully isolated environments. Sandbox is for development and testing — no real money moves, and there are no financial consequences for any action you take.

	Sandbox	Production
API key prefix	`wg_test_`	`wg_live_`
Real money	No	Yes
Fund wallets manually	Yes (`/v1/wallets/:id/fund`)	No (use transfers)
Requires KYB	No	Yes
Plan limits	Free tier applies	Based on your plan

Keys are environment-locked. A wg_test_ key cannot access production wallets, and a wg_live_ key cannot access sandbox wallets. Cross-environment requests return 403 ENVIRONMENT_MISMATCH.

Adding Test Funds

In the sandbox environment, you can add test funds to any wallet instantly using the fund endpoint. This simulates money arriving from an external source without going through a real settlement rail.

import Wallgent from '@wallgent/sdk'

const wg = new Wallgent({ apiKey: process.env.WALLGENT_API_KEY })

const result = await wg.wallets.fund('wal_01J...', {
  amount: '1000.00',
})

console.log(result.newBalance) // '1000.00000000'

REST endpoint:

POST /v1/wallets/:id/fund

{ "amount": "1000.00" }

Maximum per call: $10,000.00. Call multiple times if you need a larger balance. This endpoint is unavailable in production — calling it with a wg_live_ key returns 403 SANDBOX_ONLY.

Test Scenarios

The following scenarios cover the most important states your integration needs to handle.

1. Happy Path Payment

Fund a wallet and send a successful payment.

// Fund
await wg.wallets.fund('wal_agent', { amount: '100.00' })

// Send payment — succeeds
const payment = await wg.payments.send({
  from: 'wal_agent',
  to: 'wal_destination',
  amount: '50.00',
  description: 'Test payment',
})

console.log(payment.status) // 'POSTED'

2. Trigger Insufficient Funds

Fund the wallet with less than the payment amount to trigger INSUFFICIENT_FUNDS.

import { InsufficientFundsError } from '@wallgent/sdk'

await wg.wallets.fund('wal_agent', { amount: '10.00' })

try {
  await wg.payments.send({
    from: 'wal_agent',
    to: 'wal_destination',
    amount: '50.00',
  })
} catch (err) {
  if (err instanceof InsufficientFundsError) {
    console.log('Caught expected error:', err.code) // 'INSUFFICIENT_FUNDS'
  }
}

3. Trigger Policy Denial

Create a policy with a low maxTransactionAmount, then attempt a payment that exceeds it.

import { PolicyDeniedError } from '@wallgent/sdk'

// Create a policy capping each transaction at $20
await wg.policies.create({
  walletId: 'wal_agent',
  name: 'Low limit test policy',
  maxTransactionAmount: '20.00',
})

await wg.wallets.fund('wal_agent', { amount: '200.00' })

try {
  await wg.payments.send({
    from: 'wal_agent',
    to: 'wal_destination',
    amount: '50.00', // exceeds maxTransactionAmount
  })
} catch (err) {
  if (err instanceof PolicyDeniedError) {
    console.log('Policy blocked the payment:', err.message)
  }
}

4. Trigger Approval Workflow

Create a policy with requireHumanApproval: true. The payment returns HTTP 202 — it is queued, not failed.

import { ApprovalRequiredError } from '@wallgent/sdk'

await wg.policies.create({
  walletId: 'wal_agent',
  name: 'Approval required test policy',
  requireHumanApproval: true,
})

await wg.wallets.fund('wal_agent', { amount: '200.00' })

try {
  await wg.payments.send({
    from: 'wal_agent',
    to: 'wal_destination',
    amount: '50.00',
  })
} catch (err) {
  if (err instanceof ApprovalRequiredError) {
    // This is not a failure — the payment is pending human review
    const approvalId = err.details?.approvalId as string
    console.log('Payment queued for approval:', approvalId)
    // Poll GET /v1/approvals/:id or wait for approval.approved webhook
  }
}

Error Codes to Expect in Testing

Code	Trigger
`INSUFFICIENT_FUNDS`	Payment amount exceeds wallet balance
`POLICY_DENIED`	Payment violates a spend policy (amount, recipient, time)
`APPROVAL_REQUIRED`	Policy requires human approval (HTTP 202, not a failure)
`WALLET_FROZEN`	Payment attempted on a frozen wallet
`ENVIRONMENT_MISMATCH`	Using a `wg_test_` key against production resources
`SANDBOX_ONLY`	Calling `/fund` with a `wg_live_` key

Going Live Checklist

Production access requires completing all four activation steps. Check your current status at any time:

GET /v1/activation/status

{
  "kybVerified": false,
  "tosAccepted": false,
  "billingMethodAdded": false,
  "productionActivated": false
}

Complete KYB (Know Your Business)

Submit your business verification documents via the dashboard under Settings → Compliance. KYB review typically takes 1-3 business days.

Accept Terms of Service

POST /v1/activation/accept-tos

{ "tosVersion": "1.0.0" }

Or accept via the dashboard. This is recorded with your IP address and timestamp for compliance.

Add a Payment Method

Add a credit card or bank account in the dashboard under Settings → Billing. This is used for Wallgent's monthly platform fee.

Activate Production

Once the first three steps are complete, activate production access:

POST /v1/activation/activate-production

If any requirement is missing, the API returns 400 ACTIVATION_INCOMPLETE with a missing array:

{
  "error": {
    "code": "ACTIVATION_INCOMPLETE",
    "message": "Cannot activate production. Missing requirements: kybVerified, billingMethodAdded",
    "missing": ["kybVerified", "billingMethodAdded"]
  }
}

On success:

{ "activated": true, "activatedAt": "2026-03-03T12:00:00.000Z" }

You can now create wg_live_ API keys and access production wallets.

Environment Isolation

Sandbox and production wallets, transactions, and keys share no data. This means:

Test transactions do not appear in production reports
A wg_test_ key used against a production wallet ID returns 403 ENVIRONMENT_MISMATCH
Production API keys require completed activation — calling production endpoints without activation returns 403 ACTIVATION_REQUIRED