Developer Documentation

Everything you need to integrate Sogo's financial services into your application. Use these guides alongside the interactive API Reference to explore every endpoint.

Account Requirements

Sandbox keys are available to accounts with at least Tier 2 KYC (identity verification) approved - start building and testing in minutes. Live keys require full Tier 3 KYC identity verification and KYB & Compliance (business verification) approval first.

To meet these key requirements:

• KYC Tier 2 (for Sandbox & Live): Submit basic personal information and verify your identity using a valid ID number (BVN/NIN) from KYC & Limits in your Sogo profile. Approved instantly.
• KYC Tier 3 (for Live): Submit your identity document, proof of address, and video selfie from KYC & Limits in your Sogo profile. Reviewed within 1-2 business days.
• KYB & Compliance (for Live): Submit your business documents - CAC certificate, status report, director information, and supporting compliance documents - from KYB & Compliance in your Sogo profile. Reviewed within 1-3 business days.

Base URLs

The Partner API has two independent environments. Use sandbox for all development and testing - it mirrors live behaviour without touching real money.

# Live
https://api.sogo.africa/v1

# Sandbox
https://sandbox.sogo.africa/v1

Environments (Live & Sandbox)

The Sogo Partner API operates in two environments: Live and Sandbox. The sandbox is a full-fidelity replica of the live API that lets you build, test, and debug your integration without touching real money or real utility providers. Every endpoint, request shape, response shape, error code, webhook event, and idempotency mechanism works identically to live.

Simulating Outcomes

No real providers are contacted in sandbox.

Bills (Airtime, Data, Electricity, Cable TV, Education, Bet Funding)
Outcomes are determined by the last 4 digits of the primary customer identifier (phone, meter_number, smartcard_number, profile_id, account_id):

Gift Cards
Outcomes are determined by the last 4 characters of the additional_info field (for e-code cards) or the first image filename (for physical cards):

RMB Purchases (Buy orders)
Outcomes are determined by the last 4 characters of the recipient_identifier field:

Crypto Sells (Test deposits)
Simulated deposits are triggered via POST /v1/crypto/test-deposit. The outcome is determined by the last 4 characters of the test_reference field:

Published Test Identifiers

Copy and paste these directly into your requests:

API Keys

Every request must be authenticated with an API key. Send it as a Bearer token in the Authorization header. Alternatively, you can use the X-API-Key header.

POST https://api.sogo.africa/v1/bills/airtime
Authorization: Bearer sogo_sk_live_<your_key>
Content-Type: application/json

Keys are generated from your profile under the Developer tab. You can create up to 5 key pairs per environment, restrict to specific IP addresses, and scope keys to only the permissions they need.

Key Types

Each key pair consists of a secret key and a public key.

• sogo_sk_live_ / sogo_sk_test_ - Secret keys. Full API access. Never expose these in client-side code, mobile apps, or public repositories.
• sogo_pk_live_ / sogo_pk_test_ - Public keys. Restricted to read-only operations explicitly allowed for public keys. Safe to embed in client apps.

Scopes

Scopes control which endpoints your API key can access. Assign the minimum set of scopes your integration needs - you can always add more later. The full list of available scopes is also returned by GET /v1/scopes.

If your key is missing a required scope, the API returns 403 invalid_scope. If you send a public key to an endpoint that requires a secret key, it returns 403 secret_key_required.

Idempotency

All write operations on financial endpoints require an Idempotency-Key header. This prevents duplicate transactions if a request is retried due to a network timeout or connection drop.

POST https://api.sogo.africa/v1/bills/airtime
Authorization: Bearer sogo_sk_live_<your_key>
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

Key rules:

• Must be unique per operation. A UUID v4 generated client-side is the recommended format.
• Keys are scoped to your account - the same key used by two different accounts does not conflict.
• A key is permanently and uniquely bound to its transaction. No duplicate charge can ever be created regardless of when you retry - minutes, days, or years later.
• Replayed responses include an Idempotency-Replayed: true header so you can distinguish them from new transactions.
• If a request is currently in-flight with the same key, you'll receive a 409 idempotency_request_in_progress. Wait and retry.

Reconciliation: If a network error prevented you from receiving the response, use your original idempotency key to check the outcome - no retry needed:

GET https://api.sogo.africa/v1/transactions/{idempotency-key}?type=bill_payment
Authorization: Bearer sogo_sk_live_<your_key>

A 404 means the transaction was never created and it is safe to retry with the same key. A 200 response contains the transaction - check the status field to determine next steps.

Rate Limiting

