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.

https://api.gosurge.xyz/api/v1

Authentication

The Surge API uses API keys to authenticate requests. View and manage your API keys in the Surge Merchant Dashboard.

Authentication is performed via the Authorization header using Bearer tokens.

Authorization: Bearer <YOUR_SECRET_KEY>

Your Secret Key should never be exposed in client-side code (browser JavaScript, native apps). Always make API calls from your server backend.

---

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.

---

Response Format

All responses follow a consistent envelope:

{
  "ok": true,
  "data": { ... }
}

Errors return "ok": false with an HTTP 4xx/5xx status code and a detail field explaining the failure.

---

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.

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 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 — invalid or missing 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).