> ## Documentation Index
> Fetch the complete documentation index at: https://catchbackcards.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

In about 15 minutes you'll run the whole flow a customer goes through: buy a pack, receive the item, and sell it back. It all happens in the **sandbox**, a test copy of the API. Payments there are simulated, so no real money moves, but the digital representations are real tokens on a public test network.

## Before you start

**What we send you.** Email [support@catchbackcards.com](mailto:support@catchbackcards.com) and we'll set you up with:

* a **sandbox base URL**, where the test API lives;
* a **sandbox API key**, which only works there;
* your **test chain** and **sandbox contract address**.

**What you need.** A test wallet address on that chain, standing in for your customer. Any EVM wallet works (MetaMask, Rabby, or one your code creates). Selling back needs the wallet to sign one transaction, so give it a little testnet gas from a public faucet.

Save the two values you'll use in every call:

```bash theme={null}
export CATCHBACK_BASE_URL="https://…"     # the sandbox base URL we sent
export CATCHBACK_KEY="cb_live_…"          # your sandbox key (keys look the same in every environment)
export WALLET="0x…"                       # your test wallet address
```

## 1. Check your key

```bash theme={null}
curl "$CATCHBACK_BASE_URL/api/partner/v2/keys" \
  -H "Authorization: Bearer $CATCHBACK_KEY"
```

You should see your key with `"scopes": ["nft:orders"]` and your `program`. A `401` means the key is wrong; a `403` means it's missing the `nft:orders` scope, so contact us.

## 2. Pick a pack

List the packs you can sell:

```bash theme={null}
curl "$CATCHBACK_BASE_URL/api/partner/v2/catalog/packs?category=pokemon" \
  -H "Authorization: Bearer $CATCHBACK_KEY"
```

Each pack has a `pack_type` (for example `bronze`), a `price` in dollars, and `available`. Pick one where `available` is `true`. To see its odds and every item it can pull, the same view you'd show a customer, call [Get a pack's odds and pool](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-pack-pool.md) with that `pack_type`.

## 3. Create an order for your test wallet

```bash theme={null}
curl -X POST "$CATCHBACK_BASE_URL/api/partner/v2/orders" \
  -H "Authorization: Bearer $CATCHBACK_KEY" \
  -H "Idempotency-Key: quickstart-001" \
  -H "Content-Type: application/json" \
  -d "{ \"pack_type\": \"bronze\", \"category\": \"pokemon\", \"recipient\": \"$WALLET\" }"
```

* `recipient` is the wallet the item is delivered to.
* `Idempotency-Key` is your own id for the order. If a call fails or times out, send it again with the same key and you'll get the same order back, never a second one. You'll also use it to look the order up.

The response has the `order`, with `"status": "awaiting_payment"`, and a `payment`. In production you'd hand `payment` to your customer to pay. Here, copy `payment.intent_id`: it starts with `sbx_pi_`.

## 4. Pay for it (simulated)

```bash theme={null}
curl -X POST "$CATCHBACK_BASE_URL/api/partner/v2/sandbox/payments/sbx_pi_…" \
  -H "Authorization: Bearer $CATCHBACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

This marks the payment as settled, exactly as a real customer payment would.

## 5. Open the pack and receive the item

Our background work runs every two minutes. In the sandbox you can also run it straight away by calling **tick**, so you don't have to wait:

```bash theme={null}
curl -X POST "$CATCHBACK_BASE_URL/api/partner/v2/sandbox/tick" \
  -H "Authorization: Bearer $CATCHBACK_KEY"

curl "$CATCHBACK_BASE_URL/api/partner/v2/orders/quickstart-001" \
  -H "Authorization: Bearer $CATCHBACK_KEY"
```

Repeat both calls until `order.status` reaches `minted`. Along the way it moves:

| Status | What happened |
| - | - |
| `paid` | The payment settled |
| `rolled` | The pack opened. `order.pull` shows the item: its name and value |
| `minted` | The digital representation is in your test wallet. `order.token.token_id` is its id |

That's the moment your app shows the customer what they pulled. Check your test wallet: the token is there.

## 6. Sell it back

Ask for a quote. It fixes the price for 10 minutes:

```bash theme={null}
curl -X POST "$CATCHBACK_BASE_URL/api/partner/v2/tokens/TOKEN_ID/quote" \
  -H "Authorization: Bearer $CATCHBACK_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"kind\": \"sellback\", \"holder\": \"$WALLET\" }"
```

`amount_usd` is what the customer gets. To accept, the **wallet holder** signs one transaction that burns the token with the signed `quote`. The code for that is on the [Sell-back](https://catchbackcards.mintlify.site/partner-api/v2/sell-back.md#evm-burn-with-the-signed-quote) page. Then tick and check the quote:

```bash theme={null}
curl -X POST "$CATCHBACK_BASE_URL/api/partner/v2/sandbox/tick" \
  -H "Authorization: Bearer $CATCHBACK_KEY"

curl "$CATCHBACK_BASE_URL/api/partner/v2/quotes/QUOTE_ID" \
  -H "Authorization: Bearer $CATCHBACK_KEY"
