> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.senjaropay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.senjaropay.com/_mcp/server.

# Authentication

Every call to `https://api.senjaropay.com` must include a valid **Public Key** and **API secret** in headers.
In the dashboard, the **Public Key** maps directly to `x-api-key`.

The merchant API uses **POST** for every endpoint, including reads. Send a JSON body (use `{}` when there are no parameters).

## Request headers

```http
x-api-key: <public_key>
x-api-secret: <secret>
```

Use **HTTPS only**. API keys are for **server-side** use—never from browsers, mobile apps, or other untrusted environments.

***

## Issuing and rotating keys

1. Sign in to the [SenjaroPay dashboard](https://senjaropay.com/).
2. Go to **Settings** → **API keys**.
3. Copy the **Public Key** (use as `x-api-key`) and **Secret Key** (use as `x-api-secret`).
4. Store both in server-side secrets. Do not expose them in client apps.

If a secret is lost, leaked, or no longer needed: **revoke** it in the dashboard and **issue a new key**. Prefer rotation over reusing compromised material.

***

## Example

```bash
curl -sS -X POST https://api.senjaropay.com/senjaropay/merchant/payments/status \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${SENJARO_API_KEY}" \
  -H "x-api-secret: ${SENJARO_API_SECRET}" \
  -d '{"referenceId":"mock-ref-7b2a4f3e"}'
```

Supply the secret from your deployment configuration (environment variable, vault, or managed secrets). Use **POST**, **`Content-Type: application/json`**, and a JSON body on every call.

Raw request shape:

```http
POST /senjaropay/merchant/payments/status HTTP/1.1
Host: api.senjaropay.com
Content-Type: application/json
x-api-key: <secret>
x-api-secret: <secret>

{"referenceId":"mock-ref-7b2a4f3e"}
```

***

## Scopes

Request only the credentials that belong to the environment you are integrating (sandbox vs production), and keep them server-side.

***

## Errors

| Status  | `error_code`   | Meaning                                                           |
| ------- | -------------- | ----------------------------------------------------------------- |
| **401** | `unauthorized` | Key missing, malformed, revoked, or used in the wrong environment |
| **403** | `forbidden`    | Credentials valid but operation not allowed for account           |

**401 — response body (example)**

```json
{
  "status": "error",
  "code": 401,
  "error_code": "unauthorized",
  "message": "invalid or missing API key"
}
```

**403 — response body (example)**

```json
{
  "status": "error",
  "code": 403,
  "error_code": "forbidden",
  "message": "operation not allowed for merchant account"
}
```

For **403**, verify the account permissions and environment keys being used.

***

## Security

* Store secrets outside source control; never commit keys or paste them into tickets or chat.
* Use **distinct keys** per environment where the product supports it (for example sandbox vs production).
* **Rotate** on a schedule and **revoke immediately** if exposure is suspected.
* Avoid logging request headers or full key values; redact when debugging.