API reference

Merchant

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.
`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

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"

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

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

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

200 OK

{
  "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 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.

Changing your settings#

There is no update call. To change your payout wallet or secret, get new keys 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.