Skip to main content

​
Base URL

All requests to the Surge API must be made over HTTPS. 
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: 
Authorization: Bearer surge_live_sk_...
Example: 
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.
Never expose your API key in client-side code. Always call the Surge API from your server backend.

​
Key rotation

To generate your first key or rotate an existing one, call: 
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: 
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.
API key generation requires your account to have API access enabled. If the endpoint returns 403, contact support@gosurge.xyz to have it unlocked.

​
HTTP Conventions

MethodMeaning
GETRetrieve a resource
POSTCreate a resource
PATCHPartially update a resource
DELETERemove 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 valueAPI value (amount)
₦1,200.00120000
₦50.005000
₦10,000.001000000
Always pass integer kobo values. Divide by 100 when displaying amounts to customers.

​
Response Format

All responses follow a consistent envelope: 
{
  "ok": true,
  "data": { ... }
}
Errors come in two shapes depending on how the endpoint raises them: FastAPI exceptions (HTTPException) return: 
{ "detail": "Human-readable error message" }
Soft errors (explicit endpoint returns) return: 
{ "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. 
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

PlanRequests
Sandbox100 req/min
Production500 req/min
Exceeding the limit returns HTTP 429 Too Many Requests. Retry with exponential back-off.

​
Error Codes

HTTP StatusMeaning
400Bad Request — malformed payload or missing required field
401Unauthorized — missing or invalid API key
403Forbidden — the request is not allowed (e.g. inactive merchant)
404Not Found — the resource does not exist
409Conflict — resource already exists (e.g. session already completed)
429Too Many Requests — rate limit exceeded
500Internal 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).