```

When `quote.payout.status` is `sent`, the sale is complete, and in the sandbox the payout lands instantly.

That's the whole flow. To try shipping instead, see [Shipping](https://catchbackcards.mintlify.site/partner-api/v2/shipping.md): estimate, create and pay a shipment, burn, then mark it shipped with [`POST /sandbox/shipments/{id}`](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/sandbox-ship).

## How the sandbox differs from production

| Production | Sandbox |
| - | - |
| Unifold Payment Intent, paid by the customer | Intent ids start `sbx_pi_`; mark one paid with [`POST /sandbox/payments/{intentId}`](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/sandbox-pay) |
| `publishable_key`, deposit addresses | Placeholders (`pk_sandbox`, fixed addresses) |
| Background work and webhooks every two minutes | Also every two minutes, or right away when you call [`POST /sandbox/tick`](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/sandbox-tick) |
| USDC payouts and refunds | Complete instantly (transfer ids start `sbx_tr_`); Solana payouts are allowed |
| Carrier rates | One fixed rate: USPS Priority Mail (sandbox), \$9.85 |
| Your mint chain | A public testnet, real contract |
| Sanctions screening | The real OFAC list |
| Webhook URLs | Public `https://` URLs, as in production. To receive on your own machine, use a tunnel such as ngrok |

All three sandbox endpoints return **404** outside the sandbox.

| Endpoint | What it does |
| - | - |
| [`POST /sandbox/payments/{intentId}`](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/sandbox-pay) | Pays an order's or a shipment's sandbox intent, exactly as a settled payment would |
| [`POST /sandbox/tick`](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/sandbox-tick) | Runs one pass of the background work (open, mint, watch the chain, pay out, ship) and delivers the webhooks it produced |
| [`POST /sandbox/shipments/{id}`](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/sandbox-ship) | Plays our shipping team: marks a burned shipment `shipped`, then `delivered` |

## A full run (TypeScript + viem)

The same flow our own certification suite runs against the sandbox. `burnForQuote` and `CATCHBACK_CARDS_ABI` are on the [Sell-back](https://catchbackcards.mintlify.site/partner-api/v2/sell-back.md#evm-burn-with-the-signed-quote) page; `alice`, `bob`, their viem wallets and `CONTRACT` are yours.

```ts theme={null}
const BASE = process.env.CATCHBACK_BASE_URL!;
const KEY = process.env.CATCHBACK_KEY!;

async function api(method: string, path: string, body?: unknown, idem?: string) {
  const res = await fetch(`${BASE}/api/partner/v2${path}`, {
    method,
    headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json', ...(idem ? { 'Idempotency-Key': idem } : {}) },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  return { status: res.status, body: await res.json() };
}

/** Tick the sandbox until `check` returns something. */
async function settle<T>(check: () => Promise<T | null | undefined | false>, tries = 20): Promise<T> {
  for (let i = 0; i < tries; i++) {
    const v = await check();
    if (v) return v;
    await api('POST', '/sandbox/tick');
    await new Promise((r) => setTimeout(r, 1500));
  }
  throw new Error('did not settle');
}

// 1. Pick an available pack and read its odds.
const { body: cat } = await api('GET', '/catalog/packs?category=pokemon');
const pack = cat.packs.find((p: any) => p.available);
const { body: pool } = await api('GET', `/catalog/packs/pool?pack_type=${pack.pack_type}&category=pokemon`);

// 2. Order it for Alice, and pay (sandbox).
const key = `ord-${crypto.randomUUID()}`;
const { body: created } = await api('POST', '/orders', { pack_type: pack.pack_type, category: 'pokemon', recipient: alice.address }, key);
await api('POST', `/sandbox/payments/${created.payment.intent_id}`, {});

// 3. Tick until minted.
const order = await settle(async () => {
  const o = (await api('GET', `/orders/${key}`)).body.order;
  if (o.status === 'refund_due' || o.status === 'refunded') throw new Error(o.failure_reason);
  return o.status === 'minted' ? o : null;
});
const tokenId = order.token.token_id;

// 4. Alice trades it to Bob on chain; tick until CatchBack sees it.
await aliceWallet.writeContract({ address: CONTRACT, abi: CATCHBACK_CARDS_ABI, functionName: 'transferFrom', args: [alice.address, bob.address, BigInt(tokenId)] });
await settle(async () => (await api('GET', `/wallets/${bob.address}/tokens`)).body.tokens.some((t: any) => t.token_id === tokenId));

// 5. Bob sells it back: quote, burn, then tick until paid.
const { body: quote } = await api('POST', `/tokens/${tokenId}/quote`, { kind: 'sellback', holder: bob.address });
await burnForQuote(bobWallet, quote);
await settle(async () => {
  const q = (await api('GET', `/quotes/${quote.quote_id}`)).body.quote;
  return q.payout.status === 'sent' ? q : null;
});
```

> [!TIP]
>
> Use a separate key per environment (sandbox, production).

## Next steps

* [Webhooks](https://catchbackcards.mintlify.site/partner-api/v2/webhooks.md): get each status change pushed to you instead of polling.
* [Orders](https://catchbackcards.mintlify.site/partner-api/v2/orders.md): every status, including refunds and multi-pack orders.
* [Go-live checklist](https://catchbackcards.mintlify.site/partner-api/v2/go-live-checklist.md): what to confirm before switching to your production key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.