Sandbox
Sandbox stores and test products that trigger every outcome, the way test card numbers do. Free, instant, and nothing is ever charged.
Use a sandbox key (hk_test_…). Sandbox keys can also look up offers at real stores, which is safe because lookups never buy anything.
Sandbox stores
Each one behaves like a real route.
| Store | Product links | Behaves like |
|---|---|---|
sbx_woo_store |
https://woo.sandbox.harbor.local/products/{product} |
A store Harbor completes itself, once the user's rules pass. The simplest path. |
sbx_ucp_store |
https://ucp.sandbox.harbor.local/products/{product} |
A platform store. Needs buyer.email and shipping_address; the user finishes on the store's page. |
sbx_major_store |
https://major.sandbox.harbor.local/products/{product} |
A major retailer. The user must connect it first. |
Shipping is $5.00 under $50 and free above. Tax is 8%.
Test products
Put the product in the link, for example https://woo.sandbox.harbor.local/products/sbx_expensive.
| Product | Price | What happens |
|---|---|---|
sbx_widget |
$19.99 | Everything succeeds. |
sbx_expensive |
$499.00 | Over typical limits: fails with RULE_VIOLATION above max_per_order, or asks the user to confirm above confirm_above. |
sbx_oos |
$89.00 | Out of stock. The offer says out_of_stock and the checkout fails with OUT_OF_STOCK. |
sbx_price_change |
$25.00 | The price at checkout is $27.50, so the user must confirm the new total. |
sbx_decline |
$59.00 | Confirm fails with PAYMENT_DECLINED. |
sbx_otp |
$39.00 | Confirm asks for a verification_code (user_input). The code is 123456. Not on sbx_ucp_store. |
Controls
These endpoints stand in for things only a real user or store can do. They only work with sandbox keys, and all but the first need the user's token.
| Endpoint | Stands in for |
|---|---|
POST /v1/sandbox/public_token |
The user approving in Harbor Approve. Body: { "approval_token": "…" }. |
POST /v1/sandbox/connections |
The user connecting a store. Body: { "merchant_id": "sbx_major_store", "status": "active" }. needs_user and revoked send the matching webhook. |
POST /v1/sandbox/checkouts/{id}/user_confirm |
The user approving on the confirm page. |
POST /v1/sandbox/checkouts/{id}/merchant_complete |
The user finishing on the store's checkout page (after redirect_to_merchant). |
POST /v1/sandbox/orders/{id}/advance |
The order moving from placed to shipped to delivered. |
Recipes
A purchase that needs the user's confirmation. Approve with "max_per_order": 60000, "confirm_above": 7500, then check out sbx_expensive (its total with tax is $538.92). The checkout asks for confirm; call user_confirm, then confirm.
A platform store purchase. Check out a sbx_ucp_store product with a buyer email and address, call confirm to get redirect_to_merchant, then merchant_complete.
A major retailer purchase. Call sandbox/connections for sbx_major_store, then check out and confirm. Use sbx_otp to practice the verification code step.