# Merchant

Source: https://caravelpay.app/docs/merchant.html · Caravel Pay docs · Last updated 2026-11-09

Read what Caravel Pay knows about your merchant: the site your URLs may point to, the wallet new checkouts pay out to, and whether you can take payments. It's also the quickest way to test your credentials.

## The merchant object

| Field | Description |
|---|---|
| `id` · string | Your merchant id, for example `mch_7Q2KZX4PRB`. The same value you send in `Caravel-Merchant`. |
| `site_url` · string | The site you connected. |
| `origins` · array | The origins from your `site_url`, with and without `www`. Your `return_url`, `cancel_url` and `callback_url` must use one of them. |
| `payout_address` · string | The Polygon wallet that new checkouts pay out to. |
| `status` · string | `active`, `pending_review` or `paused`. See [status](https://caravelpay.app/docs/merchant.html#status). |
| `paused_reason` · string or null | While `status` is `paused`, a short reason from Caravel Pay (at most 200 characters), for example *Paused while we check an unusual payment pattern. Email hello@caravelpay.app.* `null` when the merchant isn't paused or no reason was given. Show it to the store owner; don't parse it. |
| `fee_rate` · string | Always `"2%"`. |

## Retrieve your merchant

`GET/v1/merchant`

Signed like any request, with an empty body. The WooCommerce plugin calls it to show whether your store is connected.

*GET /v1/merchant · curl*

```sh
TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" GET /v1/merchant "" \
  | openssl dgst -sha256 -hmac "$CARAVEL_SECRET" | awk '{print $NF}')

curl https://api.caravelpay.app/v1/merchant \
  -H "Caravel-Merchant: $CARAVEL_MERCHANT" \
  -H "Caravel-Timestamp: $TS" \
  -H "Caravel-Signature: $SIG"
```

*GET /v1/merchant · Node.js*

```js
const merchant = await caravel("GET", "/v1/merchant");
```

*GET /v1/merchant · PHP*

```php
$merchant = caravel('GET', '/v1/merchant');
```

*GET /v1/merchant · Python*

```py
merchant = caravel("GET", "/v1/merchant")
```

*200 OK*

```json
{
  "id": "mch_7Q2KZX4PRB",
  "site_url": "https://shop.example",
  "origins": ["https://shop.example", "https://www.shop.example"],
  "payout_address": "0x52908400098527886E0F7030069857D2E4169EE7",
  "status": "active",
  "paused_reason": null,
  "fee_rate": "2%"
}
```

A `401` here means the merchant id, secret or clock is off. [Common mistakes](https://caravelpay.app/docs/authentication.html#mistakes) lists the usual causes.

## Status

| Status | What it means |
|---|---|
| `active` | You can create checkouts. Merchants are active as soon as they get their keys. |
| `pending_review` | The site is waiting for approval. Creating a checkout answers `403 merchant_pending_review` until it is approved. |
| `paused` | New checkouts answer `403 merchant_paused`. Open checkouts and their payouts still finish. `paused_reason` says why, when one was given. Email [hello@caravelpay.app](mailto:hello@caravelpay.app). |

## Changing your settings

There is no update call. To change your payout wallet or secret, [get new keys](https://caravelpay.app/docs/connect.html#reconnect) and switch to them; keep the old ones until the checkouts made with them have finished. The WooCommerce plugin does this for you when you save a new wallet.