Skip to main content

​
Base URL

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

​
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:
Example:
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:
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:
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

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. Always pass integer kobo values. Divide by 100 when displaying amounts to customers.

​
Response Format

All responses follow a consistent envelope:
Errors come in two shapes depending on how the endpoint raises them: FastAPI exceptions (HTTPException) return:
Soft errors (explicit endpoint returns) return:
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.
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

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

​
Error Codes

​
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).