# Quickstart — merchant sandbox

**Base URL:** `https://www.strawberryid.com/api` (adjust if your deployment uses another host).

## 1. Create the merchant

```bash
curl -X POST https://www.strawberryid.com/api/merchants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Commerce",
    "legalName": "Acme Commerce Limited",
    "contactName": "Tomi Adebayo",
    "contactEmail": "ops@acme.example.com",
    "country": "Nigeria",
    "businessType": "E-commerce"
  }'
```

## 2. Issue a sandbox API key

Replace `<merchant_id>` with the id from step 1.

```bash
curl -X POST https://www.strawberryid.com/api/merchants/<merchant_id>/api-keys \
  -H "Content-Type: application/json" \
  -d '{"environment":"TEST"}'
```

Store the returned secret in your backend env and use it as Bearer auth on `/v1/*` routes:

```dotenv
STRAWBERRY_API_BASE_URL=https://www.strawberryid.com/api
STRAWBERRY_API_KEY=sk_test_...
```

If your project already uses `ONE_WALLET_*` names, map internally:

```dotenv
ONE_WALLET_API_BASE_URL=${STRAWBERRY_API_BASE_URL}
ONE_WALLET_SECRET_KEY=${STRAWBERRY_API_KEY}
```

## 3. Request identity fields (user must approve)

```bash
curl "https://www.strawberryid.com/api/v1/data-requests" \
  -X POST \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: req_001" \
  -H "Content-Type: application/json" \
  -d '{
    "strawberry_id": "SR1-ABCD-EFGH-X",
    "requested_fields": ["strawberry_id", "display_name", "kyc_status"]
  }'
```

## 4. Read approved identity

```bash
curl "https://www.strawberryid.com/api/v1/identity?strawberry_id=SR1-ABCD-EFGH-X&fields=display_name,kyc_status" \
  -H "Authorization: Bearer sk_test_..."
```

## Going live

When the merchant is `ACTIVE`, create a live key:

`POST /merchants/:id/api-keys` with body `{ "environment": "LIVE" }`, then use `sk_live_*` in production.

There is no separate merchant publishable key for `/v1/*` calls; keep `sk_*` keys server-side only.

## 5. One Wallet refunds (checkout partners)

After a customer pays with One Wallet, persist Strawberry `transaction_id` and/or `reference` on the order. To return funds to the customer wallet, call `POST /v1/refunds` with the same Bearer key and a unique `Idempotency-Key`. Full guide: [payments-refunds.md](./payments-refunds.md).

See also: [api-overview.md](./api-overview.md), [OpenAPI JSON](../openapi/merchant-v1.openapi.json).