Central Africa's Payment Infrastructure API.

One API to collect payments from customers, disburse payouts to recipients, and access a growing catalog of value-added services across mobile money and digital wallets in Africa.

Key concepts

The S3P API uses a dynamic service model. Two top-level categories cover all use cases — but 90% of integrations only need one of them.

Vocabulary

Throughout this guide we use merchant-perspective business terms. Each one maps to a single catalog endpoint you call once at startup to discover the available payment packages.

Authentication

The S3P API uses standard OAuth 2.0 with the client_credentials grant. Trade your publicKey and secretKey for a short-lived JWT bearer token, then send it on every request — every standard HTTP client and every Authorization: Bearer …-aware tool works as-is.

OAuth 2.0 (client_credentials)

Two-step flow: exchange your publicKey and secretKey for a short-lived JWT access token at /oauth/token, then attach Authorization: Bearer … on every API request. Once minted, only the bearer travels with each call — your credentials stay on your server.

1. Request a token

   Send publicKey:secretKey as HTTP Basic credentials. grant_type is optional; if present it must be client_credentials.

   POST {YOUR_API_HOST}/oauth/tokenhttp
   POST /oauth/token HTTP/1.1
   Host: {YOUR_API_HOST}
   Content-Type: application/x-www-form-urlencoded
   Authorization: Basic <base64(publicKey:secretKey)>
   
   grant_type=client_credentials

   200 OKjson
   {
     "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
     "token_type":   "Bearer",
     "expires_in":   3600
   }

   ℹ️

   Read expires_in off every responseToken TTL is set per-response — don't hard-code it. Refresh roughly 60s early to absorb clock skew.

2. Attach as a bearer header

   examplehttp
   Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

   Send this header on every secured endpoint. The publicKey:secretKey pair stays out of the request — only the short-lived JWT travels.

3. Refresh before expiry

   client_credentials tokens are not refreshable — request a new one when the current one expires. Track now + expires_in client-side and refresh ~60s early.

Collections & Disbursement

The primary integration category. Collect payments from customers' mobile wallets, or disburse funds to recipients. Payment packages are static — cache once, then quote → execute → verify.

Watch the flow run end to end.

Two flows, same four-step pattern: quote, execute, customer step, callback. Each stage below shows the customer device on the left and your server's HTTP traffic on the right. Press Run flow to step through it. The default outcome path is callback-driven — we POST the final status to the URL configured on your account; polling /verifytx is only the fallback if a callback hasn't arrived within your SLA.

The flow above is the same primitive you'll use for collections, payouts, and most VAS calls — only the discovery endpoint and the package's payItemId change. Read the accept-a-payment and send-a-payout guides for full request/response details.

Accept a payment money flows out of customer's wallet

Four steps: get a quote using a cached package from /cashout, execute the collection, wait for the customer to approve on their phone, then receive a callback with the final status. GET /verifytx is the fallback if no callback arrives within your SLA.

1. Cache collection packages (once at startup)

   Fetch available collection packages. This is a static catalog — cache it and refresh periodically.

   GET /v2/cashoutjson
   [{
     "payItemId":      "S-1-10-CMMTNMOMO-90001-500100-1",
     "amountLocalCur": null,    // null = variable amount
     "localCur":       "XAF",
     "name":           "MTN Mobile Money Collection"
   }]

2. Request a quote

   Use the cached payItemId and the amount the customer will pay.

   ⏱️

   Quotes expire and are single-useExecute the collection immediately — the quoteId expires after a short window.

   POST /v2/quotestdjson
   { "payItemId": "S-1-10-CMMTNMOMO-90001-500100-1", "amount": 10000 }
   
   // Response
   { "quoteId": "Q-8821-cde456", "priceLocalCur": 10000, "localCur": "XAF" }

3. Execute the collection

   Submit the quoteId and the customer's mobile wallet number. Smobilpay sends an approval prompt to their phone. Store the returned PTN immediately.

   POST /v2/collectstdjson
   {
     "quoteId":             "Q-8821-cde456",
     "serviceNumber":       "237700000001",
     "customerPhonenumber": "237700000001",
     "trid":                "order-00123"
   }
   
   // Response — store PTN immediately
   { "ptn": "99999164577717700069821234567890", "status": "PENDING" }

4. Receive the callback (and fall back to polling if needed)

   Once the customer approves on their phone, Smobilpay POSTs the final status to the callback URL configured on your account. Acknowledge with a 2xx within ~5 seconds; non-2xx responses are retried. If a callback hasn't arrived within your SLA window, fall back to GET /verifytx?trid=<your-trid> for reconciliation (rate limit: at most once every 10 seconds per transaction).

   🚨

   Only fulfil the order on SUCCESSPENDING means the customer has not yet approved. Never release goods or credit until you see SUCCESS.

   Transaction status

   Status	Meaning	Action
   PENDING	Awaiting customer approval	Wait for callback (or poll as fallback)
   SUCCESS	Customer approved — funds received	Fulfil order
   ERRORED	Declined, timed out, or wrong PIN	Check errorCode, notify customer
   REVERSED	Rare - Reversed during reconciliation	Contact support

