Sandbox testing

Sandbox lets you build and test your integration without moving real money. To get sandbox access, contact peter@trykarat.com — see Environments. Once sandbox is enabled on your account, you can use a set of pre-configured test recipients. Sending a payout to one of these email addresses drives the payout to a specific outcome.

Simulate payout statuses

Send a payout to one of these recipients to drive it to the corresponding status:

Recipient email	Resulting status
`sandbox+completed@trykarat.com`	Completed
`sandbox+failed@trykarat.com`	Failed
`sandbox+returned@trykarat.com`	Returned
`sandbox+canceled@trykarat.com`	Canceled
`sandbox+pending@trykarat.com`	Pending
`sandbox+created@trykarat.com`	Created
`sandbox+awaiting_acceptance@trykarat.com`	Awaiting acceptance

Simulate recipient onboarding milestones

These recipients instantly trigger a recipient.updated webhook with the corresponding status. The webhook fires in two situations: when you create a recipient with one of these emails, and when you send a payout to one:

Recipient email	`recipient.updated` status
`sandbox+onboarding_started@trykarat.com`	`onboarding_started`
`sandbox+tax_info_collected@trykarat.com`	`tax_info_collected`
`sandbox+onboarding_completed@trykarat.com`	`onboarding_completed`

curl https://payouts.api.trykarat.com/recipients \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      { "email": "sandbox+onboarding_completed@trykarat.com" }
    ]
  }'

Unlike real onboarding — where each milestone is sent at most once per invitation — sandbox milestone recipients fire the webhook every time, so you can re-test your handler freely.

Recipient profiles in sandbox

Sandbox recipients are simulated and never go through real onboarding, so they have no tax information of their own. To let you exercise the full response shape, GET /recipients and GET /recipients/{id} return a placeholder profile for them instead of null:

{
  "firstName": "Sandbox",
  "lastName": "Completed",
  "fullName": "Sandbox Completed",
  "businessName": null,
  "businessType": "individual",
  "dba": null,
  "permanentAddress": {
    "line1": "100 Sandbox Way",
    "line2": null,
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94103",
    "country": "US"
  },
  "mailingAddress": null
}

The names mirror the ones you created the recipient with; the rest of the placeholder is fixed. In production, profile stays null until the payee completes onboarding, and businessType reflects whether they registered as an individual or an entity.

Simulate errors

Send a payout to one of these recipients to trigger a specific error:

Recipient email	Simulated error
`sandbox+error_insufficient_funds@trykarat.com`	Insufficient funds to cover the payout batch
`sandbox+error_invalid_amount@trykarat.com`	All payout amounts must be greater than zero

Example

curl https://payouts.api.trykarat.com/payments \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payouts": [
      { "payeeEmail": "sandbox+completed@trykarat.com", "amount": 25000 }
    ]
  }'

Combine sandbox status recipients with webhooks to verify your payout.updated handler end to end before going live.

Get started

API reference

Simulate payout statuses

Simulate recipient onboarding milestones

Recipient profiles in sandbox

Simulate errors

Example

​Simulate payout statuses

​Simulate recipient onboarding milestones

​Recipient profiles in sandbox

​Simulate errors

​Example

Simulate payout statuses

Simulate recipient onboarding milestones

Recipient profiles in sandbox

Simulate errors

Example