> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gosurge.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> The Surge API is organized around REST. It accepts JSON-encoded request bodies, returns JSON responses, and uses standard HTTP response codes and authentication.

## Base URL

All requests to the Surge API must be made over HTTPS.

```bash theme={null}
https://api.gosurge.xyz/api/v1
```

## Authentication

The Surge API authenticates merchant requests using **API keys**. Your key is issued when your merchant account is approved and has the format `surge_live_sk_...`.

Include it on every request:

```bash theme={null}
Authorization: Bearer surge_live_sk_...
```

**Example:**

```bash theme={null}
curl -X POST https://api.gosurge.xyz/api/v1/checkout/sessions \
  -H "Authorization: Bearer surge_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

Store your key as an environment variable (`SURGE_API_KEY`) and never commit it to version control.

<Warning>
  Never expose your API key in client-side code. Always call the Surge API from your server backend.
</Warning>

### Key rotation

To generate your first key or rotate an existing one, call:

```bash theme={null}
POST /api/v1/merchant/{merchant_id}/rotate-api-key
Authorization: Bearer surge_live_sk_...
Content-Type: application/json

{ "name": "Production Server" }
```

The `name` field is optional but recommended — it identifies the key in your rotation history. The new plaintext key is returned once in `data.apiKey`. Store it immediately. The old key is invalidated on rotation and archived to your key history.

To view past revoked keys:

```bash theme={null}
GET /api/v1/merchant/{merchant_id}/api-key/history
Authorization: Bearer surge_live_sk_...
```

Returns an array of revoked keys with their name, masked prefix, created date, and revocation date.

<Note>
  API key generation requires your account to have API access enabled. If the endpoint returns `403`, contact [support@gosurge.xyz](mailto:support@gosurge.xyz) to have it unlocked.
</Note>

***

## HTTP Conventions

| Method   | Meaning                     |
| :------- | :-------------------------- |
| `GET`    | Retrieve a resource         |
| `POST`   | Create a resource           |
| `PATCH`  | Partially update a resource |
| `DELETE` | Remove a resource           |

All request bodies must be **JSON** with the `Content-Type: application/json` header.

***

## Amounts & Currency

All monetary amounts in the Surge API are in **kobo** (the smallest Nigerian currency unit). There are 100 kobo in 1 Naira.

| Display value | API value (`amount`) |
| :------------ | :------------------- |
| ₦1,200.00     | `120000`             |
| ₦50.00        | `5000`               |
| ₦10,000.00    | `1000000`            |

Always pass integer kobo values. Divide by 100 when displaying amounts to customers.

***

## Response Format

All responses follow a consistent envelope:

```json theme={null}
{
  "ok": true,
  "data": { ... }
}
```

Errors come in two shapes depending on how the endpoint raises them:

**FastAPI exceptions** (`HTTPException`) return:

```json theme={null}
{ "detail": "Human-readable error message" }
```

**Soft errors** (explicit endpoint returns) return:

```json theme={null}
{ "ok": false, "error": { "code": "ERROR_CODE", "message": "Human-readable message" } }
```

Always check the HTTP status code first, then inspect `detail` or `error.message` depending on which shape is present.

***

## Idempotency

For write operations (e.g. creating a checkout session), you can send an `Idempotency-Key` header containing a UUID to safely retry requests without creating duplicates.

```bash theme={null}
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

If Surge receives a second request with the same key within **24 hours**, it returns the original response without executing the operation again. See the [Server Integration guide](/docs/server-integration#idempotency) for details.

***

## Rate Limits

| Plan       | Requests    |
| :--------- | :---------- |
| Sandbox    | 100 req/min |
| Production | 500 req/min |

Exceeding the limit returns HTTP `429 Too Many Requests`. Retry with exponential back-off.

***

## Error Codes

| HTTP Status | Meaning                                                             |
| :---------- | :------------------------------------------------------------------ |
| `400`       | Bad Request — malformed payload or missing required field           |
| `401`       | Unauthorized — missing or invalid API key                           |
| `403`       | Forbidden — the request is not allowed (e.g. inactive merchant)     |
| `404`       | Not Found — the resource does not exist                             |
| `409`       | Conflict — resource already exists (e.g. session already completed) |
| `429`       | Too Many Requests — rate limit exceeded                             |
| `500`       | Internal Server Error — something went wrong on our end             |

***

## Settlement & Fees

Surge charges a **2.5% platform fee** on each successful payment collected. For every installment:

* Surge retains **2.5%**
* The merchant receives **97.5%** of the installment amount

Merchants are paid out to their registered bank account. You can view your wallet balance and transaction history via the merchant dashboard or the ledger API endpoints (`GET /api/v1/merchant/{merchant_id}/wallet`).