Make a payout money flows into recipient's wallet

A payout moves funds from your Maviance account to a recipient's mobile wallet using /cashin packages. No customer approval needed — funds land immediately on success and Smobilpay POSTs the final status to your callback URL.

The flow mirrors collections, just using /cashin packages. Quote with the payout amount, execute with the recipient's wallet, then receive the callback when funds settle. Fall back to GET /verifytx?trid=... for reconciliation or before any retry. Payouts typically settle faster than collections.

POST /v2/collectstd — payout examplejson
{
  "quoteId":             "Q-9103-fgh789",
  "serviceNumber":       "237680000002",   // recipient's wallet
  "customerPhonenumber": "237680000002",
  "trid":                "payout-ref-456"
}

Value-added services

Bill payments, top-ups, vouchers, and subscriptions. These require a per-customer lookup step before quoting — the payable item is dynamic per customer or service number.

VAS flow

Endpoint reference

All endpoints require a valid Authorization header.

Collections & Disbursement

Returns available payment packages for accepting money from customers. Cache at startup, refresh periodically.

Returns available packages for disbursing funds to recipients. Cache at startup, refresh periodically.

Value-added services

Returns open bills for a customer's account. Each result includes a payItemId for quoting. Called on-demand per customer.

Returns available airtime and data top-up packages. Cache at startup.

Returns the fixed product catalog. Cache at startup.

Returns available vouchers. A successful collection returns a redeemable PIN in the pin field of the POST /collectstd response.

Returns subscriptions for a customer account. Each has its own payItemId. Called on-demand per customer.

Shared

200 OKjson
{ "status": "OK", "version": "3.2.0" }

Returns your current agent balance in XAF. Insufficient balance blocks all collections and payouts (error 40201). Monitor regularly.

Returns all available merchants. Cache and refresh daily — new providers are added without API changes.

Returns services under a merchant. The serviceType tells you whether it's a collection, payout, bill, etc. Check isVerifiable for pre-validation support.

For services where isVerifiable: true, returns a boolean indicating whether the supplied serviceNumber is valid for the selected service and merchant. Lightweight existence check — does not return customer identity data. Reduces failed transactions when used before /quotestd.

Validates an account (destination + serviceId) against the upstream service provider and, when available, returns the associated CustomerAccount including the customer's name. Unlike /verify, this endpoint returns personally identifiable information.

Used by all service types. Returns the exact cost and a single-use quoteId. Execute immediately — quotes expire quickly.

Executes any payment type. Returns a PTN — store immediately. The serviceNumber is the customer's wallet (collections) or recipient's wallet (payouts).

Get the current status of any payment by PTN or your trid. Use this as a fallback when a callback hasn't arrived within your SLA, or before any retry to confirm idempotency. Don't poll faster than once every 10 seconds per transaction.

Paginated transaction history. Only one filter parameter per request (error 40011 if multiple).

Error codes

All HTTP errors return a JSON object. Use respCode for logic, devMsg for debugging, usrMsg is safe to surface to customers.

error response formatjson
{
  "respCode": 4009,
  "devMsg":   "Access token invalid",
  "usrMsg":   "Authentication error",
  "link":     "<support-url>"
}

Authentication

Account & limits

Execution errors

These appear in POST /collectstd responses as validation errors before the payment is processed.

Payment errors (in errorCode)

These appear in callbacks or GET /verifytx responses when status: "ERRORED".

SDKs & libraries

Six official Maviance clients (v3.2.0) cover the partner API end-to-end with OAuth 2.0 client_credentials built in — token mint, refresh, and Authorization: Bearer … attachment are handled for you. All six share the same endpoint coverage and a common smoke-test harness so cross-language behaviour stays in lock-step. If your language isn't listed, any standard HTTP client works as-is once you mint a token at POST /oauth/token.

Testing your integration

Use the staging environment to validate your full integration before requesting production access.

Staging environment

Testing checklist

• ✓
  Authentication works — GET /ping returns 200
• ✓
  Collection packages load — GET /cashout returns payItemId values
• ✓
  Disbursement packages load — GET /cashin returns payItemId values
• ✓
  Collection full flow — quote → execute → callback → SUCCESS
• ✓
  Payout full flow — quote → execute → callback → SUCCESS
• ✓
  Callback fallback works — GET /verifytx?trid=... returns the same final status when callback is unreachable
• ✓
  Customer decline handled — error 703202 shows correct message