The API allows 300 requests per minute per live API key and 10 requests per minute per sandbox test API key. Exceeding this limit returns a 429 rate_limit_exceeded response. Implement exponential backoff when you receive a 429.

Monetary Amounts

All numeric amount fields in both requests and responses use major currency units (e.g. 1000 or 1000.00 for ₦1,000.00). Fields ending in _formatted are display strings only and should not be parsed.

This applies to request body amounts (e.g. amount on purchase endpoints), transaction response fields (amount.raw, fee.raw, net_amount.raw), and wallet response fields (balance, withdrawable_balance).

Integration Flows

Flow A - Bill purchase (standard)

Use this flow for all bill payment products: airtime, data, electricity, cable TV, education, ePIN, and bet funding.

1. Discover providers. Call GET /v1/bills/catalog (optionally with ?type=) to get every supported provider, its slug, full name, and the endpoints available for that bill type. For products with variable plans (data, cable TV, education), follow up with the relevant listing endpoint (e.g. GET /v1/bills/data-plans?network=mtn) to retrieve available variation codes and pricing.
2. Verify the customer identifier. For electricity, cable TV, and JAMB products, call the corresponding verify endpoint to confirm the meter number, smartcard number, or JAMB profile before submitting payment.
3. Generate a UUID client-side as your Idempotency-Key. Store it before sending the request so you can use it for reconciliation if the response is lost.
4. Submit the purchase. POST to the relevant endpoint with the Idempotency-Key header and the validated plan details.
5. Handle the response. A 201 response contains the transaction object. Check transaction.status - the transaction may be processing (fulfilment in progress) or completed already.
6. Track completion. Subscribe to transaction.completed and transaction.refunded webhooks, or poll GET /v1/transactions/{reference} until the status is final.
7. Reconcile if no response was received. If a network error or timeout means you never received the API response, look up the outcome by your idempotency key before retrying:
   HTTP

   GET https://api.sogo.africa/v1/transactions/{idempotency-key}?type=bill_payment
   Authorization: Bearer sogo_sk_live_<your_key>

   A 404 means the transaction was never created - safe to retry with the same key. A 200 response returns the transaction; check status to decide next steps.

Flow B - Payment verification

Use this flow when you need to confirm that a payment already completed before fulfilling an order on your side (for example, a customer claims they paid via Sogo).

1. Receive the transaction reference from your order flow or the customer.
2. Call POST /v1/transactions/verify with the expected reference, amount, and currency.
3. Gate fulfilment on verified: true in the response. A false result includes a reason field explaining the mismatch (not_found, not_completed, amount_mismatch, currency_mismatch).

Transaction Status

Every transaction has a status field reflecting its current state. Understanding each status is essential for knowing when to fulfil orders and when it is safe to retry.

Webhooks

Webhooks let Sogo push real-time transaction events to your server instead of you polling for status changes. Register up to 3 webhook endpoints from your profile's Developer tab.

Each endpoint can subscribe to one or more event types. When an event fires, Sogo makes a POST request to your URL with a JSON payload and several identifying headers.

Events

Example payload for transaction.completed:

{
  "id": "evt_Xk9mQ2rNpL4sYv8F",
  "event": "transaction.completed",
  "created_at": "2026-05-09T08:30:00+00:00",
  "data": {
    "object": "transaction",
    "id": "8f7243e0-49c7-4f7c-a7a8-2d4e3f7ac001",
    "reference": "BILL202605090830A120123",
    "type": "bill_payment",
    "status": "completed",
    "amount": 5000.00,
    "fee": 50.00,
    "net_amount": 4950.00,
    "currency": "NGN",
    "description": "Airtime - MTN (08061464003)",
    "completed_at": "2026-05-09T08:30:00+00:00",
    "created_at": "2026-05-09T08:28:00+00:00"
  }
}

Verifying signatures

Every webhook request includes a signature so you can verify it genuinely came from Sogo. Check the X-Sogo-Signature-256 header before processing any payload.

To verify: compute HMAC-SHA256(raw_body, webhook_secret) and compare it to the value after sha256= in the header. Use a constant-time comparison to prevent timing attacks.

$rawBody  = file_get_contents('php://input');
$secret   = getenv('SOGO_WEBHOOK_SECRET');
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$received = $_SERVER['HTTP_X_SOGO_SIGNATURE_256'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);

Error Codes

When a request fails, the API returns a structured error object. Every error includes a doc_url that links directly to the relevant entry below.

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or revoked API key.",
    "doc_url": "https://developer.sogo.africa/docs/errors#authentication_failed"
  }
}