Architecture & HMAC Proxy

AfriSwitch relies on a secure institutional architecture based on an HMAC proxy that protects access to the internal API https://api.afriswitch.net/api/v1/. The enterprise portal acts as the orchestration, authentication and standardisation layer.

1. Overview

Client (Partner System / Postman)
        ↓
AfriSwitch Enterprise Portal (organisation authentication)
        ↓
HMAC Proxy (automatic signature)
        ↓
Institutional AfriSwitch API
        ↓
Institutional Response
        ↓
Portal (standardised formatting)
        ↓
Client

2. Role of the AfriSwitch Portal

• Validates that the organisation is active
• Checks permissions
• Automatically applies the HMAC signature
• Forwards the request to the institutional API
• Returns a standardised response

3. The HMAC Proxy

The HMAC proxy is an internal component that signs all outgoing requests to the institutional API. Partners never need to generate any signature manually.

Internal service used:

call_institutional_api(
    portal_company=request.company,
    method="GET/POST",
    path="/api/v1/...",
    json_body=request.json_body,
    params=request.GET,
    use_hmac=True,
)

This service:

• Generates the HMAC signature
• Adds the required headers
• Sends the request to the institutional API
• Returns the raw response inside data

4. Response Structure (Portal)

{
  "status": 200,
  "data": {
    ...
  }
}

The data field contains the institutional response (sensitive values masked in the documentation).

5. Security

• API keys are unique to each organisation
• The portal signs all requests on behalf of the partner
• No internal keys are ever exposed
• Dates, references and numbers are masked in the documentation

6. Testing & Validation

• Use Postman with x-api-key and api-secret
• Test PAYIN / PAYOUT flows
• Observe real operator behaviour (payment_url, OTP, USSD)
• Check statuses via /transactions/status/

Conclusion

This architecture ensures a secure, scalable and institutional-grade integration for all AfriSwitch partners.