• ✓
  Idempotency works — GET /verifytx?trid=... before any retry
• ✓
  PTN is stored — DB records PTN immediately on execution response

Common mistakes

• Crediting on PENDING — never fulfil until verifytx returns SUCCESS.
• Duplicate payouts — a network error doesn't mean failure. Always check /verifytx?trid=... first if recovering from a network/timeout error
• Hard-coded token TTL — read expires_in off every /oauth/token response and refresh ~60s before expiry. Hard-coding a value (e.g. 3600) breaks if the TTL is ever shortened.
• Bearer rejected (4009) — mint tokens only via POST /oauth/token. Bearers obtained any other way will not authenticate.
• Clock drift — JWT exp is checked against the server clock. Hosts with >5 min NTP drift may see tokens rejected as expired sooner than expected.

Callbacks & transaction status

After executing a payment via POST /collectstd, the transaction enters PENDING. Smobilpay resolves it asynchronously. The recommended pattern is to wait for a callback, falling back to polling only if it doesn't arrive or if the network request encountered an interruption/timeout.

Webhook setup

Webhooks are an opt-in feature. To enable, contact the Maviance ops team and provide the following:

Delivery format

When a transaction reaches a final state (SUCCESS, ERRORED, or REVERSED), Smobilpay sends an HTTP POST with a JSON body to your configured URL. Delivery is at-least-once: transient failures are retried with exponential backoff and jitter (default 5 attempts).

Request headers

Request body

Field order on the wire is fixed: timestamp, trid, errorCode, status. All four are always present (no omitempty). Producers and merchants are advised to normalize strings to Unicode NFC before UTF-8 encoding so the HMAC-SHA1 signature is stable across implementations.

Example callback

POST /your-webhook-endpointhttp
POST /exampleEndpoint HTTP/1.1
Host: your-server.example.com
Content-Type: application/json; charset=UTF-8
Accept: application/json
X-Delivery: fe6f0b85-0b3a-4f62-9f89-d7b3a18a8b18
X-Ptn: 99999152778369900057856272351928
X-Signature: 4ba0a40bff4fc5370f45e29f42a7a07bffacee26

{"timestamp":"2018-05-31 16:21:40","trid":"13550","errorCode":"0","status":"SUCCESS"}

Verifying the signature

Recompute the HMAC-SHA1 hex digest of the raw request body using your configured secret, then compare it to X-Signature. Use a constant-time comparison to prevent timing attacks.

Reference example

signature inputstext
// Raw body to sign (exact bytes — no whitespace, fixed field order):
{"timestamp":"2018-05-31 16:21:40","trid":"13550","errorCode":"0","status":"SUCCESS"}

// Secret:
secret

// HMAC-SHA1 hex digest:
4ba0a40bff4fc5370f45e29f42a7a07bffacee26

Verification snippets

Express — capture raw bodyjavascript
const express = require('express');
const crypto  = require('crypto');
const app = express();

// Capture raw bytes — DO NOT use express.json() before signing.
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const raw       = req.body;                          // Buffer
  const received  = req.get('X-Signature') || '';
  const expected  = crypto
    .createHmac('sha1', process.env.SMOBILPAY_WEBHOOK_SECRET)
    .update(raw)
    .digest('hex');

  if (
    received.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  ) {
    return res.status(401).send('invalid signature');
  }

  const body     = JSON.parse(raw.toString());
  const ptn      = req.get('X-Ptn');
  const delivery = req.get('X-Delivery');

  // Idempotency: skip if delivery already processed
  if (alreadyProcessed(delivery)) return res.sendStatus(200);

  handleStatusChange(ptn, body.trid, body.status, body.errorCode);
  markProcessed(delivery);

  res.sendStatus(200); // 2xx tells Smobilpay it was received
});

Flaskpython
import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["SMOBILPAY_WEBHOOK_SECRET"].encode()

@app.post("/webhook")
def webhook():
    raw      = request.get_data()                          # bytes
    received = request.headers.get("X-Signature", "")
    expected = hmac.new(SECRET, raw, hashlib.sha1).hexdigest()

    if not hmac.compare_digest(received, expected):
        abort(401)

    body     = request.get_json(force=True)
    ptn      = request.headers["X-Ptn"]
    delivery = request.headers["X-Delivery"]

    if already_processed(delivery):
        return "", 200

    handle_status_change(ptn, body["trid"], body["status"], body["errorCode"])
    mark_processed(delivery)
    return "", 200

PHPphp
$raw      = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected = hash_hmac('sha1', $raw, getenv('SMOBILPAY_WEBHOOK_SECRET'));

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

$body     = json_decode($raw, true);
$ptn      = $_SERVER['HTTP_X_PTN'];
$delivery = $_SERVER['HTTP_X_DELIVERY'];

