# API overview — routes and request bodies

**Base URL:** `https://www.strawberryid.com/api`

Merchant integration uses **Bearer** authentication with `sk_test_*` or `sk_live_*` keys on `/v1/*` routes. Write operations that create side effects should send `Idempotency-Key` (unique per logical operation).

## Credentials and configuration

- Required for merchant backend calls: API base URL + Bearer secret (`sk_test_*` or `sk_live_*`).
- Required for webhook verification: webhook secret returned when you create a webhook endpoint.
- No separate merchant publishable/browser key is used for `/v1/*`.
- Strawberry does not require `ONE_WALLET_*` variable names; use your own names and map in config if needed.

Example backend env:

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

---

## Merchant API (`/v1`) — server-to-server

### `GET /v1/whoami`

No body. Returns merchant id, status, sandbox/live access flags.

### `POST /v1/data-requests`

```json
{
  "strawberry_id": "SR1-ABCD-EFGH-X",
  "requested_fields": ["strawberry_id", "display_name", "country", "kyc_status"]
}
```

Headers: `Authorization`, `Idempotency-Key`, `Content-Type: application/json`.

### `GET /v1/identity`

Query: `strawberry_id` (required), `fields` optional comma-separated list.

Allowed fields include: `strawberry_id`, `display_name`, `country`, `email`, `phone_verified`, `kyc_status`.

### `POST /v1/kyc/verifications`

```json
{
  "strawberry_id": "SR1-ABCD-EFGH-X",
  "kind": "nin",
  "id": "12345678901",
  "verification_consent": true,
  "tier": "TIER_1"
}
```

Either `user_id` or `strawberry_id` is required. Supported `kind` values: `bvn`, `nin`, `vnin`, `phone`, `nin_phone`.

Optional `validation` object may include `first_name`, `last_name`, `date_of_birth`, `selfie` (provider-specific).

### `GET /v1/kyc/verifications/:reference`

No body. Returns verification status for a merchant-linked user.

### `POST /v1/refunds`

Refunds a **settled One Wallet payment** back to the customer’s Strawberry wallet (merchant does not custody funds). **Requires** `Idempotency-Key`.

```json
{
  "reference": "checkout-ref-from-your-order",
  "amount": 1500.5,
  "currency": "NGN",
  "reason": "Customer cancelled — Order ORD-991",
  "merchant_reference": "refund-ord-991-1"
}
```

Use **`transaction_id`** (Strawberry `Transaction.id`) **or** **`reference`** (checkout reference). Omit **`amount`** for a **full** refund.

**Policy and integration details:** [payments-refunds.md](./payments-refunds.md).

---

## Merchant provisioning (no merchant key — onboarding / ops)

### `POST /merchants`

Creates a merchant (sandbox-ready flow). Example body:

```json
{
  "name": "Acme Commerce",
  "legalName": "Acme Commerce Limited",
  "contactName": "Tomi Adebayo",
  "contactEmail": "ops@acme.example.com",
  "country": "Nigeria",
  "businessType": "E-commerce"
}
```

### `POST /merchants/:id/api-keys`

```json
{ "environment": "TEST" }
```

Use `"LIVE"` when the merchant is `ACTIVE`.

### `POST /merchants/:id/webhooks`

```json
{ "url": "https://merchant.example.com/webhooks/strawberryid" }
```

---

## Webhook delivery headers

- `X-Strawberry-Signature` — HMAC-SHA256 hex digest of the raw JSON body
- `X-Strawberry-Event`
- `X-Strawberry-Event-Id`

Topics include: `transaction.settled`, `refund.completed`, `merchant.identity.consent_granted`, `merchant.identity.request.approved`, `merchant.identity.request.denied`.

Details: [webhooks.md](./webhooks.md).

---

**Machine-readable:** [merchant-v1.openapi.json](../openapi/merchant-v1.openapi.json)