if (already_processed($delivery)) { http_response_code(200); exit; }

handle_status_change($ptn, $body['trid'], $body['status'], $body['errorCode']);
mark_processed($delivery);
http_response_code(200);

Spring Bootjava
@PostMapping("/webhook")
public ResponseEntity<String> webhook(
    @RequestHeader("X-Signature") String received,
    @RequestHeader("X-Ptn") String ptn,
    @RequestHeader("X-Delivery") String delivery,
    @RequestBody byte[] raw,
    @Value("${smobilpay.webhook.secret}") String secret
) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA1");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA1"));
    StringBuilder hex = new StringBuilder();
    for (byte b : mac.doFinal(raw)) hex.append(String.format("%02x", b));
    String expected = hex.toString();

    if (!MessageDigest.isEqual(expected.getBytes(), received.getBytes())) {
        return ResponseEntity.status(401).build();
    }
    // parse, deduplicate by delivery, dispatch...
    return ResponseEntity.ok().build();
}

net/httpgo
func webhook(w http.ResponseWriter, r *http.Request) {
    raw, _ := io.ReadAll(r.Body)
    received := r.Header.Get("X-Signature")

    mac := hmac.New(sha1.New, []byte(os.Getenv("SMOBILPAY_WEBHOOK_SECRET")))
    mac.Write(raw)
    expected := hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(received), []byte(expected)) {
        http.Error(w, "invalid signature", 401)
        return
    }

    var body struct {
        Timestamp string `json:"timestamp"`
        Trid      string `json:"trid"`
        Status    string `json:"status"`
        ErrorCode string `json:"errorCode"`
    }
    json.Unmarshal(raw, &body)

    delivery := r.Header.Get("X-Delivery")
    if alreadyProcessed(delivery) {
        w.WriteHeader(200)
        return
    }
    handleStatusChange(r.Header.Get("X-Ptn"), body.Trid, body.Status, body.ErrorCode)
    markProcessed(delivery)
    w.WriteHeader(200)
}

Receiver checklist

• ✓
  HTTPS only — accept callbacks over TLS; reject plain HTTP.
• ✓
  Verify the signature on every request before doing anything else. Use constant-time comparison.
• ✓
  Sign the raw body — capture bytes before any JSON parsing or middleware.
• ✓
  Deduplicate by X-Delivery — UUID is stable across automatic retries within one delivery, so dedup is safe without parsing the body. For logical idempotency across requeues, also key on (X-Ptn, trid).
• ✓
  Match by X-Ptn or trid against your stored transaction record.
• ✓
  Return 2xx fast — any 2xx is treated as success and stops retries. Return 5xx, 408, or 429 if you want the delivery retried; other 4xx responses are recorded for audit but not retried. Acknowledge within a few seconds, then process asynchronously if work is heavy.
• ✓
  Always keep polling as a fallback — if a callback does not arrive within your SLA, fall back to GET /verifytx. Service providers occasionally experience service delays or interruptions, which can cause delays in fullfillment on the Smobilpay platform.

Going to production

Going live requires completing the Partner Integration Process — a structured onboarding journey managed jointly by you and Maviance.

Partner integration process

1. Kick-off workshop

   API presentation, overview of functions, Q&A.

2. Test account setup

   Maviance sets up your partner account on the test environment and shares test credentials.

3. Integration

   You perform the integration. Maviance provides live support.

4. Validation

   Maviance validates and certifies that the integration meets requirements.

5. Go live

   Maviance sets up your partner account on production and shares production credentials.

Certifying your integration

Before production access is granted, Maviance performs a full User Acceptance Test in four stages.

1. Implementation completed — partner finishes implementation.
2. Partner self-certification UAT — provide logfiles and a completed test scenario document.
3. Partner provides Maviance access — integration in test system, Maviance support as needed.
4. Maviance final UAT — functional compliance to business processes & technical compliance to API restrictions.

Integration policies

During certification Maviance verifies compliance with the following policies. Violations in production can result in automatic account suspension without warning.

Production security checklist

• ✓
  HTTPS only — never transmit bearer tokens or credentials over HTTP in production.
• ✓
  Credentials stay server-side — never expose your publicKey/secretKey (or a minted bearer) in client code, mobile binaries, or version control.
• ✓
  Store every PTN immediately — write PTN to DB before responding to the customer.
• ✓
  Idempotent retries via trid — always call GET /verifytx?trid=... before retrying.
• ✓
  Callbacks over polling — never faster than every 10 seconds per transaction.
• ✓
  Cache master data — refresh once daily.
• ✓
  Monitor account balance — set low-balance alerts; error 40201 blocks all payments.
• ✓
  Rotate credentials regularly — support zero-downtime rotation via the admin portal.